Direct Messages lookup

​

Introduction

This initial release of Direct Messages lookup includes three GET methods:

• GET /2/dm_conversations/with/:participant_id/dm_events - Retrieves Direct Message events associated with a one-to-one conversation. The :participant_id path parameter is the User ID of the account having the conversation with the authenticated user making this request. 
• GET /2/dm_conversations/:dm_conversation_id/dm_events - Retrieves Direct Message events associated with a specific conversation ID, as indicated by the :dm_conversation_id path parameter. 
• GET /2/dm_events - Retrieves Direct Message events associated with a user, including both one-to-one and group conversations. Events from up to 30 days ago are available.  

Note that Direct Message event IDs are common across the v1.1 and v2 (as well as the X App), so the v1.1 method to list a single event can be used along with these new v2 endpoints. Also note that the Enterprise and Premium Account Activity APIs support v2 one-to-one messages, but do not yet support group conversations.   

With this release, three event types are supported, and these endpoints support query parameters to filter on them:

• MessageCreate - A message has been created. 
• ParticipantsJoin - A new participant has joined a conversation. 
• ParticipantsLeave - A participant has left a conversation. 

There is a user rate limit of 300 requests per 15 minutes for the GET methods. This rate limit is shared across these GET endpoints.

Since you are making requests on behalf of a user with Direct Message v2 endpoints, you must authenticate with either OAuth 1.0a User Context or OAuth 2.0 Authorization Code with PKCE, using Access Tokens associated with users that have authorized your X App. To generate these Access Tokens with OAuth 1.0a, you can use the 3-legged OAuth flow. To generate user Access Tokens with OAuth 2.0, you can use the Authorization Code with PKCE grant flow.

Account setup

To access these endpoints, you will need:

• An approved developer account.
• To authenticate using the keys and tokens from a developer App that is located within a Project. 

Learn more about getting access to the X API v2 endpoints in our getting started guide.

​

Getting started with the manage Direct Message endpoints

This quick start guide will help you make your first request to the Direct Message endpoints using Postman, a tool for managing and making HTTP requests. To learn more about our Postman collections, please visit our Using Postman guide.

Please visit our X API v2 sample code GitHub repository if you want to review Python-based examples. In addition, the official X Developer Platform software development kits (SDKs) will be updated to support these Direct Message endpoints.  

​

Steps to building Direct Message lookup requests

In this example, in one request, we’ll create a new group conversation and add our first message to it. We’ll then add a second message to the created conversation.

​

Step one: Start with a tool or library

To begin working with the manage Direct Message endpoints we are going to use the Postman tool to simplify the process. A XDevelopers-authored collection of example X API v2 requests will be used to explore six endpoints used to create new Direct Messages and to list Direct Message conversation events.

While most of the collection is pre-filled, there are a few details that you’ll need to provide that are based on the X App created to host these API requests. First, let’s get the collection loaded/updated.

To load X API v2 Postman collection into your environment, please click on the following button:

Once you have the X API v2 collection loaded in Postman, navigate to the “Manage Direct Messages” folder. This folder’s Authorization tab has been pre-filled where possible. You will need to update a few settings to share your X App’s authentication details.

This folder also contains three endpoints for creating new Direct Messages. Note that there is also a “Direct Message lookup” folder with three available endpoints for retrieving Direct Message conversation events, including sending and receiving messages, and when conversation participants join and leave.

Since creating group conversations is a new feature of the X API v2, this example will focus on that. We will be working with the “New group DM and conversation” example. We will use this request to create a Direct Message group conversation.

The next step is to authenticate with the endpoint.

​

Step two: Authenticate your request

To properly make a request to the X API, you need to verify that you have permission to do so. To make a successful request to this endpoint, we will be using OAuth 2.0 Authorization Code Flow with PKCE. You can generate an access token within Postman. 

With Postman you can set the authentication method at the folder level or at the request level. Here we will be configuring the authentication details at the folder level. Navigate to the “Mange Direct Messages” folder, select the “Authorization” tab and confirm that the Type to set to “OAuth 2.0”, and “Add auth data to” is set to “Request Headers.” In the “Current Token” section, make sure the “header Prefix” is set to Bearer.  

To configure and generate a new token:

1. Create a Token Name, such as “DM lookup.”

2. Confirm that Grant Type is set to Authorization Code (with PKCE).

