Integration Guide

Key concepts and best practices for integrating DM lookup endpoints

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

---

Authentication

DM endpoints require user authentication to access private conversations:

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.read	Reading DM events
tweet.read	Required with dm.read
users.read	Required with dm.read

---

Conversation types

One-to-one

Always has exactly two participants. Conversation ID format: {smaller_user_id}-{larger_user_id}

Group

Two or more participants. Membership can change over time.

---

Event types

Event	Description	Key fields
MessageCreate	A message was sent	text, sender_id
ParticipantsJoin	User joined group	participant_ids, sender_id
ParticipantsLeave	User left group	participant_ids

Example events

MessageCreate

{
  "id": "1582838499983564806",
  "event_type": "MessageCreate",
  "text": "Hi everyone.",
  "sender_id": "944480690",
  "dm_conversation_id": "1578398451921985538",
  "created_at": "2022-10-19T20:58:00.000Z"
}

ParticipantsJoin

{
  "id": "1582835469712138240",
  "event_type": "ParticipantsJoin",
  "participant_ids": ["944480690"],
  "sender_id": "17200003",
  "dm_conversation_id": "1578398451921985538",
  "created_at": "2022-10-19T20:45:58.000Z"
}

ParticipantsLeave

{
  "id": "1582838535115067392",
  "event_type": "ParticipantsLeave",
  "participant_ids": ["944480690"],
  "dm_conversation_id": "1578398451921985538",
  "created_at": "2022-10-19T20:58:09.000Z"
}

---

Fields and expansions

Default fields

Event type	Default fields
MessageCreate	id, event_type, text
ParticipantsJoin/Leave	id, event_type, participant_ids

Available fields

Field	Description	Events
dm_conversation_id	Conversation ID	All
created_at	Event timestamp	All
sender_id	Who sent/invited	MessageCreate, Join
attachments	Media attachments	MessageCreate
referenced_tweets	Shared Posts	MessageCreate

Available expansions

Expansion	Returns
sender_id	User object for sender
participant_ids	User objects for participants
attachments.media_keys	Media objects
referenced_tweets.id	Post objects

Example with expansions

cURL

shellscript

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

---

Pagination

DM events are returned in reverse chronological order (newest first):

cURL

shellscript

# First request
curl "https://api.x.com/2/dm_events?max_results=100" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

# Subsequent request with pagination token
curl "https://api.x.com/2/dm_events?max_results=100&pagination_token=NEXT_TOKEN" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

Events from up to 30 days ago are available.

---

ID compatibility with v1.1

Conversation and event IDs are shared between v1.1 and v2 endpoints. This means you can:

• Use v2 to retrieve events, then use v1.1 to delete specific messages
• Reference conversation IDs from x.com URLs in API requests

---

Next steps

Quickstart

Make your first DM lookup request

Send DMs

Send Direct Messages

API Reference

Full endpoint documentation

Sample code

Working code examples