Skip to main content
The Direct Messages endpoints let you read your inbox, read a conversation’s full decrypted history, send text and media, and delete / react / edit messages — all as the auth_token account. X’s encrypted chats (XChat) are end-to-end encrypted, so reading or signing those messages needs one extra credential beyond your auth_token.

​
The two credentials

auth_token

The X account the action runs as (same as every other endpoint).

encryption_code

Your XChat PIN — the code you set when enabling encrypted chats on X. Used to recover your key so messages can be decrypted and outgoing events signed.
When is encryption_code required? For anything that touches encrypted content: reading a conversation, reacting, editing, deleting, and sending media. It’s optional on the inbox (provide it to also get a preview of each conversation’s most recent message) and optional on send (provide it to send an encrypted message instead of a standard one).
Every DM endpoint also accepts an optional proxy to route the call through your own proxy. See Authentication.

​
Key concepts

​
Encrypted vs legacy send

POST /dm/send has two modes:
  • Encrypted — supply encryption_code (with a conversation_id). The message is end-to-end encrypted and can later be deleted for everyone (delete_for_all).
  • Legacy — omit encryption_code. Uses X’s reliable delivery path, but such messages can only be removed from your own view (delete_for_all: false).
delete_for_all: true only works on your own encrypted messages. Trying it on a legacy-sent message returns 422 — use delete_for_all: false to remove it from your view instead.

​
Typical flow

1

List conversations

GET /dm/list (with encryption_code for last-message previews) → pick a conversation_id.
2

Read the history

POST /dm/conversation → the conversation’s messages, each with a seq_id. Edited messages show their latest text and reactions are attached to the message they apply to.
3

Act on it

POST /dm/send to reply, POST /dm/send_media to attach a file, or POST /dm/react / POST /dm/edit / POST /dm/delete targeting a seq_id.
Every endpoint has a live Send playground in the API Reference — paste your API key, auth_token, and encryption_code, and try it against your own account.