---
title: "List messages"
method: GET
path: "/v2/messages"
tags: ["messaging"]
---

# List messages

`GET /v2/messages`

Lists the current user's messages from their connected social accounts, ordered by creation time (most recent first). Supports cursor-based pagination and filtering by platform and conversation.

## Query parameters

- `limit` integer
- `cursor` string
- `conversationId` string
- `platform` string[]
- `accountId` string

## Response `200`

Default Response

- object
  - `items` object[], required — List of messages.
    - `conversationId` string, nullable, required — Parent Blotato conversation id.
    - `createdAt` string, required
    - `direction` 'incoming' | 'outgoing', required
    - `errorCode` integer, nullable, required — Set only when status is `failed`.
    - `errorMessage` string, nullable, required — Set only when status is `failed`.
    - `id` string, required
    - `payload` object, nullable
      - `attachment` object
        - `type` 'button', required
        - `buttons` union[], required — Up to 3 call-to-action buttons attached to the message.
          - union
            - object
              - …
            - object
              - …
      - `quickReplies` object[]
        - `title` string, required — Chip label shown to the recipient.
        - `payload` string, required — Message replied with on chip selection.
      - `selection` object
        - `payload` string, nullable, required
        - `type` 'postback' | 'quick-reply', required
    - `platform` 'facebook' | 'instagram', required
    - `recipientId` string, required
    - `senderId` string, nullable, required
    - `status` 'delivered' | 'failed' | 'processing' | 'queued' | 'sent', required
    - `text` string, required
  - `cursor` string — Cursor for the next page. Absent when there are no more messages.

## Other responses

- `403` — Forbidden
- `404` — Not found
- `422` — Validation error
- `500` — Server error

---

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