Skip to main content

API and Webhook Reference | Developer Documentation

API and Webhook Reference

Updated: Nov 25, 2025

Calling API endpoints

Configure or update calling settings

Call the Update Phone Number Settings endpoint and pass in Calling API parameters to configure settings on a business phone number you designate in the request syntax.
Endpoint parameters
Placeholder Description Sample Value
<PHONE_NUMBER_ID>
Integer
Required
The business phone number for which you are updating Calling API settings.
+12784358810
Parameter details: Calling status
When the status parameter is set to “ENABLED”, calling features are enabled for the business phone number. WhatsApp client applications will render the call button icon in both the business chat and business chat profile.
When the status parameter is set to “DISABLED”, calling features are disabled, and both the business chat and business chat profile do not display the call button icon.
Updates to status will update the call button icon in existing business chats in near real-time when the business phone number is in the WhatsApp user’s contacts.
Otherwise, updates are real-time for a limited number of users in conversation with the business, and are eventually updated for the rest of conversations.
Parameter details: Call button icon visibility
When Calling API features are enabled for a business number, you can still choose whether to show the call button icon or not by using the call_icon_visibility parameter. Note: Disabling call button icon visibility does not disable a WhatsApp user’s ability to make unsolicited calls to your business.
The behavior for supported options is as follows:
DEFAULT
The Call button icon will be displayed in the chat menu bar and the business info page, allowing for unsolicited calls to the business by WhatsApp users.
Screenshot showing the call button icon displayed in the WhatsApp chat menu bar and business info page
DISABLE ALL
The call button icon is hidden in the chat menu bar and the business info page, and all other entry points external to the chat are also disabled. Consumers cannot make unsolicited calls to the business.
Your business can still send interactive messages or template messages with a Calling API CTA button.
Screenshot showing the WhatsApp chat interface with the call button icon hidden
Callback permissions
Calling a WhatsApp user requires explicit permission from the user. One way to obtain calling permissions is to request permission when a WhatsApp user calls your business.
You can configure the call permission UI to automatically show in the WhatsApp user’s client app when they call your business number. The user may change their permission selection at any time.
Screenshot showing the WhatsApp call permission request dialog
Success response


{
"success": true
}








Error response


Possible errors that can occur:


    Permissions/Authorization errorsInvalid statusInvalid schedule for call_hoursHoliday given in call_hours is a past dateTimezone is invalid in call_hoursweekly_operating_hours in call_hours cannot be emptyDate format in holiday_schedule for call_hours is invalidMore than 2 entries not allowed in weekly_operating_hours schedule in call_hoursOverlapping schedule in call_hours is not allowed



    

    

    

    Get phone number calling settings
    

    Call the Get Phone Number Settings endpoint to retrieve Calling API settings on an individual business phone number you designate in the request syntax.
    

    This endpoint can return information for other Cloud API feature settings.
    

    

    

    

    Endpoint parameters
    

    

    


    
Parameter 
Description 
Sample Value 
    


    


    

    <PHONE_NUMBER_ID>
    

    Integer
    		


    

    Required
    


    The business phone number for which you are getting Calling API settings.
    

    		


    

    +12784358810
    

    

    

    

    App permission required
    

    whatsapp_business_management: Advanced access is required to use the API for end business clients
    

    

    

    

    Response details
    

    The GET /<PHONE_NUMBER_ID>/settings endpoint returns Calling API settings, along with other configuration information for your WhatsApp business phone number.
    


    

    

    

    Error response
    

    Possible errors that can occur:
    

      Permissions/Authorization errors



      

      

      

      Pre-accept call
      

      When you pre-accept an inbound call, you allow the calling media connection to be established before attempting to send call media through the connection.
      

      When you then call the accept call endpoint, media begins flowing immediately since the connection has already been established.
      

      Pre-accepting calls is recommended because it facilitates faster connection times and avoids audio clipping issues.
      

      There is about 30 to 60 seconds after the Call Connect webhook is sent for the business to accept the phone call. If the business does not respond, the call is terminated on the WhatsApp user side with a “Not Answered” notification and a Terminate Webhook is delivered back to you.
      

      

      Note: Since the WebRTC connection is established before calling the Accept Call endpoint, make sure to flow the call media only after you receive a 200 OK response back.
      

      If call media flows too early, the caller will miss the first few words of the call. If call media flows too late, callers will hear silence.
      

      

      

      

      Body parameters
      

      

      


      
