List messages
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.
Twitter, Instagram, Telegram, WhatsApp and Reddit honor the requested
order from the local message store. For 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.
API key authentication - use your Zernio API key as a Bearer token
In: header
Path Parameters
The conversation ID (id field from list conversations endpoint). This is the platform-specific conversation identifier, not an internal database ID.
Query Parameters
Social account ID
Number of messages to return per page. Default 100, max 100.
1001 <= value <= 100Opaque pagination cursor. Pass pagination.nextCursor from a prior response.
Order of returned messages. Default asc (oldest first, chat style).
Twitter, Instagram, Telegram, WhatsApp and Reddit honor this order
across cursor pages. For Facebook and Bluesky, only intra-page
ordering is affected — pages always walk newest→oldest. See
sortOrderApplied in the response.
"asc""asc" | "desc"Response Body
application/json
application/json
import Zernio from '@zernio/node';const zernio = new Zernio({ apiKey: process.env.ZERNIO_API_KEY });const { data } = await zernio.messages.getInboxConversationMessages({ path: { conversationId: 'conversation_abc123', }, query: { accountId: 'account_abc123', },});console.log(data);{
"status": "string",
"pagination": {
"hasMore": true,
"nextCursor": "string"
},
"sortOrderApplied": "asc",
"messages": [
{
"id": "string",
"conversationId": "string",
"accountId": "string",
"platform": "string",
"message": "string",
"senderId": "string",
"senderName": "string",
"senderVerifiedType": "blue",
"direction": "incoming",
"createdAt": "2019-08-24T14:15:22Z",
"attachments": [
{
"id": "string",
"type": "image",
"url": "string",
"filename": "string",
"previewUrl": "string"
}
],
"subject": "string",
"storyReply": true,
"isStoryMention": true,
"isEdited": true,
"editedAt": "2019-08-24T14:15:22Z",
"editCount": 0,
"editHistory": [
{
"text": "string",
"attachments": [
{
"type": "string",
"url": "string",
"payload": {}
}
],
"editedAt": "2019-08-24T14:15:22Z"
}
],
"isDeleted": true,
"deletedAt": "2019-08-24T14:15:22Z",
"deliveryStatus": "sent",
"deliveredAt": "2019-08-24T14:15:22Z",
"readAt": "2019-08-24T14:15:22Z",
"sentAt": "2019-08-24T14:15:22Z",
"deliveryError": {
"code": 0,
"title": "string",
"message": "string"
},
"reactions": [
{
"emoji": "string",
"fromMe": true,
"reactedAt": "2019-08-24T14:15:22Z"
}
],
"metadata": {}
}
],
"lastUpdated": "2019-08-24T14:15:22Z"
}{
"error": "Unauthorized"
}Create conversation (send a WhatsApp template) POST
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. Supported platforms: X/Twitter, Bluesky, Reddit, and WhatsApp. Other platforms return PLATFORM_NOT_SUPPORTED. WhatsApp: this is the endpoint for sending an approved template message to a phone number. Provide templateName, templateLanguage, and templateParams (body variable values), with the recipient phone in participantId. A template is required because WhatsApp does not permit freeform messages to open a conversation; a missing template returns TEMPLATE_REQUIRED. Templates with media headers (image, video, document) are handled automatically: Zernio reads the approved template definition and fills the header at send time. Calling this for a number you already have a thread with simply sends the template into that thread, which also makes it the way to re-engage a contact after the 24-hour customer-service window has closed. Once the recipient replies (opening the 24h window), send freeform messages with the send-message endpoint (POST /v1/inbox/conversations/{conversationId}/messages). Template fields are accepted on the JSON body only, not on multipart requests. DM eligibility (X/Twitter): 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).
Get conversation GET
Retrieve details and metadata for a specific conversation. Requires accountId query parameter.