Skip to content

quickstart.mdx

Latest commit

 

History

History
340 lines (249 loc) · 8.17 KB

quickstart.mdx

File metadata and controls

340 lines (249 loc) · 8.17 KB
Raw
title Quickstart
sidebarTitle Quickstart
description This guide walks you through sending Direct Messages and creating group conversations. Before you begin. Enterprise X API v2 tier.
keywords
manage direct messages quickstart
send DM quickstart
DM management quickstart
create group DM

import { Button } from '/snippets/button.mdx';

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

You need the user ID of the person you want to message. You can get this from the [User lookup endpoint](/x-api/users/lookup/introduction). 
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}`);
```json { "data": { "dm_conversation_id": "1234567890-9876543210", "dm_event_id": "1582103724607971332" } } ```

Create a group conversation

Gather the user IDs of everyone you want in the group (excluding yourself). 
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}`);
```json { "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 -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

First, upload your media using the [Media Upload endpoint](/x-api/media/quickstart/media-upload-chunked). 
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 -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

Retrieve DM conversations Key concepts and best practices Full endpoint documentation Working code examples