Manage direct messages

Manage Direct Messages

​

Introduction

Only available to those with Pro and Enterprise access

Direct Messages enable private conversations on X. Direct Messages are one of the most popular features of X, with a wide variety of use cases. These use cases range from group chats among friends, to powering customer support for brands around the world. New v2 versions of Direct Messages endpoints will be introduced in stages, and this first stage includes fundamental endpoints for creating Direct Messages and listing Direct Message conversation events. For the first time, the X API v2 supports group conversations.

This initial release of Manage Direct Messages includes three POST methods for creating Direct Messages:

• POST /2/dm_conversations/with/:participant_id/messages - Creates a one-to-one Direct Message. This method either creates a new 1-1 conversation or retrieves the current conversation and adds the Direct Message to it. The :participant_idpath parameter is the User ID of the account receiving the 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. 
• 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. 

Note that Direct Message event IDs are common across the v1.1 and v2 (as well as the X App), so the v1.1 methods to hide/delete Direct Messages can be used along with this new v2 endpoint. Also note that the Enterprise and Premium Account Activity APIs support v2 one-to-one messages, but do not yet support group conversations.   

There is a user rate limit of 200 requests per 15 minutes for the POST method. There is also a rate limit of 1000 requests per 24 hours per user. Additionally, there is a rate limit of 15000 requests per 24 hours. Note that these rate limits are shared across these POST endpoints.

Since you are making requests on behalf of a user with the manage Posts endpoints, you must authenticate with either OAuth 1.0a User Contextor OAuth 2.0 Authorization Code with PKCE, and use a user Access Tokens associated with a user that has authorized your App. To generate this user Access Token with OAuth 1.0a, you can use the 3-legged OAuth flow. To generate a user Access Token with OAuth 2.0, you can use the Authorization Code with PKCE grant flow).

​

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 manage Direct Message 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 XDev-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 the 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, and you can 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 an exciting 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 “Manage 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 “Manage DMs.”

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, and 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 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: Specify the Direct Message conversation participants and message contents

Navigate to the “Body” tab and make updates to the example JSON object. Set the participant_ids attribute to the accounts you want to send the Direct Message to.

{ "message": {"text": "Hello to just you two, this is a new group conversation."}, "participant_ids": ["944480690","906948460078698496"], "conversation_type": "Group" }

​

Step four: Make your request and review the response

Once you have everything set up, hit the “Send” button, and you will receive a similar response to the example response below. A reminder that if your token has expired since you created it above, you can return to the folder’s Authorization tab and click on the “Get New Access Token” to create a fresh token.

{
   "data": {
       "dm_conversation_id": "1582103724607971328",
       "dm_event_id": "1582103724607971332"
   }
}

If the returned response “data” object contains a dm_conversation_id and an dm_event_id, you have successfully created a new Direct Message conversation. To start looking up events associated with this conversation, head over to the Direct Message lookup Quick start guide.

​

Step five: Add another message to that group conversation

Now select the “Add DM to conversation” example, and select the “Params” tab. Under “Path Variables” , update the dm_conversation_id to the ID of the conversation you created above.

Using this conversation ID, the request path will resolve to: https://api.x.com/2/dm_conversations/1582103724607971328/messages

Also, update the “Body” tab with request JSON containing the message text you want to send: 

{
   "text": "Adding a new message to our group conversation..."
}

Once you have everything set up, hit the “Send” button, and you will receive a similar response to the following example response:

{
   "data": {
       "dm_conversation_id": "1582103724607971328",
       "dm_event_id": "1582106224379559940"
   }
}

​

Integration guide

The Direct Messages endpoints v2 introduce conversations and conversation events as core X API objects, and makes a distinction between one-to-one and group conversations. One-to-one 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 Manage Direct Messages 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

  • Including media attachments and referencing Posts

  • Authentication

  • Developer portal, Projects, and developer Apps

  • Rate limits

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

{
   "text": "Hello just you. This will appear as a new conversation if we have never messaged, or will be added to our existing thread. "
}

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

{
   "message": {"text": "Hello to just you two, this is a new group conversation."},
   "participant_ids": ["944480690","906948460078698496"],
   "conversation_type": "Group"
}

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

{
   "text": "Here is a new message."
}

