> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kapso.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List messages

> Retrieve a paginated list of WhatsApp messages for a phone number.

Supports filtering by conversation, direction, status, and time range.
Uses cursor-based pagination for efficient scrolling through large result sets.




## OpenAPI

````yaml /api/meta/whatsapp/openapi-whatsapp.yaml get /{phone_number_id}/messages
openapi: 3.1.0
info:
  title: Kapso Meta Proxy API
  version: 1.0.0
  description: >
    Kapso's Meta Proxy API provides a unified interface to WhatsApp Business
    Platform with enhanced features and Kapso-specific extensions.


    This API acts as a proxy layer between your application and WhatsApp,
    adding:

    - Simplified authentication with project-level API keys

    - Enhanced message metadata and tracking

    - Conversation management capabilities

    - Voice call integration

    - Extended contact and template management


    ## Base URL


    All API requests are made to: `https://api.kapso.ai/meta/whatsapp/v24.0`


    ## Authentication


    The API supports authentication via **X-API-Key header** (recommended):


    ```

    X-API-Key: your_project_api_key

    ```


    Alternative: Bearer token authentication is also supported for backward
    compatibility:


    ```

    Authorization: Bearer your_access_token

    ```


    Note: X-API-Key is the recommended authentication method for the Meta Proxy
    API.
  contact:
    name: Kapso Support
    url: https://kapso.ai
    email: dev@kap.so
servers:
  - url: https://api.kapso.ai/meta/whatsapp/v24.0
    description: Production server
security:
  - ApiKeyAuth: []
  - BearerAuth: []
tags:
  - name: Messages
    description: Send and retrieve WhatsApp messages
  - name: Conversations
    description: Manage WhatsApp conversations
  - name: Contacts
    description: Manage WhatsApp contacts
  - name: Templates
    description: Manage message templates
  - name: Media
    description: Upload and retrieve media files
  - name: Calls
    description: Manage voice calls
  - name: Settings
    description: Account settings and configuration
  - name: Business Profile
    description: Business profile management
  - name: Phone Numbers
    description: Phone number management
  - name: Flows
    description: WhatsApp Flow management (Beta)
  - name: Block Users
    description: Block and unblock WhatsApp users
  - name: Usernames
    description: Reserve and manage WhatsApp business usernames
