Webhook Payloads

This page documents the structure of webhook payloads sent by Vocobase when events occur.

Headers

Every webhook request includes these headers:

Header	Description
`Content-Type`	`application/json`
`X-Webhook-Signature`	HMAC-SHA256 signature: `sha256=<hex>`
`X-Webhook-Timestamp`	ISO 8601 timestamp when the event was sent

Event types

Branch on the top-level event field. These are the values accepted in an endpoint’s events allowlist — see Scoping & Event Filtering.

Event	Fired when
`session.completed`	A session finished and the post-call pipeline is done
`call.status.updated`	Telephony call status changed
`call.transferred`	The call was handed to a human or another number
`whatsapp.message.sent`	An outbound WhatsApp message was accepted by the provider
`whatsapp.message.failed`	An outbound WhatsApp message could not be sent
`whatsapp.message.status_updated`	Delivery or read receipt for a WhatsApp message

Six event types, and that is the complete list. GET /api/v2/config/webhooks returns the same set as data.available_events, so you can read it from the API rather than hard-coding it. webhook.test is fired only by the test endpoint and is not a valid allowlist value — it always reaches the endpoint being tested. Handle or ignore it explicitly.

How a failed session surfaces

A session that ends in a terminal failure — carrier no-answer, busy, rejected, or a bot that never started — is delivered as session.completed, not as a separate failure event. Every session-terminal path builds its payload through the same builder, which always emits event: "session.completed", including the explicit failure path. Branch on the payload, not on the event name:

Signal	Successful session	Failed session
`data.duration_seconds`	Actual bot-leg duration	`0`
`data.credits_used`	Credits deducted	`0`
`data.transcript`	Array of turns	`null`
`data.recording_url`	Presigned URL, or `null` if recording was off	`null`
`data.extraction`	Present when the agent has a Custom Analysis config	Absent
`data.call.status`	`completed`	`failed`, `no_answer`, `busy`, or `canceled`

data.call.status is the reliable discriminator for telephony sessions. For WebRTC sessions there is no call object at all, so use duration_seconds and transcript.

session.failed was previously published in this catalog with no producer behind it. It has been removed, and it is no longer accepted in an endpoint’s events allowlist — sending it now returns 400 VALIDATION_ERROR. Existing allowlists that contained it were stripped of it automatically; an endpoint left with an empty allowlist receives every event type.

inbound.route (below) is a pre-answer routing callback with its own headers and a required response body. It is not part of this event stream and cannot be subscribed to.

Event: `webhook.test`

Sent by POST /api/v2/config/webhooks/{id}/test. Signed and retried exactly like a real event, so receiving it confirms your URL, TLS, and signature verification all work end to end.

{
  "event": "webhook.test",
  "timestamp": "2026-05-25T10:30:00.000Z",
  "data": {
    "endpoint_id": "12345678-abcd-1234-abcd-123456789012",
    "label": "prod",
    "agent_id": null,
    "message": "This is a test event from Vocobase. If you received it, your endpoint and signature verification are wired correctly."
  }
}

agent_id is the endpoint’s scope: null for an account-wide endpoint, the agent’s id for an agent-scoped one.

Event: `inbound.route`

This event is sent when an account-configured pre-answer policy is available for a Vobiz or Plivo inbound call.

Payload structure

