> ## 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

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




## OpenAPI

````yaml /api/platform/v1/openapi-platform.yaml get /whatsapp/messages
openapi: 3.1.0
info:
  title: Kapso Platform API
  version: 0.2.0
  description: >
    Build WhatsApp messaging into your product. Manage customers, connect phone
    numbers, send broadcasts, and handle conversations.
servers:
  - url: https://api.kapso.ai/platform/v1
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Customers
    description: Manage customer accounts
  - name: Setup Links
    description: WhatsApp onboarding via embedded signup
  - name: Phone Numbers
    description: Connect and manage WhatsApp numbers
  - name: Webhooks
    description: Subscribe to WhatsApp events
  - name: Display Names
    description: Update WhatsApp business display names
  - name: Broadcasts
    description: |
      Send template messages at scale

      **Alpha**: This API is in alpha and subject to change
  - name: Conversations
    description: Manage conversation state
  - name: Media
    description: Upload media files for WhatsApp messaging
  - name: Users
    description: Manage project team members
  - name: Inbox Embeds
    description: Create and manage embeddable inbox access links
  - name: Webhook Deliveries
    description: View webhook delivery attempts and their status
  - name: External API Logs
    description: View logs of external API calls made by the project
  - name: Log Search
    description: Search log events across API, Meta, workflow, and webhook sources
  - name: Events
    description: Emit and query project-scoped events
  - name: Provider Models
    description: List available AI provider models
  - name: WhatsApp Flows
    description: Build interactive WhatsApp Flows for surveys and forms
  - name: Contacts
    description: Manage WhatsApp contacts
paths:
  /whatsapp/messages:
    get:
      tags:
        - Messages
      summary: List messages
      description: >
        Query WhatsApp messages across all conversations. Results are returned
        newest first. Use cursor pagination (`limit`, `after`, `before`) to
        traverse large message histories efficiently.
      operationId: listWhatsappMessages
      parameters:
        - name: phone_number_id
          in: query
          description: Filter by WhatsApp phone number ID
          schema:
            type: string
        - name: conversation_id
          in: query
          description: Filter by conversation ID
          schema:
            type: string
            format: uuid
        - name: phone_number
          in: query
          description: Filter by contact phone number (partial match)
          schema:
            type: string
        - name: business_scoped_user_id
          in: query
          description: Filter by exact WhatsApp business-scoped user ID
          schema:
            type: string
        - name: direction
          in: query
          description: Filter by message direction
          schema:
            type: string
            enum:
              - inbound
              - outbound
        - name: status
          in: query
          description: Filter by message status
          schema:
            type: string
            enum:
              - pending
              - sent
              - delivered
              - read
              - failed
        - name: message_type
          in: query
          description: Filter by message type
          schema:
            type: string
        - name: has_media
          in: query
          description: Filter messages with media attachments
          schema:
            type: boolean
        - name: limit
          in: query
          description: >-
            Maximum number of results per cursor-paginated page (default 20, max
            100).
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: before
          in: query
          description: Cursor for the previous page (Base64 encoded).
          schema:
            type: string
        - name: after
          in: query
          description: Cursor for the next page (Base64 encoded).
          schema:
            type: string
      responses:
        '200':
          description: List of messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WhatsappMessageListResponse'
              examples:
                messages:
                  value:
                    data:
                      - id: wamid.HBgMMTIzNDU2Nzg5MBUCABIYGTA5RTlCQkI2NTI3
                        timestamp: '1705395000'
                        type: text
                        from: '14155550123'
                        text:
                          body: Hello, I need help with my order
                        kapso:
                          direction: inbound
                          status: delivered
                          processing_status: processed
                          origin: cloud_api
                          phone_number: '14155550123'
                          phone_number_id: '123456789012345'
                          has_media: false
                          whatsapp_conversation_id: c63ced48-1283-4d55-8c8d-930f525aa0e5
                          contact_name: Alicia
                          content: Hello, I need help with my order
                    paging:
                      cursors:
                        before: >-
                          eyJ2YWx1ZXMiOlsiMjAyNi0wMy0yNlQxNTowNTowMC4wMDAwMDBaIiwiMzQzMCJdLCJjb2x1bW5zIjpbImNyZWF0ZWRfYXQiLCJpZCJdfQ==
                        after: >-
                          eyJ2YWx1ZXMiOlsiMjAyNi0wMy0yNlQxNTowMDowMC4wMDAwMDBaIiwiMzQyMSJdLCJjb2x1bW5zIjpbImNyZWF0ZWRfYXQiLCJpZCJdfQ==
                      next: >-
                        eyJ2YWx1ZXMiOlsiMjAyNi0wMy0yNlQxNTowMDowMC4wMDAwMDBaIiwiMzQyMSJdLCJjb2x1bW5zIjpbImNyZWF0ZWRfYXQiLCJpZCJdfQ==
                      previous: null
        '401':
          $ref: '#/components/responses/UnauthorizedError'