3. Set your Callback URL. You will want to update your Callback URL to exactly match the Callback URL associated with your application in the v2 Dev Portal. With the X App used with this example, the Callback URL is set to - https://www.example.com. (Note that since this must match exactly, https://example.com would not work.) 

4. Confirm that Auth URL is set to https://twitter.com/i/oauth2/authorize

5. Confirm that Access Token URL is set to https://api.x.com/2/oauth2/token.Client ID - Copy and paste OAuth 2.0 client ID from the Developer Portal Client Secret - You will need this only if you are using an App type that is a confidential client. If so, copy and paste the OAuth 2.0 Client Secret from the Developer Portal. 

6. Confirm that Scope is set to dm.read dm.write tweet.read users.read.

7. Confirm that State is set to “state.”

8. Confirm that Client Authentication is set to Send as Basic Auth header.

9. Click where it says “Get New Access Token”, click “Authorize app” as part of the “Sign-in with X” process.

10. Click the “Proceed” button and then the “Use Token” to generate a token. 

11. Click on the “Save” button to save these configuration details.

You may get a message that you are not logged into X. If you get this error, you will need to log in to the X account that you are trying to post on behalf of inside of Postman.

Now that these OAuth 2.0 details have been set at the folder level, navigate to each of the examples and their “Authorization” tab and confirm that they have their Type set to “Inherit auth from parent.” 

Note that this token will expire soon, and you’ll need to regenerate it by clicking on the “Get New Access Token” button. Clicking that will trigger the “Sign-in with X” process and generate a fresh token to make requests with.

​

Step three: Retrieve Direct Messages conversation events

When retrieving Direct Message conversation events with this endpoint, you need to specify a conversation ID. The conversation ID is part of the endpoint path: https://api.x.com/2/dm\_conversations/:dm\_conversation\_id/dm\_events

In Postman, navigate to the “Params” tab and enter the ID of the conversation you want to retrieve events for in the “Path Variables” section.

The setting would be:

With this conversation specified, the resulting path becomes https://api.x.com/2/dm\_conversations/1582103724607971328/dm\_events

If you click the “Send” button you will receive the default Direct Message object fields in your response: id,  text, and event_type. There will also be a “meta” object with the number of results, along with pagination tokens used for retrieving more events if available.

{
   "data": [
       {
           "event_type": "MessageCreate",
           "id": "1580705921830768647",
           "text": "hello to you two, this is a new group conversation."
       }
   ],
   "meta": {
       "result_count": 1,
       "next_token": "18LAA5FFPEKJA52G0G00ZZZZ",
       "previous_token": "1BLC45FFPEKJA52G0S00ZZZZ"
   }
}

If you would like to receive additional fields, you will have to specify those fields in your request with the field and/or expansion parameters.

For this exercise, we will request additional sets of fields of the dm_event object:

1. The default Direct Message object fields, id, text, and event_type.

2. Additional Direct Message object fields: dm_conversation_id, created_at, sender_id, attachments, participant_ids, referenced_tweets

In Postman, navigate to the “Params” tab and add the following key:value pair to the “Query Params” table:

You should now see the following URL next to the “Send” button:

https://api.x.com/2/dm\_conversations/:dm\_conversation\_id/dm\_events?dm\_event.fields=id,text,event\_type,dm\_conversation\_id,created\_at,sender\_id,attachments,participant\_ids,referenced\_tweets

​

Step four: Make your request and review your response

Once you have everything set up, hit the “Send” button again, and you will receive a response similar to the below response. Note that this response includes all the available dm_event fields.

{
   "data": [
       {
           "text": "hello to you two, this is a new group conversation.",
           "id": "1580705921830768647",
           "dm_conversation_id": "1580705921830768643",
           "event_type": "MessageCreate",
           "sender_id": "17200003",
           "created_at": "2022-10-13T23:43:54.000Z"
       }
   ],
   "meta": {
       "result_count": 1,
       "next_token": "18LAA5FFPEKJA52G0G00ZZZZ",
       "previous_token": "1BLC45FFPEKJA52G0S00ZZZZ"
   }
}

​

Integration guide

The Direct Messages endpoints v2 introduce conversations and conversation events as core X API objects, and make a distinction between 1-1 and group conversations. 1-1 conversations always have two, and only two, participants, while group conversations can have two or more and memberships that can change.   

This page contains information on several tools and key concepts that you should be aware of as you integrate the Direct Messages lookup endpoints into your system. We’ve broken the page into two sections:

