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

# List WhatsApp messages

`GET /v2/whatsapp/messages`

Retrieves a list of WhatsApp messages for your account with flexible date filtering.

Messages are returned in reverse chronological order (newest first).

**Date Filtering:**
- Preset ranges (last_week, last_thirty, last_month): Calculated using your account timezone
- Custom date ranges: Use RFC3339 timestamps (max 90 days)
- The 'all' option provides up to 365 days of history
- All timestamps in responses are returned in UTC format

**Pagination:**
- Cursor-based pagination for efficient data retrieval
- Control page size with the limit parameter (1-100 messages per page)

## Query parameters

- `date_range` 'last_week' | 'last_thirty' | 'last_month' | 'all' | 'custom_date'
- `start_date` string
- `end_date` string
- `limit` integer
- `cursor` string
- `direction` 'next' | 'prev'
- `campaign_id` string, uuid

## Response `200`

OK

- object
  - `data` object, required — Container for the list of WhatsApp messages.
    - `messages` WhatsappListMessageItem[], required — Array of WhatsApp messages.
      - `id` string, required — Unique identifier for the message.
      - `message_ref` string — Optional reference ID set by the user for the message.
      - `campaign_id` string — UUID of the campaign that produced this message. Omitted when the message is not associated with a campaign.
      - `sender` string, phone, required — Registered WhatsApp sender number in international format.
      - `recipient` string, phone, required — WhatsApp recipient phone number in international format.
      - `content_type` 'text' | 'template' | 'custom', required — Type of the message content.
      - `content` union, required — Content details for the message.
        - object
          - `text` Text, required — Text content for the message.
            - `message` string, required — The text message body.
        - object
          - `template` Template, required — Template details for the message content.
            - `name` string, required — The **exact name** of the WhatsApp template. - **Format:** Lowercase, alphanumeric, underscores only. - **Example:** `order_confirmation` - **Must be pre-approved** in your WhatsApp Business account.
            - `parameters` string[] — The **dynamic values** to populate placeholdes in the template message. - The number of parameters **must match** the template placeholders. - Supports **text only** (strings). Other types (e.g., images, documents) are not allowed. - **Example Usage:** - Template: `"Hello, {1}! Your order {2} has been shipped."` - Parameters: `["Tony", "#12345"]` - Final message: `"Hello, Tony! Your order #12345 has been shipped."`
            - `locale` string — Optional locale for the template (e.g., en_US), if not provided, the default locale is `en`.
        - object
          - `custom` Custom, required — Custom content following the Meta Cloud API guidelines.
      - `status` 'QUEUED' | 'SENT' | 'DELIVERED' | 'READ' | 'FAILED', required — Current status of a WhatsApp message.
      - `created_at` string, date-time, required — Timestamp in RFC3339 format (e.g., 2025-08-26T10:30:00Z) when the message was created on the server.
  - `request` object — Optional metadata (e.g. requestId, traceId)
  - `meta` object — Metadata for the list messages response including pagination details.
    - `pagination` PaginationMeta, required — Pagination metadata for cursor-based pagination. Reusable across all paginated API endpoints.
      - `type` 'cursor', required — The pagination strategy being used.
      - `next_cursor` string, nullable — Cursor to fetch the next page of results. Omitted if there are no more results.
      - `prev_cursor` string, nullable — Cursor to fetch the previous page of results. Omitted if on the first page.
      - `has_next` boolean, required — Indicates whether there are more results available after the current page.
      - `has_prev` boolean, required — Indicates whether there are results available before the current page.

## Other responses

- `400` — Input Validation Error
- `401` — Unauthorized
- `500` — Internal Server Error

---

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