components:
  schemas:
    WhatsappMessageListResponse:
      type: object
      required:
        - data
        - paging
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/WhatsappMessage'
        paging:
          $ref: '#/components/schemas/Paging'
    WhatsappMessage:
      type: object
      description: |
        WhatsApp message in Meta-compatible format with Kapso extensions.
        The structure mirrors Meta's webhook payload format.
      required:
        - id
        - timestamp
        - type
        - kapso
      properties:
        id:
          type: string
          description: WhatsApp message ID (WAMID)
          example: wamid.HBgLMTU1NTEyMzQ1NjcVAgASGBQzQUY5
        timestamp:
          type: string
          description: Unix timestamp in seconds (as string per Meta convention)
          example: '1705329600'
        type:
          type: string
          description: Message type
          enum:
            - text
            - image
            - video
            - audio
            - document
            - location
            - interactive
            - template
            - reaction
            - contacts
            - sticker
            - button
            - order
        from:
          type:
            - string
            - 'null'
          description: Sender phone number when phone-based identity is available
          example: '15551234567'
        from_user_id:
          type:
            - string
            - 'null'
          description: Sender business-scoped user ID when available
          example: US.13491208655302741918
        from_parent_user_id:
          type:
            - string
            - 'null'
          description: Sender parent business-scoped user ID when available
          example: US.ENT.506847293015824
        to:
          type:
            - string
            - 'null'
          description: Recipient phone number when phone-based identity is available
          example: '15551234567'
        to_user_id:
          type:
            - string
            - 'null'
          description: Recipient business-scoped user ID when available
          example: US.13491208655302741918
        to_parent_user_id:
          type:
            - string
            - 'null'
          description: Recipient parent business-scoped user ID when available
          example: US.ENT.506847293015824
        username:
          type:
            - string
            - 'null'
          description: WhatsApp username when available
          example: '@testusername'
        context:
          type: object
          description: Reply context when message is a reply
          properties:
            id:
              type: string
              description: ID of the message being replied to
            from:
              type: string
              description: Phone number of original message sender
            referred_product:
              type: object
              description: Product being referenced
              additionalProperties: true
        text:
          type: object
          description: Text message payload (when type=text)
          properties:
            body:
              type: string
        image:
          type: object
          description: Image message payload (when type=image)
          properties:
            id:
              type: string
              description: Media ID from Meta
            link:
              type: string
              format: uri
            caption:
              type: string
        video:
          type: object
          description: Video message payload (when type=video)
          properties:
            id:
              type: string
            link:
              type: string
              format: uri
            caption:
              type: string
        audio:
          type: object
          description: Audio message payload (when type=audio)
          properties:
            id:
              type: string
            link:
              type: string
              format: uri
        document:
          type: object
          description: Document message payload (when type=document)
          properties:
            id:
              type: string
            link:
              type: string
              format: uri
            filename:
              type: string
            caption:
              type: string
        location:
          type: object
          description: Location message payload (when type=location)
          properties:
            latitude:
              type: number
            longitude:
              type: number
            name:
              type: string
            address:
              type: string
        sticker:
          type: object
          description: Sticker message payload (when type=sticker)
          properties:
            id:
              type: string
            link:
              type: string
              format: uri
            mime_type:
              type: string
            animated:
              type: boolean
        interactive:
          type: object
          description: Interactive message payload (when type=interactive)
          additionalProperties: true
        button:
          type: object
          description: Button response payload (when type=button)
          properties:
            text:
              type: string
            payload:
              type: string
        template:
          type: object
          description: Template message payload (when type=template)
          properties:
            name:
              type: string
            language:
              type: object
              properties:
                code:
                  type: string
            components:
              type: array
              items:
                type: object
                additionalProperties: true
        reaction:
          type: object
          description: Reaction message payload (when type=reaction)
          properties:
            emoji:
              type: string
            message_id:
              type: string
        contacts:
          type: array
          description: Contacts message payload (when type=contacts)
          items:
            type: object
            additionalProperties: true
        order:
          type: object
          description: Order message payload (when type=order)
          properties:
            catalog_id:
              type: string
            product_items:
              type: array
              items:
                type: object
                additionalProperties: true
            order_text:
              type: string
        kapso:
          type: object
          description: Kapso-specific extensions
          required:
            - direction
            - status
            - whatsapp_conversation_id
          properties:
            direction:
              type: string
              enum:
                - inbound
                - outbound
            status:
              type: string
              enum:
                - pending
                - sent
                - delivered
                - read
                - failed
            processing_status:
              type: string
              enum:
                - pending
                - processed
                - blocked
            origin:
              type: string
              description: Message origin
              enum:
                - cloud_api
                - business_app
                - history_sync
            phone_number:
              type:
                - string
                - 'null'
              description: Contact phone number
            phone_number_id:
              type:
                - string
                - 'null'
              description: Meta phone number ID for the WhatsApp number
            has_media:
              type: boolean
            whatsapp_conversation_id:
              type: string
              format: uuid
              description: Kapso conversation ID
            contact_name:
              type:
                - string
                - 'null'
              description: Contact name if available
            content:
              type:
                - string
                - 'null'
              description: Text content of the message
            statuses:
              type: array
              description: Status event history (raw Meta payloads)
              items:
                type: object
                additionalProperties: true
            transcript:
              type: object
              description: Audio transcript (for audio messages)
              properties:
                text:
                  type: string
            media_data:
              type: object
              description: Media attachment details
              properties:
                url:
                  type: string
                  format: uri
                filename:
                  type: string
                content_type:
                  type: string
                byte_size:
                  type: integer
            media_url:
              type: string
              format: uri
              description: Direct media URL
            message_type_data:
              type: object
              description: Type-specific data (caption, template params, etc.)
              additionalProperties: true
            flow_response:
              type: object
              description: WhatsApp Flow response data
              additionalProperties: true
            flow_token:
              type: string
            flow_name:
              type: string
            order_text:
              type: string
              description: Order text for order messages
    Paging:
      type: object
      properties:
        cursors:
          $ref: '#/components/schemas/PaginationCursor'
        next:
          type: string
          nullable: true
        previous:
          type: string
          nullable: true
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
    PaginationCursor:
      type: object
      properties:
        before:
          type: string
          description: Cursor for previous page (Base64 encoded)
        after:
          type: string
          description: Cursor for next page (Base64 encoded)
  responses:
    UnauthorizedError:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````