Answer WhatsApp calls with an Omni agent

Your customers already have WhatsApp open. With WhatsApp Business Calling, a tap on the call button in your business chat rings straight into an Omni agent, no phone number to buy, no telephony bridge to run. PyAI terminates Meta’s WebRTC leg and hands your agent the same audio it gets on a phone call.

Preview. WhatsApp calling is rolling out per deployment. The API below is final; ask us to enable it on your org.

How it fits together

Meta signals the call to PyAI (calls webhook) and streams the audio over WebRTC. PyAI answers, converts the audio, and opens an Omni session for the agent bound to the number. You never touch SDP, ICE, or Opus.

Before you start

A WhatsApp Business number on Meta’s Cloud API with a messaging limit of at least 2,000 conversations per day (Meta’s prerequisite for calling).
A system-user access token for that WhatsApp Business Account with the whatsapp_business_messaging permission.
A PyAI live API key with the telephony:manage scope.

1. Point Meta’s webhooks at PyAI

In your Meta app: WhatsApp → Configuration → Webhooks. Set the callback URL to https://api.pyai.com/public/whatsapp/webhook, use the verify token PyAI gave you, and subscribe to calls and messages (the second one carries call-permission replies).

2. Register the number and bind an agent

curl https://api.pyai.com/v1/whatsapp/numbers \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "waba_id": "1029384756",
    "phone_number_id": "1234567890",
    "display_phone_number": "+14155550123",
    "access_token": "EAAB...",
    "agent_id": "agent_29c8b2bb..."
  }'

The token is stored encrypted and never returned. Rebind the agent any time with POST /v1/whatsapp/numbers/{id}/assign.

3. Turn calling on

curl -X POST https://api.pyai.com/v1/whatsapp/numbers/wan_.../calling \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

This pushes Meta’s calling settings for the number (call button on, and a user who calls you automatically grants a 7-day call-back permission). Users may take a little while to see the call button; opening the chat info page refreshes it. That’s it for inbound. Tap the call button in the business chat and your agent answers with its greeting.

Calling a user (business-initiated)

Meta requires the user’s permission before you can call them. Ask for it:

curl -X POST https://api.pyai.com/v1/whatsapp/call-permissions \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "number_id": "wan_...", "to": "+919876543210",
        "text": "May we call you about your order?" }'

Meta shows the user a prompt; their answer arrives on the webhook and PyAI records it. Check it with GET /v1/whatsapp/call-permissions?number_id=…&user=…. Then place the call:

curl -X POST https://api.pyai.com/v1/whatsapp/calls \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -H "Idempotency-Key: order-4711-callback" \
  -H "Content-Type: application/json" \
  -d '{ "number_id": "wan_...", "to": "+919876543210" }'

Without a live permission the call is refused with call_permission_required. Permission requests are rate-limited by Meta (one per 24 hours, two per 7 days per user), and business-initiated calls are not offered in every country.

Call records

GET /v1/whatsapp/calls lists calls newest first with direction, status, connect and end times, and duration. Hang up from your side with POST /v1/whatsapp/calls/{id}/terminate.

What’s different from a phone call

No DTMF. WhatsApp users speak; keypad tones are not delivered to the agent.
No transfer to a human. There is no phone leg to transfer; end the call and follow up in the chat instead.
Audio is wideband on WhatsApp’s side; the agent hears it at telephony quality today.

Reference

The WhatsApp tag in the OpenAPI contract lists every endpoint and schema.
Telephony audio for what the agent hears on a call leg.
Meta’s Cloud API Calling docs for number prerequisites and regional availability.

Get started

Agents

Speech To Text (Hear)

Text To Speech (Speak)

Clone

Cast

Dub

Calls & intelligence

Frameworks

Integrations

Use cases

Reference

Answer WhatsApp calls with an Omni agent

How it fits together

Before you start

1. Point Meta’s webhooks at PyAI

2. Register the number and bind an agent

3. Turn calling on

Calling a user (business-initiated)

Call records

What’s different from a phone call

Reference

​How it fits together

​Before you start

​1. Point Meta’s webhooks at PyAI

​2. Register the number and bind an agent

​3. Turn calling on

​Calling a user (business-initiated)

​Call records

​What’s different from a phone call

​Reference

How it fits together

Before you start

1. Point Meta’s webhooks at PyAI

2. Register the number and bind an agent

3. Turn calling on

Calling a user (business-initiated)

Call records

What’s different from a phone call

Reference