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:
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
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 withkind: "meta". Kapso-format webhooks and project webhooks don’t receive them.
Check whether the number already has 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 Metamessageschanges. 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.

