- Key Concepts
- Helpful tools
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 Manage Direct Message endpoints provide three POST methods for creating new messages and adding them to conversations:- POST /2/dm_conversations/with/:participant_id/messages - Creates a one-to-one Direct Message. This method either adds the message to an existing one-to-one conversation or creates a new one. The :participant_id path parameter is the User ID of the account receiving the message. Here is an example JSON request body for sending a one-to-one Direct Message:
- POST /2/dm_conversations - Creates a new group conversation and adds a Direct Message to it. These requests require a list of conversation participants. Note that you can create multiple conversations with the same participant list. These requests will always return a new conversation ID.Below is an example JSON request body for creating a new group conversation and adding a Direct Message. Note that this requires a “conversation_type” field and that must be set to “Group” (case sensitive).
- POST /2/dm_conversations/:dm_conversation_id/messages - Creates a Direct Message and adds it to an existing conversation. The :dm_conversation_id path parameter is the ID of the conversation that the message will be added to. This method can be used to add a message to both one-to-one and group conversations. Here is an example JSON request body for sending Direct Message to both one-to-one and group conversations:
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. These methods are 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.Including media attachments and referencing Posts
The Manage Direct Message endpoints all support attaching one piece of media (photo, video, or GIF). Attaching media requires a media ID generated by the v1.1 Upload media endpoint. The authenticated user posting the Direct Message must have also uploaded the media. Once uploaded, media is available for 24 hours for including with the message. To illustrate how to include media, the following is an example JSON request body: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.write, dm.read, tweet.read, user.read. To enable OAuth 2.0 in your App, you must enable it in your 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 Manage Direct Message endpoints are rate limited at both the per-user and X App levels. This means that the authenticated user that you are making the request on behalf of can only send a certain number of messages with your X App. In addition, there is a daily limit on how many Direct Messages can be sent by your X App. There is a user rate limit of 200 requests/messages per 15 minutes for the POST methods. Users are also limited to 1000 Direct Messages per 24 hours. In addition, X Apps have a limit of 15000 messages per 24 hours. These rate limits are shared across the POST endpoints. 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