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).
API key authentication - use your Zernio API key as a Bearer token
In: header
The social account ID to send from
Twitter numeric user ID of the recipient. Provide either this or participantUsername.
Twitter username (with or without @) of the recipient. Resolved to a user ID via lookup. Provide either this or participantId.
Text content of the message. At least one of message or attachment is required.
Skip the receives_your_dm eligibility check before sending. Use if you have already verified the recipient accepts DMs.
falseResponse Body
application/json
application/json
application/json
application/json
import Zernio from '@zernio/node';const zernio = new Zernio({ apiKey: process.env.ZERNIO_API_KEY });const { data } = await zernio.messages.createInboxConversation({ body: { accountId: 'account_abc123', },});console.log(data);{
"success": true,
"data": {
"messageId": "string",
"conversationId": "string",
"participantId": "string",
"participantName": "string",
"participantUsername": "string"
}
}{
"error": "string",
"code": "PLATFORM_NOT_SUPPORTED"
}{
"error": "Unauthorized"
}{
"error": "string",
"code": "DM_NOT_ALLOWED"
}List conversations GET
Fetch conversations (DMs) from all connected messaging accounts in a single API call. Supports filtering by profile and platform. Results are aggregated and deduplicated. Supported platforms: Facebook, Instagram, Twitter/X, Bluesky, Reddit, Telegram. Twitter/X limitation: X has replaced traditional DMs with encrypted "X Chat" for many accounts. Messages sent or received through encrypted X Chat are not accessible via X's API (the /2/dm_events endpoint only returns legacy unencrypted DMs). This means some Twitter/X conversations may show only outgoing messages or appear empty. This is an X platform limitation that affects all third-party applications. See X's docs on encrypted messaging for more details.
List messages GET
Fetch messages for a specific conversation, with cursor-based pagination and ordering control. Pagination: pass `pagination.nextCursor` from a prior response back as the `cursor` query param to fetch the next page. The cursor is opaque; do not parse or construct it client-side. Sort order: defaults to `asc` (oldest first, chat style). For the "show me the latest messages" pattern, pass `?sortOrder=desc&limit=N`. For Twitter, Facebook and Bluesky, the upstream APIs only return newest-first and have no order parameter — sort order is best-effort and only reverses items within a single page (pages still walk newest→oldest). The response field `sortOrderApplied` tells you what was actually applied. Reddit threads are paginated client-side because Reddit's API has no per-thread cursor. Very long threads may be upstream-truncated by Reddit's inbox/sent windows (~100 most-recent items each); this is a Reddit platform limitation. Twitter/X limitation: X's encrypted "X Chat" messages are not accessible via the API. Conversations where the other participant uses encrypted X Chat may only show your outgoing messages. See the list conversations endpoint for more details. This endpoint is read-only and does NOT mark messages as read or send read receipts. To mark a conversation read (and send WhatsApp blue ticks on eligible accounts), call `POST /v1/inbox/conversations/{conversationId}/read`.