Skip to main content
SocialAPI lists the direct message (DM) conversations of a connected X account, reads their messages, and sends text replies. X DMs use the same endpoints as every other platform with DMs, and a send is text only. The cross-platform rules are in Direct messages. A send costs 1 interaction credit. Reading costs no credits. X also bills every read and write to your own X developer app, because X connects through your own X app. X has no messaging window, but it delivers a DM only to a person who accepts DMs from the connected account. X sends no DM events, so new messages appear after a refresh: see New messages.

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:
Response (HTTP 200):
Send a reply into that conversation:
Response (HTTP 200):
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_id is 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_id is 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, and participant_name and participant_picture are that person’s X name and profile picture. In a 1:1 conversation where only the connected account has written, participant_id is the other person’s ID, and participant_name and participant_picture are empty. In a group conversation where no other member had written when it first appeared, participant_id is empty. It stays empty, and a send to that conversation returns 400 validation.participant_required.
  • unread_count is always 0 on X, and POST /v1/inbox/conversations/{conversation_id}/read has 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.
Response (HTTP 200):
The fields are described in Read messages. On X:
  • Text only. attachment_type and attachment_url are null, including on a message that carried an image or a video in X. reply_to is null.
  • sender_name is the sender’s X name, not the @ username.
  • No delivery status. X reports no delivery or read receipts, so status on a message sent through SocialAPI stays pending. A message the account sent in X has no status.
  • 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, and sync_state shows it. To read new X messages right away, call POST /v1/inbox/sync:
  • With account_id only, the sync refreshes the conversation list: new conversations, and each conversation’s last_message and last_message_at.
  • With conversation_id too, the sync refreshes that conversation’s messages. After you read a conversation’s messages once, new messages in it appear in GET /v1/inbox/conversations/{conversation_id}/messages after a sync of that conversation.
The first 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 with 429 platform.twitter.throttled, or with a validation.* error before any message is sent: see When a credit comes back. Text X refuses as malformed returns 400 validation.field_required with error.meta.field set to request_body, and the credit comes back. Every other platform.twitter.* code, 501 resource.not_supported, and 404 resource.not_found keep the credit. 422 messaging.tag_not_supported is 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 returns 404 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. When participant_id is empty, the call returns 400 validation.participant_required and the credit comes back.
  • No new conversations. You send only into a conversation that GET /v1/inbox/conversations lists. 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 with 400 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_count set to 1 and error.meta.failed_index set to 1, and the credit is spent.
To share a file, send its URL in 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:
  1. 401, 403 auth.insufficient_scope. The API key is invalid, or a scoped key lacks dms:send.
  2. 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 than account_id, or the account needs reconnecting. 401 platform.twitter.unauthorized leaves the account working: if it persists, reconnect.
  3. 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.
  4. 403 account.permission_missing. The account lacks the permission the call needs: messages.write to send, messages.read to start or read a sync. error.meta.permission names it.
  5. 403 platform.twitter.insufficient_scope. The X connection lacks dm.read or dm.write. Check the app permissions in Use your own X app, then reconnect the account.
  6. 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.
  7. 501 resource.not_supported. The person does not accept DMs from the account, or the call is a reaction or a sender action.
  8. 404 resource.not_found. The person’s X account no longer exists.
  9. 402 platform.twitter.usage_capped. Your X app is out of credits or at its spending limit.
  10. 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 the Retry-After header 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 the Retry-After header.
When a conversation or a message is missing, check that it was less than 30 days old when SocialAPI first read the account, then start a sync as in New messages. The full catalog is in Errors.

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 no dm.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.
Last modified on November 15, 2026