Parameter 
Description 
Sample Value 
      


      


      

      call_id
      

      String
      		


      

      Required
      


      The ID of the phone call.
      

      For inbound calls, you receive a call ID from the Call Connect webhook when a WhatsApp user initiates the call.
      		


      

      “wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh”
      

      


      

      action
      

      String
      		


      

      Optional
      


      The action being taken on the given call ID.
      

      Values can be connect | pre_accept | accept | reject | terminate
      		


      

      “pre_accept”
      

      


      

      session
      

      JSON object
      		


      

      Optional
      


      Contains the session description protocol (SDP) type and description language.
      

      Requires two values:
      

      sdp_type — (String) Required
      

      “offer”, to indicate SDP offer
      

      sdp — (String) Required
      

      The SDP info of the device on the other end of the call. The SDP must be compliant with RFC 8866⁠.
      


      		


      

      

      

      

      

      Success response
      

      

      

      

      

      Error response
      

      Possible errors that can occur:
      

        Invalid call-idInvalid phone-number-idError related to your payment methodInvalid Connection info, for example, sdp, iceAccept/Reject an already In Progress/Completed/Failed callPermissions/Authorization errors



        

        

        

        Accept call
        

        Use this endpoint to connect to a call by providing a call agent’s SDP.
        

        You have about 30 to 60 seconds after the Call Connect Webhook is sent to accept the phone call. If your business does not respond, the call is terminated on the WhatsApp user side with a “Not Answered” notification and a Terminate Webhook is delivered back to you.
        

        

        

        

        Body parameters
        

        

        

        

        

        Success response
        

        

        

        

        

        Error response
        

        Possible errors that can occur:
        

          Invalid call-idInvalid phone-number-idError related to your payment methodInvalid Connection info, for example, sdp, ice, or other connection parametersAccept/Reject an already In Progress/Completed/Failed callPermissions/Authorization errorsSDP answer provided in accept does not match the SDP answer given in the Pre-Accept endpoint for the same call-id



          

          

          

          Reject call
          

          Use this endpoint to reject a call.
          

          You have about 30 to 60 seconds after the Call Connect webhook is sent to accept the phone call. If the business does not respond, the call is terminated on the WhatsApp user side with a “Not Answered” notification and a Terminate Webhook is delivered back to you.
          

          

          

          

          Body parameters
          

          

          


          
Parameter 
Description 
Sample Value 
          


          


          

          call_id
          

          String
          		


          

          Required
          


          The ID of the phone call.
          

          For inbound calls, you receive a call ID from the Call Connect webhook when a WhatsApp user initiates the call.
          		


          

          “wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh”
          

          


          

          action
          

          String
          		


          

          Optional
          


          The action being taken on the given call ID.
          

          Values can be connect | pre_accept | accept | reject | terminate
          		


          

          “reject”
          

          

          

          

          Success response
          

          

          

          

          

          Error response
          

          Possible errors that can occur:
          

            Invalid call-idInvalid phone-number-idAccept/Reject an already In Progress/Completed/Failed callPermissions/Authorization errors



            

            

            

            Initiate call
            

            Use this endpoint to initiate a call to a WhatsApp user by providing a phone number and a WebRTC call offer.
            

            

            

            

            Body parameters
            

            

            

            

            

            Success response
            

            

            

            

            

            Error response
            

            Possible errors that can occur:
            

              Invalid phone-number-idPermissions/Authorization errorsRequest format validation errors, for example connection info, sdp, iceSDP validation errors



              

              

              

              Terminate call
              

              Use this endpoint to terminate an active call.
              

              This must be done even if there is an RTCP BYE packet in the media path. Ending the call this way also ensures pricing is more accurate.
              

              When the WhatsApp user terminates the call, you do not have to call this endpoint. Once the call is successfully terminated, a Call Terminate Webhook will be sent to you.
              

              

              

              

              Body parameters
              

              

              


              
