Twitter DM API: How to Send Twitter/X DMs With an API in 2026
The Twitter DM API workflow for Twitter/X direct messages is a three-step loop: list conversations, read a thread, and send a reply. This guide preserves the exact request contract for each step so you can trace one conversation from inbox to sent message, derive the recipient correctly, and check the scopes and tier conditions that can cause a send to fail.
Prerequisites: scopes and X tier
Before you call any messaging endpoint, confirm three prerequisites. You need an API key, a connected Twitter/X account, and the correct permissions on both the connection and the X app. Sending and reading Twitter/X direct messages requires the dm.read and dm.write scopes on the connection. The X app must also have Direct Messages enabled and the account must be on a Basic or Pro X API tier; the free tier does not allow DM access. If an account was connected before DM support existed, reconnect it so the dm.read and dm.write scopes can be requested again.
Authentication with x-access-key
Every request uses the x-access-key header with your API key. Treat the key like a password and keep it out of public code and logs. If a later DM call fails, check that you are using the correct key for the project that owns the connected account.
Connect Twitter/X account and obtain accountId
Connect a Twitter/X account through the integrations flow, the same way you would for posting. The difference for DMs is scopes: the connection must include dm.read and dm.write so messages can be read and sent on behalf of the account. If you connected the account before DM support existed, it will not have those scopes yet, so reconnect and authorize again. After connecting, call the integrations endpoint to retrieve the connected account id. That id is the accountId you pass on every DM call below. If a later DM call fails, check this accountId first: a wrong or stale accountId will not match the connection that holds the DM scopes.
List conversations with GET /v1/messages
Start with GET /v1/messages to pull your inbox. Pass platform=twitter, your accountId, and a limit. The response returns selfId and selfUsername so you can tell which side of a conversation is you, plus a conversations array ordered by newest activity. Each conversation carries an id, a participants array, a lastMessage object, and an updatedTime you can sort on. Twitter conversations are built from recent DM events, so this list represents your active inbox rather than your entire message history. If there are more conversations than limit, the response includes a nextCursor; pass it back as after to page through the rest. See the field map in List conversations: field map and the request and response examples in List Twitter/X conversations and List conversations response example.
Read conversation with GET /v1/messages/:conversationId
Take a conversation id from the list and call GET /v1/messages/:conversationId with platform=twitter, your accountId, and a limit. The response is a flat messages array, newest first, with a nextCursor that is null when there are no older messages. Compare each message from.id against selfId to know who said what, and use after with nextCursor to page in older messages. This read step also gives you the value you need to reply: recipientId is the other participant's numeric user id, meaning the id in the participants array that is not your selfId. In the worked example, selfId is 1589374650000000000, so the recipient is 2096592231452807170. See Read a conversation and Read conversation response example for the exact request and response shapes.
Send DM with POST /v1/messages
To send, POST to /v1/messages with platform, accountId, recipientId, and text in the JSON body. A successful send returns success true and a messageId for the new message. Twitter does not impose a 24-hour reply window, so you are not racing a clock to respond. You cannot cold-message any account, however: you can only DM accounts that accept messages from you, such as accounts whose DMs are open, accounts that follow you, or accounts that have otherwise allowed messages. If the recipient does not accept messages from you, the send is rejected on the X side. See Send a Twitter/X DM and Send DM response example.
Three-call responder loop and credit costs
A minimal automated reply flow needs only three operations in sequence. First, check the inbox through GET /v1/messages to spot fresh activity. Second, open the relevant thread through GET /v1/messages/:conversationId so you have the surrounding context and can work out recipientId. Third, deliver your answer with a POST to /v1/messages. Because repeated inbox checks and thread reads add up against your available credits, choose a polling interval that matches your budget instead of querying continuously. The worked example follows dm-conv-8f21 through each stage: the inbox listing surfaces Dana Lee's question, the thread view confirms the context and recipientId 2096592231452807170, and the final request returns messageId msg-aa02.
Troubleshooting scopes and tiers
If a send fails, work through the failure matrix in order. First confirm the connection includes dm.read and dm.write, and reconnect if the account was connected before DM support existed. Next confirm the X app has Direct Messages enabled and the account is on a Basic or Pro tier. Then confirm you derived recipientId from the participant that is not selfId, not from the conversation id or the lastMessage sender alone. Finally, confirm the recipient accepts messages from you; a recipient who does not will cause the send to be rejected even when your scopes and tier are correct. See the full matrix in Failure matrix: scopes, tier, and recipient checks.
| Field | Where it appears | Meaning |
|---|---|---|
| success | List, read, and send responses | Boolean indicating the call succeeded. |
| selfId | List conversations response | Your own numeric user id; compare against participants and message from.id. |
| selfUsername | List conversations response | Your own username. |
| conversations[].id | List conversations response | Conversation id used as :conversationId in GET /v1/messages/:conversationId. |
| conversations[].participants[].id | List conversations response | Participant numeric user id; the one that is not selfId is the recipientId. |
| conversations[].lastMessage | List conversations response | Most recent message preview with id, text, from, and timestamp. |
| conversations[].updatedTime | List conversations response | Timestamp for sorting conversations by recent activity. |
| messages[].id | Read conversation response | Individual message id. |
| messages[].from.id | Read conversation response | Sender numeric user id; compare against selfId. |
| nextCursor | List and read responses | Pagination cursor; pass back as after. Null when no older items remain. |
| after | List and read requests | Query parameter carrying the previous nextCursor value. |
| recipientId | POST /v1/messages request | Other participant's numeric user id, derived as the participants id that is not selfId. |
| messageId | POST /v1/messages response | Id of the newly sent message on success. |
Captured parity specification; illustrative_unexecuted.
| Check | What to verify | If it fails |
|---|---|---|
| Scopes | Connection includes dm.read and dm.write | Reconnect the account so DM scopes can be requested. |
| X tier | X app has Direct Messages enabled; account on Basic or Pro tier | Free tier does not allow DM access; upgrade tier or enable Direct Messages. |
| accountId | accountId matches the connected account id from the integrations endpoint | Re-fetch the integrations list and use the correct id. |
| recipientId | recipientId is the participants id that is not selfId | Re-derive recipientId from the conversation participants. |
| Recipient acceptance | Recipient's DMs are open, follows you, or otherwise allows messages from you | Send is rejected on the X side; do not retry as a cold message. |
Captured parity specification; illustrative_unexecuted.
curl {{API_BASE_URL}}/v1/connect/integrations \
-H "x-access-key: YOUR_API_KEY"curl "{{API_BASE_URL}}/v1/messages?platform=twitter&accountId=6a8df8be8572dce3a2937c99&limit=20" \
-H "x-access-key: YOUR_API_KEY"{
"success": true,
"selfId": "1589374650000000000",
"selfUsername": "yourbrand",
"conversations": [
{
"id": "dm-conv-8f21",
"participants": [
{
"id": "1589374650000000000",
"name": "Your Brand",
"username": "yourbrand",
"profilePictureUrl": "https://.../you.jpg"
},
{
"id": "2096592231452807170",
"name": "Dana Lee",
"username": "danalee",
"profilePictureUrl": "https://.../dana.jpg"
}
],
"lastMessage": {
"id": "msg-aa01",
"text": "An example comment.",
"from": { "id": "2096592231452807170", "name": "Dana Lee" },
"timestamp": "2026-10-18T14:22:10Z"
},
"updatedTime": "2026-10-18T14:22:10Z"
}
],
"nextCursor": "QVFIUmxk..."
}curl "{{API_BASE_URL}}/v1/messages/dm-conv-8f21?platform=twitter&accountId=6a8df8be8572dce3a2937c99&limit=25" \
-H "x-access-key: YOUR_API_KEY"{
"success": true,
"messages": [
{
"id": "msg-aa01",
"text": "An example comment.",
"from": { "id": "2096592231452807170", "name": "Dana Lee" },
"timestamp": "2026-10-18T14:22:10Z"
},
{
"id": "msg-aa00",
"text": "An example comment.",
"from": { "id": "1589374650000000000", "name": "Your Brand" },
"timestamp": "2026-10-18T14:19:02Z"
}
],
"nextCursor": null
}curl -X POST {{API_BASE_URL}}/v1/messages \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"platform": "twitter",
"accountId": "6a8df8be8572dce3a2937c99",
"recipientId": "2096592231452807170",
"text": "An example comment."
}'{
"success": true,
"messageId": "msg-aa02"
}