Quickstart

Este guia mostra como enviar Mensagens Diretas e criar conversas em grupo.

Pré-requisitosAntes de começar, você precisará de:

Uma conta de desenvolvedor com um App aprovado
User Access Token (OAuth 2.0 PKCE com escopos dm.write e dm.read)

Envie uma mensagem individual

Obtenha o user ID do destinatário

Você precisa do user ID da pessoa para quem deseja enviar a mensagem. Você pode obtê-lo no endpoint User lookup.

Envie a mensagem

cURL

curl -X POST "https://api.x.com/2/dm_conversations/with/9876543210/messages" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello! This is a message from the API."}'

from xdk import Client

client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# Send a one-to-one message
response = client.dm.send_message(
    participant_id="9876543210",
    text="Hello! This is a message from the API."
)

print(f"Message sent: {response.data.dm_event_id}")
print(f"Conversation: {response.data.dm_conversation_id}")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

// Send a one-to-one message
const response = await client.dm.sendMessage({
  participantId: "9876543210",
  text: "Hello! This is a message from the API.",
});

console.log(`Message sent: ${response.data?.dm_event_id}`);
console.log(`Conversation: ${response.data?.dm_conversation_id}`);

Analise a resposta

{
  "data": {
    "dm_conversation_id": "1234567890-9876543210",
    "dm_event_id": "1582103724607971332"
  }
}

Crie uma conversa em grupo

Defina os participantes

Reúna os user IDs de todas as pessoas que você deseja no grupo (excluindo você mesmo).

Crie o grupo com a primeira mensagem

cURL

curl -X POST "https://api.x.com/2/dm_conversations" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_type": "Group",
    "participant_ids": ["944480690", "906948460078698496"],
    "message": {"text": "Welcome to our new group!"}
  }'

from xdk import Client

client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# Create a group conversation
response = client.dm.create_conversation(
    conversation_type="Group",
    participant_ids=["944480690", "906948460078698496"],
    message={"text": "Welcome to our new group!"}
)

print(f"Group created: {response.data.dm_conversation_id}")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

// Create a group conversation
const response = await client.dm.createConversation({
  conversationType: "Group",
  participantIds: ["944480690", "906948460078698496"],
  message: { text: "Welcome to our new group!" },
});

console.log(`Group created: ${response.data?.dm_conversation_id}`);

Receba o ID da conversa

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

Salve o dm_conversation_id para adicionar mais mensagens depois.

Adicione uma mensagem a uma conversa existente

Envie uma mensagem para uma conversa da qual você já faz parte:

cURL

curl -X POST "https://api.x.com/2/dm_conversations/1582103724607971328/messages" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Adding another message to the conversation."}'

from xdk import Client

client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# Add message to existing conversation
response = client.dm.send_message_to_conversation(
    dm_conversation_id="1582103724607971328",
    text="Adding another message to the conversation."
)

print(f"Message sent: {response.data.dm_event_id}")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

// Add message to existing conversation
const response = await client.dm.sendMessageToConversation(
  "1582103724607971328",
  { text: "Adding another message to the conversation." }
);

console.log(`Message sent: ${response.data?.dm_event_id}`);

Envie uma mensagem com mídia

Faça upload da mídia

Primeiro, faça upload da sua mídia usando o endpoint de Media Upload.

Envie com anexo de mídia

cURL

curl -X POST "https://api.x.com/2/dm_conversations/with/9876543210/messages" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Check out this image!",
    "attachments": [{"media_id": "1234567890123456789"}]
  }'

from xdk import Client

client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# Send message with media
response = client.dm.send_message(
    participant_id="9876543210",
    text="Check out this image!",
    attachments=[{"media_id": "1234567890123456789"}]
)

print(f"Message with media sent: {response.data.dm_event_id}")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

// Send message with media
const response = await client.dm.sendMessage({
  participantId: "9876543210",
  text: "Check out this image!",
  attachments: [{ mediaId: "1234567890123456789" }],
});

console.log(`Message with media sent: ${response.data?.dm_event_id}`);

Exclua uma mensagem

Exclua uma mensagem que você enviou:

cURL

curl -X DELETE "https://api.x.com/2/dm_events/1582103724607971332" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# Delete a message
response = client.dm.delete_message("1582103724607971332")
print(f"Deleted: {response.data.deleted}")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

// Delete a message
const response = await client.dm.deleteMessage("1582103724607971332");
console.log(`Deleted: ${response.data?.deleted}`);

Resposta:

{
  "data": {
    "deleted": true
  }
}

Você só pode excluir mensagens que você enviou, não mensagens de outros participantes.

Escopos necessários

Ao usar OAuth 2.0 PKCE, seu access token deve ter estes escopos:

Escopo	Descrição
`dm.write`	Enviar e excluir mensagens
`dm.read`	Ler conversas (necessário com dm.write)
`tweet.read`	Necessário para algumas expansions
`users.read`	Necessário para expansions de usuário

Próximos passos

Consulta de DM

Recupere conversas de DM

Guia de integração

Conceitos-chave e boas práticas

Referência da API

Documentação completa do endpoint

Código de exemplo

Exemplos de código funcionais

Getting Started

Products

Fundamentals

Partners & Customers

Resources

Quickstart

Envie uma mensagem individual

Crie uma conversa em grupo

Adicione uma mensagem a uma conversa existente

Envie uma mensagem com mídia

Exclua uma mensagem

Escopos necessários

Próximos passos

Consulta de DM

Guia de integração

Referência da API

Código de exemplo

​Envie uma mensagem individual

​Crie uma conversa em grupo

​Adicione uma mensagem a uma conversa existente

​Envie uma mensagem com mídia

​Exclua uma mensagem

​Escopos necessários

​Próximos passos

Consulta de DM

Guia de integração

Referência da API

Código de exemplo

Envie uma mensagem individual

Crie uma conversa em grupo

Adicione uma mensagem a uma conversa existente

Envie uma mensagem com mídia

Exclua uma mensagem

Escopos necessários

Próximos passos