Quickstart

This guide walks you through sending Direct Messages and creating group conversations. Reference for the X API v2 standard tier covering manage.

This guide walks you through sending Direct Messages and creating group conversations.

Prerequisites

Before you begin, you’ll need:

• A developer account with an approved App
• User Access Token (OAuth 2.0 PKCE with dm.write and dm.read scopes)

---

Send a one-to-one message

1. Get the recipient's user ID

   You need the user ID of the person you want to message. You can get this from the User lookup endpoint.

2. Send the message

   cURL

   shellscript

   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}`);
   
3. Review the response

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

---

Create a group conversation

1. Define participants

   Gather the user IDs of everyone you want in the group (excluding yourself).

2. Create the group with first message

   cURL

   shellscript

   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}`);
   
3. Receive the conversation ID

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

   Save the dm_conversation_id to add more messages later.

---

Add a message to an existing conversation

Send a message to a conversation you’re already part of:

cURL

shellscript

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}`);

---

Send a message with media

1. Upload the media

   First, upload your media using the Media Upload endpoint.

2. Send with media attachment

   cURL

   shellscript

   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}`);
   

---

Delete a message

Delete a message you sent:

cURL

shellscript

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}`);

Response:

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

You can only delete messages you sent, not messages from other participants.

---

Required scopes

When using OAuth 2.0 PKCE, your access token must have these scopes:

Scope	Description
dm.write	Send and delete messages
dm.read	Read conversations (required with dm.write)
tweet.read	Required for some expansions
users.read	Required for user expansions

---

Next steps

DM lookup

Retrieve DM conversations

Integration guide

Key concepts and best practices

API Reference

Full endpoint documentation

Sample code

Working code examples