paths:
  /{phone_number_id}/messages:
    parameters:
      - name: phone_number_id
        in: path
        required: true
        description: WhatsApp Business Phone Number ID
        schema:
          type: string
        example: '110987654321'
    get:
      tags:
        - Messages
      summary: List messages
      description: >
        Retrieve a paginated list of WhatsApp messages for a phone number.


        Supports filtering by conversation, direction, status, and time range.

        Uses cursor-based pagination for efficient scrolling through large
        result sets.
      operationId: listMessages
      parameters:
        - name: conversation_id
          in: query
          description: Filter by conversation ID
          schema:
            type: string
          example: 123e4567-e89b-12d3-a456-426614174000
        - name: direction
          in: query
          description: Filter by message direction
          schema:
            type: string
            enum:
              - inbound
              - outbound
          example: inbound
        - name: status
          in: query
          description: Filter by message status
          schema:
            type: string
            enum:
              - pending
              - sent
              - delivered
              - read
              - failed
          example: delivered
        - name: since
          in: query
          description: Filter messages created on or after this time (ISO 8601)
          schema:
            type: string
            format: date-time
          example: '2024-01-15T00:00:00.000Z'
        - name: until
          in: query
          description: Filter messages created on or before this time (ISO 8601)
          schema:
            type: string
            format: date-time
          example: '2024-01-15T23:59:59.000Z'
        - name: limit
          in: query
          description: Maximum number of results per page (default 20, max 100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          example: 20
        - name: before
          in: query
          description: Cursor for previous page (Base64 encoded)
          schema:
            type: string
          example: >-
            eyJ2YWx1ZXMiOlsiMjAyNC0wMS0xNVQxMjozNDo1Ni4xMjM0NTZaIiwiMTIzNDUiXSwiY29sdW1ucyI6WyJjcmVhdGVkX2F0IiwiaWQiXX0=
        - name: after
          in: query
          description: Cursor for next page (Base64 encoded)
          schema:
            type: string
          example: >-
            eyJ2YWx1ZXMiOlsiMjAyNC0wMS0xNFQwOToyMTozMi43ODkwMTJaIiwiMTIzMjAiXSwiY29sdW1ucyI6WyJjcmVhdGVkX2F0IiwiaWQiXX0=
        - name: fields
          in: query
          description: >
            Filter response fields. Use `kapso()` to include Kapso-specific
            extensions.


            Example: `fields=kapso(direction,status,processing_status)`
          schema:
            type: string
          example: kapso()
      responses:
        '200':
          description: Successfully retrieved messages
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WhatsappMessageResponse'
                  paging:
                    $ref: '#/components/schemas/Paging'
              examples:
                inbound_text:
                  summary: Inbound text message
                  description: Basic text message from customer with core kapso fields
                  value:
                    data:
                      - id: >-
                          wamid.HBgNMTU1NTE0OTU5Nzg1FQIAERgSMDhGRjdBMDEyOTcxQzFFQkFBAA==
                        timestamp: '1705328096'
                        type: text
                        from: '15551234567'
                        text:
                          body: Hello! I need help with my order
                        kapso:
                          direction: inbound
                          status: delivered
                          processing_status: completed
                          phone_number: '+15551234567'
                          has_media: false
                          whatsapp_conversation_id: 123e4567-e89b-12d3-a456-426614174000
                          contact_name: John Doe
                          content: Hello! I need help with my order
                    paging:
                      cursors:
                        after: >-
                          eyJ2YWx1ZXMiOlsiMjAyNC0wMS0xNVQxMjozNDo1Ni4xMjM0NTZaIiwiMTIzNDUiXSwiY29sdW1ucyI6WyJjcmVhdGVkX2F0IiwiaWQiXX0=
                outbound_image:
                  summary: Outbound image with caption
                  description: Image message with media fields and type-specific data
                  value:
                    data:
                      - id: >-
                          wamid.HBgNMTU1NTE0OTU5Nzg1FQIAERgSMDhGRjdBMDEyOTcxQzFFQkFCAA==
                        timestamp: '1705328150'
                        type: image
                        to: '15551234567'
                        image:
                          id: abc123def456
                          caption: Your order has been shipped!
                        kapso:
                          direction: outbound
                          status: sent
                          processing_status: completed
                          phone_number: '+15551234567'
                          has_media: true
                          whatsapp_conversation_id: 123e4567-e89b-12d3-a456-426614174000
                          contact_name: John Doe
                          media_data:
                            url: https://api.kapso.ai/storage/media/abc123.jpg
                            filename: package.jpg
                            content_type: image/jpeg
                            byte_size: 245678
                          media_url: https://api.kapso.ai/storage/media/abc123.jpg
                          message_type_data:
                            caption: Your order has been shipped!
                            has_media: true
                    paging:
                      cursors:
                        after: >-
                          eyJ2YWx1ZXMiOlsiMjAyNC0wMS0xNVQxMjozNDo1Ni4xMjM0NTZaIiwiMTIzNDUiXSwiY29sdW1ucyI6WyJjcmVhdGVkX2F0IiwiaWQiXX0=
                template_message:
                  summary: Template message
                  description: Outbound template with template-specific kapso data
                  value:
                    data:
                      - id: >-
                          wamid.HBgNMTU1NTE0OTU5Nzg1FQIAERgSMDhGRjdBMDEyOTcxQzFFQkFDAA==
                        timestamp: '1705328200'
                        type: template
                        to: '15551234567'
                        template:
                          name: order_confirmation
                          language:
                            code: en_US
                          components:
                            - type: body
                              parameters:
                                - type: text
                                  text: John
                                - type: text
                                  text: ORD-12345
                        kapso:
                          direction: outbound
                          status: delivered
                          processing_status: completed
                          phone_number: '+15551234567'
                          has_media: false
                          whatsapp_conversation_id: 123e4567-e89b-12d3-a456-426614174000
                          contact_name: John Doe
                          message_type_data:
                            name: order_confirmation
                            language:
                              code: en_US
                            params:
                              - John
                              - ORD-12345
                    paging:
                      cursors:
                        after: >-
                          eyJ2YWx1ZXMiOlsiMjAyNC0wMS0xNVQxMjozNDo1Ni4xMjM0NTZaIiwiMTIzNDUiXSwiY29sdW1ucyI6WyJjcmVhdGVkX2F0IiwiaWQiXX0=
                interactive_message:
                  summary: Interactive button message
                  description: Interactive message with type-specific data
                  value:
                    data:
                      - id: >-
                          wamid.HBgNMTU1NTE0OTU5Nzg1FQIAERgSMDhGRjdBMDEyOTcxQzFFQkFEAA==
                        timestamp: '1705328250'
                        type: interactive
                        to: '15551234567'
                        interactive:
                          type: button
                          body:
                            text: Would you like to proceed with your order?
                        kapso:
                          direction: outbound
                          status: sent
                          processing_status: completed
                          phone_number: '+15551234567'
                          has_media: false
                          whatsapp_conversation_id: 123e4567-e89b-12d3-a456-426614174000
                          contact_name: John Doe
                          message_type_data:
                            type: button
                            body_text: Would you like to proceed with your order?
                    paging:
                      cursors:
                        after: >-
                          eyJ2YWx1ZXMiOlsiMjAyNC0wMS0xNVQxMjozNDo1Ni4xMjM0NTZaIiwiMTIzNDUiXSwiY29sdW1ucyI6WyJjcmVhdGVkX2F0IiwiaWQiXX0=
                location_message:
                  summary: Location share
                  description: Inbound location message with coordinates and details
                  value:
                    data:
                      - id: >-
                          wamid.HBgNMTU1NTE0OTU5Nzg1FQIAERgSMDhGRjdBMDEyOTcxQzFFQkFFAA==
                        timestamp: '1705328300'
                        type: location
                        from: '15551234567'
                        location:
                          latitude: 37.7749
                          longitude: -122.4194
                          name: Warehouse Location
                          address: 123 Main St, San Francisco, CA
                        kapso:
                          direction: inbound
                          status: delivered
                          processing_status: completed
                          phone_number: '+15551234567'
                          has_media: false
                          whatsapp_conversation_id: 123e4567-e89b-12d3-a456-426614174000
                          contact_name: John Doe
                          message_type_data:
                            latitude: 37.7749
                            longitude: -122.4194
                            name: Warehouse Location
                            address: 123 Main St, San Francisco, CA
                    paging:
                      cursors:
                        after: >-
                          eyJ2YWx1ZXMiOlsiMjAyNC0wMS0xNVQxMjozNDo1Ni4xMjM0NTZaIiwiMTIzNDUiXSwiY29sdW1ucyI6WyJjcmVhdGVkX2F0IiwiaWQiXX0=
        '400':
          description: Bad request (invalid parameters)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (invalid or missing API key)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Phone number not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    WhatsappMessageResponse:
      type: object
      required:
        - id
        - timestamp
        - type
      properties:
        id:
          type: string
          description: Message ID
          example: wamid.HBgNMTU1NTE0OTU5Nzg1FQIAERgSMDhGRjdBMDEyOTcxQzFFQkFBAA==
        timestamp:
          type: string
          description: Message timestamp (Unix timestamp as string)
          example: '1705328096'
        type:
          $ref: '#/components/schemas/MessageType'
        from:
          type: string
          nullable: true
          description: Sender WhatsApp ID (phone-based identity when available)
          example: '15551234567'
        from_user_id:
          type: string
          nullable: true
          description: Sender business-scoped user ID when available
          example: US.13491208655302741918
        from_parent_user_id:
          type: string
          nullable: true
          description: Sender parent business-scoped user ID when available
          example: US.ENT.506847293015824
        to:
          type: string
          nullable: true
          description: Recipient WhatsApp ID (phone-based identity when available)
          example: '110987654321'
        to_user_id:
          type: string
          nullable: true
          description: Recipient business-scoped user ID when available
          example: US.13491208655302741918
        to_parent_user_id:
          type: string
          nullable: true
          description: Recipient parent business-scoped user ID when available
          example: US.ENT.506847293015824
        username:
          type: string
          nullable: true
          description: WhatsApp username when available
          example: '@testusername'
        context:
          type: object
          description: Reply context
          properties:
            from:
              type: string
              description: Sender of the original message
            id:
              type: string
              description: ID of the message being replied to
            referred_product:
              type: object
              description: Product reference (for catalog messages)
              properties:
                catalog_id:
                  type: string
                product_retailer_id:
                  type: string
        text:
          $ref: '#/components/schemas/TextMessage'
        image:
          $ref: '#/components/schemas/MediaMessage'
        video:
          $ref: '#/components/schemas/MediaMessage'
        audio:
          $ref: '#/components/schemas/AudioMessage'
        document:
          $ref: '#/components/schemas/MediaMessage'
        sticker:
          $ref: '#/components/schemas/StickerMessage'
        location:
          $ref: '#/components/schemas/LocationMessage'
        contacts:
          type: array
          items:
            $ref: '#/components/schemas/ContactCard'
        order:
          $ref: '#/components/schemas/OrderMessage'
        interactive:
          type: object
          description: Interactive message content (for inbound interactive responses).
          properties:
            type:
              type: string
              enum:
                - button_reply
                - list_reply
                - nfm_reply
              description: |-
                Type of interactive response:
                - button_reply: Reply button was tapped
                - list_reply: List item was selected
                - nfm_reply: Native Flow Message (address_message, etc.)
              example: button_reply
            button_reply:
              type: object
              description: Reply button response
              properties:
                id:
                  type: string
                  description: Button ID that was tapped
                  example: button_1
                title:
                  type: string
                  description: Button title that was tapped
                  example: 'Yes'
            list_reply:
              type: object
              description: List selection response
              properties:
                id:
                  type: string
                  description: Row ID that was selected
                  example: row_express
                title:
                  type: string
                  description: Row title that was selected
                  example: Express Shipping
                description:
                  type: string
                  description: Row description
                  example: 1-2 business days
            nfm_reply:
              type: object
              description: Native Flow Message response (e.g., address_message)
              properties:
                name:
                  type: string
                  description: NFM action name
                  example: address_message
                response_json:
                  type: string
                  description: JSON string containing form response data
                  example: '{"values":{"name":"John Doe","in_pin_code":"400063"}}'
                body:
                  type: string
                  description: Human-readable summary of response
                  example: John Doe, +919876543210, 400063, Mumbai
        template:
          type: object
          description: Template message content
        reaction:
          $ref: '#/components/schemas/ReactionMessage'
        kapso:
          type: object
          description: Kapso-specific message extensions
          properties:
            direction:
              type: string
              enum:
                - inbound
                - outbound
              description: Message direction
              example: inbound
            status:
              type: string
              enum:
                - pending
                - sent
                - delivered
                - read
                - failed
              description: Delivery status
              example: delivered
            processing_status:
              type: string
              enum:
                - pending
                - processing
                - completed
                - failed
              description: Processing state
              example: completed
            phone_number:
              type: string
              nullable: true
              description: Associated phone number when phone-based identity is available
              example: '+15559876543'
            has_media:
              type: boolean
              description: Whether message has attached media files
              example: false
            whatsapp_conversation_id:
              type: string
              description: Conversation UUID
              example: 123e4567-e89b-12d3-a456-426614174000
            contact_name:
              type: string
              nullable: true
              description: Contact display name from conversation
              example: John Doe
            content:
              type: string
              nullable: true
              description: Message text content
              example: Hello! I need help with my order
            media_data:
              type: object
              description: Complete media information (when has_media is true)
              properties:
                url:
                  type: string
                  format: uri
                  description: Download URL for the media file
                  example: https://api.kapso.ai/storage/media/abc123.jpg
                filename:
                  type: string
                  description: Original filename
                  example: package.jpg
                content_type:
                  type: string
                  description: MIME type
                  example: image/jpeg
                byte_size:
                  type: integer
                  description: File size in bytes
                  example: 245678
            media_url:
              type: string
              format: uri
              description: >-
                Convenience field with just the media URL (when has_media is
                true)
              example: https://api.kapso.ai/storage/media/abc123.jpg
            message_type_data:
              type: object
              description: Type-specific message data (structure varies by message type)
              additionalProperties: true
            flow_response:
              type: object
              description: Flow response data (for Flow messages)
              additionalProperties: true
            flow_token:
              type: string
              description: Flow session token (for Flow messages)
              example: user_session_abc123
            flow_name:
              type: string
              description: Flow display name (for Flow messages)
              example: Appointment Booking
            order_text:
              type: string
              description: Order text (for order messages)
              example: I'd like to order this item
    Paging:
      type: object
      properties:
        cursors:
          $ref: '#/components/schemas/PaginationCursor'
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
            - type
            - code
          properties:
            message:
              type: string
              description: Human-readable error message
              example: Invalid phone number format
            type:
              type: string
              description: Error category
              example: OAuthException
            code:
              type: integer
              description: Error code
              example: 400
            error_subcode:
              type: integer
              description: More specific error code
              example: 1001
            fbtrace_id:
              type: string
              description: Facebook trace ID for debugging
              example: AXk7s_8dR4eVHp9Kq2MmNlO
    MessageType:
      type: string
      enum:
        - text
        - image
        - video
        - audio
        - document
        - sticker
        - location
        - contacts
        - interactive
        - template
        - reaction
      description: Type of WhatsApp message
    TextMessage:
      type: object
      required:
        - body
      properties:
        body:
          type: string
          description: Text content of the message
          example: Hello! How can I help you today?
        preview_url:
          type: boolean
          description: Whether to show URL preview (defaults to false if omitted)
          example: true
    MediaMessage:
      type: object
      properties:
        id:
          type: string
          description: |-
            Media ID from WhatsApp (uploaded media).
            Recommended over `link` for better performance.
          example: abc123def456
        link:
          type: string
          format: uri
          description: >-
            Public URL to media file (hosted media).

            Using uploaded media with `id` is recommended for better
            performance.
          example: https://example.com/image.jpg
        caption:
          type: string
          description: |-
            Media caption text.
            - Images: max 1024 characters
            - Videos: max 1024 characters
            - Documents: max 1024 characters

            Not supported for stickers or audio.
          maxLength: 1024
          example: Check out this photo!
        filename:
          type: string
          description: >-
            Filename with extension (for documents only).

            WhatsApp client displays appropriate file type icon based on
            extension.
          example: report.pdf
    AudioMessage:
      type: object
      properties:
        id:
          type: string
          description: Media ID from WhatsApp (uploaded media)
          example: abc123def456
        link:
          type: string
          format: uri
          description: >-
            Public URL to audio file (hosted media).

            Using uploaded media with `id` is recommended for better
            performance.
          example: https://example.com/audio.mp3
        voice:
          type: boolean
          description: >-
            Set to `true` for voice messages (voice notes with transcription
            support).

            Voice messages must be .ogg files encoded with OPUS codec.

            Set to `false` or omit for basic audio messages.


            Voice messages include: automatic download, profile picture, voice
            icon, and optional transcription.

            Basic audio messages display a download icon and music icon.
          example: true
    StickerMessage:
      type: object
      properties:
        id:
          type: string
          description: Media ID from WhatsApp
          example: abc123def456
        link:
          type: string
          format: uri
          description: Public URL to sticker file
          example: https://example.com/sticker.webp
        mime_type:
          type: string
          description: MIME type of the sticker
          example: image/webp
        animated:
          type: boolean
          description: Whether the sticker is animated
          example: false
    LocationMessage:
      type: object
      required:
        - latitude
        - longitude
      properties:
        latitude:
          type: number
          format: double
          description: Latitude coordinate
          example: 37.7749
        longitude:
          type: number
          format: double
          description: Longitude coordinate
          example: -122.4194
        name:
          type: string
          description: Location name
          example: Golden Gate Bridge
        address:
          type: string
          description: Location address
          example: San Francisco, CA
    ContactCard:
      type: object
      required:
        - name
      properties:
        addresses:
          type: array
          description: Physical addresses for the contact
          items:
            type: object
            properties:
              street:
                type: string
                description: Street number and name
                example: 1 Lucky Shrub Way
              city:
                type: string
                description: City name
                example: Menlo Park
              state:
                type: string
                description: State abbreviation or full name
                example: CA
              zip:
                type: string
                description: ZIP or postal code
                example: '94025'
              country:
                type: string
                description: Full country name
                example: United States
              country_code:
                type: string
                description: Two-letter country code (ISO 3166-1 alpha-2)
                example: US
              type:
                type: string
                description: Address type (HOME, WORK, etc.)
                example: WORK
        birthday:
          type: string
          format: date
          description: Contact's birthday in YYYY-MM-DD format
          example: '1999-01-23T00:00:00.000Z'
        emails:
          type: array
          items:
            type: object
            properties:
              email:
                type: string
                example: john@example.com
              type:
                type: string
                example: WORK
        name:
          type: object
          required:
            - formatted_name
          properties:
            formatted_name:
              type: string
              description: Full formatted name (appears in message)
              maxLength: 200
              example: Barbara J. Johnson
            first_name:
              type: string
              description: First name
              example: Barbara
            last_name:
              type: string
              description: Last name
              example: Johnson
            middle_name:
              type: string
              description: Middle name
              example: Joana
            suffix:
              type: string
              description: Name suffix (Jr., Sr., etc.)
              example: Esq.
            prefix:
              type: string
              description: Name prefix (Dr., Mr., Ms., etc.)
              example: Dr.
        org:
          type: object
          description: Organization information
          properties:
            company:
              type: string
              description: Company name
              example: Lucky Shrub
            department:
              type: string
              description: Department name
              example: Legal
            title:
              type: string
              description: Job title
              example: Lead Counsel
        phones:
          type: array
          items:
            type: object
            properties:
              phone:
                type: string
                description: Phone number
                example: '+15551234567'
              type:
                type: string
                description: Phone type (MOBILE, HOME, WORK, etc.)
                example: MOBILE
              wa_id:
                type: string
                description: >-
                  WhatsApp ID for this phone number.

                  If omitted, message will display "Invite to WhatsApp" button
                  instead of "Message" button.
                example: '15551234567'
        urls:
          type: array
          description: Website URLs associated with the contact
          items:
            type: object
            properties:
              url:
                type: string
                format: uri
                description: Website URL
                example: https://www.luckyshrub.com
              type:
                type: string
                description: Website type (WORK, HOME, etc.)
                example: WORK
    OrderMessage:
      type: object
      properties:
        catalog_id:
          type: string
          description: Catalog ID
          example: cat_12345
        product_items:
          type: array
          description: Array of product items
          items:
            type: object
        order_text:
          type: string
          description: Order text
          example: I'd like to order this item
    ReactionMessage:
      type: object
      required:
        - message_id
        - emoji
      properties:
        message_id:
          type: string
          description: ID of message to react to
          example: wamid.HBgNMTU1NTE...
        emoji:
          type: string
          description: Emoji to react with
          example: 👍
    PaginationCursor:
      type: object
      properties:
        before:
          type: string
          description: Cursor for previous page (Base64 encoded)
          example: >-
            eyJ2YWx1ZXMiOlsiMjAyNC0wMS0xNVQxMjozNDo1Ni4xMjM0NTZaIiwiMTIzNDUiXSwiY29sdW1ucyI6WyJjcmVhdGVkX2F0IiwiaWQiXX0=
        after:
          type: string
          description: Cursor for next page (Base64 encoded)
          example: >-
            eyJ2YWx1ZXMiOlsiMjAyNC0wMS0xNFQwOToyMTozMi43ODkwMTJaIiwiMTIzMjAiXSwiY29sdW1ucyI6WyJjcmVhdGVkX2F0IiwiaWQiXX0=
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >
        Project API key for authentication. This is the recommended
        authentication method.


        Get your API key from the Kapso dashboard under Integrations > API keys.
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        Bearer token authentication (alternative method).

        Note: X-API-Key authentication is recommended for the Meta Proxy API.

````