These POST methods support attaching a single piece of media. POST request bodies must include either or both the “text” and “attachments” fields. The “text” attribute is required if the “attachments” field is not included, and the “attachments” field is required if the “text” field is not included. See the next section for more information.

For more information see the Manage Direct Messages 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. 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:

{
 "text": "Here's a photo...",
 "attachments": [{"media_id": "1583157113245011970}]
}

The resulting MessageCreate event will include the following metadata:

{
    "attachments": {
        "media_keys": [
            "5_1583157113245011970"
        ]
    }
}

Posts can also be included by including the Post URL in the message text. To illustrate how to include Posts in messages, the following is an example JSON request body:

{
 "text": "Here's the Tweet I has talking about: https://twitter.com/SnowBotDev/status/1580559079470145536"
}

The resulting MessageCreate event will include the following metadata:

{
    "referenced_tweets": [
        {
            "id": "1580559079470145536"
        }
    ]
}

​

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

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 Manage Direct Message endpoints

Both v1.1 and v2 versions of the Direct Messages endpoints provide methods for creating Direct Message messages. 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 managing Direct Messages:

• POST direct_messages/events/new - Creates a one-to-one Direct Message. This v1.1 endpoint can only create one-to-one messages, and does not support group messages.  

• DELETE direct_messages/events/destroy - Deletes a one-to-one message from the view of the authenticating user. 

With this v2 release, there are three POST methods for creating Direct Messages: 

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

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

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

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 manage Direct Messages endpoints. The X API v2 characteristics shared here are common to all of the Direct Message lookup endpoints.

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

Create a new one-to-one Direct Message

Path: POST /2/dm_conversations/with/:participant_id/messages

Create a new Direct Message group conversation and add a message to it

Path: POST /2/dm_conversations

Add a Direct Message to an existing conversation by ID

Path: POST /2/dm_conversations/:dm_conversation_id/messages

​

API reference index

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

​

Manage Direct Messages

Only available to those with Pro and Enterprise access

​

POST /2/dm_conversations/:dm_conversation_id/messages

Creates a Direct Message on behalf of an authenticated user, and adds it to the specified conversation.

​

Endpoint URL

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

​

Authentication and rate limits

​

OAuth 2.0 scopes required by this endpoint

​

Path parameters

​

JSON body parameters

​

Example code with offical SDKs

• cURL

      curl -X POST "https://api.x.com/2/dm_conversations/:dm_conversation_id/messages" -d '{"text": "Adding a Direct Message to a conversation by referencing the conversation ID. This method supports both one-to-one and group conversations."}' -H "Authorization: Bearer $ACCESS_TOKEN"

​

Example responses

• Successful response

{
  "dm_conversation_id": "1346889436626259968",
  "dm_event_id": "128341038123"
}

​

Response fields

​

POST /2/dm_conversations/with/:participant_id/messages

Creates a one-to-one Direct Message and adds it to the one-to-one conversation. This method either creates a new one-to-one conversation or retrieves the current conversation and adds the Direct Message to it.

​

Endpoint URL

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

​

Authentication and rate limits

​

OAuth 2.0 scopes required by this endpoint

​

Path parameters

​

JSON body parameters

​

Example code with offical SDKs

• cURL

      curl -X POST "https://api.x.com/2/dm_conversations/with/:participant_id/messages" -d '{"text": "This is a one-to-one Direct Message with an attachment","attachments": [{"media_id": "1455952740635586573"}]}' -H "Authorization: Bearer $ACCESS_TOKEN"

​

Example responses

• Successful response

{
  "dm_conversation_id": "1346889436626259968",
  "dm_event_id": "128341038123"
}

​

Response fields

​

POST /2/dm_conversations

Creates a new group conversation and adds a Direct Message to it on behalf of an authenticated user.

​

Endpoint URL

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

​

Authentication and rate limits

​

OAuth 2.0 scopes required by this endpoint

​

JSON body parameters

​

Example code with offical SDKs

• cURL

      curl -X POST "https://api.x.com/2/dm_conversations" -d '{"conversation_type":"Group", "participant_ids": ["944480690", "906948460078698496"],"message": {"text": "Hello to you two, this is a new group conversation"}}' -H "Authorization: Bearer $ACCESS_TOKEN"

​

Example responses

• Successful response

{
  "dm_conversation_id": "1346889436626259968",
  "dm_event_id": "128341038123"
}

​

Response fields