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

> Retrieve a paginated list of WhatsApp voice calls.

**Kapso Extension**: This endpoint returns call records stored in Kapso's database, not Meta's API.

Supports filtering by direction, status, and time range. Uses cursor-based pagination.




## OpenAPI

````yaml /api/meta/whatsapp/openapi-whatsapp.yaml get /{phone_number_id}/calls
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}/calls:
    parameters:
      - name: phone_number_id
        in: path
        required: true
        description: WhatsApp Business Phone Number ID
        schema:
          type: string
        example: '110987654321'
    get:
      tags:
        - Calls
      summary: List calls
      description: >
        Retrieve a paginated list of WhatsApp voice calls.


        **Kapso Extension**: This endpoint returns call records stored in
        Kapso's database, not Meta's API.


        Supports filtering by direction, status, and time range. Uses
        cursor-based pagination.
      operationId: listCalls
      parameters:
        - name: direction
          in: query
          description: Filter by call direction
          schema:
            type: string
            enum:
              - inbound
              - outbound
          example: inbound
        - name: status
          in: query
          description: Filter by call status
          schema:
            type: string
            enum:
              - initiated
              - ringing
              - answered
              - completed
              - failed
          example: completed
        - name: since
          in: query
          description: Filter calls started 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 calls started 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
        - name: before
          in: query
          description: Cursor for previous page (Base64 encoded)
          schema:
            type: string
        - name: after
          in: query
          description: Cursor for next page (Base64 encoded)
          schema:
            type: string
        - name: fields
          in: query
          description: Filter response fields
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved calls
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WhatsappCall'
                  paging:
                    $ref: '#/components/schemas/Paging'
              examples:
                success:
                  summary: List of calls
                  value:
                    data:
                      - id: 123e4567-e89b-12d3-a456-426614174000
                        call_id: call_abc123
                        direction: inbound
                        status: completed
                        duration_seconds: 180
                        started_at: '2024-01-15T12:34:56.123Z'
                        ended_at: '2024-01-15T12:37:56.123Z'
                        session_started_at: '2024-01-15T12:34:58.123Z'
                        created_at: '2024-01-15T12:34:56.000Z'
                        updated_at: '2024-01-15T12:37:56.000Z'
                        user_wa_id: '15551234567'
                        whatsapp_contact_id: 223e4567-e89b-12d3-a456-426614174001
                        whatsapp_conversation_id: 323e4567-e89b-12d3-a456-426614174002
                        project_id: 423e4567-e89b-12d3-a456-426614174003
                        whatsapp_config_id: 523e4567-e89b-12d3-a456-426614174004
                        config_display_name: Support Line
                        config_display_phone_number: +1 (555) 123-4567
                        phone_number_id: '110987654321'
                        whatsapp_contact:
                          id: 223e4567-e89b-12d3-a456-426614174001
                          wa_id: '15551234567'
                          profile_name: John Doe
                          display_name: John (VIP Customer)
                        whatsapp_conversation:
                          id: 323e4567-e89b-12d3-a456-426614174002
                          phone_number: '15551234567'
                          status: active
                          last_active_at: '2024-01-15T14:30:00.000Z'
                      - id: 724e4567-e89b-12d3-a456-426614174006
                        call_id: call_def456
                        direction: outbound
                        status: failed
                        duration_seconds: null
                        started_at: '2024-01-15T10:20:15.123Z'
                        ended_at: null
                        session_started_at: null
                        created_at: '2024-01-15T10:20:15.000Z'
                        updated_at: '2024-01-15T10:20:30.000Z'
                        user_wa_id: '15559876543'
                        whatsapp_contact_id: 824e4567-e89b-12d3-a456-426614174007
                        whatsapp_conversation_id: null
                        project_id: 423e4567-e89b-12d3-a456-426614174003
                        whatsapp_config_id: 523e4567-e89b-12d3-a456-426614174004
                        config_display_name: Support Line
                        config_display_phone_number: +1 (555) 123-4567
                        phone_number_id: '110987654321'
                        whatsapp_contact:
                          id: 824e4567-e89b-12d3-a456-426614174007
                          wa_id: '15559876543'
                          profile_name: Jane Smith
                          display_name: null
                        whatsapp_conversation: null
                    paging:
                      cursors:
                        after: >-
                          eyJ2YWx1ZXMiOlsiMjAyNC0wMS0xNVQxMDoyMDoxNS4wMDAwMDBaIiwiNzI0ZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDA2Il0sImNvbHVtbnMiOlsiY2FsbF90aW1lc3RhbXAiLCJpZCJdfQ==
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    WhatsappCall:
      type: object
      required:
        - id
        - project_id
        - whatsapp_config_id
        - phone_number_id
      properties:
        id:
          type: string
          description: Call ID (UUID)
          example: 123e4567-e89b-12d3-a456-426614174000
        call_id:
          type: string
          description: WhatsApp call ID
          example: call_abc123
        direction:
          type: string
          enum:
            - inbound
            - outbound
          description: Call direction
          example: inbound
        status:
          type: string
          enum:
            - initiated
            - ringing
            - answered
            - completed
            - failed
          description: Call status
          example: completed
        duration_seconds:
          type: integer
          nullable: true
          description: Call duration in seconds
          example: 180
        started_at:
          type: string
          format: date-time
          nullable: true
          description: Call start time
          example: '2024-01-15T12:34:56.123Z'
        ended_at:
          type: string
          format: date-time
          nullable: true
          description: Call end time
          example: '2024-01-15T12:37:56.123Z'
        session_started_at:
          type: string
          format: date-time
          nullable: true
          description: Session start time
          example: '2024-01-15T12:34:58.123Z'
        created_at:
          type: string
          format: date-time
          description: Record creation timestamp
          example: '2024-01-15T12:34:56.000Z'
        updated_at:
          type: string
          format: date-time
          description: Record update timestamp
          example: '2024-01-15T12:37:56.000Z'
        user_wa_id:
          type: string
          nullable: true
          description: User's WhatsApp ID (phone number) when available
          example: '15551234567'
        business_scoped_user_id:
          type: string
          nullable: true
          description: User business-scoped user ID when available
          example: US.13491208655302741918
        parent_business_scoped_user_id:
          type: string
          nullable: true
          description: User parent business-scoped user ID when available
          example: US.ENT.506847293015824
        username:
          type: string
          nullable: true
          description: WhatsApp username when available
          example: '@testusername'
        whatsapp_contact_id:
          type: string
          nullable: true
          description: Associated contact ID (UUID)
          example: 223e4567-e89b-12d3-a456-426614174001
        whatsapp_conversation_id:
          type: string
          nullable: true
          description: Associated conversation ID (UUID)
          example: 323e4567-e89b-12d3-a456-426614174002
        project_id:
          type: string
          description: Project ID (UUID)
          example: 423e4567-e89b-12d3-a456-426614174003
        whatsapp_config_id:
          type: string
          description: WhatsApp configuration ID (UUID)
          example: 523e4567-e89b-12d3-a456-426614174004
        config_display_name:
          type: string
          nullable: true
          description: Configuration display name
          example: Support Line
        config_display_phone_number:
          type: string
          nullable: true
          description: Configuration display phone number
          example: +1 (555) 123-4567
        phone_number_id:
          type: string
          description: WhatsApp Business Phone Number ID
          example: '110987654321'
        whatsapp_contact:
          type: object
          nullable: true
          description: Associated contact (basic view)
          properties:
            id:
              type: string
            wa_id:
              type: string
            profile_name:
              type: string
            display_name:
              type: string
        whatsapp_conversation:
          type: object
          nullable: true
          description: Associated conversation (basic view)
          properties:
            id:
              type: string
            phone_number:
              type: string
            status:
              type: string
            last_active_at:
              type: string
              format: date-time
    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
    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.

````