WhatsApp calling

With WhatsApp calling, people can call your number from WhatsApp: they tap the call button in the chat with your business, and your assistant answers the call as it would a phone call. The call comes straight from Meta to VoiceDock, so no phone network is involved.

You set it up with your own Meta app and WhatsApp Business Account. At Meta you register the number, turn on calling over SIP to VoiceDock and read the SIP password that Meta generates. You then give VoiceDock that password, through the API or the dashboard. The steps below cover both sides.

VoiceDock only answers calls. Messages sent to the number keep going to your own Meta app, as with any number on the WhatsApp Cloud API.

Before you start

On the VoiceDock side:

• The number must be on your VoiceDock account, active, and answered by an assistant. Meta verifies the number with a phone call, and your assistant answers it.
• The number must not already receive its calls through another SIP provider of yours, such as your own SIP trunk.
• If the number is in use on the WhatsApp or WhatsApp Business app, delete that WhatsApp account first. A number can be on the app or on the Cloud API, not both.

The examples use these placeholders:

The Meta examples use Graph API v24.0; use the version your app is on.

1. Add the number to your WhatsApp Business Account

In WhatsApp Manager, go to Phone numbers and choose Add phone number. Enter your VoiceDock number and the display name you want callers to see. Meta then shows the number with its PHONE_NUMBER_ID.

2. Verify the number by phone

Ask Meta to verify the number with a voice call:

curl -X POST "https://graph.facebook.com/v24.0/PHONE_NUMBER_ID/request_code" \
  -H "Authorization: Bearer META_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code_method": "VOICE",
    "language": "en_US"
  }'

Meta calls your VoiceDock number and an automated voice reads out a six-digit code. Your assistant answers the call like any other, so the code ends up in the call's transcript. Open the call in the dashboard under Calls, or fetch it through the API:

curl "https://api.hmsovereign.com/api/v1/calls?limit=1" \
  -H "Authorization: Bearer YOUR_API_KEY"

The code is in messages. If the transcript does not hold all six digits, listen to the recording in the dashboard, or request a new code.

Send the code to Meta:

curl -X POST "https://graph.facebook.com/v24.0/PHONE_NUMBER_ID/verify_code" \
  -H "Authorization: Bearer META_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "code": "123456" }'

3. Register the number

Register the number on the WhatsApp Cloud API with a six-digit PIN of your choice:

curl -X POST "https://graph.facebook.com/v24.0/PHONE_NUMBER_ID/register" \
  -H "Authorization: Bearer META_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "pin": "654321"
  }'

The PIN becomes the number's two-step verification PIN. Keep it: Meta asks for it when the number is registered again.

4. Turn on calling over SIP

Turn on calling for the number and point it at VoiceDock:

curl -X POST "https://graph.facebook.com/v24.0/PHONE_NUMBER_ID/settings" \
  -H "Authorization: Bearer META_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "calling": {
      "status": "ENABLED",
      "call_icon_visibility": "DEFAULT",
      "srtp_key_exchange_protocol": "SDES",
      "audio": { "additional_codecs": ["PCMA", "PCMU"] },
      "sip": {
        "status": "ENABLED",
        "servers": [{ "hostname": "sip.hmsovereign.com", "port": 5061 }]
      }
    }
  }'

call_icon_visibility: DEFAULT shows the call button in the chat with your business.

5. Read the SIP password

Meta generates a SIP password for the number. Read it from the settings:

curl "https://graph.facebook.com/v24.0/PHONE_NUMBER_ID/settings?include_sip_credentials=true" \
  -H "Authorization: Bearer META_TOKEN"

The password is in calling.sip.servers[0].sip_user_password. Treat it like any other secret.

6. Give VoiceDock the password

Send the password to VoiceDock:

curl -X PUT "https://api.hmsovereign.com/api/v1/numbers/NUMBER_ID/whatsapp" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sip_password": "THE_PASSWORD_FROM_META" }'

Or do it in the dashboard: Numbers → your number → WhatsApp calling.

