---
title: "List messages"
method: GET
path: "/v1/inbox/conversations/{conversationId}/messages"
tags: ["Messages"]
---

# List messages

`GET /v1/inbox/conversations/{conversationId}/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.

Instagram and Facebook conversations include history from before the
account was connected, replayed from Meta. That replay covers the 500
most recent messages per conversation: a longer thread keeps its newest
500 and older messages are not retrievable. Messages that arrived after
the account was connected are unaffected. Replayed messages are stored
as already read and emit no webhooks.

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

## Path parameters

- `conversationId` string, required

## Query parameters

- `accountId` string, required
- `limit` integer
- `cursor` string
- `sortOrder` 'asc' | 'desc'

## Response `200`

Messages in conversation

- object
  - `status` string
  - `pagination` object
    - `hasMore` boolean — Whether more messages are available beyond this page.
    - `nextCursor` string, nullable — Opaque cursor to fetch the next page. `null` on the last page.
  - `sortOrderApplied` 'asc' | 'desc' — Sort order actually applied to the returned page. May differ from the requested `sortOrder` for Facebook and Bluesky (always `desc` regardless of request).
  - `messages` object[]
    - `id` string
    - `conversationId` string
    - `accountId` string
    - `platform` string
    - `message` string
    - `senderId` string
    - `senderName` string, nullable
    - `senderVerifiedType` 'blue' | 'government' | 'business' | 'none', nullable — X/Twitter verified badge type. Only present for Twitter/X messages.
    - `direction` 'incoming' | 'outgoing'
    - `createdAt` string, date-time
    - `attachments` object[]
      - `id` string
      - `type` 'image' | 'video' | 'audio' | 'file' | 'sticker' | 'share'
      - `url` string
      - `filename` string, nullable
      - `previewUrl` string, nullable
    - `subject` string, nullable — Reddit message subject
    - `storyReply` boolean, nullable — Instagram story reply
    - `isStoryMention` boolean, nullable — Instagram story mention
    - `isEdited` boolean — True if the sender has edited this message at least once.
    - `editedAt` string, date-time, nullable — When the most recent edit happened.
    - `editCount` integer — Total number of edits applied.
    - `editHistory` InboxMessageEditHistoryEntry[] — Every prior version of the message, oldest first.
      - `text` string, nullable, required
      - `attachments` InboxMessageEditAttachment[], required
        - `type` string
        - `url` string
        - `payload` object
      - `editedAt` string, date-time, required
    - `isDeleted` boolean — True if the sender has deleted (unsent) this message. The original message and attachments fields remain populated.
    - `deletedAt` string, date-time, nullable
    - `deliveryStatus` 'sent' | 'delivered' | 'read' | 'failed' | 'deleted', nullable — Lifecycle status for outgoing messages. Not all platforms emit every state (see webhook support matrix).
    - `deliveredAt` string, date-time, nullable
    - `readAt` string, date-time, nullable
    - `sentAt` string, date-time, nullable — Original send time for outgoing messages (used for Messenger watermark queries).
    - `deliveryError` object, nullable — Populated when deliveryStatus === "failed".
      - `code` integer
      - `title` string
      - `message` string
    - `reactions` object[] — Emoji reactions on this message (WhatsApp / Telegram). At most one per party in a 1:1 thread.
      - `emoji` string
      - `fromMe` boolean — true if the connected account reacted, false if the contact did.
      - `reactedAt` string, date-time
    - `metadata` object — Platform-specific extras. Free-form, but commonly includes: `quotedMessageId` (platformMessageId this message replies to), `waInteractive` (a compact descriptor of WhatsApp interactive content sent: buttons / list / cta_url / flow / location_request), and for inbound interactive taps `interactiveType` / `interactiveId`.
  - `lastUpdated` string, date-time

## Other responses

- `401` — Unauthorized
- `403` — Inbox addon required

---

[API](https://skmtc.net/zernio/apis/zernio-api.md) · [All operations](https://skmtc.net/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zernio/zernio-api/versions/51932b099b2f/schema)