Skip to content

Twitter X direct messages API

The Twitter X direct messages API lets you list conversations, read message history, and send direct messages programmatically through one unified endpoint.

List conversations request
curl "{{API_BASE_URL}}/v1/messages?platform=twitter&accountId=acc_tw_123&limit=20" \
  -H "x-access-key: your-api-key"
Illustrative request
Example line 1

curl "{{API_BASE_URL}}/v1/messages?platform=twitter&accountId=acc_tw_123&limit=20" \

Illustrative request
Example line 2

-H "x-access-key: your-api-key"

You connect a Twitter/X account once, then use the same /v1/messages surface to build an inbox, route support conversations into your own tooling, or reconcile sent messages against your records.

Add social messaging in three steps

Start by getting an API key, then integrate by connecting once to the unified API. From that connection you can publish, schedule, analyze, manage comments, and handle messages without building and maintaining a separate integration for each platform. The Twitter/X messaging surface uses the same /v1/messages request and response shape as the other messaging endpoints, so one integration pattern covers multiple platforms.

List conversations: exact request and field map

The list conversations example shows the exact request shape to preserve. Use the request titled List conversations request and the response titled List conversations response. The response identifies the connected account with selfId and selfUsername, returns a conversations array, and provides nextCursor for pagination. Each conversation includes an id, a participants array with id, name, username, and profilePictureUrl for each person, a lastMessage object with id, text, from, and timestamp, and an updatedTime value for sorting and freshness checks. Check success before parsing conversations, store nextCursor when you need the next page, and use updatedTime to order the inbox by recent activity. If participants are missing a profilePictureUrl, fall back to initials or a placeholder avatar rather than failing the render.

Read message history and rebuild a thread

Read message history loads the messages in a DM conversation in paginated form, with the sender and a timestamp for each message. Because history is paginated, rebuild the full thread on your side by collecting pages in order and de-duplicating by message id before display. A common failure is assuming one page is the whole thread; check for a continuation value on every page and stop only when no further page is indicated. Another check is sender identity: use the from information on each message to distinguish the connected account from the other participant, rather than relying on position in the array.

Send a direct message and reconcile by sent message ID

Send direct messages with one call to a recipient. The response returns the sent message ID, which you should store immediately so you can track delivery and reconcile the send against your inbox. Do not mark a message as delivered in your UI until you have that ID. When recipient settings block delivery, the attempt fails and the response explains why; handle that as a distinct failure from a network error, show the reason to the operator, and do not retry blindly. Reconciliation should join your local record to the returned sent message ID, so a later history read can confirm the message appears in the thread.

OAuth connection without a developer app

Users connect their Twitter/X account through an OAuth flow handled by the provider. That removes the need for you to create a Twitter developer app, manage credentials, or handle token refreshes in your own codebase. The practical check during integration is account selection: confirm the connected account matches the accountId you intend to use for list, history, and send operations, because operations are scoped to a connected account.

Build your own inbox: decision criteria

Choose a dashboard inbox when you need reading and replying quickly with minimal product work. Choose building your own inbox when you need a branded support experience, custom routing, assignment, or integration with your existing helpdesk. The API exposes the same capabilities the dashboard inbox uses, including listing conversations with participants and last message, loading history, and sending replies, so the decision is about ownership of the user experience rather than access to the underlying operations. Before committing, verify that your product can store conversation ids, participant profilePictureUrl values, lastMessage text, and updatedTime for sorting, and that it can persist sent message IDs for reconciliation.

One /v1/messages surface across platforms

The same /v1/messages surface is used across messaging platforms, including Instagram, Facebook, LinkedIn, and TikTok. That consistency means the list, history, and send patterns you learn for Twitter/X transfer to other platforms, with the platform and accountId identifying the target. The same connected accounts can also support posting, scheduling, analytics, and comments, so a single connection can power several social capabilities in your product.

List conversations input contract
ParameterLocationRequirednessNotes
platformQuery stringNot specified in sourceExample value: twitter
accountIdQuery stringNot specified in sourceExample value: acc_tw_123
limitQuery stringNot specified in sourceExample value: 20

Requiredness not specified in source for these parameters; values shown are from the source example.

List conversations response field map
FieldType in examplePurpose
successbooleanIndicates whether the request succeeded
selfIdstringConnected account identifier
selfUsernamestringConnected account username
conversationsarrayList of DM conversations
conversations[].idstringConversation identifier
conversations[].participants[]arrayParticipants in the conversation
participants[].idstringParticipant identifier
participants[].namestringParticipant display name
participants[].usernamestringParticipant username
participants[].profilePictureUrlstringParticipant profile picture URL
conversations[].lastMessageobjectMost recent message in the conversation
lastMessage.idstringMost recent message identifier
lastMessage.textstringMost recent message text
lastMessage.fromobjectSender of the most recent message
lastMessage.timestampstringTimestamp of the most recent message
conversations[].updatedTimestringLast update time for the conversation
nextCursorstringCursor for the next page of conversations

Types inferred only from the shown JSON example values; source does not supply a separate schema.

Failure and edge cases
CaseWhat happensCheck to perform
Recipient does not accept messages from your accountSend is rejected and the API surfaces the reasonShow the surfaced reason; do not treat as a generic network failure
History is paginatedOne page may not contain the full threadCollect pages, de-duplicate by message id, and rebuild the thread in order
Send succeedsResponse returns the sent message IDStore the ID immediately and reconcile against your inbox and later history

Limited to source-supported cases.

Frequently asked questions

What can I do with Twitter/X DMs through this API?

You can list DM conversations, load the history for any conversation, and send direct messages through the unified /v1/messages endpoint.

Do I need to create a Twitter developer app?

No. The connection model uses OAuth handled by the provider, so users connect their Twitter/X account through that OAuth flow and you do not need to create a Twitter developer app or touch the developer portal.

Can I DM anyone?

Eligibility depends on how the recipient has configured their message settings. When those settings block incoming messages from your account, the attempt fails and the response explains why, so your product can present that explanation instead of a generic error.

Is Twitter/X messaging available today?

Yes, this messaging surface is described as available for use. Connect a Twitter/X account that has DM access, then list conversations, read history, and send DMs through the same unified Messages API.

Is there a UI, or is it API only?

Both options exist. A dashboard inbox supports reading and replying, while the API exposes equivalent operations so you can embed messaging inside your own product.

List conversations response
{
  "success": true,
  "selfId": "44196397",
  "selfUsername": "yourbrand",
  "conversations": [
    {
      "id": "44196397-2233445566",
      "participants": [
        {
          "id": "2233445566",
          "name": "Jane Doe",
          "username": "jane_doe",
          "profilePictureUrl": "https://pbs.twimg.com/profile_images/..."
        },
        {
          "id": "44196397",
          "name": "Your Brand",
          "username": "yourbrand",
          "profilePictureUrl": "https://pbs.twimg.com/profile_images/..."
        }
      ],
      "lastMessage": {
        "id": "1560000000000000001",
        "text": "An example comment.",
        "from": {
          "id": "2233445566",
          "name": "Jane Doe"
        },
        "timestamp": "2026-08-05T16:40:00Z"
      },
      "updatedTime": "2026-08-05T16:40:00Z"
    }
  ],
  "nextCursor": "QVFIUl9..."
}