WhatsApp Business API
WhatsApp Calls API — Initiate & Manage Business Voice Calls
Initiate and manage WhatsApp Business voice calls through Vobiz - WebRTC-based signaling for inbound, outbound, and call state management.
POST
/
api
/
v1
/
Account
/
{auth_id}
/
WhatsApp
/
Call
/
Place a call
curl --request POST \
--url https://api.vobiz.ai/api/v1/Account/{auth_id}/WhatsApp/Call/ \
--header 'Content-Type: application/json' \
--header 'X-Auth-ID: <api-key>' \
--header 'X-Auth-Token: <api-key>' \
--data '
{
"channel_id": "0a8f3feb-9598-47f2-8a6c-df1aeb306ae1",
"to": "+919876543210",
"sdp_offer": "v=0\r\no=- 0 0 IN IP4 0.0.0.0\r\n..."
}
'import requests
url = "https://api.vobiz.ai/api/v1/Account/{auth_id}/WhatsApp/Call/"
payload = {
"channel_id": "0a8f3feb-9598-47f2-8a6c-df1aeb306ae1",
"to": "+919876543210",
"sdp_offer": "v=0
o=- 0 0 IN IP4 0.0.0.0
..."
}
headers = {
"X-Auth-ID": "<api-key>",
"X-Auth-Token": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-Auth-ID': '<api-key>',
'X-Auth-Token': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
channel_id: '0a8f3feb-9598-47f2-8a6c-df1aeb306ae1',
to: '+919876543210',
sdp_offer: 'v=0\r\no=- 0 0 IN IP4 0.0.0.0\r\n...'
})
};
fetch('https://api.vobiz.ai/api/v1/Account/{auth_id}/WhatsApp/Call/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"call_id": "wacid.HBgMOTE5ODc2NTQzMjEwFQIAEhggQzVGNkE3QjhDOUQwRTFGMkEz",
"from": "+14155550100",
"to": "+919876543210",
"status": "initiated",
"direction": "outbound"
}WhatsApp Business Calling runs over WhatsApp’s WebRTC infrastructure, not the PSTN. The recipient’s device must support WhatsApp voice calls and be connected to the internet.
https://api.vobiz.ai/api/v1/Account/{auth_id}/WhatsApp
These are WhatsApp calls under /WhatsApp/Call/. They are separate from the Voice API’s /Account/{auth_id}/Call/, which places PSTN and SIP calls.
Authentication: every request needs the X-Auth-ID: MA_XXXXXXXX and X-Auth-Token: YOUR_AUTH_TOKEN headers, and the {auth_id} in the path must be the account those credentials belong to. Set Content-Type: application/json on requests with a body. Get your credentials from console.vobiz.ai.
Endpoints overview
| Method | Endpoint | Description |
|---|---|---|
POST | /api/v1/Account/{auth_id}/WhatsApp/Call/ | Initiate a WhatsApp call |
POST | /api/v1/Account/{auth_id}/WhatsApp/Call/Action/ | Manage a call (pre-accept/accept/reject/terminate) |
GET | /api/v1/Account/{auth_id}/WhatsApp/Call/Log/ | List call history |
Initiate a WhatsApp call
POST https://api.vobiz.ai/api/v1/Account/{auth_id}/WhatsApp/Call/
201 Created when WhatsApp accepts the call request.
This rings a real person. Use your own credentials and confirm the recipient before you place the call.
The response carries the call ID, not an SDP answer. The recipient’s SDP answer arrives later, through the
call.* webhook events, when they answer.Request body
| Field | Required | Description |
|---|---|---|
channel_id | Yes | Channel (UUID) to call from |
to | Yes | The WhatsApp user to call, in E.164 format (e.g. +919876543210). Spaces, hyphens, and parentheses are removed, and a missing + is added. |
sdp_offer | Yes | Your WebRTC SDP offer string |
cURL
curl -X POST \
"https://api.vobiz.ai/api/v1/Account/MA_XXXXXXXX/WhatsApp/Call/" \
-H "X-Auth-ID: MA_XXXXXXXX" \
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"channel_id": "0a8f3feb-9598-47f2-8a6c-df1aeb306ae1",
"to": "+919876543210",
"sdp_offer": "v=0\r\no=- 0 0 IN IP4 0.0.0.0\r\n..."
}'
201 Created
{
"call_id": "wacid.HBgMOTE5ODc2NTQzMjEwFQIAEhggQzVGNkE3QjhDOUQwRTFGMkEz",
"from": "+14155550100",
"to": "+919876543210",
"status": "initiated",
"direction": "outbound"
}
| Field | Description |
|---|---|
call_id | WhatsApp’s call ID. Use it as call_id in Manage call. |
from | The channel’s phone number |
to | The normalized number you called |
status | Always initiated |
direction | Always outbound |
400.
Manage call (actions)
POST https://api.vobiz.ai/api/v1/Account/{auth_id}/WhatsApp/Call/Action/
channel_id, the call_id, and one of the four actions. For accept and pre_accept, include your WebRTC SDP answer in the sdp field. Returns 200 OK when WhatsApp accepts the action, or 404 when the channel or call isn’t found.
Request body
| Field | Required | Description |
|---|---|---|
channel_id | Yes | Channel (UUID) the call is on |
call_id | Yes | WhatsApp’s call ID (meta_call_id in call logs and call events) |
action | Yes | pre_accept, accept, reject, or terminate |
sdp | Conditional | Your WebRTC SDP answer. Send it with accept and pre_accept |
| Action | Description |
|---|---|
pre_accept | Send your SDP answer early, so media connects as soon as you accept |
accept | Answer an incoming call (send SDP answer) |
reject | Decline an incoming call |
terminate | End a connected call |
curl -X POST \
"https://api.vobiz.ai/api/v1/Account/MA_XXXXXXXX/WhatsApp/Call/Action/" \
-H "X-Auth-ID: MA_XXXXXXXX" \
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"channel_id": "0a8f3feb-9598-47f2-8a6c-df1aeb306ae1",
"call_id": "wacid.HBgMOTE5ODc2NTQzMjEwFQIAEhggQzVGNkE3QjhDOUQwRTFGMkEz",
"action": "accept",
"sdp": "v=0\r\no=- 0 0 IN IP4 0.0.0.0\r\n..."
}'
curl -X POST \
"https://api.vobiz.ai/api/v1/Account/MA_XXXXXXXX/WhatsApp/Call/Action/" \
-H "X-Auth-ID: MA_XXXXXXXX" \
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"channel_id": "0a8f3feb-9598-47f2-8a6c-df1aeb306ae1",
"call_id": "wacid.HBgMOTE5ODc2NTQzMjEwFQIAEhggQzVGNkE3QjhDOUQwRTFGMkEz",
"action": "terminate"
}'
200 OK
{
"call_id": "wacid.HBgMOTE5ODc2NTQzMjEwFQIAEhggQzVGNkE3QjhDOUQwRTFGMkEz",
"action": "accept",
"success": true
}
List call logs
GET https://api.vobiz.ai/api/v1/Account/{auth_id}/WhatsApp/Call/Log/
| Query param | Default | Description |
|---|---|---|
page | 1 | Page number, starting at 1 |
limit | 25 | Page size, from 1 to 100 |
direction | - | inbound or outbound |
status | - | Filter by call status: initiated, ringing, pre_accepted, accepted, rejected, terminated, failed, or missed |
channel_id | - | Return only calls on this channel (UUID) |
phone_number | - | Return only calls to or from this number. Spaces, hyphens, and parentheses are removed, and a missing + is added before matching. |
cURL
curl -X GET \
"https://api.vobiz.ai/api/v1/Account/MA_XXXXXXXX/WhatsApp/Call/Log/?page=1&limit=25&direction=outbound&status=terminated" \
-H "X-Auth-ID: MA_XXXXXXXX" \
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
200 OK
{
"items": [
{
"id": "e6f70819-2031-4b4c-95d6-e7f809102233",
"account_id": "MA_XXXXXXXX",
"channel_id": "0a8f3feb-9598-47f2-8a6c-df1aeb306ae1",
"meta_call_id": "wacid.HBgMOTE5ODc2NTQzMjEwFQIAEhggQzVGNkE3QjhDOUQwRTFGMkEz",
"direction": "outbound",
"from_number": "+14155550100",
"to_number": "+919876543210",
"status": "terminated",
"call_type": "voice",
"started_at": "2026-10-25T14:00:00Z",
"answered_at": "2026-10-25T14:00:04Z",
"ended_at": "2026-10-25T14:03:05Z",
"duration_seconds": 181,
"created_at": "2026-10-25T14:00:00Z",
"updated_at": "2026-10-25T14:03:05Z"
}
],
"total": 1,
"page": 1,
"limit": 25,
"has_more": false
}
Call log object
| Field | Type | Description |
|---|---|---|
id | UUID | Call log ID |
account_id | string | Owning account (MA_XXXXXXXX) |
channel_id | UUID | Channel the call belongs to |
meta_call_id | string | WhatsApp’s call ID. Omitted when not known. |
direction | string | inbound or outbound |
from_number | string | Caller number (E.164) |
to_number | string | Called number (E.164) |
status | string | initiated, ringing, pre_accepted, accepted, rejected, terminated, failed, or missed |
call_type | string | Call type, for example voice |
offer_sdp | string | WebRTC SDP offer. Omitted when not recorded. |
answer_sdp | string | WebRTC SDP answer. Omitted when not recorded. |
ice_candidates | any | ICE candidate data, as received. Omitted when not recorded. |
started_at | RFC3339 | Call start (UTC) |
answered_at | RFC3339 | Call answered (UTC) |
ended_at | RFC3339 | Call ended (UTC) |
duration_seconds | int | Call duration in seconds |
hangup_cause | string | Why the call ended. Omitted when not known. |
metadata | any | Additional call metadata. Omitted when there is none. |
created_at | RFC3339 | Creation timestamp (UTC) |
updated_at | RFC3339 | Last update timestamp (UTC) |
Authorizations
Path Parameters
Body
application/json
Response
WhatsApp accepted the call request.
Was this page helpful?
⌘I
Place a call
curl --request POST \
--url https://api.vobiz.ai/api/v1/Account/{auth_id}/WhatsApp/Call/ \
--header 'Content-Type: application/json' \
--header 'X-Auth-ID: <api-key>' \
--header 'X-Auth-Token: <api-key>' \
--data '
{
"channel_id": "0a8f3feb-9598-47f2-8a6c-df1aeb306ae1",
"to": "+919876543210",
"sdp_offer": "v=0\r\no=- 0 0 IN IP4 0.0.0.0\r\n..."
}
'import requests
url = "https://api.vobiz.ai/api/v1/Account/{auth_id}/WhatsApp/Call/"
payload = {
"channel_id": "0a8f3feb-9598-47f2-8a6c-df1aeb306ae1",
"to": "+919876543210",
"sdp_offer": "v=0
o=- 0 0 IN IP4 0.0.0.0
..."
}
headers = {
"X-Auth-ID": "<api-key>",
"X-Auth-Token": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-Auth-ID': '<api-key>',
'X-Auth-Token': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
channel_id: '0a8f3feb-9598-47f2-8a6c-df1aeb306ae1',
to: '+919876543210',
sdp_offer: 'v=0\r\no=- 0 0 IN IP4 0.0.0.0\r\n...'
})
};
fetch('https://api.vobiz.ai/api/v1/Account/{auth_id}/WhatsApp/Call/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"call_id": "wacid.HBgMOTE5ODc2NTQzMjEwFQIAEhggQzVGNkE3QjhDOUQwRTFGMkEz",
"from": "+14155550100",
"to": "+919876543210",
"status": "initiated",
"direction": "outbound"
}