Parameter 
Description 
Sample Value 
              


              


              

              call_id
              

              String
              		


              

              Required
              


              The ID of the phone call.
              

              For inbound calls, you receive a call ID from the Call Connect webhook when a WhatsApp user initiates the call.
              		


              

              “wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh”
              

              


              

              action
              

              String
              		


              

              Required
              


              The action being taken on the given call ID.
              

              Values can be connect | pre_accept | accept | reject | terminate
              		


              

              “terminate”
              

              

              

              

              Success response
              

              

              

              

              

              Error response
              

              Possible errors that can occur:
              

                Invalid call idInvalid phone-number-idThe WhatsApp user has already terminated the callReject call is already in progressPermissions/Authorization errors



                

                

                

                Get current call permission state
                

                Use this endpoint to get the call permission state for a business phone number with a single WhatsApp user phone number.
                

                

                

                

                Request parameters
                

                

                


                
Parameter 
Description 
Sample Value 
                


                


                

                <PHONE_NUMBER_ID>
                

                String
                		


                

                Required
                


                The business phone number you are fetching permissions against.
                

                		


                

                +18762639988
                

                


                

                <CONSUMER_WHATSAPP_ID>
                

                Integer
                		


                

                Required
                


                The phone number of the WhatsApp user who you are requesting call permissions from.
                

                		


                

                +13057765456
                

                

                

                

                Response parameters
                

                

                

                

                

                Error response
                

                Possible errors that can occur:
                

                  Invalid phone-number-idIf the consumer phone number is uncallable, the api response will be no_permission.Permissions/Authorization errors.Rate limit reached. A maximum of 5 requests in a 1 second window can be made to the API.Calling is not enabled for the business phone number.



                  

                  

                  

                  SDP overview and sample SDP structures
                  

                  Session Description Protocol (SDP) is a text-based format that describes multimedia session characteristics, such as voice and video calls, in real-time communication applications. SDP provides a standardized way to convey information about the session’s media streams, including the type of media, codecs, protocols, and other parameters necessary for establishing and managing the session.
                  

                  In the context of WebRTC, SDP is used to negotiate the media parameters between the sender and receiver, enabling them to agree on the specifics of the media exchange.
                  

                  

                  

                  

                  Business-initiated sample SDP structures
                  

                  

                  

                  

                  Sample SDP offer structure
                  

                  v=0
o=-36261663187458529552 IN IP4 127.0.0.1
s=-
t=00
a=group:BUNDLE 0
a=extmap-allow-mixed
a=msid-semantic: WMS d8b26053-4474-4eb7-b3c3-c93d6c8c9b2e
m=audio 9 UDP/TLS/RTP/SAVPF 11163908110126
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-25635: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:63111/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
                  

                  

                  

                  

                  Sample SDP answer structure
                  

                  v=0
o=-7418078391020537252 IN IP4 127.0.0.1
s=-
t=00
a=group:BUNDLE 0
a=extmap-allow-mixed
a=msid-semantic: WMS 798a9670-c0d6-47a8-925e-5f082ef4d8a0
a=ice-lite
m=audio 3482 UDP/TLS/RTP/SAVPF 111908110126
c=IN IP4 31.13.65.130
a=rtcp:9 IN IP4 0.0.0.0
a=candidate:27549362801 udp 211393715131.13.65.1303482 typ host generation 0 network-cost 50 ufrag JHqAXFH4HcAY/8
a=candidate:15814963991 udp 21139397112a03:2880:f211:d1:face:b00c:0:699c3482 typ host generation 0 network-cost 50 ufrag JHqAXFH4HcAY/8
a=ice-ufrag:JHqAXFH4HcAY/8
a=ice-pwd:dNNMmR8wUcGezvfBZOO0Qgcwl2m86GP/
a=ice-options:trickle
a=fingerprint:sha-2569C:97:5C:4C:A9:BE:9E:2F:06:94:F5:BB:38:2C:A1:29:B5:69:B8:FA:94:10:56:1D:0B:5D:80:28:C1:FD:F0:F6
a=setup:active
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=sendrecv
a=rtcp-mux
a=rtpmap:111 opus/48000/2
a=rtcp-fb:111 transport-cc
a=fmtp:111 minptime=10;useinbandfec=1
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:3407645770 cname:bg8KQDoIk2UJa6sf
a=ssrc:3407645770 msid:798a9670-c0d6-47a8-925e-5f082ef4d8a0 audio#nuxVMf9EAJX
a=ssrc:3407645770 mslabel:798a9670-c0d6-47a8-925e-5f082ef4d8a0
a=ssrc:3407645770 label:audio#nuxVMf9EAJX
                  

                  

                  

                  

                  User-initiated sample SDP structures
                  

                  

                  

                  

                  Sample SDP offer structure
                  

                  v=0
