Skip to main content

​
Overview

The DirectMessagesClient provides methods to create and manage direct message conversations, send messages, and retrieve message events from the X API.

​
Initialization

Access the DirectMessagesClient through the main XDK client: 
from xdk import Client

client = Client(
    bearer_token="YOUR_BEARER_TOKEN",
    access_token="YOUR_ACCESS_TOKEN"
)

dm_client = client.direct_messages

​
Methods

​
create_conversation

Initiates a new direct message conversation with specified participants. 
def create_conversation(
    body: Optional[CreateConversationRequest] = None
) -> Dict[str, Any]
​
body
CreateConversationRequest
Request body containing conversation details
Returns: CreateConversationResponse - The created conversation data Example: 
from xdk.direct_messages.models import CreateConversationRequest

response = client.direct_messages.create_conversation(
    body=CreateConversationRequest(
        conversation_type="Group",
        participant_ids=["user_id_1", "user_id_2"]
    )
)

print(f"Conversation ID: {response.data.dm_conversation_id}")

​
create_by_conversation_id

Sends a new direct message to a specific conversation by its ID. 
def create_by_conversation_id(
    dm_conversation_id: str,
    body: Optional[CreateByConversationIdRequest] = None
) -> Dict[str, Any]
​
dm_conversation_id
str
required
The DM Conversation ID to send the message to
​
body
CreateByConversationIdRequest
Request body containing message content and attachments
Returns: CreateByConversationIdResponse - The created message data Example: 
from xdk.direct_messages.models import CreateByConversationIdRequest

response = client.direct_messages.create_by_conversation_id(
    dm_conversation_id="123456789",
    body=CreateByConversationIdRequest(
        text="Hello from XDK!",
        attachments=[{"media_id": "media_123"}]
    )
)

print(f"Message ID: {response.data.dm_event_id}")

​
get_events

Retrieves a list of recent direct message events across all conversations. This method automatically handles pagination. 
def get_events(
    max_results: int = None,
    pagination_token: Any = None,
    event_types: List = None,
    dm_event_fields: List = None,
    expansions: List = None,
    media_fields: List = None,
    user_fields: List = None,
    tweet_fields: List = None
) -> Iterator[GetEventsResponse]
​
max_results
int
The maximum number of results per page
​
pagination_token
str
Token to get a specific page of results
​
event_types
List[str]
The set of event types to include in the results (e.g., [‘MessageCreate’, ‘ParticipantsJoin’])
​
dm_event_fields
List[str]
DM event fields to display (e.g., [‘id’, ‘text’, ‘event_type’, ‘created_at’])
​
expansions
List[str]
Fields to expand (e.g., [‘attachments.media_keys’, ‘referenced_tweets.id’])
Returns: Iterator[GetEventsResponse] - Yields pages of DM events Example: 
# Get all DM events with pagination
for page in client.direct_messages.get_events(
    max_results=50,
    dm_event_fields=['id', 'text', 'event_type', 'created_at'],
    expansions=['sender_id', 'attachments.media_keys']
):
    for event in page.data:
        print(f"{event.event_type}: {event.text}")

# Get just the first page
first_page = next(client.direct_messages.get_events(max_results=10))
print(f"Total events: {len(first_page.data)}")

​
get_events_by_conversation_id

Retrieves direct message events for a specific conversation. This method automatically handles pagination. 
def get_events_by_conversation_id(
    id: Any,
    max_results: int = None,
    pagination_token: Any = None,
    event_types: List = None,
    dm_event_fields: List = None,
    expansions: List = None,
    media_fields: List = None,
    user_fields: List = None,
    tweet_fields: List = None
) -> Iterator[GetEventsByConversationIdResponse]
​
id
str
required
The DM conversation ID
​
max_results
int
The maximum number of results per page
​
dm_event_fields
List[str]
DM event fields to display
Returns: Iterator[GetEventsByConversationIdResponse] - Yields pages of conversation events Example: 
conversation_id = "123456789"

# Retrieve all messages in a conversation
for page in client.direct_messages.get_events_by_conversation_id(
    id=conversation_id,
    max_results=100,
    dm_event_fields=['id', 'text', 'created_at', 'sender_id']
):
    for message in page.data:
        print(f"[{message.created_at}] {message.sender_id}: {message.text}")

​
get_events_by_participant_id

Retrieves direct message events for a one-to-one conversation with a specific participant. 
def get_events_by_participant_id(
    participant_id: Any,
    max_results: int = None,
    pagination_token: Any = None,
    event_types: List = None,
    dm_event_fields: List = None,
    expansions: List = None,
    media_fields: List = None,
    user_fields: List = None,
    tweet_fields: List = None
) -> Iterator[GetEventsByParticipantIdResponse]
​
participant_id
str
required
The ID of the participant user for the one-to-one DM conversation
​
max_results
int
The maximum number of results per page
Returns: Iterator[GetEventsByParticipantIdResponse] - Yields pages of conversation events Example: 
# Get DM history with a specific user
for page in client.direct_messages.get_events_by_participant_id(
    participant_id="user_123",
    max_results=50,
    dm_event_fields=['id', 'text', 'created_at']
):
    for message in page.data:
        print(f"{message.text}")

​
Authentication

All DirectMessagesClient methods require user context authentication:
  • OAuth 2.0 User Token (recommended for user operations)
  • OAuth 1.0a User Token

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us