• Key Concepts
  • Direct Message conversations
  • Shared conversation and event IDs across v1.1 and v2
  • Direct Message event fields and expansions
  • Conversation event types
  • Authentication
  • Developer portal, Projects, and Apps
  • Rate limits
  • Pagination
• Helpful tools

​

Key Concepts

​

Direct Message conversations

All Direct Messages are part of a Direct Message conversation. These conversations can be one-to-one conversations or group conversations. This launch provides the foundational endpoints needed to create Direct Messages and retrieve events associated with Direct Message conversations. All conversations have a unique dm_conversation_id, and the events that make up that conversation all have a unique dm_event_id.  

The Direct Message lookup endpoints provide methods for retrieving events associated with conversations. These GET endpoints are used to retrieve the messages that make up a conversation, and for group conversations, can be used to understand who has joined and left group conversations.

This initial release of Direct Messages lookup includes three GET methods:

• GET /2/dm_conversations/with/:participant_id/dm_events - Retrieves Direct Message events associated with a one-to-one conversation. The :participant_id path parameter is the numeric User ID of the account having the conversation with the authenticated user making this request.  

• GET /2/dm_conversations/:dm_conversation_id/dm_events - Retrieves Direct Message events associated with a specific conversation ID, as indicated by the :dm_conversation_id path parameter. Both one-to-one and group conversations IDs are supported.  

• GET /2/dm_events - Retrieves Direct Message events associated with the authenticating user, including both one-to-one and group conversations. Events from up to 30 days ago are available.  

These GET endpoints all support retrieving dm_events by event type with an event_types request query parameters. Currently, there are three conversation event types supported:

• MessageCreate - Created when a new Direct Message is created. This event object can include the time and text of the message, along with the account ID of who sent the message, and the conversation and event IDs. 

• ParticipantsJoin - Created when a new participant joins a group conversation. This dm_event object includes the ID of the participant joining, along with the created_at time and the sender_id of the ‘invite’ event. 

• ParticipantsLeave - Created when a participant leaves a conversation.This event object includes the ID of the participant leaving, along with the time of the event. 

For more information see the Direct Messages lookup API References.

​

Shared conversation and event IDs across v1.1 and v2

An important concept is that conversation and event IDs are shared across v1.1 and v2 versions of the X Platform. This means both versions can be used together. For example, the Direct Messages v1.1 endpoints provide methods for returning a single event and for deleting events, methods not yet available with v2. Since IDs are common across v1.1 and v2, you can make v1.1 requests based on IDs provided by v2, or by referencing conversation IDs displayed in conversation URLs on the X application.  

​

Direct Message event fields and expansions

The X API v2 allows users to select exactly which data they want to return from the API using a set of tools called fields and expansions. For example, Direct Message lookup endpoints support the following dm_events fields: 

• id, event_type, and text are the defaults for MessageCreate events. 

• id, event_type, and participant_ids are the defaults for ParticipantsJoin and ParticipantsLeave events.

• dm_conversation_id and created_at are available for all events.

• attachments and referenced_tweets are available for MessageCreate events. 

• sender_id is available for MessageCreate and ParticipantsJoin events. 

• participant_ids is available for ParticipantsJoin and ParticipantsLeave events. 

In addition, the Direct Message lookup endpoints support the following expansions:

• sender_id - Expands the User object associated with who sent the message or who invited someone to the conversation. 

• referenced_tweets.id - Expands the Post object if the Direct Message text includes a link to a Post. 

• attachments.media_keys - Expands the Media object if the Direct Message includes a media attachment. 

• participant_ids - Expands the User object associated with who joined or left a group conversation.

Since expansion include Posts, Users, and Media objects, you can also use the tweet.fields, user.fields, and media.fields request query parameters. See our guide on how to use fields and expansions for more information.

​

Conversation event types

Below are example JSON objects for Direct Message the MessageCreate, ParticipantsJoin, and ParticipantsLeave event types. 

Available dm_event object fields: id, text, event_type, dm_conversation_id, created_at, sender_id, attachments, referenced_tweets, participant_ids. See the the Fields and Expansion section for more details on selecting these fields in your requests. 

Example MessageCreate event: 

With all the dm_event fields specified, here is the response for a simple text Direct Message: 

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

Example ParticipantsJoin event:

With all the dm_event fields specified, here is the response for a participant joining a conversation:

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