o=-76025637897899450802 IN IP4 127.0.0.1
s=-
t=00
a=group:BUNDLE audio
a=msid-semantic: WMS 6932bc1c-db1a-4abe-b437-0c4168be8a13
a=ice-lite
m=audio 40012 UDP/TLS/RTP/SAVPF 111126
c=IN IP4 31.13.65.60
a=rtcp:9 IN IP4 0.0.0.0
a=candidate:19726373201 udp 211393715131.13.65.6040012 typ host generation 0 network-cost 50 ufrag 6k2qP1R6kBfI/2
a=candidate:16522627911 udp 21139397112a03:2880:f211:cf:face:b00c:0:644340012 typ host generation 0 network-cost 50 ufrag 6k2qP1R6kBfI/2
a=ice-ufrag:6k2qP1R6kBfI/2
a=ice-pwd:UApvJw3NcwFRDvIMKdM0vWCdlXah25E9
a=fingerprint:sha-2561B:B6:6B:40:A5:0B:8C:75:0D:8C:CB:90:2F:99:74:1E:26:45:AE:AF:45:C1:51:60:8F:73:C9:2D:10:6D:8A:88
a=setup:actpass
a=mid:audio
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=sendrecv
a=rtcp-mux
a=rtpmap:111 opus/48000/2
a=rtcp-fb:111 transport-cc
a=fmtp:111 minptime=10;useinbandfec=1
a=rtpmap:126 telephone-event/8000
a=ssrc:4208138518 cname:gAXq2V9TKltrnapv
a=ssrc:4208138518 msid:6932bc1c-db1a-4abe-b437-0c4168be8a13 audio#R5wfXFcdmT6
a=ssrc:4208138518 mslabel:6932bc1c-db1a-4abe-b437-0c4168be8a13
a=ssrc:4208138518 label:audio#R5wfXFcdmT6
                  

                  

                  

                  

                  Sample SDP answer structure
                  

                  v=0
o=-28226442481446439332 IN IP4 127.0.0.1
s=-
t=00
a=group:BUNDLE audio
a=msid-semantic: WMS eb909cf0-87f0-4358-a4c9-7861680d9431
m=audio 9 UDP/TLS/RTP/SAVPF 111126
c=IN IP4 0.0.0.0
a=rtcp:9 IN IP4 0.0.0.0
a=ice-ufrag:X1ho
a=ice-pwd:7fJSbV2N5qWiA5QiDKwK3vuh
a=fingerprint:sha-2562E:35:9F:21:9E:63:72:E5:42:74:76:2D:B3:70:F7:CB:24:14:9B:14:52:71:05:48:DA:4D:67:31:09:58:2A:ED
a=setup:active
a=mid:audio
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=sendrecv
a=rtcp-mux
a=rtpmap:111 opus/48000/2
a=rtcp-fb:111 transport-cc
a=fmtp:111 minptime=10;useinbandfec=1
a=rtpmap:126 telephone-event/8000
a=ssrc:330833028 cname:EDc1JutBl8rwHQc2
a=ssrc:330833028 msid:eb909cf0-87f0-4358-a4c9-7861680d9431 ea478c16-d9f7-493c-8cec-19bfac750a36
                  

                  

                  

                  

                  Sample call connect webhook
                  

                  

                  

                  

                  Call connect webhook
                  

                  
    
                          
                  
    
                  

            
                  
        
                  
    
                  

    
                  

    
    
                  
        
                  
             Back to top