Skip to main content

Call lifecycle

Complete Calling setup first.
  1. Receive a calls change with event: "connect", direction: "USER_INITIATED", and an SDP offer.
  2. Create one media session for the call ID, apply the offer, and generate an SDP answer.
  3. Start the audio pipeline without speaking, and send pre_accept with the answer.
  4. Once media is ready, send accept. Greet only after accept succeeds and media is connected; pre_accept doesn’t answer the call.
  5. On event: "terminate", stop the pipeline and close the media connection.
One delivery can batch several entries, changes, calls, and statuses. Iterate over all of them and route by value.metadata.phone_number_id. Statuses such as RINGING, ACCEPTED, and REJECTED arrive in value.statuses[] on the same calls field, with the call ID in id. Outbound calls rely on them.
Store from_user_id when present, and don’t assume from is a phone number; see business-scoped user IDs.

Verify the webhook

Kapso signs forwarded Meta webhooks with a hex HMAC-SHA256 of the raw request body in X-Webhook-Signature, keyed with your webhook’s secret_key. Verify it before parsing JSON. This isn’t Meta’s X-Hub-Signature-256 scheme and doesn’t use your Meta app secret. This Express handler verifies the signature and queues every event. enqueueCallEvent and enqueueOtherMetaChange are yours to implement with your queue or router; they must persist the event before the handler returns 200. Don’t start the conversation inside the request.
Register this route before any global JSON parser so the raw body stays intact. Return 200 within the 10-second webhook timeout, and run session startup and the conversation in a worker. If you already process normal messages from a Kapso-format webhook, skip them here to avoid processing them twice, but keep handling interactive.call_permission_reply.

Pre-accept and accept

Both actions use your API key. answer.sdp must come from the WebRTC session that applied this call’s offer.
To record or transcribe the call, add recording and/or transcription to the accept body, never to pre_accept. See Recordings and transcripts. A 409 means Kapso gave the call to another answerer, based on the number’s Incoming call answering setting. Stop the media session and don’t send reject; Kapso refuses it the same way.
For SDK equivalents, see Calls. To generate answer.sdp from a voice runtime, see Connect a voice agent.

End or reject a call

  • Caller hangs up: you receive terminate. Stop the pipeline and close the media connection. Don’t start a new session or try to accept the call.
  • Your agent hangs up: let the farewell audio finish, send terminate, then close the media connection. Stopping the AI pipeline alone doesn’t end the WhatsApp call.

Handle duplicates and late events

Webhooks can be delivered more than once, so guard at two levels:
  • Per delivery. X-Idempotency-Key identifies the whole webhook body. Combine it with each event’s position in the payload, as the receiver above does; using the header alone would drop other calls in the same delivery. If the header is missing, skip this check rather than generating keys that collide.
  • Per call. Create at most one session per Meta call ID (call.id or status.id), and keep a terminal state so a late or repeated connect can’t restart an ended call.
With multiple workers, keep call state in shared storage and route each call’s events to the worker that owns its media session. call_recording_available and transcript events (call_transcript_available or call_transcription_available) arrive after terminate. Treat them as metadata: they must never start a session or reopen an ended call.