Account actions

Read a conversation

Messages of one conversation, decrypted, newest first, with a cursor for older messages.

Paginated: pass the bottom cursor of one page as cursor to get the next. Each page is one billed call.

Reference: https://www.twittrapi.com/docs/account-actions/client-dm-conversation

post/client/dm/conversation

Request

  • Base URL: https://api.twittrapi.com
  • URL: https://api.twittrapi.com/client/dm/conversation
  • Auth: API key in header X-API-KEY

Query parameters

format'raw' | 'simple'

raw (default): X's JSON passed through. simple: flat camelCase JSON with a fixed schema and a {data, nextCursor, previousCursor, hasNextPage} envelope. Same price. The header X-Response-Format: simple does the same.

Request body

cookiestring required

Cookie header of your own logged-in X session. Must contain auth_token, ct0 and twid (your account ID, set by x.com at login); guest_id is used when present.

proxystring required

Your proxy, format http://user:pass@host:port. The requests to X go out through it. Used only for this request.

passcodestring required

Your X Chat passcode, the one you set up for encrypted messages on X. Send it as a string (a number works too, but loses leading zeros), up to 64 characters. It unlocks your chat keys for this request and is not saved. The unlocked keys stay in the server's memory for up to 30 minutes, so follow-up calls need no new unlock.

conversation_idstring

ID of the conversation, as returned by /client/dm/inbox. A one-to-one chat has the ID <smaller user ID>:<larger user ID>. Letters, digits, colon, hyphen and underscore, up to 128 characters. Either conversation_id or user_id is required.

user_idstring

Numeric ID of the other person (up to 20 digits) for a one-to-one chat. Used when conversation_id is not set.

cursorstring

cursor from the previous page (digits only, up to 20) to get older messages. Leave it out for the newest page.

Response

{conversation_id, messages, has_more, cursor, message_request_state, undecrypted, events}. messages are newest first; cursor is set when has_more is true. undecrypted lists events the API could not read ({id, sender_id, error}; for example data x.com keeps in your own conversation), events the other decrypted events (read receipts, settings and key changes). Each message: id (sequence ID, also the cursor unit), message_id, conversation_id, sender_id, created_at and expires_at (Unix milliseconds; expires_at only in chats with disappearing messages), type (text, reaction, reaction_removed, edit, deleted, ...), text, verified (the sender's signature was checked) and content (the decrypted message as X's chat library returns it: reactions, replies, attachments). Expired disappearing messages are left out.

With format=simple: Collection of Message objects {id, senderId, createdAt, expiresAt, type, text, emoji, targetId, replyTo {id, senderId, text}, attachments [{kind, type, filename, filesizeBytes, durationMs, width, height, url, mediaHashKey}], verified}; times are RFC 3339, unknown values null. nextCursor is the cursor for older messages, null on the last page.

RawPassthrough required

X's own JSON (raw format, the default), passed through unchanged. The shape is X's and can change; see https://www.twittrapi.com/docs/response-format.

Changes

No recorded changes to this operation across all 1 revision of this API.