Integration Guide

This guide covers the key concepts you need to integrate the manage Direct Messages endpoints into. Reference for the X API v2 standard tier covering manage.

This guide covers the key concepts you need to integrate the manage Direct Messages endpoints into your application.

---

Authentication

DM endpoints require user authentication:

Method	Description
OAuth 2.0 Authorization Code with PKCE	Recommended
OAuth 1.0a User Context	Legacy support

App-Only authentication is not supported. All Direct Messages are private.

Required scopes (OAuth 2.0)

Scope	Required for
dm.write	Sending and deleting messages
dm.read	Required with dm.write
tweet.read	Required with dm scopes
users.read	Required with dm scopes

---

Endpoints overview

Method	Endpoint	Description
POST	/2/dm_conversations/with/:participant_id/messages	Send one-to-one message
POST	/2/dm_conversations	Create group conversation
POST	/2/dm_conversations/:dm_conversation_id/messages	Add message to conversation
DELETE	/2/dm_events/:event_id	Delete a message

---

Sending messages

One-to-one message

Send a message to a specific user. Creates a new conversation if one doesn’t exist:

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!"}'

from xdk import Client

client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# Send a one-to-one DM
response = client.dm_conversations.create_message(
    participant_id="9876543210",
    text="Hello!"
)
print(response.data)

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

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

// Send a one-to-one DM
const response = await client.dmConversations.createMessage({
  participantId: "9876543210",
  text: "Hello!",
});
console.log(response.data);

Group conversation

Create a new group and send the 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 group!"}
  }'

from xdk import Client

client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

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

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

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

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

The conversation_type field must be set to "Group" (case sensitive).

Add to existing conversation

Send a message to any conversation you’re 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": "Another message"}'

from xdk import Client

client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# Add message to existing conversation
response = client.dm_conversations.add_message(
    dm_conversation_id="1582103724607971328",
    text="Another message"
)
print(response.data)

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

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

// Add message to existing conversation
const response = await client.dmConversations.addMessage({
  dmConversationId: "1582103724607971328",
  text: "Another message",
});
console.log(response.data);

---

Media attachments

Attach one piece of media (photo, video, or GIF) per message.

1. Upload media

   Use the Media Upload endpoint to upload your file and get a media_id.

2. Include in message

   {
     "text": "Check out this image!",
     "attachments": [{"media_id": "1583157113245011970"}]
   }
   

• The authenticated user must have uploaded the media
• Media is available for 24 hours after upload
• Only one attachment per message is supported

---

Sharing posts

Include a Post in your message by adding the Post URL to the text:

{
  "text": "Have you seen this? https://x.com/XDevelopers/status/1580559079470145536"
}

The response will include a referenced_tweets field with the Post ID.

---

Message requirements

Field	Required	Notes
text	Yes*	Required if no attachments
attachments	Yes*	Required if no text

*At least one of text or attachments must be provided.

---

ID compatibility with v1.1

Conversation and event IDs are shared between v1.1 and v2 endpoints. This enables hybrid workflows:

• Create messages with v2
• Delete messages with v1.1 (not yet available in v2)
• Reference conversation IDs from x.com URLs

---

Error handling

Status	Error	Solution
400	Invalid request	Check request body format
401	Unauthorized	Verify access token
403	Forbidden	Check scopes and user permissions
429	Too Many Requests	Wait and retry

Common issues

Cannot send to user

The recipient may have DM settings that prevent messages from unknown users, or may have blocked you.

Media attachment failed

Ensure the media was uploaded by the same authenticated user and is less than 24 hours old.

Group creation failed

Verify all participant IDs are valid and the users allow group DM invites.

---

Next steps

Quickstart

Send your first Direct Message

DM lookup

Retrieve DM conversations

Media upload

Upload media for attachments

API Reference

Full endpoint documentation