{
  "event": "inbound.route",
  "version": "2026-07-04",
  "provider": "plivo",
  "call": {
    "provider_call_id": "call-id",
    "from_number": "+919999999999",
    "to_number": "+918888888888"
  },
  "phone_number": {
    "id": "f1a2c3d4-1111-2222-3333-444455556666",
    "number": "+918888888888"
  },
  "agent": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Headers

Inbound route webhooks for this feature use feature-specific headers:

Header	Description
`Content-Type`	`application/json`
`X-Vocobase-Event`	`inbound.route`
`X-Vocobase-Timestamp`	Unix milliseconds when the payload was sent
`X-Vocobase-Signature`	`v1=<hex-hmac>`

Response contract

Accounts return JSON with an action value:

ANSWER_WITH_AI
SELECT_AGENT
TRANSFER
REJECT

When action is TRANSFER, to_number must be E.164. When action is SELECT_AGENT, agent_id must be set. Vocobase records each resolved route decision for your own observability. Query GET /api/v2/inbound-route-decisions to inspect action, source, webhook status, webhook latency, failure reason, transfer target, and created session or phone-call IDs.

Event: `call.status.updated`

Sent whenever Vocobase learns that a telephony call moved to a new meaningful call status. This event is for real-time orchestration: live dashboards, your own dialer queues, and concurrency release. call.status.updated is sent for phone calls only. Browser WebRTC sessions do not have a carrier call leg and therefore do not emit this event.

Payload structure

{
  "event": "call.status.updated",
  "timestamp": "2026-03-15T14:30:05.000Z",
  "data": {
    "call_id": "c1234567-abcd-1234-abcd-123456789012",
    "session_id": "s1234567-abcd-1234-abcd-123456789012",
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "agent_name": "Sales Assistant",
    "client_reference_id": "lead-9821",
    "direction": "outbound",
    "from_number": "+14155551234",
    "to_number": "+919876543210",
    "status": "ringing",
    "disposition": null,
    "answered_by": null,
    "end_call_reason": null,
    "hangup_cause": null,
    "hangup_source": null,
    "previous_status": "pending",
    "terminal": false,
    "concurrency_released": false,
    "account_concurrency": {
      "limit": 10,
      "active": 4,
      "remaining": 6
    },
    "provider": "twilio",
    "provider_status": "ringing",
    "provider_event": "ringing",
    "occurred_at": "2026-03-15T14:30:05.000Z"
  }
}

Field reference

Field	Type	Description
`event`	string	Always `"call.status.updated"`
`timestamp`	string (ISO 8601)	When Vocobase created the webhook event
`data.call_id`	string (UUID)	Unique Vocobase call identifier
`data.session_id`	string (UUID) or null	Associated session identifier. Normally present for calls started through `POST /calls/start`.
`data.agent_id`	string (UUID)	The agent assigned to the call
`data.agent_name`	string or null	Agent display name
`data.client_reference_id`	string or null	Client-supplied correlation key from `POST /calls/start`, when provided
`data.direction`	string	`outbound` or `inbound`
`data.from_number`	string	Caller phone number
`data.to_number`	string	Destination phone number
`data.status`	string	Normalized Vocobase call status. See Call status values.
`data.disposition`	string or null	Final call outcome when known: `completed`, `voicemail`, `user_hangup_no_speech`, `no_answer`, `busy`, `canceled`, `blocked`, `failed`, or `transferred`. Usually `null` on non-terminal updates.
`data.answered_by`	string or null	Best-known answer classification: `human`, `machine`, `unknown`, or `not_answered`. `machine` indicates an answering machine or voicemail.
`data.end_call_reason`	string or null	Why the call ended, in one vocabulary that reads the same on every carrier. `null` while the call is still live — see End call reason. On a terminal update this usually carries the carrier half only; `session.completed` is authoritative.
`data.hangup_cause`	string or null	Deprecated — removed in the next release. Use `end_call_reason`. Raw normalized carrier hangup cause when available
`data.hangup_source`	string or null	Deprecated — removed in the next release. Use `end_call_reason`. Best-known party or system that ended the call: `caller`, `callee`, `system`, `api`, `carrier`, `error`, or `unknown`
`data.previous_status`	string or null	Previous normalized status, when known
`data.terminal`	boolean	`true` when this status is final for the carrier call leg
`data.concurrency_released`	boolean	`true` when accounts can start the next call in their own queue
`data.account_concurrency`	object or null	Account-wide concurrency snapshot at event time. `limit`/`remaining` are `null` for unlimited accounts.
`data.provider`	string or null	Telephony provider: `twilio`, `plivo`, `vobiz`, `tata_smartflo`, `voicelink`, `sip`, `mcube`, or `exotel`
`data.provider_status`	string or null	Raw provider status value when available
`data.provider_event`	string or null	Raw provider event name when available
`data.occurred_at`	string (ISO 8601)	When the status transition was recorded. Not an end-of-call timestamp — see the warning below.

Do not build a call record from call.status.updated alone. This event is enqueued from the carrier’s callback, which can arrive several seconds before we have written the call’s final row. On a terminal update that means hangup_cause and hangup_source are frequently still null, end_call_reason usually carries only what the carrier said (not what our bot saw), and there is no end timestamp on this event at all — occurred_at marks the moment of the state transition, not the end of the call.Use call.status.updated for real-time dialer and concurrency orchestration. Use session.completed for the final record: it is built after the call row is settled and carries call.started_at, call.answered_at, call.ended_at and the final hangup attribution. If you need the record before session.completed arrives, poll GET /calls/{call_id}, which returns started_at and ended_at under those same names. answered_at is currently carried only on session.completed.

Call status values

Vocobase normalizes provider-specific call states into one vocabulary:

Status	Terminal	Releases concurrency	Meaning
`pending`	No	No	Vocobase accepted the call request and is waiting for provider progress
`ringing`	No	No	The callee’s phone is ringing
`in_progress`	No	No	The call was answered and the bot/callee leg is active
`completed`	Yes	Yes	An answered call ended normally
`failed`	Yes	Yes	The provider could not connect or continue the call
`no_answer`	Yes	Yes	The callee did not answer
`busy`	Yes	Yes	The callee line was busy
`canceled`	Yes	Yes	The call was canceled before completion

Provider normalization

Accounts should branch on data.status, not on provider-specific values. Vocobase stores the raw provider value for debugging.

Provider value	Vocobase status
Twilio `initiated`	`pending`
Twilio, Plivo, Vobiz `ringing`	`ringing`
Twilio, Plivo, Vobiz `in-progress`; Twilio call-progress `answered`; VoiceLink `call.answered`	`in_progress`
Twilio, Plivo, Vobiz `completed`; answered VoiceLink terminal call	`completed`
Twilio, Plivo, Vobiz `busy`	`busy`
Twilio, Plivo, Vobiz `no-answer`	`no_answer`
Twilio `canceled`; Plivo/Vobiz `cancel`; VoiceLink canceled classifications	`canceled`
Twilio `failed`; Plivo/Vobiz `timeout`; provider error states	`failed`
Tata Smartflo lifecycle payloads (`call_status` is `Answered` or `Missed`; flat snake_case fields include `call_id`, `uuid`, `hangup_cause`, `start_stamp`, `answer_stamp`, `end_stamp`, `billsec`, `recording_url`, and `direction`)	`Answered` maps to `in_progress` while live and `completed` after hangup; `Missed` maps to `no_answer`; terminal carrier/error causes map to `busy`, `canceled`, or `failed`

External queue orchestration

If you run your own dialer, use call.status.updated to manage slots:

function handleVocobaseWebhook(event) {
  if (event.event === "call.status.updated") {
    const update = event.data;

    updateDialerCall(update.call_id, update.status);

    if (update.concurrency_released) {
      startNextQueuedCall();
    }

    return;
  }

  if (event.event === "session.completed") {
    saveTranscriptAndRecording(event.data);
  }
}

Do not wait for session.completed to release a dialer slot. session.completed is the final rich result after transcript, recording, billing, and extraction processing.

Event: `session.completed`

Sent when a Vocobase session has reached final post-call processing. For telephony calls, this happens after the call leg ends and the bot/session pipeline has persisted transcript, recording metadata, billing, variables, and extraction results.

Payload structure

{
  "event": "session.completed",
  "timestamp": "2026-03-15T14:32:08.000Z",
  "data": {
    "session_id": "s1234567-abcd-1234-abcd-123456789012",
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "agent_name": "Sales Assistant",
    "duration_seconds": 127,
    "credits_used": 2.12,
    "processing_complete": true,
    "pipeline_completed_at": "2026-03-15T14:32:08.000Z",
    "transcript": [
      {
        "role": "bot",
        "content": "Hello! Thanks for taking my call. How can I help you today?",
        "timestamp": "2026-03-15T14:30:01.000Z"
      },
      {
        "role": "user",
        "content": "Hi, I'm interested in your enterprise plan.",
        "timestamp": "2026-03-15T14:30:04.500Z"
      },
      {
        "role": "bot",
        "content": "Great choice! Our enterprise plan includes unlimited agents, priority support, and custom voice training.",
        "timestamp": "2026-03-15T14:30:05.200Z"
      }
    ],
    "recording_url": "https://downloads.example.com/recordings/rec_abc123.wav?signature=...",
    "variables": {
      "callee_name": "Sajal",
      "mobile_number": "+919876543210"
    },
    "extraction": {
      "status": "success",
      "values": {
        "interested": true,
        "callback_at": "2026-05-01T15:00:00Z",
        "outcome": "callback_requested"
      },
      "model": "vocobase-managed",
      "extractedAt": "2026-03-15T14:32:09.840Z",
      "latencyMs": 1840,
      "attempts": 1
    },
    "hold": {
      "detected": false,
      "events": [],
      "total_secs": 0,
      "ended_on_hold": false,
      "kinds": []
    },
    "call": {
      "call_id": "c1234567-abcd-1234-abcd-123456789012",
      "client_reference_id": "lead-9821",
      "from_number": "+14155551234",
      "to_number": "+919876543210",
      "direction": "outbound",
      "status": "completed",
      "disposition": "completed",
      "answered_by": "human",
      "started_at": "2026-03-15T14:30:01.000Z",
      "answered_at": "2026-03-15T14:30:09.400Z",
      "ended_at": "2026-03-15T14:32:05.200Z",
      "end_call_reason": "CUSTOMER_HUNG_UP",
      "hangup_cause": "NORMAL_CLEARING",
      "hangup_source": "callee",
      "transferred": false,
      "transferred_at": null,
      "transfer_target": null
    }
  }
}

Field reference

Field	Type	Description
`event`	string	Always `"session.completed"`
`timestamp`	string (ISO 8601)	When the webhook was sent
`data`	object	Event data (see below)

Data object fields

Field	Type	Description
`session_id`	string (UUID)	Unique session identifier
`agent_id`	string (UUID)	The agent that handled the call
`agent_name`	string	Agent display name at time of call
`duration_seconds`	integer	Call duration in seconds
`credits_used`	number	Credits deducted for this call
`processing_complete`	boolean	`true` when post-call processing has finished. Always `true` on the webhook payload itself. Use it when polling `GET /calls/{id}` to tell final results from in-progress processing.
`pipeline_completed_at`	string (ISO 8601) or null	Timestamp when post-call processing finished. Non-null on the webhook. `null` when polling `GET /calls/{id}` and processing has not completed yet, or on older sessions that pre-date this field.
`transcript`	array or null	Ordered list of conversation turns (see below). `null` when the bot never ran — see How a failed session surfaces.
`recording_url`	string or null	Presigned URL for the call recording. `null` if recording was not enabled. URL is valid for 7 days. If it expires, mint a fresh one with `GET /calls/{call_id}/recording-url`.
`variables`	object	Pre-call variable values that were substituted into the agent’s prompt and greeting. Empty object `{}` when no variables were supplied. Echoed for your own audit.
`extraction`	object or absent	Post-call extraction result, present only when the agent has a Custom Analysis config defined. Status is `success`, `failed`, or `skipped` (no transcript). Values are typed per the agent’s config; missing keys are emitted as `null`. See Post-call Extraction below.
`hold`	object or null	Holds detected on the call: the phone network’s hold message, an automated receptionist, or the person asking to wait. `null` when hold detection did not run for this call; `{"detected": false, ...}` when it ran and found none. See Call holds below.
`call`	object or absent	Call metadata. Present only for telephony sessions started via `POST /calls/start`. Omitted entirely for browser WebRTC sessions started via `POST /sessions/webrtc` (no associated phone call).
`call.call_id`	string (UUID)	Unique call identifier
`call.client_reference_id`	string or null	Client-supplied correlation key from `POST /calls/start`, when provided. Same key and value as on `call.status.updated`.
`call.from_number`	string	Caller phone number (E.164)
`call.to_number`	string	Destination phone number (E.164)
`call.direction`	string	`"outbound"`
`call.status`	string	Final call lifecycle/carrier status at the time `session.completed` is emitted. Voicemail is exposed through `call.disposition`, not `call.status`.
`call.disposition`	string or null	Final call outcome: `completed`, `voicemail`, `user_hangup_no_speech`, `no_answer`, `busy`, `canceled`, `blocked`, `failed`, or `transferred`.
`call.answered_by`	string or null	Best-known answer classification: `human`, `machine`, `unknown`, or `not_answered`. `machine` indicates an answering machine or voicemail.
`call.started_at`	string (ISO 8601)	When the call leg was created — the moment Vocobase handed the dial to the carrier. Always present.
`call.answered_at`	string (ISO 8601) or null	When the callee picked up. `null` for calls that were never answered (`no_answer`, `busy`, `canceled`) — there was no media path, so there is no answer time.
`call.ended_at`	string (ISO 8601) or null	When the call leg was torn down. `null` only if the leg was never closed out (a stuck call the reaper has not yet finalized). This is the authoritative end-of-call timestamp — see the note below.
`call.end_call_reason`	string	Why the call ended. Never `null` on this event — every terminal call resolves to a value, including `UNKNOWN` and `NOT_CONNECTED`. Same key and same vocabulary as `call.status.updated` and `GET /calls/{call_id}`. See End call reason below.
`call.hangup_cause`	string or null	Deprecated — removed in the next release. Use `end_call_reason`. Raw normalized carrier hangup cause when available. Same value and same key as on `call.status.updated`.
`call.hangup_source`	string or null	Deprecated — removed in the next release. Use `end_call_reason`. Best-known party or system that ended the call: `caller`, `callee`, `system`, `api`, `carrier`, `error`, or `unknown`. Same value and same key as on `call.status.updated`. Not reported by every carrier.
`call.transferred`	boolean	`true` if the bot handed the call off to a human via the cold-transfer flow. See Transferred calls below.
`call.transferred_at`	string (ISO 8601) or null	When the bot left the room and the carrier began bridging the caller to the human. `null` for non-transferred calls.
`call.transfer_target`	string or null	E.164 destination the caller was bridged to. `null` for non-transferred calls.
`ivr`	object or absent	What the IVR flow did. Present only for calls placed on an IVR flow; absent on every other session. See IVR Flows calls below.

Transcript entry format

Each entry in the transcript array has:

Field	Type	Description
`role`	string	`"user"` or `"bot"`
`content`	string	What was said
`timestamp`	string (ISO 8601)	When this turn occurred

recording_url is a presigned URL valid for 7 days from the moment the webhook fires. Download and persist the recording on your side if you need long-term retention. If the URL expires before you can download it, call GET /calls/{call_id}/recording-url to mint a fresh one with another 7-day window.

End call reason

end_call_reason answers one question — why did this call end? — with one vocabulary that reads the same on every carrier, including MCube and Exotel, which report no carrier hangup cause at all. It is never null on session.completed. UNKNOWN and NOT_CONNECTED are values, not absence: they say what we honestly know, rather than implying a conversation that nothing witnessed.

Value	Resolved from	Meaning
`COMPLETED`	our bot	The bot ended the call — it said goodbye, the customer went quiet through the idle prompts, the duration cap was reached, or the call was left on hold for over a minute (then `hold.ended_on_hold` is `true` — see Call holds). On the terminal `call.status.updated` event only, also used when the carrier says the call connected and ended normally but our bot has not reported yet.
`CUSTOMER_HUNG_UP`	our bot	The remote leg disconnected first.
`VOICEMAIL`	carrier AMD or our bot	A machine answered. Agrees with `disposition: "voicemail"`.
`SCREENER`	our bot	A call screener answered. Takes precedence over carrier machine detection, so a screener never reads as `VOICEMAIL`.
`TRANSFERRED`	Vocobase	A transfer to a human was initiated. See the caveats below.
`SYSTEM_ERROR`	either	Infrastructure tore the call down mid-conversation, a connected call ended `failed` with no report from the bot, or the carrier reported a platform fault before connect.
`BUSY`	carrier or status	The line was busy.
`NO_ANSWER`	carrier or status	Rang out with no answer.
`REJECTED`	carrier	Declined by the callee or by their network — a DND scrub or a barred caller id reaches us identically to a human pressing decline (SIP 403 maps to Q.850 21). Do not read this as “a person said no”.
`BLOCKED`	carrier	The carrier refused to place the call at all.
`INVALID_NUMBER`	carrier	The number is unallocated or malformed.
`NETWORK_ERROR`	carrier	Congestion, circuit failure, or a network-side refusal.
`CANCELED`	status	The call was canceled before it completed.
`NOT_CONNECTED`	status	The call never connected and the carrier reported no reason. Common on MCube and Exotel, which report nothing: busy, no answer, wrong number and rejected all collapse into this one state and are genuinely not distinguishable.
`UNKNOWN`	status	The call is marked complete, but nothing witnessed a conversation: our bot never reported on it (for example, the bot process died mid-call and the session was reconciled from the carrier’s callback alone). The carrier cause is not consulted here. On `session.completed` and the `GET /calls` routes, a connected call with no bot report is `UNKNOWN`, never `COMPLETED`.

How it relates to `disposition`

They answer different questions and are both correct at once.

disposition is the coarse outcome bucket that drives campaign retry logic.
end_call_reason is why the call ended.

So these pairs are normal, not contradictions:

`end_call_reason`	`disposition`
`CUSTOMER_HUNG_UP`	`completed`	the most common pair on answered calls
`SYSTEM_ERROR`	`completed`	the conversation happened; our process was torn down during teardown
`REJECTED`	`blocked`	on Plivo and Vobiz
`REJECTED`	`failed`	on VoiceLink

Use disposition for retry logic. Use end_call_reason for reporting and for explaining an outcome to a human.

Caveats worth reading once

On call.status.updated, end_call_reason is null while the call is live. A reason for ending does not exist until the call ends.
On the terminal call.status.updated, it usually reflects the carrier half only. The carrier’s completion callback reaches us before our bot’s own end-of-call report is persisted, so an answered call typically reads COMPLETED on that event and, say, CUSTOMER_HUNG_UP on session.completed. session.completed is the authoritative one.
TRANSFERRED means the transfer was initiated, not that the human picked up: a busy transfer destination still reads TRANSFERRED.
TRANSFERRED is not reported on VoiceLink or MCube. Those carriers bridge the transfer in-band, so we never see it happen; a transferred call on them reads CUSTOMER_HUNG_UP. This is a known gap.
GET /calls and GET /calls/{call_id} can disagree on a call whose session failed but whose carrier leg completed. The single-call route reports the session’s status (failed, and so typically SYSTEM_ERROR); the list reports the carrier’s (completed, and so whatever the bot reported, or UNKNOWN). This is a pre-existing difference in how the two routes report status, which end_call_reason now follows. GET /calls/{call_id} is the more complete of the two.
GET /calls/{call_id} can report a transient failed / SYSTEM_ERROR in the short window after the carrier has ended a call but before our bot’s end-of-call report has been persisted (typically seconds; longer if the report is being retried). Once the report lands, the same call reads the bot’s reason. If you poll immediately after call.status.updated, prefer to wait for session.completed instead.
hangup_cause and hangup_source remain on every payload this release and are deprecated; they are removed in the next release. end_call_reason replaces both.

Call holds

Vocobase notices when a call is put on hold and reports every hold in hold.

`kind`	What it is	Example
`carrier_hold`	The phone network’s hold message	”The person you’re speaking with has put your call on hold”
`ivr_screen`	An automated receptionist screening the call	”Please stay on the line”, “Say your name and reason for calling”
`human_hold`	The person asks you to wait, then goes quiet	”One minute”, “ek minute, hold karo”, “hold on”

English, Hindi and Hinglish are recognised, plus common Punjabi and Marathi hold messages.

"hold": {
  "detected": true,
  "events": [
    {
      "kind": "carrier_hold",
      "started_at": "2026-03-15T14:30:40.500Z",
      "ended_at": "2026-03-15T14:31:46.300Z",
      "duration_secs": 65.8,
      "recovered": false
    }
  ],
  "total_secs": 65.8,
  "ended_on_hold": true,
  "kinds": ["carrier_hold"]
}

Field	Type	Description
`hold.detected`	boolean	`true` if at least one hold was found
`hold.events`	array	One entry per hold, in call order
`hold.events[].kind`	string	`carrier_hold`, `ivr_screen` or `human_hold`
`hold.events[].started_at`	string (ISO 8601)	When the hold began
`hold.events[].ended_at`	string (ISO 8601)	When the hold ended, or when the call ended if it was still on hold
`hold.events[].duration_secs`	number	Length of this hold in seconds
`hold.events[].recovered`	boolean	`true` if the person came back and the conversation carried on
`hold.total_secs`	number	Sum of all hold durations
`hold.ended_on_hold`	boolean	`true` if the call ended while still on hold
`hold.kinds`	array of string	Distinct kinds seen, in first-seen order

null is not the same as “no hold”. null means hold detection did not run for this call (it was off for the agent, or the call predates the feature). {"detected": false, ...} means it ran and found no hold. Long holds end the call. If a single hold lasts more than a minute, the agent says a short goodbye and hangs up, so a call parked on hold does not keep running. The call then reports end_call_reason: "COMPLETED" with hold.ended_on_hold: true. For a person asking to wait, only their silence counts toward the minute, not the agent’s own speech. Short waits are not holds. A person asking to wait is reported only if they stay quiet for at least 15 seconds; “one second” followed by more talking is ordinary conversation. A question (“one minute, who is this?”) is never a hold, and talking about a hold (“my loan is on hold”) is not one either. Holds inform extraction. When a hold is found, your post-call extraction is told about it, so an outcome such as “customer asked us to wait” is not missed just because the call carried on afterwards.

A hold message played by the phone network appears in transcript as a user turn, because it is heard on the customer’s side of the line. Use hold rather than the transcript to tell the two apart.

Hold detection is switched on per agent. Contact support to turn it off for an agent.

Final call status on `session.completed`

call.status in session.completed reflects the final known carrier state. For real-time intermediate statuses, use call.status.updated.

Status	Description
`completed`	Call connected and ended normally
`failed`	Call could not be placed (provider error)
`no_answer`	Recipient did not answer
`busy`	Recipient’s line was busy
`canceled`	Call was canceled before connecting

Call disposition values

Disposition	Description
`completed`	Human-answered call completed normally
`voicemail`	Carrier AMD or bot-side detection classified the answer as voicemail
`user_hangup_no_speech`	The callee answered, then hung up quickly before speaking
`no_answer`	Recipient did not answer
`busy`	Recipient’s line was busy
`canceled`	Call was canceled before connecting
`blocked`	Carrier/provider rejected or blocked the call
`failed`	Call failed or ended with an unmapped error outcome
`transferred`	Call was handed off to a human via the cold-transfer flow

Transferred calls

When an agent transfers a live call to a human:

The bot speaks the configured announcement (transfer_message).
Vocobase transfers the caller to transfer_target.
The session.completed webhook includes transfer metadata.

The session.completed webhook fires once the bot leg ends, not when the caller eventually hangs up with the human. This means:

duration_seconds reflects only the bot leg (caller-on-with-bot time).
recording_url, when present, is the bot-leg recording. The human side is not recorded.
call.transferred is true; call.transferred_at is the redirect moment; call.transfer_target is the destination E.164.

Use call.transferred as the cheap discriminator if your downstream automation needs to distinguish a transferred call from a normal hangup.

{
  "call": {
    "call_id": "c1234567-abcd-1234-abcd-123456789012",
    "from_number": "+14155551234",
    "to_number": "+919876543210",
    "direction": "outbound",
    "status": "completed",
    "disposition": "completed",
    "answered_by": "human",
    "transferred": true,
    "transferred_at": "2026-05-06T14:32:11.000Z",
    "transfer_target": "+14155559999"
  }
}

IVR Flows calls

Calls placed with POST /ivr-flows/{flowId}/calls (and test calls from the IVR editor) carry an extra ivr block on session.completed. Every other field is unchanged. The lead you pushed is echoed as variables. agent_id and agent_name identify an internal agent that backs the flow; key your integration on ivr.flow_id.

"ivr": {
  "flow_id": "f1234567-abcd-1234-abcd-123456789012",
  "flow_version": 3,
  "is_test": false,
  "outcome": "info_wrong",
  "failure": null,
  "keys": [ { "block": "confirm_menu", "key": "5", "at": 14200 } ],
  "path": [ "start", "fetch_loan", "intro", "confirm_menu", "end_wrong" ],
  "fetches": [ { "block": "fetch_loan", "status": 200, "latency_ms": 412, "ok": true } ]
}

Field	Type	Description
`ivr.flow_id`	string (UUID)	The IVR flow the call ran.
`ivr.flow_version`	integer or null	Version of the flow the call ran.
`ivr.is_test`	boolean	`true` for a test call placed from the dashboard on the unpublished draft.
`ivr.outcome`	string or null	Outcome code of the End block the call reached. `null` when the call ended before an End block: the caller hung up, the call failed, or a safety limit ended it.
`ivr.failure`	string or null	`null` on a normal call. `prefetch_failed`: a Fetch block that runs before dialing failed, so the number was never dialed. `max_steps` or `max_duration`: the call hit a safety limit and was ended. `dead_end`: the flow reached an exit with no arrow, so the call was ended. `runner_error`: the call was ended because of an error on our side.
`ivr.keys`	array	Keys pressed, in order. Each entry has `block` (the Menu block ID), `key` (`0`-`9`, `*`, `#`, or the digits entered on a collect menu) and `at` (integer, milliseconds from the start of the flow). On a menu marked masked, every digit is reported as `•`.
`ivr.path`	array of strings	Block IDs the call visited, in order.
`ivr.fetches`	array	One entry per Fetch block that ran: `block`, `status` (HTTP status, or `null` when no response arrived), `latency_ms`, `ok`, and `error` when `ok` is `false`.

ivr.fetches[].error is one of timeout, connect_error, url_blocked, too_large, bad_json, render_error, http_<status> (your API answered with a non-2xx status), missing_<field> (a required field was not in the response) or type_<field> (a field could not be read as its type). The ivr block never carries Fetch URLs, headers, request bodies or the values your API returned. Pre-dial failures. When a pre-dial Fetch fails, the number is never dialed. The call ends the way any failed session does: call.status is failed, call.end_call_reason is NOT_CONNECTED, duration_seconds and credits_used are 0, and transcript is null. ivr.failure is prefetch_failed, ivr.path ends at the Fetch that failed, and ivr.fetches shows why.

Event: `call.transferred`

Fired the moment a live call is handed off to a human, from the transfer route on a successful transfer. The call is still in progress when this fires, so there is no duration, disposition, transcript, or recording yet — transferred_at and transfer_target are the payload. Emitted for phone calls only. Browser WebRTC sessions cannot be transferred.

Payload structure

{
  "event": "call.transferred",
  "timestamp": "2026-05-06T14:32:11.000Z",
  "data": {
    "session_id": "s1234567-abcd-1234-abcd-123456789012",
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "agent_name": "Sales Assistant",
    "call": {
      "call_id": "c1234567-abcd-1234-abcd-123456789012",
      "client_reference_id": "lead-9821",
      "from_number": "+14155551234",
      "to_number": "+919876543210",
      "direction": "outbound",
      "transferred": true,
      "transferred_at": "2026-05-06T14:32:11.000Z",
      "transfer_target": "+14155559999"
    }
  }
}

Field reference

Field	Type	Description
`event`	string	Always `"call.transferred"`
`timestamp`	string (ISO 8601)	When Vocobase created the webhook event
`data.session_id`	string (UUID)	The session whose call was transferred
`data.agent_id`	string (UUID)	The agent that handed off the call
`data.agent_name`	string or null	Agent display name
`data.call.call_id`	string (UUID)	Unique call identifier
`data.call.client_reference_id`	string or null	Client-supplied correlation key from `POST /calls/start`, when provided
`data.call.from_number`	string	Caller phone number (E.164)
`data.call.to_number`	string	Destination phone number (E.164)
`data.call.direction`	string	`outbound` or `inbound`
`data.call.transferred`	boolean	Always `true` on this event
`data.call.transferred_at`	string (ISO 8601) or null	When the bot left the room and the carrier began bridging
`data.call.transfer_target`	string or null	E.164 destination the caller was bridged to

call.transferred does not replace session.completed. A transferred call still emits session.completed when the bot leg ends, with call.transferred: true. Use call.transferred when you need to react at hand-off time; use session.completed for the final record.

Events: `whatsapp.message.*`

Three events cover outbound WhatsApp messaging. They share one payload shape and differ only in the event value and the data.status that triggered them.

Event	Fired when
`whatsapp.message.sent`	The message was accepted by the provider
`whatsapp.message.failed`	The provider reported a terminal failure
`whatsapp.message.status_updated`	A non-failure delivery status advanced (delivered, read)

Payload structure

{
  "event": "whatsapp.message.status_updated",
  "data": {
    "message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgS",
    "session_id": "s1234567-abcd-1234-abcd-123456789012",
    "to_number": "+919876543210",
    "template_ref": "callback_confirmation/en",
    "status": "DELIVERED",
    "provider": "AISENSY",
    "ts": "2026-05-25T10:30:00.000Z"
  }
}

These payloads have no top-level timestamp. Every other event in this reference carries one; the WhatsApp events carry data.ts instead. If your handler reads event.timestamp unconditionally it will get undefined here. Fall back to data.ts, or to the X-Webhook-Timestamp header, which is sent on every delivery including these.

Field reference

Field	Type	Description
`event`	string	One of the three `whatsapp.message.*` values above
`data.message_id`	string or null	Provider message id. `null` until the provider has assigned one.
`data.session_id`	string (UUID) or null	The session the message belongs to. `null` for messages not tied to a session.
`data.to_number`	string	Destination number
`data.template_ref`	string	Campaign name, or `name/lang` for a template message
`data.status`	string	Delivery status, uppercase: `QUEUED`, `SENT`, `DELIVERED`, `READ`, `FAILED`, or `SKIPPED`
`data.error_code`	string or absent	Provider error code. Present only when the log row carries one — typically on `whatsapp.message.failed`.
`data.provider`	string	Messaging provider: `AISENSY` or `INTERAKT`
`data.ts`	string (ISO 8601)	When Vocobase built the event

data.status is uppercase here, unlike call.status.updated and session.completed, whose call statuses are lowercased. Compare case-insensitively if you normalize statuses across event types.

Scope resolution: the messaging log has no agent of its own, so the agent is resolved through the message’s session when there is one. A message with no session is agentless and therefore reaches account-wide endpoints only — an agent-scoped endpoint will never see it. See Scoping & Event Filtering.

Polling `GET /calls/{id}` vs webhook

Both the webhook and GET /api/v2/calls/{id} return the same data shape, so an account that can’t accept inbound webhooks (or wants to reconcile dropped deliveries) can poll the GET endpoint instead. A call can appear completed before all transcript, recording, and extraction fields are ready. The processing_complete boolean tells you when the response is final:

status                processing_complete    meaning
─────────────────────────────────────────────────────────────────────────────
pending/ringing/
in_progress           false                  call still in progress
completed             false                  call ended; post-call processing still running
completed             true                   final — transcript / recording / extraction are stable
failed/no_answer/
busy/canceled         true                   terminal failure; no bot transcript

Recommended polling pattern

async function fetchUntilReady(callId) {
  while (true) {
    const { data } = await vocobase.get(`/calls/${callId}`);
    if (data.session?.processing_complete === true) return data;
    if (data.status === 'failed' || data.status === 'no_answer' || data.status === 'busy') return data;
    await sleep(30_000);
  }
}

In practice the session.completed webhook will reach you before polling kicks in — polling is the fallback for accounts that can’t accept inbound webhooks, or for reconciliation after a delivery failure.

For sessions created before this field shipped, pipeline_completed_at will be null permanently. Treat null + status: completed on an older row as “final” — those rows pre-date the signal.

Post-call extraction

When the agent has a Custom Analysis config defined, the platform runs an LLM extraction over the transcript after every completed call and ships the result inline in the same session.completed webhook — no second webhook to handle. Configure extraction via the dashboard’s “Variables & Analytics” tab on the agent editor or via PUT /api/v2/agent/:id with extraction_config.

Extraction object structure

{
  "status": "success",
  "values": {
    "interested": true,
    "callback_at": "2026-05-01T15:00:00Z",
    "outcome": "callback_requested"
  },
  "model": "vocobase-managed",
  "extractedAt": "2026-03-15T14:32:09.840Z",
  "latencyMs": 1840,
  "attempts": 1
}

Field	Type	Description
`status`	string	`success`, `failed`, or `skipped`
`values`	object or absent	Extracted fields, typed per the agent’s `extraction_config.keys`. Missing fields are emitted as `null`. Absent entirely when `status != 'success'`.
`error`	string or absent	Failure reason — present only when `status === 'failed'`
`model`	string	Opaque extraction model identifier. Do not branch business logic on this value.
`extractedAt`	string (ISO 8601)	When extraction ran
`latencyMs`	integer	LLM latency in milliseconds
`attempts`	integer	Number of attempts (1 = success on first try; 2-3 = retried)

Extraction failures never block webhook delivery. The unified payload always ships with extraction.status indicating outcome — accounts that need extraction values can branch on status === 'success', accounts that just need transcript + recording can ignore the field.

Replay extraction against a past session

If you edit extraction_config and want to backfill an existing session, call POST /api/v2/calls/{call_id}/extract with { "dry_run": false }. Optional dry_run: true returns the result without persisting. The replay uses the agent’s current config (not the config at original-call time).

Pre-call variables

The variables field on every webhook echoes the per-call values that were substituted into the agent’s prompt and greeting. Configure variable names via the dashboard “Variables & Analytics” tab or PUT /api/v2/agent/:id with variables: ["callee_name", "mobile_number"]. Supply per-call values via POST /api/v2/calls/start body field variables: { callee_name: "Sajal" }. Missing values render as empty strings — the platform never errors on missing variables.

​Webhook Payloads

​Headers

​Event types

​How a failed session surfaces

​Event: webhook.test

​Event: inbound.route

​Payload structure

​Headers

​Response contract

​Event: call.status.updated

​Payload structure

​Field reference

​Call status values

​Provider normalization

​External queue orchestration

​Event: session.completed

​Payload structure

​Field reference

​Data object fields

​Transcript entry format

​End call reason

​How it relates to disposition

​Caveats worth reading once

​Call holds

​Final call status on session.completed

​Call disposition values

​Transferred calls

​IVR Flows calls

​Event: call.transferred

​Payload structure

​Field reference

​Events: whatsapp.message.*

​Payload structure

​Field reference

​Polling GET /calls/{id} vs webhook

​Recommended polling pattern

​Post-call extraction

​Extraction object structure

​Replay extraction against a past session

​Pre-call variables

​Next steps

Webhook Setup

Error Handling

Webhook Payloads

Headers

Event types

How a failed session surfaces

Event: `webhook.test`

Event: `inbound.route`

Payload structure

Headers

Response contract

Event: `call.status.updated`

Payload structure

Field reference

Call status values

Provider normalization

External queue orchestration

Event: `session.completed`

Payload structure

Field reference

Data object fields

Transcript entry format

End call reason

How it relates to `disposition`

Caveats worth reading once

Call holds

Final call status on `session.completed`

Call disposition values

Transferred calls

IVR Flows calls

Event: `call.transferred`

Payload structure

Field reference

Events: `whatsapp.message.*`

Payload structure

Field reference

Polling `GET /calls/{id}` vs webhook

Recommended polling pattern

Post-call extraction

Extraction object structure

Replay extraction against a past session

Pre-call variables

Next steps