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.
curl "{{API_BASE_URL}}/v1/messages?platform=twitter&accountId=acc_tw_123&limit=20" \
-H "x-access-key: your-api-key"curl "{{API_BASE_URL}}/v1/messages?platform=twitter&accountId=acc_tw_123&limit=20" \
-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.
| Parameter | Location | Requiredness | Notes |
|---|---|---|---|
| platform | Query string | Not specified in source | Example value: twitter |
| accountId | Query string | Not specified in source | Example value: acc_tw_123 |
| limit | Query string | Not specified in source | Example value: 20 |
Requiredness not specified in source for these parameters; values shown are from the source example.
| Field | Type in example | Purpose |
|---|---|---|
| success | boolean | Indicates whether the request succeeded |
| selfId | string | Connected account identifier |
| selfUsername | string | Connected account username |
| conversations | array | List of DM conversations |
| conversations[].id | string | Conversation identifier |
| conversations[].participants[] | array | Participants in the conversation |
| participants[].id | string | Participant identifier |
| participants[].name | string | Participant display name |
| participants[].username | string | Participant username |
| participants[].profilePictureUrl | string | Participant profile picture URL |
| conversations[].lastMessage | object | Most recent message in the conversation |
| lastMessage.id | string | Most recent message identifier |
| lastMessage.text | string | Most recent message text |
| lastMessage.from | object | Sender of the most recent message |
| lastMessage.timestamp | string | Timestamp of the most recent message |
| conversations[].updatedTime | string | Last update time for the conversation |
| nextCursor | string | Cursor for the next page of conversations |
Types inferred only from the shown JSON example values; source does not supply a separate schema.
| Case | What happens | Check to perform |
|---|---|---|
| Recipient does not accept messages from your account | Send is rejected and the API surfaces the reason | Show the surfaced reason; do not treat as a generic network failure |
| History is paginated | One page may not contain the full thread | Collect pages, de-duplicate by message id, and rebuild the thread in order |
| Send succeeds | Response returns the sent message ID | Store 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.
{
"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..."
}