Skip to main content

Deploy the starter

The WhatsApp voice agent starter is a Python server that answers your number’s calls through Kapso. The conversation runs on ElevenLabs Agents or xAI Grok Voice, Cal.com booking tools run on your server, and a small console shows recent calls.
gokapso/whatsapp-voice-agent-starter
Loading repository data...
Deploy on Railway The Railway template runs Grok Voice with a local development calendar. You need:
  • A Kapso number with Calling enabled, Incoming call answering set to Agent or integration, and no dashboard voice agent.
  • An xAI API key, your Kapso API key, and the number’s Meta phone number ID.
At startup, the server registers itself as the number’s Meta webhook if the number doesn’t have one; it never replaces an existing one. Then call the number from WhatsApp. To use ElevenLabs, connect Cal.com, or change the agent, deploy your own copy from the repository.

Choose an integration

To build your own, complete Calling setup first. Kapso handles call signaling; your media server or voice provider handles audio and the conversation.
Provider guides often connect directly to Meta. Through Kapso, use your Kapso API key, Kapso’s call-action URL, and Kapso’s webhook signature instead of a Meta access token and app-secret check. A provider’s own WhatsApp integration, such as ElevenLabs’, imports the number into that provider, so the number leaves Kapso.
The dashboard Pipecat provider launches Pipecat Cloud sessions. A stock self-hosted Pipecat server doesn’t implement that launch contract, so point the number’s Meta webhook at your own receiver instead. Only one of them should answer the number’s calls. Using ElevenLabs text-to-speech inside a Pipecat pipeline is different from ElevenLabs Agents, which hosts the conversation, prompt, and tools.

Connect the call to the agent

Your integration has three parts:
  1. Receiver and call state. Verify signatures, process every call and status in a delivery, and keep one session per Meta call ID. See Receive calls.
  2. WebRTC media. Generate SDP from the peer that carries this call’s audio, and keep that peer alive from ringing until hangup. Audio needs a reachable WebRTC path, with TURN if your network requires it.
  3. Provider session. Bridge the peer’s audio to your runtime. Match encodings and sample rates; for ElevenLabs, read the negotiated formats from the conversation metadata. Keep provider credentials on your server, and map the provider’s session ID to the Meta call ID.
Start the agent only once the caller can hear it:
  • Inbound: prepare media without speaking, send pre_accept, then accept. Greet after accept succeeds and media is connected.
  • Outbound: apply the SDP answer to the pending connection as soon as it arrives, often while the phone is still ringing. Greet after the matching ACCEPTED status and media is connected. If your provider speaks as soon as a conversation opens, don’t open it until then.
Prompt, voice, turn detection, and tools are configured in your provider, not in Kapso. For Meta’s native recording or transcript, opt in on accept or connect; see Recordings and transcripts. Your runtime can also record or transcribe on its own, for example with Pipecat’s audio buffer or ElevenLabs post-call data. Those files stay with your provider, are billed by it, and don’t appear in Kapso’s call details.

End both sessions

  • Caller hangs up: Meta sends terminate. Close the provider session, pipeline, and WebRTC peer.
  • Agent hangs up: let the farewell audio finish, send terminate through Kapso, then release the same resources. For ElevenLabs, wire end-call behavior and conversation completion to this cleanup.
  • Startup or provider fails: reject an unanswered inbound call or terminate an active one, and release resources even if cleanup errors.
  • Audio never connects: if media isn’t connected shortly after accept, terminate the call and release resources. The starter waits 30 seconds.
Closing the pipeline or provider socket doesn’t end the WhatsApp call; from your side, only terminate does.

Test a full conversation

On a real phone, check:
  • Two-way audio.
  • A spoken request that reaches the right tool.
  • An interruption, followed by another turn that works.
  • Caller hangup and agent hangup.
A greeting alone doesn’t prove the agent hears the caller. For outbound calls, also run the outbound tests. If something breaks, see troubleshooting.

Agent skills

For agent-assisted implementation, use Kapso Agent Skills with these guides and the Calling API reference.