Endpoints
{conversation_id} is the conversation id from GET /v1/inbox/conversations. Reactions and sender actions (typing indicators, seen receipts) return 501 resource.not_supported on X.
Your first message
List the conversations of the X account:message_ids holds the SocialAPI ID of the message sent. X delivers the DM to the person in participant_id. The fields of both responses are described in Direct messages.
Conversations
GET /v1/inbox/conversations lists conversations, most recent activity first. Add platform=twitter to list only X conversations. The parameters and fields are in Conversations. On X:
platform_idis X’s conversation ID. A conversation between 2 people has the form{smaller_user_id}-{larger_user_id}. A group conversation has a numeric ID.participant_idis the X user ID of the member who sent the most recent message by anyone other than the connected account, as of when the conversation first appeared, andparticipant_nameandparticipant_pictureare that person’s X name and profile picture. In a 1:1 conversation where only the connected account has written,participant_idis the other person’s ID, andparticipant_nameandparticipant_pictureare empty. In a group conversation where no other member had written when it first appeared,participant_idis empty. It stays empty, and a send to that conversation returns400 validation.participant_required.unread_countis always0on X, andPOST /v1/inbox/conversations/{conversation_id}/readhas no visible effect.- 30-day history. X returns only the last 30 days of DMs. A conversation or message that is already more than 30 days old when SocialAPI first reads the account never appears.
- First list after connecting. The list starts with the conversations in the account’s 100 most recent DMs. An older conversation appears when someone sends a new message in it.
Read messages
GET /v1/inbox/conversations/{conversation_id}/messages lists the messages of a conversation, newest first. limit is 25 by default, and a value above 200 is treated as 200.
- Text only.
attachment_typeandattachment_urlarenull, including on a message that carried an image or a video in X.reply_toisnull. sender_nameis the sender’s X name, not the@username.- No delivery status. X reports no delivery or read receipts, so
statuson a message sent through SocialAPI stayspending. A message the account sent in X has nostatus. - History. When SocialAPI first reads a conversation, its history starts with its 100 most recent messages from the last 30 days.
New messages
X sends no DM events to SocialAPI, so a new conversation or message appears only after SocialAPI refreshes the inbox from X. Listing conversations can start a refresh, andsync_state shows it. To read new X messages right away, call POST /v1/inbox/sync:
- With
account_idonly, the sync refreshes the conversation list: new conversations, and each conversation’slast_messageandlast_message_at. - With
conversation_idtoo, the sync refreshes that conversation’s messages. After you read a conversation’s messages once, new messages in it appear inGET /v1/inbox/conversations/{conversation_id}/messagesafter a sync of that conversation.
GET /v1/inbox/conversations after you connect the account waits for X and returns the account’s conversations. The first GET /v1/inbox/conversations/{conversation_id}/messages on a conversation waits for X and returns up to limit of its most recent messages. Its older messages appear in later calls.
Poll GET /v1/inbox/sync until state leaves syncing, then list again. A start while a sync of the same target is still running returns 202 with that sync, state syncing, and starts nothing new. Each target accepts 1 new sync you start every 5 minutes: another start within that time, once the running one has finished, returns 429 inbox.sync_rate_limited with a Retry-After header. X bills your X app for the DMs each refresh reads.
Send a message
POST /v1/inbox/conversations/{conversation_id}/messages sends a text DM to the person in the conversation’s participant_id.
- Cost. A send costs 1 interaction credit. When the plan’s allowance is used up, the call returns
429 validation.interaction_limit_exhausted. The credit comes back when the request fails with429 platform.twitter.throttled, or with avalidation.*error before any message is sent: see When a credit comes back. Text X refuses as malformed returns400 validation.field_requiredwitherror.meta.fieldset torequest_body, and the credit comes back. Every otherplatform.twitter.*code,501 resource.not_supported, and404 resource.not_foundkeep the credit.422 messaging.tag_not_supportedis refused before any credit is charged. - Who receives it. X delivers a DM only to a person whose X message settings accept DMs from the connected account. When the person does not accept DMs from the account, X refuses the send and the call returns
501 resource.not_supported. When the person’s X account no longer exists, the call returns404 resource.not_found. - Group conversations. A send on a group conversation goes as a 1-to-1 DM to the member in
participant_id, not to the group. Whenparticipant_idis empty, the call returns400 validation.participant_requiredand the credit comes back. - No new conversations. You send only into a conversation that
GET /v1/inbox/conversationslists. SocialAPI has no endpoint to start an X conversation.
Attachments are refused
X DMs sent through SocialAPI carry text only. SocialAPI sends the text first, then each attachment, and the first attachment fails the call with400 validation.attachment_unsupported. The result depends on what the request holds:
- Attachments only. Nothing is sent, and the credit comes back.
- Text and attachments. The text is delivered. The call then fails with
error.meta.sent_countset to1anderror.meta.failed_indexset to1, and the credit is spent.
text.
What X does not allow
Limits
Past one of X’s rate limits, the call returns
429 platform.twitter.rate_limit, with a Retry-After header when X reports when the limit resets. The same code is returned when X is temporarily unavailable. See Rate limits.
Errors and debugging
Check these in order when an X DM call fails:401,403 auth.insufficient_scope. The API key is invalid, or a scoped key lacksdms:send.404 conversation.not_found,404 account.not_found,403 account.reconnection_required,401 platform.twitter.auth,401 platform.twitter.unauthorized. The conversation is not yours or belongs to another connected account thanaccount_id, or the account needs reconnecting.401 platform.twitter.unauthorizedleaves the account working: if it persists, reconnect.412 byok.app_access_denied,401 byok.credentials_invalid. X refused your X app access to its API, or rejected the app credentials saved in SocialAPI. Fix the app as in Use your own X app, then reconnect the account.403 account.permission_missing. The account lacks the permission the call needs:messages.writeto send,messages.readto start or read a sync.error.meta.permissionnames it.403 platform.twitter.insufficient_scope. The X connection lacksdm.readordm.write. Check the app permissions in Use your own X app, then reconnect the account.400 validation.field_required,400 validation.text_required,400 validation.attachment_unsupported,400 validation.participant_required,422 messaging.tag_not_supported. The request holds something X DMs cannot send: see Send a message.501 resource.not_supported. The person does not accept DMs from the account, or the call is a reaction or a sender action.404 resource.not_found. The person’s X account no longer exists.402 platform.twitter.usage_capped. Your X app is out of credits or at its spending limit.429 validation.interaction_limit_exhausted,429 platform.twitter.rate_limit,429 platform.twitter.throttled.validation.interaction_limit_exhausted: your plan’s interaction allowance is used up until the next billing period. Upgrade the plan to send now.platform.twitter.rate_limit: X’s own limit. Wait for theRetry-Afterheader when it is present.platform.twitter.throttled: X refused this account with its own rate limit, and SocialAPI refuses its calls until the wait ends. Wait for theRetry-Afterheader.
Scopes
The X connection needs
dm.read to read DMs and dm.write to send them, on top of tweet.read and users.read. Your X app needs the Direct message app permission for X to grant them. The full list is in X scopes.
Events
X sends no DM events, so SocialAPI emits nodm.received, dm.sent, or dm.status.* events for X. Read new messages as described in New messages.
Use from an AI agent
No MCP tool starts an inbox sync. The tool list is in MCP tools.
Related
- X / Twitter API: capabilities, connect rules, limits, and scopes for X
- X / Twitter comments: list and answer the replies to your X posts
- Direct messages: the cross-platform DM endpoints and fields
- Unified inbox: start and poll an inbox sync
- Use your own X app: the X app and its Direct message permission
- Plans and usage: what costs an interaction credit