Quickstart

This guide walks you through retrieving Direct Message events for the authenticated user. Reference for the X API v2 standard tier covering lookup.

This guide walks you through retrieving Direct Message events for the authenticated user.

Prerequisites

Before you begin, you’ll need:

• A developer account with an approved App
• User Access Token (OAuth 1.0a or OAuth 2.0 PKCE)

---

Get all DM events

Retrieve all DM events for the authenticated user:

cURL

shellscript

curl "https://api.x.com/2/dm_events?\
dm_event.fields=created_at,sender_id,text&\
max_results=100" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# Get all DM events with pagination
for page in client.dm_events.list(
    dm_event_fields=["created_at", "sender_id", "text"],
    max_results=100
):
    for event in page.data:
        print(f"{event.event_type}: {event.text}")

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

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

// Get all DM events with pagination
const paginator = client.dmEvents.list({
  dmEventFields: ["created_at", "sender_id", "text"],
  maxResults: 100,
});

for await (const page of paginator) {
  page.data?.forEach((event) => {
    console.log(`${event.event_type}: ${event.text}`);
  });
}

Response

{
  "data": [
    {
      "id": "1234567890",
      "event_type": "MessageCreate",
      "text": "Hello! How are you?",
      "sender_id": "9876543210",
      "created_at": "2024-01-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "result_count": 1,
    "next_token": "abc123"
  }
}

---

Get one-to-one conversation

Retrieve DM events from a specific one-to-one conversation:

cURL

shellscript

curl "https://api.x.com/2/dm_conversations/with/9876543210/dm_events?\
dm_event.fields=created_at,sender_id,text" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# Get DM events from a one-to-one conversation
for page in client.dm_events.get_by_participant(
    participant_id="9876543210",
    dm_event_fields=["created_at", "sender_id", "text"]
):
    for event in page.data:
        print(f"{event.created_at}: {event.text}")

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

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

// Get DM events from a one-to-one conversation
const paginator = client.dmEvents.getByParticipant("9876543210", {
  dmEventFields: ["created_at", "sender_id", "text"],
});

for await (const page of paginator) {
  page.data?.forEach((event) => {
    console.log(`${event.created_at}: ${event.text}`);
  });
}

Replace 9876543210 with the other participant’s user ID.

---

Get conversation by ID

Retrieve DM events from a specific conversation ID:

cURL

shellscript

curl "https://api.x.com/2/dm_conversations/1234567890-9876543210/dm_events?\
dm_event.fields=created_at,sender_id,text" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# Get DM events from a conversation by ID
for page in client.dm_events.get_by_conversation(
    dm_conversation_id="1234567890-9876543210",
    dm_event_fields=["created_at", "sender_id", "text"]
):
    for event in page.data:
        print(f"{event.created_at}: {event.text}")

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

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

// Get DM events from a conversation by ID
const paginator = client.dmEvents.getByConversation("1234567890-9876543210", {
  dmEventFields: ["created_at", "sender_id", "text"],
});

for await (const page of paginator) {
  page.data?.forEach((event) => {
    console.log(`${event.created_at}: ${event.text}`);
  });
}

---

Filter by event type

Get only specific event types:

cURL

shellscript

curl "https://api.x.com/2/dm_events?\
event_types=MessageCreate&\
dm_event.fields=created_at,sender_id,text" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# Get only MessageCreate events
for page in client.dm_events.list(
    event_types=["MessageCreate"],
    dm_event_fields=["created_at", "sender_id", "text"]
):
    for event in page.data:
        print(f"{event.text}")

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

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

// Get only MessageCreate events
const paginator = client.dmEvents.list({
  eventTypes: ["MessageCreate"],
  dmEventFields: ["created_at", "sender_id", "text"],
});

for await (const page of paginator) {
  page.data?.forEach((event) => {
    console.log(event.text);
  });
}

Event types

Type	Description
MessageCreate	A message was sent
ParticipantsJoin	User joined conversation
ParticipantsLeave	User left conversation

---

Include user data

Expand sender information:

cURL

shellscript

curl "https://api.x.com/2/dm_events?\
dm_event.fields=created_at,sender_id,text&\
expansions=sender_id&\
user.fields=username,profile_image_url" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# Get DM events with sender info
for page in client.dm_events.list(
    dm_event_fields=["created_at", "sender_id", "text"],
    expansions=["sender_id"],
    user_fields=["username", "profile_image_url"]
):
    for event in page.data:
        # Match sender from includes
        print(f"{event.sender_id}: {event.text}")

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

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

// Get DM events with sender info
const paginator = client.dmEvents.list({
  dmEventFields: ["created_at", "sender_id", "text"],
  expansions: ["sender_id"],
  userFields: ["username", "profile_image_url"],
});

for await (const page of paginator) {
  page.data?.forEach((event) => {
    console.log(`${event.sender_id}: ${event.text}`);
  });
  // Sender user objects are in page.includes.users
}

Response with expansion

{
  "data": [
    {
      "id": "1234567890",
      "event_type": "MessageCreate",
      "text": "Hello!",
      "sender_id": "9876543210"
    }
  ],
  "includes": {
    "users": [
      {
        "id": "9876543210",
        "username": "example_user",
        "profile_image_url": "https://..."
      }
    ]
  }
}

---

Common parameters

Parameter	Description
max_results	Events per page (1-100, default 100)
pagination_token	Token for next page
dm_event.fields	Event fields to return
event_types	Filter by event type
expansions	Related objects to include

---

Next steps

Send DMs

Send Direct Messages

Integration guide

Key concepts and best practices

API Reference

Full endpoint documentation