Quickstart

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

PrerequisitesBefore 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

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.

Send the message

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

Review the response

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

Create a group conversation

Define participants

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

Create the group with first message

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

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

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

Upload the media

First, upload your media using the Media Upload endpoint.

Send with media attachment

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

Delete a message

Delete a message you sent:

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

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

Overview

Posts

Articles

Users

Direct Messages

Likes

Lists

Spaces

Communities

Community Notes

Trends

News

Media

X Activity

Usage

Stream Connections

Compliance

Webhooks

Quickstart

Send a one-to-one message

Create a group conversation

Add a message to an existing conversation

Send a message with media

Delete a message

Required scopes

Next steps

DM lookup

Integration guide

API Reference

Sample code

​Send a one-to-one message

​Create a group conversation

​Add a message to an existing conversation

​Send a message with media

​Delete a message

​Required scopes

​Next steps

DM lookup

Integration guide

API Reference

Sample code

Send a one-to-one message

Create a group conversation

Add a message to an existing conversation

Send a message with media

Delete a message

Required scopes

Next steps