WhatsApp Calls API

Use the **`/{Phone-Number-ID}/calls`** endpoint to initiate, manage, and terminate WhatsApp calls. This API allows businesses to handle voice calling functionality through the WhatsApp Business Platform. ## Prerequisites * [User Access Token](https://developers.facebook.com/docs/facebook-login/access-tokens#usertokens) with **`whatsapp_business_messaging`** permission * `phone-number-id` for your registered WhatsApp account * Call request permission from the WhatsApp user ## Call Actions - **connect**: Initiate a new call - **pre_accept**: Pre-accept a call (prepare for accepting) - **accept**: Accept an incoming call - **reject**: Reject an incoming call - **terminate**: Terminate an active call ## Session Description Protocol (SDP) For actions that require audio/video negotiation (connect, accept), you must provide session information including: - `sdp_type`: Must be "offer" for connect action, "answer" for accept action - `sdp`: RFC 8866 compliant SDP information ## Error Handling Error code 138006 indicates lack of call request permission for the business number from the WhatsApp user.

Documentation GitHub OpenAPI

Operations 1

POST /{Version}/{Phone-Number-ID}/calls Manage Calls #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/whatsapp:whatsapp-calls-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Meta Graph API - Application Connected Client Businesses…
  version: v23.0
  description: 'API for retrieving connected client businesses associated with a Meta application.


    This endpoint allows applications to retrieve information about businesses that have

    established client connections through the application. This is essential for managing

    business relationships and understanding client business configurations.'
  contact:
    name: Meta Business Platform Team
    url: https://developers.facebook.com/support
  license:
    name: Meta Platform Terms
    url: https://developers.facebook.com/terms
  termsOfService: https://developers.facebook.com/terms
servers:
- url: https://graph.facebook.com
  description: Production Graph API server
- url: https://graph.facebook.com
- url: https://graph.facebook.com
  description: WhatsApp Business Cloud API
- url: https://graph.facebook.com
  description: Meta Graph API production server
tags:
- name: Calls
  description: 'Use the **`/{Phone-Number-ID}/calls`** endpoint to initiate, manage, and terminate WhatsApp calls. This API allows businesses to handle voice calling functionality through the WhatsApp Business Platform.


    ## Prerequisites


    * User Access Token with **`whatsapp_business_messaging`** permission

    * `phone-number-id` for your registered WhatsApp account

    * Call request permission from the WhatsApp user


    ## Call Actions


    - **connect**: Initiate a new call

    - **pre_accept**: Pre-accept a call (prepare for accepting)

    - **accept**: Accept an incoming call

    - **reject**: Reject an incoming call

    - **terminate**: Terminate an active call


    ## Session Description Protocol (SDP)


    For actions that require audio/video negotiation (connect, accept), you must provide session information including:

    - `sdp_type`: Must be "offer" for connect action, "answer" for accept action

    - `sdp`: RFC 8866 compliant SDP information


    ## Error Handling


    Error code 138006 indicates lack of call request permission for the business number from the WhatsApp user.'