The response is 202 Accepted with status pending:

{
  "status": "pending",
  "error_code": null,
  "sip_username": "31850835037",
  "updated_at": "2026-10-15T12:00:00Z"
}

sip_username is the number without the +, which is the username Meta uses. You only need to send sip_username if Meta authenticates with a different one. The password is stored encrypted and is never returned.

Check the status until it is active, usually within a minute:

curl "https://api.hmsovereign.com/api/v1/numbers/NUMBER_ID/whatsapp" \
  -H "Authorization: Bearer YOUR_API_KEY"

Once it is active, open WhatsApp on a phone, go to the chat with your number and tap the call button. Your assistant answers.

What callers experience

• They call from the chat with your business by tapping the call button, or by opening https://wa.me/call/31850835037: your number without the +. You can put that link on your website or in an email.
• WhatsApp calling works in the WhatsApp app on Android and iOS, not in WhatsApp Web or WhatsApp Desktop.
• Your assistant answers as it does a phone call, with the same prompt, voice and tools.
• The caller's number is the phone number of their WhatsApp account. It arrives in customer.number in your webhooks and in caller_phone on the call.

Every webhook carries call.channel, and every call record channel. It is whatsapp for these calls and phone for calls over the phone network, so your systems can tell them apart:

{
  "message": {
    "type": "status-update",
    "call": {
      "id": "5c4d030f-43e3-4e65-899e-8148521e660f",
      "type": "inbound_phone_call",
      "channel": "whatsapp",
      "status": "in-progress"
    },
    "phone_number": { "number": "+31850835037" },
    "customer": { "number": "+31612345678" }
  }
}

Rules for WhatsApp calls

• Calls placed by WhatsApp users only. Your assistant answers WhatsApp calls; it does not place them.
• Billing. Meta does not charge for calls that WhatsApp users place to your business. On VoiceDock a WhatsApp call is billed like any other call, except that there is no telephony charge, because the call does not use the phone network.
• Simultaneous calls. Meta allows up to 1,000 simultaneous WhatsApp calls per number.
• Keep your assistant answering. When many WhatsApp calls go unanswered, Meta can hide the call button for your number. Keep the assistant assigned to the number and your credits topped up.
• Up to 10 numbers per organization. Contact support if you need more.

Status and error codes

GET /numbers/{id}/whatsapp returns one of these statuses:

With refused or failed, error_code is one of:

While the status is pending, error_code can show lock_busy (another change is being applied first) or upgrade_in_progress (platform maintenance). The change goes through by itself afterwards; there is nothing to do.

The endpoint itself answers with these errors, in the format { "error": "<code>", "message": "..." }:

Change or reset the password

If the password may have leaked, have Meta generate a new one. Turn off calling and SIP for the number:

curl -X POST "https://graph.facebook.com/v24.0/PHONE_NUMBER_ID/settings" \
  -H "Authorization: Bearer META_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "calling": {
      "status": "DISABLED",
      "sip": { "status": "DISABLED", "servers": [] }
    }
  }'

Then turn it on again with the request from step 4, read the new password as in step 5, and send it to VoiceDock with the same PUT as in step 6. Sending the PUT again replaces the stored password. Until VoiceDock has the new password, WhatsApp calls to the number do not reach your assistant.

Turn off WhatsApp calling

curl -X DELETE "https://api.hmsovereign.com/api/v1/numbers/NUMBER_ID/whatsapp" \
  -H "Authorization: Bearer YOUR_API_KEY"

The response is 202 Accepted with status disabling, and the stored password is removed. Phone calls to the number are not affected. Turn off calling for the number at Meta as well, or WhatsApp users keep seeing a call button that no longer reaches your assistant.

Troubleshooting

Related

• Phone Numbers: the numbers WhatsApp calling runs on
• Get WhatsApp calling status, Turn on WhatsApp calling and Turn off WhatsApp calling: the API reference
• Webhooks: call.channel in every payload
• Call Transfers: transfers on phone calls