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 conversas individuais (um a um) de conversas em grupo. Conversas individuais sempre têm dois, e apenas dois, participantes, enquanto conversas em grupo podem ter dois ou mais participantes e membros que podem mudar.    Esta página reúne informações sobre várias ferramentas e conceitos essenciais que você deve conhecer ao integrar os endpoints de Gerenciar Mensagens diretas ao seu sistema. Dividimos a página em duas seções: Conceitos essenciais

​
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 fundamentais necessários para criar Mensagens diretas e recuperar eventos associados a 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 gerenciamento de Mensagens diretas fornecem três métodos POST para criar novas mensagens e adicioná-las às conversas:
  • POST /2/dm_conversations/with/:participant_id/messages - Cria uma Mensagem direta individual (um para um). Esse método adiciona a mensagem a uma conversa individual existente ou cria uma nova. O parâmetro de caminho :participant_id é o User ID da conta que está recebendo a mensagem.  Aqui está um exemplo de corpo de requisição JSON para enviar uma Mensagem direta individual:
{
   "text": "Olá, só para você. Isso aparecerá como uma nova conversa se nunca conversamos antes, ou será adicionado à nossa conversa existente. "
}
  • POST /2/dm_conversations - Cria uma nova conversa em grupo e adiciona uma Mensagem Direta a ela. Essas requisições exigem uma lista de participantes da conversa. Observe que é possível criar várias conversas com a mesma lista de participantes. Essas requisições sempre retornarão um novo id de conversa. Abaixo está um exemplo de corpo de requisição JSON para criar uma nova conversa em grupo e adicionar uma Mensagem Direta. Observe que isso requer o campo “conversation_type”, que deve ser definido como “Group” (com diferenciação de maiúsculas e minúsculas).
{
   "message": {"text": "Olá para vocês dois, esta é uma nova conversa em grupo."},
   "participant_ids": ["944480690","906948460078698496"],
   "conversation_type": "Group"
}
  • POST /2/dm_conversations/:dm_conversation_id/messages - Cria uma mensagem direta e a adiciona a uma conversa existente. O parâmetro de caminho :dm_conversation_id é o id da conversa à qual a mensagem será adicionada. Este método pode ser usado para adicionar uma mensagem tanto em conversas individuais quanto em conversas em grupo. A seguir, um exemplo de corpo de requisição JSON para enviar uma mensagem direta tanto para conversas individuais quanto para conversas em grupo:
{
   "text": "Aqui está uma nova mensagem."
}
Esses métodos POST permitem anexar uma única mídia. Os corpos das requisições POST devem incluir um ou ambos os fields “text” e “attachments”. O atributo “text” é obrigatório se o field “attachments” não for incluído, e o field “attachments” é obrigatório se o field “text” não for incluído. Consulte a próxima seção para mais informações. Para mais informações, consulte as referências da API de Mensagens diretas.

​
IDs de conversa e de 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 X Platform. Isso significa que ambas as versões podem ser usadas em conjunto. Por exemplo, os endpoints de Mensagens diretas v1.1 fornecem métodos para retornar um único evento e para excluir eventos. Esses métodos ainda não estão disponíveis em v2. Como os IDs são comuns entre v1.1 e v2, você pode fazer solicitações v1.1 com base em IDs fornecidos por v2 ou referenciar IDs de conversa exibidos nas URLs de conversa no aplicativo X.  

​
Inclusão de anexos de mídia e referência a Posts

Os endpoints de Manage Direct Message permitem anexar um único item de mídia (foto, vídeo ou GIF). Anexar mídia requer um media id gerado pelo endpoint v1.1 Upload media. O usuário autenticado que enviar a Direct Message também deve ter feito o upload da mídia. Depois de enviada, a mídia fica disponível por 24 horas para inclusão na mensagem. Para ilustrar como incluir mídia, segue um exemplo de corpo de requisição JSON: 
{
 "text": "Aqui está uma foto...",
 "attachments": [{"media_id": "1583157113245011970}]
}
O evento MessageCreate resultante incluirá as seguintes informações de metadata: 
{
    "attachments": {
        "media_keys": [
            "5_1583157113245011970"
        ]
    }
}
Posts também podem ser adicionados incluindo a URL do Post no texto da mensagem. Para ilustrar como incluir Posts em mensagens, segue um exemplo de corpo de requisição JSON: 
{
 "text": "Aqui está o Tweet sobre o qual eu estava falando: https://x.com/SnowBotDev/status/1580559079470145536"
}
O evento MessageCreate resultante incluirá as seguintes metadata: 
{
    "referenced_tweets": [
        {
            "id": "1580559079470145536"
        }
    ]
}

​
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 com êxito. 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. 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 sobre fluxos de autorização em vários dispositivos. OAuth 2.0 permite escolher escopos granulares específicos, que concedem permissões específicas em nome de um usuário. Os endpoints de consulta de Mensagens diretas exigem estes escopos: dm.write, dm.read, tweet.read, user.read. Para habilitar OAuth 2.0 na sua App, ative-o 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 dentro desse Projeto. Em seguida, você pode 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, são aplicados limites em cada endpoint, restringindo o número de requisições que você pode fazer em nome da sua App ou de um usuário autenticado. Os endpoints de Manage Direct Message têm limites tanto por usuário quanto no nível da X App. Isso significa que o usuário autenticado em cujo nome você está fazendo a requisição só pode enviar um certo número de mensagens com sua X App. Além disso, há um limite diário de quantas Mensagens diretas podem ser enviadas pela sua X App. Há um limite de 200 requisições/mensagens por 15 minutos para os métodos POST. Os usuários também estão limitados a 1000 Mensagens diretas por 24 horas. Além disso, as X Apps têm um limite de 15000 mensagens por 24 horas. Esses limites são compartilhados entre os endpoints POST. Ferramentas úteis Aqui estão algumas ferramentas úteis que incentivamos você a explorar enquanto trabalha com os endpoints de consulta de Direct Messages: Postman Postman é uma ótima ferramenta que você pode usar para testar um endpoint. Cada requisição do Postman inclui todos os parâmetros de path e body para ajudar você a entender rapidamente o que está disponível. Para saber mais sobre nossas coleções do Postman, visite nossa página Using Postman. Exemplos de código Exemplos de código em Python para os endpoints de v2 Direct Messages estão disponíveis em 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 v2 Direct Messages e deverão estar prontas 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 espera-se que várias passem a oferecer suporte aos endpoints de v2 Direct Messages em breve. Você pode encontrar uma biblioteca que funcione com os endpoints de v2 procurando pela tag de versão apropriada.
⌘I