Guia de início rápido

​

Introdução aos endpoints de gerenciamento de Mensagens Diretas

Este guia de introdução rápida ajudará você a fazer sua primeira solicitação aos endpoints de Mensagens Diretas usando o Postman, uma ferramenta para gerenciar e executar solicitações HTTP. Para saber mais sobre nossas coleções do Postman, visite o guia Usando o Postman.

Visite nosso repositório no GitHub X API v2 sample code se quiser consultar exemplos em Python. Além disso, os kits de desenvolvimento de software (SDKs) da X Developer Platform oficiais serão atualizados para oferecer suporte a esses endpoints de Mensagens Diretas.  

Pré-requisitos

Para concluir este guia, você precisará ter um conjunto de chaves e tokens para autenticar sua solicitação. Você pode gerar essas chaves e tokens seguindo estas etapas:

• Cadastre-se para uma conta de desenvolvedor e aguarde a aprovação.
• Crie um Projeto e um App de desenvolvedor associado no portal do desenvolvedor.
• Acesse a página “Keys and tokens” do seu App para gerar as credenciais necessárias. Certifique-se de salvar todas as credenciais em um local seguro.

​

Etapas para criar solicitações de consulta de Mensagens Diretas

Neste exemplo, em uma única solicitação, criaremos uma nova conversa em grupo e adicionaremos a primeira mensagem. Em seguida, adicionaremos uma segunda mensagem à conversa criada.

​

Etapa um: comece com uma ferramenta ou biblioteca

Para começar a trabalhar com os endpoints de gerenciamento de Mensagens diretas, usaremos a ferramenta Postman para simplificar o processo. Uma coleção de requisições de exemplo da X API v2, criada pela XDevelopers, será usada para explorar seis endpoints utilizados para criar novas Mensagens diretas e listar eventos de conversas de Mensagens diretas.

Embora a maior parte da coleção já esteja pré-preenchida, há alguns detalhes que você precisará fornecer com base na X App criada para hospedar essas requisições de API. Primeiro, vamos carregar/atualizar a coleção.

Para carregar a coleção da X API v2 no Postman no seu ambiente, clique no botão a seguir:

Adicionar X API v2 ao Postman

Depois de carregar a coleção da X API v2 no Postman, navegue até a pasta “Manage Direct Messages”. A guia Authorization dessa pasta foi pré-preenchida sempre que possível. Você precisará atualizar algumas configurações para inserir os detalhes de autenticação da sua X App.

Essa pasta também contém três endpoints para criar novas Mensagens diretas. Observe que há também uma pasta “Direct Message lookup” com três endpoints disponíveis para recuperar eventos de conversas de Mensagens diretas, incluindo o envio e o recebimento de mensagens e quando participantes da conversa entram e saem.

Como a criação de conversas em grupo é um recurso novo da X API v2, este exemplo se concentrará nisso. Trabalharemos com o exemplo “New group DM and conversation”. Usaremos essa requisição para criar uma conversa em grupo de Mensagens diretas.

A próxima etapa é autenticar no endpoint.

​

Etapa dois: autentique sua solicitação

Para fazer uma solicitação corretamente à X API, você precisa verificar se tem permissão para isso. Para realizar uma solicitação bem-sucedida a este endpoint, usaremos o Authorization Code Flow do OAuth 2.0 com PKCE. Você pode gerar um access token no Postman.

Com o Postman, você pode definir o método de autenticação no nível da pasta ou da solicitação. Aqui, vamos configurar os detalhes de autenticação no nível da pasta. Navegue até a pasta “Mange Direct Messages”, selecione a aba “Authorization” e confirme que o Type está definido como “OAuth 2.0” e que “Add auth data to” está definido como “Request Headers.” Na seção “Current Token”, certifique-se de que o “header Prefix” está definido como Bearer.

Para configurar e gerar um novo token:

1. Crie um Token Name, como “DM lookup.”

2. Confirme que o Grant Type está definido como Authorization Code (with PKCE).

3. Defina sua Callback URL. Ela deve corresponder exatamente à Callback URL associada ao seu aplicativo no v2 Dev Portal. Com a X App usada neste exemplo, a Callback URL está definida como - https://www.example.com. (Observe que, como deve corresponder exatamente, https://example.com não funcionaria.)

4. Confirme que a Auth URL está definida como https://x.com/i/oauth2/authorize

