Skip to main content
Kapso forwards call events to your webhook and proxies call actions to Meta. Audio and the agent run on your own server or voice provider. To start from working code, enable Calling, then deploy the voice agent starter. It registers its own webhook and handles audio, so you can skip steps 3 and 4.
gokapso/whatsapp-voice-agent-starter
Loading repository data...

What you need

  • A dedicated WhatsApp Cloud API number in your Kapso project, with a messaging limit of at least 2,000 unique recipients per day.
  • A Kapso API key from that project and the number’s Meta phone number ID.
  • A public HTTPS endpoint for call webhooks.
  • A media server that handles WebRTC audio and generates SDP offers and answers.
The Kapso sandbox doesn’t support Calling, and coexistence numbers keep their calls in the WhatsApp Business App. Meta decides eligibility and country availability; check Meta’s current prerequisites before picking a number.

1. Configure your application

Add these to your .env:
To run the shell examples on this page, load it with set -a && source .env && set +a. Your speech-to-text, LLM, and text-to-speech provider keys go on your server too. WHATSAPP_PHONE_NUMBER_ID is Meta’s phone number ID, not the display number, WABA ID, project ID, or Kapso configuration UUID. Find it under Phone numbers in the dashboard, or list your numbers:

2. Enable Calling

Or in the dashboard: open Phone numbers, select the number, and turn on Calls in its Settings tab. Either way, Kapso sends the setting to Meta; you don’t need to change anything in Meta Business Manager. Check the result through the proxy:
calling.status should be ENABLED. If Meta rejects the number as ineligible, resolve that first. Changing the voice model or webhook won’t enable it.

Choose who answers

Once Calling is on, the number shows Incoming call answering in the dashboard. Call activity appears in the Inbox with any option. Use Agent or integration for agent-only calls. To keep the agent and let teammates answer, select Agent with Inbox fallback. See Inbox calls.

3. Register a Meta webhook

Calling events keep Meta’s payload format, so they go to a phone-number webhook with kind: "meta". Kapso-format webhooks and project webhooks don’t receive them. Check whether the number already has one:
Each number can have only one Meta webhook, including inactive ones. If one exists, reuse it or update it deliberately: changing it moves every Meta event for the number, not just calls. If there’s no Meta webhook, create one. jq encodes the URL and secret safely:
secret_key is required. Kapso signs deliveries with it; it’s not your API key. Save the returned webhook ID, then list the webhooks again and confirm the URL and active: true. Before placing a call, check for overlap:
  • A kind: "kapso" webhook already processes your messages. The Meta webhook also receives Meta messages changes. Process normal messages from only one of them to avoid duplicate replies, and handle Calling permission replies on the Meta webhook.
  • A voice agent is assigned to the number in the dashboard. Decide whether that agent or your receiver answers calls. Don’t let both answer.

4. Connect audio

Events and SDP travel over HTTPS through Kapso. Audio skips Kapso: it travels over WebRTC between Meta and your media server, so that server must be reachable for media too. ICE picks the media path: STUN discovers a reachable address, and TURN relays audio when a direct connection fails. A tunnel like Tailscale Funnel can deliver webhooks to a local server, but it doesn’t make UDP media reachable. Configure a TURN relay if your network needs one. Hosts without inbound UDP can still work: the voice agent starter connects audio on Railway with only a public STUN server. With your receiver and voice agent running, call the number from WhatsApp. To skip building both, deploy the starter. You can also send a call button that the user taps to call you.

Other Calling features

Meta can record and transcribe calls you opt in. Kapso shows the results in call details and serves them through the API; see Recordings and transcripts. Meta also documents SIP, voicemail, and partner call routing. These guides cover WebRTC only; those features need their own setup and testing. Routing a number’s calls over SIP replaces the Calling API for that number, so Kapso call actions and Inbox answering stop. A messaging handoff doesn’t transfer a live call.

Pricing

User-initiated calls are free. Meta charges business-initiated calls by destination country and monthly volume, in 6-second pulses. Kapso adds no Calling markup. See Calling pricing.

Troubleshooting

If your agent cannot answer or Inbox has no answer controls, start with Calling troubleshooting.

Receive calls

Verify events, answer a call, and end the session.

Connect a voice agent

Deploy the starter, or connect Pipecat, ElevenLabs Agents, or Grok Voice.

Make outbound calls

Check permission, dial, and apply the caller’s SDP answer.

Recordings and transcripts

Opt calls into Meta capture, then play, read, and download the results.

TypeScript SDK

Use the call action, permission, and log helpers.