Standard v1.1 compared to Twitter API v2

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):

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.

Description Standard v1.1 X API v2
Host domain https://api.x.com https://api.x.com
Endpoint root path /1.1/direct_messages

/2/dm_conversations

Direct Messages conversations are introduced as a fundamental API object. 

These endpoints retrieve MessageCreate, ParticipantsJoin, and ParticipantLeave events.

HTTP methods supported GET GET
Supports Group Direct Messages  
Event types supported message_create MessageCreate, ParticipantsJoin, ParticipantsLeave
Authentication OAuth 1.0a User Context

OAuth 1.0a User Context

OAuth 2 User Context (scopes: dm.read, tweet.read, user.read)

Requires the use of credentials from a developer App associated with a X API v2 Project  
Default request rate limits*
*All requests require user tokens
 

GET requests: 300 requests per 15 mins

Rate limit is applied across all three 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

Description Standard v1.1 X API v2
Endpoint path

GET 

/1.1/direct_messages/events/list

GET /2/dm_conversations/with/:participant_id/dm_events
How much event history is available 30 days No limit
Default request rate limits 15 requests per 15 minutes 300 requests per 15 minutes
Rate limit is applied across all three GET endpoints

Get all messages by conversation ID 

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

Description Standard v1.1 X API v2
Endpoint path

Not supported. V1.1 can return messages from one-to-one conversations only and there is no support for retrieving events by conversation IDs.

GET /2/dm_conversations/:dm_conversation_id/dm_events
How much event history is available 30 days No limit
Supports group conversations             
Default request rate limits

15 requests per 15 minutes

300 requests per 15 minutes
Rate limit is applied across all three GET endpoints
   

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

Path: GET /2/dm_events

Description Standard v1.1 X API v2
Endpoint path

GET /1.1/direct_messages/events/list

V1.1 can return messages from one-to-one conversations only.

GET /2/dm_events
How much event history is available 30 days 30 days
Supports group conversations             
Default request rate limits

15 requests per 15 minutes

300 requests per 15 minutes
Rate limit is applied across all three GET endpoints