---
title: "List messages in a conversation"
method: GET
path: "/v1/inbox/conversations/{conversationId}/messages"
tags: ["Inbox"]
---

# List messages in a conversation

`GET /v1/inbox/conversations/{conversationId}/messages`

## Request

- Base URL: `https://api.postzen.dev`
- URL: `https://api.postzen.dev/v1/inbox/conversations/{conversationId}/messages`
- Auth: HTTP bearer

Returns the messages PostZen holds for one thread, oldest first by default, refreshing them from the platform when the stored copy is stale. Strictly read-only: it never marks the thread read — use `POST /v1/inbox/conversations/{conversationId}/read` for that. Meta returns full content only for roughly the twenty newest Instagram messages, so older ones may carry an id and timestamp without text or attachments. Read-only and read-write API keys are accepted.

## Query parameters

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

## Response `200`

Messages returned.

- InboxMessagesResponse
  - `status` 'ok', required
  - `pagination` InboxDmPagination, required
    - `hasMore` boolean, required
    - `nextCursor` string, nullable, required: Pass back as `cursor` for the next page. `null` when the last page has been returned.
  - `sortOrderApplied` 'asc' | 'desc', required
  - `messages` InboxMessage[], required
    - `id` string, required: Platform message id.
    - `conversationId` string, required
    - `accountId` string, required
    - `platform` 'instagram', required
    - `message` string: Message text. Absent on an attachment-only message, and on older Instagram messages the platform no longer returns text for.
    - `senderId` string
    - `senderName` string
    - `direction` 'incoming' | 'outgoing', required: Resolved against the connected account’s own identity: `outgoing` is a message the account sent.
    - `createdAt` string, date-time, required
    - `attachments` InboxMessageAttachment[]
      - `id` string
      - `type` 'image' | 'video' | 'audio' | 'file', required
      - `url` string, uri, required: Platform-hosted URL. Meta expires these, so treat them as short-lived.
      - `previewUrl` string, uri
    - `template` InboxMessageTemplate
      - `elements` InboxMessageTemplateElement[], required: One element per card; more than one is a carousel.
        - `title` string, required: The card title, or the message text on a button-only template.
        - `subtitle` string
        - `imageUrl` string, uri
        - `buttons` InboxMessageTemplateButton[]
          - `type` 'url' | 'postback', required: `url` opens `url` in a browser. `postback` is a reply button handled inside Instagram; its payload is never exposed.
          - `title` string, required
          - `url` string, uri: Present on `url` buttons only.
    - `storyReply` boolean: Instagram only, and present only when the platform said so.
    - `isStoryMention` boolean: Instagram only, and present only when the platform said so.
  - `lastUpdated` string, date-time, required

## Other responses

- `400`: A parameter is missing or malformed — a plain `{ error }` body — or the account is not on a platform direct messages support (`platformUnsupported`).
- `401`: Missing or invalid API key.
- `403`: The account is outside the API key's profile access (`forbidden`), or the connection is missing the messaging scope this call needs (`platformCapabilityMissing`). Reconnect the account to grant it.
- `404`: No such account (`accountNotFound`) or no such conversation for that account (`conversationNotFound`).
- `424`: The connection needs to be reauthorized before its messages can be read (`connectionDead`).
- `429`: Rate limit exceeded. Retry after the interval indicated by the `Retry-After` header.
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/postzen/apis/postzen-public-api.md) · [All operations](https://skmtc.dev/postzen/apis/postzen-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/postzen/apis/postzen-public-api/revisions/40863e3710ec?raw)