Skip to content

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.

List conversations: field map
FieldWhere it appearsMeaning
successList, read, and send responsesBoolean indicating the call succeeded.
selfIdList conversations responseYour own numeric user id; compare against participants and message from.id.
selfUsernameList conversations responseYour own username.
conversations[].idList conversations responseConversation id used as :conversationId in GET /v1/messages/:conversationId.
conversations[].participants[].idList conversations responseParticipant numeric user id; the one that is not selfId is the recipientId.
conversations[].lastMessageList conversations responseMost recent message preview with id, text, from, and timestamp.
conversations[].updatedTimeList conversations responseTimestamp for sorting conversations by recent activity.
messages[].idRead conversation responseIndividual message id.
messages[].from.idRead conversation responseSender numeric user id; compare against selfId.
nextCursorList and read responsesPagination cursor; pass back as after. Null when no older items remain.
afterList and read requestsQuery parameter carrying the previous nextCursor value.
recipientIdPOST /v1/messages requestOther participant's numeric user id, derived as the participants id that is not selfId.
messageIdPOST /v1/messages responseId of the newly sent message on success.

Captured parity specification; illustrative_unexecuted.

Failure matrix: scopes, tier, and recipient checks
CheckWhat to verifyIf it fails
ScopesConnection includes dm.read and dm.writeReconnect the account so DM scopes can be requested.
X tierX app has Direct Messages enabled; account on Basic or Pro tierFree tier does not allow DM access; upgrade tier or enable Direct Messages.
accountIdaccountId matches the connected account id from the integrations endpointRe-fetch the integrations list and use the correct id.
recipientIdrecipientId is the participants id that is not selfIdRe-derive recipientId from the conversation participants.
Recipient acceptanceRecipient's DMs are open, follows you, or otherwise allows messages from youSend is rejected on the X side; do not retry as a cold message.

Captured parity specification; illustrative_unexecuted.

Get connected account ID
curl {{API_BASE_URL}}/v1/connect/integrations \
  -H "x-access-key: YOUR_API_KEY"
List Twitter/X conversations
curl "{{API_BASE_URL}}/v1/messages?platform=twitter&accountId=6a8df8be8572dce3a2937c99&limit=20" \
  -H "x-access-key: YOUR_API_KEY"
List conversations response example
{
  "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..."
}
Read a conversation
curl "{{API_BASE_URL}}/v1/messages/dm-conv-8f21?platform=twitter&accountId=6a8df8be8572dce3a2937c99&limit=25" \
  -H "x-access-key: YOUR_API_KEY"
Read conversation response example
{
  "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
}
Send a Twitter/X DM
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."
  }'
Send DM response example
{
  "success": true,
  "messageId": "msg-aa02"
}