Pular para o conteúdo principal
Os endpoints de Mensagens diretas v2 introduzem conversas e eventos de conversa como objetos centrais da X API e distinguem entre conversas 1‑1 e em grupo. Conversas 1‑1 sempre têm duas — e apenas duas — participantes, enquanto conversas em grupo podem ter duas ou mais, com participações que podem mudar.    Esta página contém informações sobre várias ferramentas e conceitos fundamentais que você deve conhecer ao integrar os endpoints de consulta de Mensagens diretas ao seu sistema. Dividimos a página em duas seções:

​
Conceitos fundamentais

​
Conversas de Mensagens diretas

Todas as Mensagens diretas fazem parte de uma conversa de Mensagens diretas. Essas conversas podem ser individuais (um para um) ou em grupo. Este lançamento fornece os endpoints essenciais necessários para criar Mensagens diretas e recuperar eventos associados às conversas de Mensagens diretas. Todas as conversas têm um dm_conversation_id exclusivo, e os eventos que compõem essa conversa têm cada um um dm_event_id exclusivo.   Os endpoints de consulta de Mensagens diretas fornecem métodos para recuperar eventos associados às conversas. Esses endpoints GET são usados para recuperar as mensagens que compõem uma conversa e, no caso de conversas em grupo, podem ser usados para identificar quem entrou e quem saiu das conversas em grupo. Esta versão inicial da consulta de Mensagens diretas inclui três métodos GET:
  • GET /2/dm_conversations/with/:participant_id/dm_events - Recupera eventos de Mensagens diretas associados a uma conversa individual. O parâmetro de caminho :participant_id é o ID numérico do Usuário da conta que está conversando com o usuário autenticado que faz esta solicitação.  
  • GET /2/dm_conversations/:dm_conversation_id/dm_events - Recupera eventos de Mensagens diretas associados a um ID de conversa específico, conforme indicado pelo parâmetro de caminho :dm_conversation_id. IDs de conversas tanto individuais quanto em grupo são aceitos.  
  • GET /2/dm_events - Recupera eventos de Mensagens diretas associados ao usuário autenticado, incluindo conversas individuais e em grupo. Eventos de até 30 dias atrás estão disponíveis.  
Todos esses endpoints GET permitem recuperar dm_events por tipo de evento com o parâmetro de consulta de requisição event_types. Atualmente, há três tipos de eventos de conversa compatíveis:
  • MessageCreate - Criado quando uma nova Mensagem direta é enviada. Esse objeto de evento pode incluir a hora e o texto da mensagem, juntamente com o ID da conta de quem enviou a mensagem, além dos IDs da conversa e do evento. 
  • ParticipantsJoin - Criado quando um novo participante entra em uma conversa em grupo. Esse objeto dm_event inclui o ID do participante que entrou, juntamente com o horário created_at e o sender_id do evento “invite”. 
  • ParticipantsLeave - Criado quando um participante sai de uma conversa. Esse objeto de evento inclui o ID do participante que saiu, juntamente com a hora do evento. 
Para mais informações, consulte as Referências da API de consulta de Mensagens diretas.

​
IDs de conversa e evento compartilhados entre v1.1 e v2

Um conceito importante é que os IDs de conversa e de evento são compartilhados entre as versões v1.1 e v2 da Plataforma X. Isso significa que ambas as versões podem ser usadas em conjunto. Por exemplo, os endpoints de Mensagens diretas v1.1 oferecem métodos para retornar um único evento e para excluir eventos, métodos ainda não disponíveis no v2. Como os IDs são comuns entre v1.1 e v2, você pode fazer solicitações v1.1 com base em IDs fornecidos pelo v2 ou referenciar IDs de conversa exibidos nas URLs de conversa no aplicativo X.  

​
Campos e expansions de eventos de Mensagens Diretas

A X API v2 permite que os usuários selecionem exatamente quais dados desejam receber da API usando um conjunto de ferramentas chamado fields e expansions. Por exemplo, os endpoints de busca de Mensagens Diretas oferecem suporte aos seguintes campos de dm_events:
  • id, event_type e text são os padrões para eventos MessageCreate.
  • id, event_type e participant_ids são os padrões para eventos ParticipantsJoin e ParticipantsLeave.
  • dm_conversation_id e created_at estão disponíveis para todos os eventos.
  • attachments e referenced_tweets estão disponíveis para eventos MessageCreate.
  • sender_id está disponível para eventos MessageCreate e ParticipantsJoin.
  • participant_ids está disponível para eventos ParticipantsJoin e ParticipantsLeave.
Além disso, os endpoints de busca de Mensagens Diretas oferecem suporte às seguintes expansions:
  • sender_id - Expande o objeto de usuário associado a quem enviou a mensagem ou convidou alguém para a conversa.
  • referenced_tweets.id - Expande o Objeto Post se o texto da Mensagem Direta incluir um link para um Post.
  • attachments.media_keys - Expande o objeto de mídia se a Mensagem Direta incluir um anexo de mídia.
  • participant_ids - Expande o objeto de usuário associado a quem entrou ou saiu de uma conversa em grupo.
Como as expansions incluem objetos de Posts, Users e Media, você também pode usar os parâmetros de query da requisição tweet.fields, user.fields e media.fields. Consulte nosso guia sobre como usar fields e expansions para mais informações.

​
Tipos de eventos de conversa