5. Confirme que a Access Token URL está definida como https://api.x.com/2/oauth2/token.Client ID - Copie e cole o OAuth 2.0 client ID do portal do desenvolvedor Client Secret - Você precisará disso apenas se estiver usando um tipo de App que seja um cliente confidencial. Se for o caso, copie e cole o OAuth 2.0 Client Secret do portal do desenvolvedor.

6. Confirme que o Scope está definido como dm.read dm.write tweet.read users.read.

7. Confirme que o State está definido como “state.”

8. Confirme que a Client Authentication está definida como Send as Basic Auth header.

9. Clique em “Get New Access Token” e depois em “Authorize app” como parte do processo “Sign-in with X”.

10. Clique no botão “Proceed” e depois em “Use Token” para gerar um token.

11. Clique no botão “Save” para salvar essas configurações.

Você pode receber uma mensagem informando que não está conectado ao X. Se ocorrer esse erro, será necessário fazer login, no Postman, na conta do X em nome da qual você está tentando publicar.

Agora que esses detalhes do OAuth 2.0 foram definidos no nível da pasta, navegue até cada um dos exemplos, acesse a aba “Authorization” e confirme que o Type está definido como “Inherit auth from parent.”

Observe que esse token expirará em breve, e você precisará regenerá-lo clicando no botão “Get New Access Token”. Ao clicar, será iniciado o processo “Sign-in with X” e gerado um novo token para fazer solicitações.

​

Etapa três: Recuperar eventos de conversas de Mensagens diretas

Ao recuperar eventos de conversas de Mensagens diretas com este endpoint, você precisa especificar um ID de conversa. O ID da conversa faz parte do caminho do endpoint: https://api.x.com/2/dm_conversations/:dm_conversation_id/dm_events

No Postman, vá até a aba “Params” e insira o ID da conversa para a qual você deseja recuperar eventos na seção “Path Variables”.

A configuração seria:

Key	Value
dm_conversation_id	1228393702244134912

Com essa conversa especificada, o caminho resultante passa a ser https://api.x.com/2/dm_conversations/1582103724607971328/dm_events

Ao clicar no botão “Send”, você receberá os fields padrão do objeto de Mensagens diretas na resposta: id, text e event_type. Também haverá um objeto “meta” com o número de resultados, juntamente com tokens de paginação usados para recuperar mais eventos, se disponíveis.

{
   "data": [
       {
           "event_type": "MessageCreate",
           "id": "1580705921830768647",
           "text": "olá para vocês dois, esta é uma nova conversa em grupo."
       }
   ],
   "meta": {
       "result_count": 1,
       "next_token": "18LAA5FFPEKJA52G0G00ZZZZ",
       "previous_token": "1BLC45FFPEKJA52G0S00ZZZZ"
   }
}

Se você quiser receber campos adicionais, será necessário especificá-los na sua solicitação com os parâmetros field e/ou expansion.

Para este exercício, solicitaremos conjuntos adicionais de fields do objeto dm_event:

1. Os campos padrão do objeto Direct Message: id, text e event_type.

2. Campos adicionais do objeto Direct Message: dm_conversation_id, created_at, sender_id, attachments, participant_ids, referenced_tweets

No Postman, navegue até a guia “Params” e adicione o seguinte par chave:valor na tabela “Query Params”:

Key	Value
dm_event.fields	dm_conversation_id,created_at,sender_id,attachments,participant_ids,referenced_tweets

Agora você deverá ver a seguinte URL ao lado do botão “Send”:

https://api.x.com/2/dm_conversations/:dm_conversation_id/dm_events?dm_event.fields=id,text,event_type,dm_conversation_id,created_at,sender_id,attachments,participant_ids,referenced_tweets

​

Etapa quatro: Faça sua solicitação e revise sua resposta

Depois que tudo estiver configurado, clique no botão “Send” novamente para receber uma resposta semelhante à mostrada abaixo. Observe que essa resposta inclui todos os fields disponíveis de dm_event.

{
   "data": [
       {
           "text": "olá para vocês dois, esta é uma nova conversa em grupo.",
           "id": "1580705921830768647",
           "dm_conversation_id": "1580705921830768643",
           "event_type": "MessageCreate",
           "sender_id": "17200003",
           "created_at": "2022-10-13T23:43:54.000Z"
       }
   ],
   "meta": {
       "result_count": 1,
       "next_token": "18LAA5FFPEKJA52G0G00ZZZZ",
       "previous_token": "1BLC45FFPEKJA52G0S00ZZZZ"
   }
}