Example ParticipantsLeave event:

With all the dm_event fields specified, here is the response for a participant leaving a conversation:

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

​

Authentication

All X API v2 endpoints require for you to authenticate your requests with a set of credentials, also known as keys and tokens. All Direct Messages are private and require user authorization to access them. 

These Direct Message endpoints require the use of OAuth 2.0 Authorization Flow with PKCE or 1.0a User Context, which means that you must use a set of API keys and user Access Tokens to make a successful request. The Access Tokens must be associated with the user that you are requesting on behalf of. If you want to generate a set of Access Tokens for another user, they must authorize or authenticate your App using the 3-legged OAuth flow.

Please note that OAuth user-context can be tricky to use. If you are not familiar with this authentication method, we recommend using a library or a tool like Postman to properly authenticate your requests. 

OAuth 2.0 Authorization Code with PKCE allows for greater control over an application’s scope, and authorization flows across multiple devices. OAuth 2.0 allows you to pick specific fine-grained scopes which give you specific permissions on behalf of a user. The Direct Messages lookup endpoints require these scopes:  dm.read, post.read, user.read

To enable OAuth 2.0 in your App, you must enable it in your’s App’s authentication settings found in the App settings section of the developer portal.

​

Developer portal, Projects, and developer Apps

To retrieve a set of authentication credentials that will work with the X API v2 endpoints, you must have an approved developer account, set up a Project within that account, and create a developer App within that Project. You can then find your keys and tokens within your developer App. 

​

Rate limits

Everyday many thousands of developers make requests to the X API. To help manage the sheer volume of these requests, rate limits are placed on each endpoint that limits the number of requests that you can make on behalf of your app or on behalf of an authenticated user. 

The Direct Message lookup endpoints are rate limited at the user-level, meaning that the authenticated user that you are making the request on behalf of can only make a certain number of requests with your X App. There is a user rate limit of 300 requests per 15 minutes for the GET methods. These rate limits are shared across the GET endpoints. 

​

Pagination

These endpoints utilize pagination so that responses are returned quickly. In cases where there are more results than what can be sent in a single response (up to 100 events) you will need to paginate. Use the max_results parameter to identify how many results will return per page, and the pagination_token parameter to return the next page of results. You can learn more by reviewing our pagination guide.

Helpful tools

Here are some helpful tools we encourage you to explore as you work with the Direct Messages lookup endpoints: 

Postman

Postman is a great tool that you can use to test out an endpoint. Each Postman request includes every path and body parameter to help you quickly understand what is available to you. To learn more about our Postman collections, please visit our Using Postman page. 

Code samples

Python sample code for the v2 Direct Messages endpoints is available in our X API v2 sample code GitHub repository. The “Manage-Direct-Messages” folder contains examples for the POST methods, and the “Direct-Messages-lookup” folder contains examples for the GET methods.

XDev Software Development Kits (SDKs)

These libraries are being updated for the v2 Direct Messages endpoints and should be ready soon:

• X API Java SDK - Official Java SDK for the X API v2
• X API TypeScript/JavaScript SDK - Official TS/JS SDK for the X API v2

Third-party libraries

There is a growing number of third-party libraries developed by our community. These libraries are designed to help you get started, and several are expected to support v2 Direct Messages endpoints soon. You can find a library that works with the v2 endpoints by looking for the proper version tag.

​

Comparing v1.1 and v2 Direct Message event lookup endpoints

Both v1.1 and v2 versions of the Direct Messages endpoints provide methods for looking up Direct Message events. This guide is intended to help understand the differences and provide information for migrating to v2. 

A major difference between the two versions is that v1.1 supports only one-to-one conversations, while v2 introduces support for group conversations. One artifact of this is that v1.1 supports only “message created” events, while v2 also supports events associated with participants joining and leaving conversations. In fact, a fundamental v2 update is establishing dm_conversations as a core API object.   

With v1.1. there are two endpoints for retrieving Direct Messages (again, new messages are the only event type supported with v1.1):

• GET direct_messages/events/show - Retrieves a single event by ID. 

• GET direct_messages/events/list - Retrieves up to 30 days of one-to-one Direct Messages sent and received by the authenticated user. Note that this method is not able to retrieve messages from group conversations. 

With this v2 release, there are three GET methods for retrieving Direct Message conversation events: 