A seguir estão exemplos de objetos JSON de Mensagens Diretas para os tipos de evento MessageCreate, ParticipantsJoin e ParticipantsLeave.  Campos disponíveis do objeto dm_event: id, text, event_type, dm_conversation_id, created_at, sender_id, attachments, referenced_tweets, participant_ids. Consulte a seção Fields and Expansion para mais detalhes sobre como selecionar esses fields em suas solicitações.  Exemplo de evento MessageCreate:  Com todos os campos de dm_event especificados, segue a resposta para uma Mensagem Direta de texto simples:  { "text": "Hi everyone.", "sender_id": "944480690", "dm_conversation_id": "1578398451921985538", "id": "1582838499983564806", "event_type": "MessageCreate", "created_at": "2022-10-19T20:58:00.000Z" } Exemplo de evento ParticipantsJoin: Com todos os campos de dm_event especificados, segue a resposta para um participante entrando em uma conversa: { "participant_ids": [ "944480690" ], "sender_id": "17200003", "dm_conversation_id": "1578398451921985538", "id": "1582835469712138240", "event_type": "ParticipantsJoin", "created_at": "2022-10-19T20:45:58.000Z" } Exemplo de evento ParticipantsLeave: Com todos os campos de dm_event especificados, segue a resposta para um participante saindo de uma conversa: { "participant_ids": [ "944480690" ], "dm_conversation_id": "1578398451921985538", "id": "1582838535115067392", "event_type": "ParticipantsLeave", "created_at": "2022-10-19T20:58:09.000Z" }

​
Autenticação

Todos os endpoints da X API v2 exigem que você autentique suas solicitações com um conjunto de credenciais, também conhecido como chaves e tokens. Todas as Mensagens diretas são privadas e exigem autorização do usuário para acessá-las. Esses endpoints de Mensagens diretas exigem o uso de OAuth 2.0 Authorization Flow with PKCE ou 1.0a User Context, o que significa que você deve usar um conjunto de chaves de API e Access Tokens de usuário para fazer uma solicitação bem-sucedida. Os Access Tokens devem estar associados ao usuário em cujo nome você está fazendo a solicitação. Se você quiser gerar um conjunto de Access Tokens para outro usuário, ele deverá autorizar ou autenticar sua App usando o fluxo OAuth de 3 etapas. Observe que o contexto de usuário do OAuth pode ser complexo de usar. Se você não estiver familiarizado com esse método de autenticação, recomendamos usar uma biblioteca ou uma ferramenta como o Postman para autenticar suas solicitações corretamente. OAuth 2.0 Authorization Code com PKCE permite maior controle sobre o escopo de uma aplicação e fluxos de autorização em vários dispositivos. O OAuth 2.0 permite escolher escopos específicos e granulares que concedem permissões específicas em nome de um usuário. Os endpoints de consulta de Mensagens diretas exigem estes escopos: dm.read, post.read, user.read Para habilitar o OAuth 2.0 na sua App, você deve ativá-lo nas configurações de autenticação da sua App, localizadas na seção de configurações da App no portal do desenvolvedor.

​
Portal do desenvolvedor, Projetos e Apps de desenvolvedor

Para obter um conjunto de credenciais de autenticação que funcione com os endpoints da X API v2, você deve ter uma conta de desenvolvedor aprovada, configurar um Projeto nessa conta e criar um App de desenvolvedor nesse Projeto. Em seguida, você poderá encontrar suas chaves e tokens no seu App de desenvolvedor. 

​
Limites de requisições

Todos os dias, muitos milhares de desenvolvedores fazem requisições à X API. Para ajudar a gerenciar o grande volume dessas requisições, limites de requisições são aplicados a cada endpoint, restringindo a quantidade de requisições que você pode fazer em nome da sua App ou de um usuário autenticado. Os endpoints de consulta de Direct Messages têm limites de requisições no nível do usuário, o que significa que o usuário autenticado em cujo nome você está fazendo a requisição só pode realizar um certo número de requisições com a sua X App. Há um limite de taxa de 300 requisições por 15 minutos para os métodos GET. Esses limites de requisições são compartilhados entre os endpoints GET.  Esses endpoints utilizam paginação para que as respostas sejam retornadas rapidamente. Quando houver mais resultados do que o possível em uma única resposta (até 100 eventos), será necessário paginar. Use o parâmetro max_results para definir quantos resultados serão retornados por página e o parâmetro pagination_token para obter a próxima página de resultados. Saiba mais consultando nosso guia de paginação. Ferramentas úteis Confira algumas ferramentas úteis que recomendamos explorar ao trabalhar com os endpoints de consulta de Mensagens diretas:  Postman O Postman é uma excelente ferramenta para testar um endpoint. Cada solicitação do Postman inclui todos os parâmetros de caminho e de corpo para ajudar você a entender rapidamente o que está disponível. Para saber mais sobre nossas coleções no Postman, visite a página Usando o Postman.  Exemplos de código Há exemplos de código em Python para os endpoints de Mensagens diretas na v2 no nosso repositório X API v2 sample code GitHub. A pasta “Manage-Direct-Messages” contém exemplos para os métodos POST, e a pasta “Direct-Messages-lookup” contém exemplos para os métodos GET. XDev Software Development Kits (SDKs) Essas bibliotecas estão sendo atualizadas para os endpoints de Mensagens diretas na v2 e devem estar disponíveis em breve: Bibliotecas de terceiros Há um número crescente de bibliotecas de terceiros desenvolvidas por nossa comunidade. Essas bibliotecas foram projetadas para ajudar você a começar, e várias devem passar a oferecer suporte aos endpoints de Mensagens diretas na v2 em breve. Você pode encontrar uma biblioteca compatível com os endpoints v2 procurando a tag de versão adequada.
⌘I