Summary
This guide explains how to integrate WhatsApp calling with your own voice agent or third-party platform. It covers inbound and outbound call flows, API authentication, WebRTC setup, webhook configuration, call permissions, and best practices for maintaining a stable voice integration.
Instructions
Wati’s WhatsApp Calls API allows businesses to connect WhatsApp calling with their own voice infrastructure using WebRTC.
The integration works by connecting:
The WhatsApp signaling layer managed by Wati APIs and webhooks
The media layer handled by your own voice agent or third-party platform
This guide is intended for developers building custom voice integrations.
Core architecture and authentication
The integration uses Session Description Protocol (SDP) exchange between Wati and your WebRTC infrastructure.
API base URL
<https://live-mt-server.wati.io/{tenant_id}/api/v1/openapi/whatsapp/calls>Replace {tenant_id} with your Wati tenant ID.
Authentication
Every API request must include a Bearer Token in the request header.
Authorization: Bearer {YOUR_ACCESS_TOKEN}Find your API credentials
Log in to your Wati account.
Navigate to Connectors → API Docs in the menu.
Copy your:
API Endpoint
Bearer Token
Note: If you change your Wati password, your existing Bearer Token becomes invalid. You must update your integration with the new token.
Handling incoming calls
Step 1: Configure inbound call webhooks
In the Wati platform, configure your webhook URL for:
New Inbound Call Webhook
This webhook receives incoming call requests and SDP offers from WhatsApp users.
Step 2: Receive the inbound webhook
When a user calls your WhatsApp number, Wati sends a POST request containing the caller’s SDP offer.
Example request payload:
{
"callId": "WHATSAPP_CALL_ID",
"sdp": "v=0... (Offer from WhatsApp)",
"businessNumber": "1234567890"
}Step 3: Perform WebRTC negotiation
Your application must now establish the WebRTC session.
Initialize the peer connection
Create an RTCPeerConnection on your server, voice agent, or third-party platform.
Set the remote description
Use the SDP received from the webhook as the remote description.
Generate an SDP answer
Generate a local SDP answer from your peer connection.
Important: Ensure SDP fingerprints are uppercase for WhatsApp compatibility.
Example:
a=fingerprint:SHA-256
Step 4: Accept the call
Send the generated SDP answer back to Wati using the Accept Call API.
Request details
Method
POST
Endpoint
<https://live-mt-server.wati.io/{tenant_id}/api/v1/openapi/whatsapp/calls/{callId}/accept>Headers
Authorization: Bearer {YOUR_ACCESS_TOKEN}Request body
{
"Sdp": "v=0... (Your Answer)"
}
Making outbound calls
WhatsApp requires businesses to receive permission from users before initiating outbound calls.
Step 1: Manage call permissions
Check existing permission status
Use the following endpoint to check whether the user has already granted call permission.
GET .../calls/permissions/{waid}Request permission
If permission has not been granted, request it using:
POST .../calls/call-permission-request/{waid}Wait for permission approval
Wati sends a Call Permission Webhook after the user accepts or declines the request.
Only proceed with the outbound call after approval.
Initiating an outbound call
Step 2: Create and send the SDP offer
Generate an SDP offer
Create an SDP offer using your WebRTC RTCPeerConnection.
Call the outbound call API
Send the SDP offer to Wati.
Method
POST
Endpoint
<https://live-mt-server.wati.io/{tenant_id}/api/v1/openapi/whatsapp/calls/outbound-call/{waid}>Headers
Authorization: Bearer {YOUR_ACCESS_TOKEN}Request body
{
"Sdp": "v=0... (Your Offer)"
}Receive the call ID
If the request is successful, Wati returns a callId.
Establishing the audio stream
Step 3: Finalize the WebRTC connection
Monitor call status
Use the New Outbound Call Status Webhook to track updates such as:
CALLING
RINGING
ACCEPTED
Receive the user's SDP answer
When the user answers the call, Wati sends the New Outbound Call Webhook containing the user's SDP answer.
Complete the connection
Set the received SDP answer as the remote description in your RTCPeerConnection.
This establishes the audio stream between the user and your voice platform.
Terminating calls
When the user hangs up
Wati sends a Terminate Call Webhook to notify your application that the call has ended.
When the business hangs up
Use the Terminate Call API.
Request details
Endpoint
POST <https://live-mt-server.wati.io/{tenant_id}/api/v1/openapi/whatsapp/calls/{callId}/terminate>Headers
Authorization: Bearer {YOUR_ACCESS_TOKEN}
Where can you post your webhook URLs?
Required webhook URLs
Configure the following webhook endpoints in Wati.
New Inbound Call Webhook
Receives incoming SDP offers from WhatsApp users.
Terminate Call Webhook
Receives notifications when calls are disconnected.
New Outbound Call Webhook
Receives SDP answers for outbound calls.
New Outbound Call Status Webhook
Receives outbound call status updates such as:
Calling
Ringing
Accepted
Call Permission Webhook
Receives permission approval or rejection events from users.
Webhook requirements
Your webhook endpoints must:
Be publicly accessible
Return an HTTP
200 OKresponseRespond within 30 seconds
Configure webhook API key verification
You can configure a dedicated API key in the Wati configuration UI for webhook verification.
Wati includes this key in the Authorization header of every webhook request.
Example:
Authorization: Bearer {ApiKey}You can use this key to:
Verify webhook authenticity
Validate incoming requests
Secure your webhook endpoints
Technical best practices
Use the Opus codec
WhatsApp Calling currently supports audio only.
Your voice platform must use the Opus audio codec for compatibility.
Disable ICE trickle
Do not use ICE Trickle during SDP negotiation.
Wati requires a complete SDP block that already contains all ICE candidates.
Send complete SDP payloads
Ensure your SDP includes:
ICE candidates
Fingerprints
Media information
before sending requests to Wati APIs.
Call flow overview
Inbound call flow
Outbound call flow
Call permission flow
Frequently Asked Questions (FAQs)
Availability and access
1. Is this feature available on all Wati plans?
No, this feature is available only for Pro and higher plans.
2. Why do I not see this configuration in my Wati account?
This configuration is enabled only on a request basis. You need to contact Wati support to enable it for your account.
Calling and integrations
3. Will calls be recorded and transcribed when using WhatsApp Calling on an external platform or BYOA?
No, calls will not be recorded or transcribed when using WhatsApp Calling on an external platform or Bring Your Own Access (BYOA). The calls happen over your own server, where Wati does not have control.
4. Can I handle calls both on Wati and an externally integrated platform?
No, all incoming calls will be routed to your externally integrated platform instead of Wati.
5. Why can outbound calls placed through Wati not detect whether a call was accepted or declined?
Outbound calls placed through Wati cannot detect whether a call was accepted or declined because you will configure your own webhook endpoint to receive call status updates such as ringing, accepted, or declined.
Support and implementation
6. Who can help me set up this feature if I am not technically familiar with the implementation?
Wati provides implementation support for Business Plan customers on a need basis. You can contact your Customer Success Manager (CSM) to schedule a call.