> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnixapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Direct Messages

> Read, send, and manage X (XChat) direct messages — including end-to-end encrypted chats.

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

<CardGroup cols={2}>
  <Card title="auth_token" icon="key">
    The X account the action runs as (same as every other endpoint).
  </Card>

  <Card title="encryption_code" icon="lock">
    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.
  </Card>
</CardGroup>

<Info>
  **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).
</Info>

<Note>
  Every DM endpoint also accepts an optional **`proxy`** to route the call through your
  own proxy. See [Authentication](/authentication#routing-through-a-proxy-optional).
</Note>

## Key concepts

| Term              | What it is                                                                                                                                                                     |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `conversation_id` | Identifies a chat, e.g. `1189...:1576...`. Get it from the inbox.                                                                                                              |
| `seq_id`          | A message's sequence id (returned by **Read Conversation**). You pass it as the target for **react**, **edit**, and **delete**, and as the `cursor` to page to older messages. |
| `next_cursor`     | Pagination token. The inbox returns `{ cursor_id, graph_snapshot_id }`; a conversation returns a `seq_id`.                                                                     |

## 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`).

<Warning>
  `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.
</Warning>

## Typical flow

<Steps>
  <Step title="List conversations">
    `GET /dm/list` (with `encryption_code` for last-message previews) → pick a `conversation_id`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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`.
  </Step>
</Steps>

<Tip>
  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.
</Tip>