• GET /2/dm_conversations/with/:participant_id/dm_events - Retrieves Direct Message events associated with a one-to-one conversation. The :participant_id path parameter is the User ID of the account having the conversation with the authenticated user making this request. 

• GET /2/dm_conversations/:dm_conversation_id/dm_events - Retrieves Direct Message events associated with a specific conversation ID, as indicated by the :dm_conversation_id path parameter. This method supports both one-to-one and group conversations. 

• GET /2/dm_events - Retrieves Direct Message events associated with a user, including both one-to-one and group conversations. Events from up to 30 days ago are available.  

An important detail is that conversation and event IDs are shared across v1.1 and v2 versions of the X Platform. This means both versions can be used together. For example, the Direct Messages v1.1 endpoints provide methods for returning a single event and for deleting events, methods not yet available with v2. Since IDs are common across v1.1 and v2, you can make v1.1 requests based on IDs provided by v2, or by referencing conversation IDs displayed in conversation URLs on the X application.

The following table compares fundamental aspects of the v1.1 and v2 Direct Message event lookup endpoints. The X API v2 characteristics shared here are common to all of the Direct Message lookup endpoints.

The following tables compare the v2 GET methods with version v1.1. Note that these v2 offerings expand the available capabilities by supporting group conversations. 

**Get all messages in a specific one-to-one conversation **

Path: GET /2/dm_conversations/with/:participant_id/dm_events

**Get all messages by conversation ID **

Path: GET /2/dm_conversations/:dm_conversation_id/dm_events

Get all events across an authenticated user’s conversations, both one-to-one and group conversations

Path: GET /2/dm_events

​

API reference index

For the complete API reference, select an endpoint from the list:

​

GET /2/dm_events

Returns a list of Direct Messages for the authenticated user, both sent and received. Direct Message events are returned in reverse chronological order. Supports retrieving events from the previous 30 days.

​

Endpoint URL

https://api.x.com/2/dm_events

​

Authentication and rate limits

​

OAuth 2.0 scopes required by this endpoint

​

Query parameters

​

Example code with offical SDKs

• cURL (default fields)
• cURL (optional fields)

      curl "https://api.x.com/2/dm_events" -H "Authorization: Bearer $ACCESS_TOKEN" -H "Authorization: Bearer $ACCESS_TOKEN"

​

Example responses

• Default fields
• Optional fields

{
  "data": [
    {
      "event_type": "MessageCreate",
      "id": "1346889436626259968",
      "text": "Hello just you..."
    }
  ]
}

​

Response fields

​

GET /2/dm_conversations/with/:participant_id/dm_events

Returns a list of Direct Messages (DM) events within a 1-1 conversation with the user specified in the participant_id path parameter. Messages are returned in reverse chronological order.

​

Endpoint URL

https://api.x.com/2/dm_conversations/with/:participant_id/dm_events

​

Authentication and rate limits

​

OAuth 2.0 scopes required by this endpoint

​

Path parameters

​

Query parameters

​

Example code with offical SDKs

• cURL (default fields)
• cURL (optional fields)

curl "https://api.x.com/2/dm_conversations/with/:participant_id/dm_events" -H "Authorization: Bearer $ACCESS_TOKEN"

​

Example responses

• Default fields
• Optional fields

{
  "data": [
    {
      "event_type": "MessageCreate",
      "id": "1346889436626259968",
      "text": "Hello just you..."
    }
  ]
}

​

Response fields

​

GET /2/dm_conversations/:dm_conversation_id/dm_events

Returns a list of Direct Messages within a conversation specified in the dm_conversation_id path parameter. Messages are returned in reverse chronological order.

Run in Postman ❯

Try a live request ❯

Build request with API Explorer ❯

​

Endpoint URL

https://api.x.com/2/dm_conversations/:dm_conversation_id/dm_events

​

Authentication and rate limits

​

OAuth 2.0 scopes required by this endpoint

​

Path parameters

​

Query parameters

​

Example code with offical SDKs

• cURL (default fields)
• cURL (optional fields)

curl "https://api.x.com/2/dm_conversations/:dm_conversation_id/dm_events" -H "Authorization: Bearer $ACCESS_TOKEN" -H "Authorization: Bearer $ACCESS_TOKEN"

​

Example responses

• Default fields
• Optional fields

• Default fields
• Optional fields

{
  "data": [
    {
      "event_type": "MessageCreate",
      "id": "1346889436626259968",
      "text": "Hello just you..."
    }
  ]
}

​

Response fields