---
title: "List messages"
method: GET
path: "/whatsapp/messages"
tags: ["Messages"]
---

# List messages

`GET /whatsapp/messages`

Query WhatsApp messages across all conversations. Results are returned newest first. Use cursor pagination (`limit`, `after`, `before`) to traverse large message histories efficiently.

## Query parameters

- `phone_number_id` string
- `conversation_id` string, uuid
- `phone_number` string
- `business_scoped_user_id` string
- `direction` 'inbound' | 'outbound'
- `status` 'pending' | 'sent' | 'delivered' | 'read' | 'failed'
- `message_type` string
- `has_media` boolean
- `limit` integer
- `before` string
- `after` string

## Response `200`

List of messages

- WhatsappMessageListResponse
  - `data` WhatsappMessage[], required
    - `id` string, required — WhatsApp message ID (WAMID)
    - `timestamp` string, required — Unix timestamp in seconds (as string per Meta convention)
    - `type` 'text' | 'image' | 'video' | 'audio' | 'document' | 'location' | 'interactive' | 'template' | 'reaction' | 'contacts' | 'sticker' | 'button' | 'order', required — Message type
    - `from` string, nullable — Sender phone number when phone-based identity is available
    - `from_user_id` string, nullable — Sender business-scoped user ID when available
    - `from_parent_user_id` string, nullable — Sender parent business-scoped user ID when available
    - `to` string, nullable — Recipient phone number when phone-based identity is available
    - `to_user_id` string, nullable — Recipient business-scoped user ID when available
    - `to_parent_user_id` string, nullable — Recipient parent business-scoped user ID when available
    - `username` string, nullable — WhatsApp username when available
    - `context` object — Reply context when message is a reply
      - `id` string — ID of the message being replied to
      - `from` string — Phone number of original message sender
      - `referred_product` object — Product being referenced
    - `text` object — Text message payload (when type=text)
      - `body` string
    - `image` object — Image message payload (when type=image)
      - `id` string — Media ID from Meta
      - `link` string, uri
      - `caption` string
    - `video` object — Video message payload (when type=video)
      - `id` string
      - `link` string, uri
      - `caption` string
    - `audio` object — Audio message payload (when type=audio)
      - `id` string
      - `link` string, uri
    - `document` object — Document message payload (when type=document)
      - `id` string
      - `link` string, uri
      - `filename` string
      - `caption` string
    - `location` object — Location message payload (when type=location)
      - `latitude` number
      - `longitude` number
      - `name` string
      - `address` string
    - `sticker` object — Sticker message payload (when type=sticker)
      - `id` string
      - `link` string, uri
      - `mime_type` string
      - `animated` boolean
    - `interactive` object — Interactive message payload (when type=interactive)
    - `button` object — Button response payload (when type=button)
      - `text` string
      - `payload` string
    - `template` object — Template message payload (when type=template)
      - `name` string
      - `language` object
        - `code` string
      - `components` object[]
    - `reaction` object — Reaction message payload (when type=reaction)
      - `emoji` string
      - `message_id` string
    - `contacts` object[] — Contacts message payload (when type=contacts)
    - `order` object — Order message payload (when type=order)
      - `catalog_id` string
      - `product_items` object[]
      - `order_text` string
    - `kapso` object, required — Kapso-specific extensions
      - `direction` 'inbound' | 'outbound', required
      - `status` 'pending' | 'sent' | 'delivered' | 'read' | 'failed', required
      - `processing_status` 'pending' | 'processed' | 'blocked'
      - `origin` 'cloud_api' | 'business_app' | 'history_sync' — Message origin
      - `phone_number` string, nullable — Contact phone number
      - `phone_number_id` string, nullable — Meta phone number ID for the WhatsApp number
      - `has_media` boolean
      - `whatsapp_conversation_id` string, uuid, required — Kapso conversation ID
      - `contact_name` string, nullable — Contact name if available
      - `content` string, nullable — Text content of the message
      - `statuses` object[] — Status event history (raw Meta payloads)
      - `transcript` object — Audio transcript (for audio messages)
        - `text` string
      - `media_data` object — Media attachment details
        - `url` string, uri
        - `filename` string
        - `content_type` string
        - `byte_size` integer
      - `media_url` string, uri — Direct media URL
      - `message_type_data` object — Type-specific data (caption, template params, etc.)
      - `flow_response` object — WhatsApp Flow response data
      - `flow_token` string
      - `flow_name` string
      - `order_text` string — Order text for order messages
  - `paging` Paging, required
    - `cursors` PaginationCursor
      - `before` string — Cursor for previous page (Base64 encoded)
      - `after` string — Cursor for next page (Base64 encoded)
    - `next` string, nullable
    - `previous` string, nullable

## Other responses

- `401` — Missing or invalid API key

---

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