paths:
  /{Version}/{Phone-Number-ID}/calls:
    parameters:
    - name: Version
      in: path
      required: true
      schema:
        type: string
        example: v21.0
      description: The API version to use
    - name: Phone-Number-ID
      in: path
      required: true
      schema:
        type: string
        example: '102290129340398'
      description: The ID of the phone number registered with your WhatsApp Business Account
    post:
      tags:
      - Calls
      summary: Manage Calls
      description: 'Use this endpoint to initiate, accept, reject, or terminate WhatsApp calls.


        **For initiating or managing a call:**

        Send a POST request with the appropriate action (connect, pre_accept, accept, reject, terminate).


        **For terminating a call:**

        Send a POST request with action "terminate" and the call_id.


        **Note:** Response with error code 138006 indicates a lack of a call request permission for this business number from the WhatsApp user.'
      operationId: manageCalls
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/ContentType'
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/CallRequestPayload'
              - $ref: '#/components/schemas/CallTerminateRequestPayload'
            examples:
              Connect Call:
                value:
                  messaging_product: whatsapp
                  to: '14085551234'
                  action: connect
                  session:
                    sdp_type: offer
                    sdp: 'v=0

                      o=- 3626166318745852955 2 IN IP4 127.0.0.1

                      s=-

                      t=0 0

                      a=group:BUNDLE 0

                      a=extmap-allow-mixed

                      a=msid-semantic: WMS d8b26053-4474-4eb7-b3c3-c93d6c8c9b2e

                      m=audio 9 UDP/TLS/RTP/SAVPF 111 63 9 0 8 110 126

                      c=IN IP4 0.0.0.0

                      a=rtcp:9 IN IP4 0.0.0.0

                      a=ice-ufrag:4g1c

                      a=ice-pwd:qY/Bb+jQzg5ICn6X4fhJQetk

                      a=ice-options:trickle

                      a=fingerprint:sha-256 35:47:24:24:9F:93:C4:3E:DB:37:7F:BB:ED:F8:20:B5:AD:AC:DC:35:C2:7D:67:EE:6C:35:54:DF:A6:00:5C:4A

                      a=setup:actpass

                      a=mid:0

                      a=extmap:1 urn:ietf:params:rtp-hdrext:ssrc-audio-level

                      a=extmap:2 http://www.webrtc.org/experiments/rtp-hdrext/abs-send-time

                      a=extmap:3 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01

                      a=extmap:4 urn:ietf:params:rtp-hdrext:sdes:mid

                      a=sendrecv

                      a=msid:d8b26053-4474-4eb7-b3c3-c93d6c8c9b2e 5b4d3d96-ea9b-44a8-87e6-11a1ad21a3bc

                      a=rtcp-mux

                      a=rtpmap:111 opus/48000/2

                      a=rtcp-fb:111 transport-cc

                      a=fmtp:111 minptime=10;useinbandfec=1

                      a=rtpmap:63 red/48000/2

                      a=fmtp:63 111/111

                      a=rtpmap:9 G722/8000

                      a=rtpmap:0 PCMU/8000

                      a=rtpmap:8 PCMA/8000

                      a=rtpmap:110 telephone-event/48000

                      a=rtpmap:126 telephone-event/8000

                      a=ssrc:2220762577 cname:w/zwpg3jXNiTFTdZ

                      a=ssrc:2220762577 msid:d8b26053-4474-4eb7-b3c3-c93d6c8c9b2e 5b4d3d96-ea9b-44a8-87e6-11a1ad21a3bc

                      '
                  biz_opaque_callback_data: 0fS5cePMok
              Terminate Call:
                value:
                  messaging_product: whatsapp
                  call_id: wacid.HBgLMTIxODU1NTI4MjgVAgARGCAyODRQIAFRoA
                  action: terminate
              Accept Call:
                value:
                  messaging_product: whatsapp
                  to: '14085551234'
                  action: accept
                  session:
                    sdp_type: answer
                    sdp: 'v=0

                      o=- 3626166318745852955 2 IN IP4 127.0.0.1

                      s=-

                      t=0 0

                      a=group:BUNDLE 0

                      a=extmap-allow-mixed

                      a=msid-semantic: WMS d8b26053-4474-4eb7-b3c3-c93d6c8c9b2e

                      m=audio 9 UDP/TLS/RTP/SAVPF 111 63 9 0 8 110 126

                      c=IN IP4 0.0.0.0

                      a=rtcp:9 IN IP4 0.0.0.0

                      a=ice-ufrag:4g1c

                      a=ice-pwd:qY/Bb+jQzg5ICn6X4fhJQetk

                      a=ice-options:trickle

                      a=fingerprint:sha-256 35:47:24:24:9F:93:C4:3E:DB:37:7F:BB:ED:F8:20:B5:AD:AC:DC:35:C2:7D:67:EE:6C:35:54:DF:A6:00:5C:4A

                      a=setup:actpass

                      a=mid:0

                      a=extmap:1 urn:ietf:params:rtp-hdrext:ssrc-audio-level

                      a=extmap:2 http://www.webrtc.org/experiments/rtp-hdrext/abs-send-time

                      a=extmap:3 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01

                      a=extmap:4 urn:ietf:params:rtp-hdrext:sdes:mid

                      a=sendrecv

                      a=msid:d8b26053-4474-4eb7-b3c3-c93d6c8c9b2e 5b4d3d96-ea9b-44a8-87e6-11a1ad21a3bc

                      a=rtcp-mux

                      a=rtpmap:111 opus/48000/2

                      a=rtcp-fb:111 transport-cc

                      a=fmtp:111 minptime=10;useinbandfec=1

                      a=rtpmap:63 red/48000/2

                      a=fmtp:63 111/111

                      a=rtpmap:9 G722/8000

                      a=rtpmap:0 PCMU/8000

                      a=rtpmap:8 PCMA/8000

                      a=rtpmap:110 telephone-event/48000

                      a=rtpmap:126 telephone-event/8000

                      a=ssrc:2220762577 cname:w/zwpg3jXNiTFTdZ

                      a=ssrc:2220762577 msid:d8b26053-4474-4eb7-b3c3-c93d6c8c9b2e 5b4d3d96-ea9b-44a8-87e6-11a1ad21a3bc

                      '
              Reject Call:
                value:
                  messaging_product: whatsapp
                  to: '14085551234'
                  action: reject
      responses:
        '200':
          description: Call Management Success
          headers:
            Access-Control-Allow-Origin:
              $ref: '#/components/headers/Access-Control-Allow-Origin'
            Alt-Svc:
              $ref: '#/components/headers/Alt-Svc'
            Cache-Control:
              $ref: '#/components/headers/Cache-Control'
            Connection:
              $ref: '#/components/headers/Connection'
            Content-Length:
              $ref: '#/components/headers/Content-Length'
            Date:
              $ref: '#/components/headers/Date'
            Expires:
              $ref: '#/components/headers/Expires'
            Pragma:
              $ref: '#/components/headers/Pragma'
            Strict-Transport-Security:
              $ref: '#/components/headers/Strict-Transport-Security'
            Vary:
              $ref: '#/components/headers/Vary'
            X-FB-Connection-Quality:
              $ref: '#/components/headers/X-FB-Connection-Quality'
            X-FB-Debug:
              $ref: '#/components/headers/X-FB-Debug'
            facebook-api-version:
              $ref: '#/components/headers/facebook-api-version'
            x-business-use-case-usage:
              $ref: '#/components/headers/x-business-use-case-usage'
            x-fb-request-id:
              $ref: '#/components/headers/x-fb-request-id'
            x-fb-rev:
              $ref: '#/components/headers/x-fb-rev'
            x-fb-trace-id:
              $ref: '#/components/headers/x-fb-trace-id'
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/CallResponsePayload'
                - $ref: '#/components/schemas/CallTerminateResponsePayload'
              examples:
                Connect Call Response:
                  value:
                    messaging_product: whatsapp
                    calls:
                    - id: wacid.ABGGFjFVU2AfAgo6V
                Terminate Call Response:
                  value:
                    success: true
      security:
      - bearerAuth: []
