VoiceBot Webhooks

voicebot webhooks allow you to receive real time notifications about events occurring during a voicebot call when specific events occur, the voicebot platform sends http post requests to your configured webhook endpoints webhooks enable real time transcripts dynamic webhook overrides per session agent transfer orchestration post call analytics pipelines overview webhooks can be configured at bot creation time overridden per session using custom parameters on the voicebot websocket connection the response of the session start webhook webhook overrides (except session start) are cached for the lifecycle of the session supported webhook types webhook description session start triggered when a voicebot call begins session end triggered when the conversation ends pre agent transfer triggered before transferring to a human agent transcript events triggered on turn progress and turn complete important notes timeouts your webhook must respond within the configured timeout success criteria http 2xx responses are treated as successful retries failed webhooks are retried based on the retry configuration ordering consumers must handle out of order events session scope webhook overrides apply only to a single session bot to bot transfer webhook endpoints should be generic special override call setup url custom param overrides the session start webhook common webhook request format all webhook requests follow the same structure { "session id" "\<voicebot session id>", "conversation id" "\<voicebot conversation id>", "start time" "2025 07 16t11 40 57 000z", "end time" null, "landing number" "", "external id" "caxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "session state" "session start | session in progress | session end", "trigger reason" "timer | turn complete | turn progress | pre agent transfer | start | end", "contact uri" "\<phone number / endpoint>", "network type" "sip | pstn", "account id" "", "bot id" "bot uuid", "bot name" "bot name", "metadata" { "call sid" "caxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "stream sid" "" }, "custom parameters" { "key1" "value1", "key2" "value2" }, "events" \[ { "event type" "sentiment", "event id" "evt 1", "event data" {} } ] } event object { "event type" "sentiment | summary | intent | entity | outcome | transcript", "event id" "\<event id>", "event data" {} } transcript event data { "transcripts" \[ { "sequence" 1, "status" "inprogress | completed", "transcript segments" \[ { "speaker" "assistant", "text" "hello! how may i help you?", "start timestamp" "2025 10 31t21 27 44 330756z", "end timestamp" "2025 10 31t21 27 51 082429z" } ] } ] } transcript notes status defaults to completed inprogress is used only for active turns accumulated transcripts are sent per turn at most one sequence per webhook transcripts are not sent in session end webhook webhook types session start webhook when triggered when a voicebot call begins allows dynamic override of other webhook endpoints expected response (2xx) { "http code" 200, "response" { "data" { "greeting message" { "text" "dynamic greeting message for the user" }, "session constants" { "phone number" "x call from" }, "conversation assistant id" "", "webhook config" { "session end" { "url" "https //api example com/webhooks/session end" }, "pre agent transfer" { "url" "https //api example com/webhooks/pre agent transfer" }, "insights events" { "url" "https //api example com/webhooks/insights", "trigger type" "timer", "trigger interval sec" 30 }, "transcript events" { "url" "https //api example com/webhooks/transcripts" } } } } } pre agent transfer webhook when triggered when the bot detects user intent to talk to an agent expected response (2xx) { "http code" 200, "response" { "data" { "agent transfer message" { "text" "connecting you to a support agent" } } } } session end webhook when triggered when the conversation ends expected response (2xx) { "http code" 200, "response" { "data" {} } } transcript events webhook when triggered on turn progress turn complete expected response (2xx) { "http code" 200, "response" { "data" {} } } error response (all webhooks) { "http code" 500, "response" { "data" null, "error data" { "error code" "cl52894", "message" "internal server error", "description" "internal server error" } } }