Create conversation

Initiate a new direct message conversation with a specified user. If a conversation already exists with the recipient, the message is added to the existing thread.

Currently supported platforms: Twitter/X only. Other platforms will return PLATFORM_NOT_SUPPORTED.

DM eligibility: Before sending, the endpoint checks if the recipient accepts DMs from your account (via the receives_your_dm field). If not, a 422 error with code DM_NOT_ALLOWED is returned. You can skip this check with skipDmCheck: true if you have already verified eligibility.

X API tier requirement: DM write endpoints require X API Pro tier ($5,000/month) or Enterprise access. This applies to BYOK (Bring Your Own Key) users who provide their own X API credentials.

Rate limits: 200 requests per 15 minutes, 1,000 per 24 hours per user, 15,000 per 24 hours per app (shared across all DM endpoints).

POST /v1/inbox/conversations

Initiate a new direct message conversation with a specified user. If a conversation already exists with the recipient, the message is added to the existing thread.

Currently supported platforms: Twitter/X only. Other platforms will return PLATFORM_NOT_SUPPORTED.

DM eligibility: Before sending, the endpoint checks if the recipient accepts DMs from your account (via the receives_your_dm field). If not, a 422 error with code DM_NOT_ALLOWED is returned. You can skip this check with skipDmCheck: true if you have already verified eligibility.

X API tier requirement: DM write endpoints require X API Pro tier ($5,000/month) or Enterprise access. This applies to BYOK (Bring Your Own Key) users who provide their own X API credentials.

Rate limits: 200 requests per 15 minutes, 1,000 per 24 hours per user, 15,000 per 24 hours per app (shared across all DM endpoints).

Request body

Content-Type: application/json

• accountId (string) required — The social account ID to send from
• participantId (string) — Twitter numeric user ID of the recipient. Provide either this or participantUsername.
• participantUsername (string) — Twitter username (with or without @) of the recipient. Resolved to a user ID via lookup. Provide either this or participantId.
• message (string) — Text content of the message. At least one of message or attachment is required.
• skipDmCheck (boolean) — Skip the receives_your_dm eligibility check before sending. Use if you have already verified the recipient accepts DMs.

Content-Type: multipart/form-data

• accountId (string) required — The social account ID to send from
• participantId (string) — Twitter numeric user ID of the recipient
• participantUsername (string) — Twitter username (with or without @) of the recipient
• message (string) — Text content of the message
• attachment (string) — Media attachment (image or video). One attachment per message.
• skipDmCheck (string) (enum: true, false) — Skip the DM eligibility check

Responses

201 — Conversation created successfully

• success (boolean)
• data (object)

400 — Validation error or platform not supported

• error (string)
• code (string) (enum: PLATFORM_NOT_SUPPORTED)

401

403 — Inbox addon required or profile limit reached

404 — Account or recipient user not found

422 — Recipient does not accept DMs from this account

• error (string)
• code (string) (enum: DM_NOT_ALLOWED)

429 — X API rate limit exceeded