Call lifecycle
Complete Calling setup first.- Receive a
callschange withevent: "connect",direction: "USER_INITIATED", and an SDP offer. - Create one media session for the call ID, apply the offer, and generate an SDP answer.
- Start the audio pipeline without speaking, and send
pre_acceptwith the answer. - Once media is ready, send
accept. Greet only afteracceptsucceeds and media is connected;pre_acceptdoesn’t answer the call. - On
event: "terminate", stop the pipeline and close the media connection.
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.
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 inX-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.
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.
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.
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-Keyidentifies 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.idorstatus.id), and keep a terminal state so a late or repeatedconnectcan’t restart an ended call.
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.