components:
  schemas:
    CallResponsePayload:
      type: object
      properties:
        messaging_product:
          type: string
          example: whatsapp
        calls:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                example: wacid.ABGGFjFVU2AfAgo6V
          example:
          - id: wacid.ABGGFjFVU2AfAgo6V
    CallRequestPayload:
      type: object
      properties:
        messaging_product:
          type: string
          example: whatsapp
          description: Messaging product
        to:
          type: string
          example: '14085551234'
          description: The number being called (callee)
        action:
          type: string
          enum:
          - connect
          - pre_accept
          - accept
          - reject
          - terminate
          example: connect
          description: The action being taken on the given call ID
        session:
          type: object
          properties:
            sdp_type:
              type: string
              enum:
              - offer
              - answer
              example: offer
              description: SDP type - "offer" for connect action, "answer" for accept action
            sdp:
              type: string
              example: 'v=0

                o=- 3626166318745852955 2 IN IP4 127.0.0.1

                s=-

                t=0 0

                a=group:BUNDLE 0

                a=extmap-allow-mixed

                a=msid-semantic: WMS d8b26053-4474-4eb7-b3c3-c93d6c8c9b2e

                m=audio 9 UDP/TLS/RTP/SAVPF 111 63 9 0 8 110 126

                c=IN IP4 0.0.0.0

                a=rtcp:9 IN IP4 0.0.0.0

                a=ice-ufrag:4g1c

                a=ice-pwd:qY/Bb+jQzg5ICn6X4fhJQetk

                a=ice-options:trickle

                a=fingerprint:sha-256 35:47:24:24:9F:93:C4:3E:DB:37:7F:BB:ED:F8:20:B5:AD:AC:DC:35:C2:7D:67:EE:6C:35:54:DF:A6:00:5C:4A

                a=setup:actpass

                a=mid:0

                a=extmap:1 urn:ietf:params:rtp-hdrext:ssrc-audio-level

                a=extmap:2 http://www.webrtc.org/experiments/rtp-hdrext/abs-send-time

                a=extmap:3 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01

                a=extmap:4 urn:ietf:params:rtp-hdrext:sdes:mid

                a=sendrecv

                a=msid:d8b26053-4474-4eb7-b3c3-c93d6c8c9b2e 5b4d3d96-ea9b-44a8-87e6-11a1ad21a3bc

                a=rtcp-mux

                a=rtpmap:111 opus/48000/2

                a=rtcp-fb:111 transport-cc

                a=fmtp:111 minptime=10;useinbandfec=1

                a=rtpmap:63 red/48000/2

                a=fmtp:63 111/111

                a=rtpmap:9 G722/8000

                a=rtpmap:0 PCMU/8000

                a=rtpmap:8 PCMA/8000

                a=rtpmap:110 telephone-event/48000

                a=rtpmap:126 telephone-event/8000

                a=ssrc:2220762577 cname:w/zwpg3jXNiTFTdZ

                a=ssrc:2220762577 msid:d8b26053-4474-4eb7-b3c3-c93d6c8c9b2e 5b4d3d96-ea9b-44a8-87e6-11a1ad21a3bc

                '
              description: The SDP info of the device on the other end of the call. The SDP must be compliant with RFC 8866
          required:
          - sdp_type
          - sdp
          description: Contains the session description protocol (SDP) type and description language
        biz_opaque_callback_data:
          type: string
          maxLength: 512
          example: 0fS5cePMok
          description: 'An arbitrary string you can pass in that is useful for tracking and logging purposes. Any app subscribed to the "calls" webhook field on your WhatsApp Business Account can receive this string, as it is included in the calls object within the subsequent Call Terminate Webhook payload. Cloud API does not process this field. Maximum 512 characters

            '
      required:
      - messaging_product
      - to
      - action
    CallTerminateRequestPayload:
      type: object
      properties:
        messaging_product:
          type: string
          example: whatsapp
          description: Messaging product
        call_id:
          type: string
          example: wacid.HBgLMTIxODU1NTI4MjgVAgARGCAyODRQIAFRoA
          description: The WhatsApp call ID
        action:
          type: string
          enum:
          - terminate
          example: terminate
          description: Action to terminate the call
      required:
      - messaging_product
      - call_id
      - action
    CallTerminateResponsePayload:
      type: object
      properties:
        success:
          type: boolean
          example: true
  parameters:
    Authorization:
      name: Authorization
      in: header
      description: 'Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token.

        '
      required: true
      schema:
        type: string
        pattern: ^Bearer\s+[A-Za-z0-9\-_.]+.*$
        example: Bearer EAABwzLixnjYBOzYmNMJJGfHq9DgNh...
    UserAgent:
      name: User-Agent
      in: header
      description: The user agent string identifying the client software making the request.
      required: false
      schema:
        type: string
        default: Meta-Business-Messaging-OpenAPI/1.0.0;spec=2025-10-21
        pattern: ^[a-zA-Z0-9\-_]+\/[0-9]+\.[0-9]+\.[0-9]+(;[a-zA-Z0-9\-=\.]+)?(\s+[a-zA-Z0-9\-_]+\/[0-9\-\.]+)?$
        example: Meta-Business-Messaging-OpenAPI/1.0.0;spec=2025-10-21
    ContentType:
      name: Content-Type
      in: header
      description: Media type of the request body
      required: true
      schema:
        type: string
        enum:
        - application/json
        - application/x-www-form-urlencoded
        - multipart/form-data
        default: application/json
        example: application/json
  headers:
    Content-Length:
      schema:
        type: string
        example: '25'
      description: Size of the response body in bytes
    x-fb-request-id:
      schema:
        type: string
        example: AGaOBl2yM-g8gdON-dhzl5y
      description: Unique identifier for the request for debugging purposes
    Expires:
      schema:
        type: string
        example: Sat, 01 Jan 2000 00:00:00 GMT
      description: Expiration date for cached responses
    Access-Control-Allow-Origin:
      schema:
        type: string
        example: '*'
      description: CORS policy allowing access from any origin
    x-fb-trace-id:
      schema:
        type: string
        example: E7riEe9OW2e
      description: Facebook trace identifier for request tracking
    Vary:
      schema:
        type: string
        example: Accept-Encoding
      description: Headers that affect caching and content negotiation
    x-business-use-case-usage:
      schema:
        type: string
        example: '{"102290129340398":[{"type":"whatsapp_business_management","call_count":1,"total_cputime":1,"total_time":1,"estimated_time_to_regain_access":0},{"type":"whatsapp","call_count":1,"total_cputime":1,"total_time":1,"estimated_time_to_regain_access":0}]}'
      description: Business use case usage metrics and rate limiting information
    X-FB-Debug:
      schema:
        type: string
        example: 52zkUgodnaVRhbBE+3RiGz6TnmjmDEGunwYd+vKSc4synE+Xii//dy6twB/7yKgOJiMUuV0OF248UAZ1qL3v0A==
      description: Facebook debug information for troubleshooting
    Connection:
      schema:
        type: string
        example: keep-alive
      description: Connection management directive
    facebook-api-version:
      schema:
        type: string
        example: v22.0
      description: Facebook Graph API version used for the request
    Strict-Transport-Security:
      schema:
        type: string
        example: max-age=15552000; preload
      description: HSTS header enforcing HTTPS connections
    X-FB-Connection-Quality:
      schema:
        type: string
        example: EXCELLENT; q=0.9, rtt=7, rtx=0, c=10, mss=1380, tbw=372, tp=-1, tpl=-1, uplat=527, ullat=0
      description: Facebook connection quality metrics
    Pragma:
      schema:
        type: string
        example: no-cache
      description: Legacy cache control directive
    Alt-Svc:
      schema:
        type: string
        example: h3=":443"; ma=86400
      description: Alternative service advertisement for HTTP/3
    Cache-Control:
      schema:
        type: string
        example: private, no-cache, no-store, must-revalidate
      description: Cache control directives for the response
    Date:
      schema:
        type: string
        example: Fri, 24 Jan 2025 00:48:41 GMT
      description: Date and time when the response was generated
    x-fb-rev:
      schema:
        type: string
        example: '1019544279'
      description: Facebook internal revision number
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'System user access token with whatsapp_business_management permission. Format: Bearer YOUR_SYSTEM_USER_ACCESS_TOKEN

        '

WhatsApp Calls API

Operations 1

Documentation

Specifications

SDKs

Schemas & Data

Other Resources