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 realizar 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 revisar exemplos em Python. Além disso, os software development kits (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:

• Inscreva-se para obter 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 gerenciar solicitações 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. Usaremos uma coleção de exemplos de solicitações da X API v2, criada pela XDev, para explorar seis endpoints usados para criar novas Mensagens diretas e listar eventos de conversas de Mensagens diretas.

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

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

Adicionar X API v2 ao Postman

Depois que você 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, e você pode atualizar algumas configurações para incluir 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 também há uma pasta “Direct Message lookup” com três endpoints disponíveis para recuperar eventos de conversas de Mensagens diretas, incluindo envio e recebimento de mensagens e quando participantes da conversa entram e saem.

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

A próxima etapa é autenticar com o 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 fazer uma solicitação bem-sucedida a este endpoint, usaremos o OAuth 2.0 Authorization Code Flow with 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 no nível da solicitação. Aqui, configuraremos os detalhes de autenticação no nível da pasta.

Navegue até a pasta “Manage Direct Messages”, selecione a guia “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” esteja definido como Bearer.  

Para configurar e gerar um novo token:

1. Crie um Token Name, como “Manage DMs”.

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

3. Defina sua Callback URL. Atualize sua Callback URL para 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 isso 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 Developer Portal Client Secret - Você só precisará disso se estiver usando um App type que seja um confidential client. Nesse caso, copie e cole o OAuth 2.0 Client Secret do Developer Portal. 

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

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

8. Confirme que o Client Authentication está definido como Send as Basic Auth header.

9. Clique em Get New Access Token e clique 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 esses detalhes de configuração.

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

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

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

​

Etapa três: Especifique os participantes da conversa de Mensagem Direta e o conteúdo da mensagem

Acesse a guia “Body” e atualize o objeto JSON de exemplo. Defina o atributo participant_ids para as contas para as quais você deseja enviar a Mensagem Direta.

{ "message": {"text": "Olá, só para vocês dois: esta é uma nova conversa em grupo."}, "participant_ids": ["944480690","906948460078698496"], "conversation_type": "Group" }

​

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

Quando tudo estiver configurado, clique no botão “Send” e você receberá uma resposta semelhante ao exemplo abaixo. Lembrete: se o seu token tiver expirado desde que você o criou acima, você pode voltar à guia Authorization da pasta e clicar em “Get New Access Token” para gerar um novo token.

{
   "data": {
       "dm_conversation_id": "1582103724607971328",
       "dm_event_id": "1582103724607971332"
   }
}

Se o objeto “data” da resposta retornada contiver um dm_conversation_id e um dm_event_id, você criou com sucesso uma nova conversa de Mensagem Direta. Para começar a consultar eventos associados a essa conversa, acesse o guia Introdução rápida de busca de Mensagens Diretas.

​

Etapa cinco: Adicionar outra mensagem a essa conversa em grupo

Agora selecione o exemplo “Add DM to conversation” e, em seguida, a guia “Params”. Em “Path Variables”, atualize o dm_conversation_id para o ID da conversa que você criou acima.

Key	Value
dm_conversation_id	1582103724607971328

Usando esse ID de conversa, o caminho da requisição será: https://api.x.com/2/dm_conversations/1582103724607971328/messages

Além disso, atualize a guia “Body” com o JSON da requisição contendo o texto da mensagem que você deseja enviar:

{
   "text": "Adicionando uma nova mensagem à nossa conversa em grupo..."
}

Depois que tudo estiver configurado, clique no botão “Send” e você receberá uma resposta semelhante ao exemplo a seguir:

{
   "data": {
       "dm_conversation_id": "1582103724607971328",
       "dm_event_id": "1582106224379559940"
   }
}