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.
- 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.
| 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 |
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 |
| 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 |
| 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 |