Telephony Webhooks

Telephony Webhooks

Receive call, recording and verification events the moment they happen instead of polling. Every delivery is a signed JSON event with a stable envelope.

Payload version
2026-06-01
Format
JSON over HTTPS POST
Signature
HMAC-SHA256
Timestamps
IST and UTC

Introduction

Webhooks push events from Agentive cloud telephony to your own server. When a call or a verification code moves through its lifecycle, we send a signed HTTPS POST to each endpoint you register, so your CRM, order system or dashboard learns the outcome within seconds and you never have to poll.

Use webhooks when you need to react to a call: mark an order as confirmed when the recipient presses 1, retry a lead tomorrow after call.no_answer, unlock a signup on otp.verified, or file a recording the moment it is ready. Every event describes an object from the Voice API at https://voice.agentive.co.in/api/public/v1, so anything you learn here can be reconciled against Get call status.

Webhook delivery is free. You pay only for the calls and verification codes that generate the events, billed in INR against your Voice wallet at the rates shown in the Voice Broadcast and Voice OTP references. All timestamps are given in both Indian Standard Time and UTC.

Current payload version
The current payload version is 2026-06-01, sent as api_version on every event. See Versioning for the compatibility promise.

Platform conventions

Agentive ships two API families: the Voice APIs (Voice Broadcast, Click to Call, AI Voice Agent, Voice OTP and telephony webhooks) and the WhatsApp Business API. They share a brand, a dashboard account and a set of habits, but they are separate products and they do not agree on everything. This section is the one place that says what is common and, where they differ, exactly how.

Base URLs

Voice APIsWhatsApp Business API
Base URLhttps://api.agentive.co.in/api/public/v1, the API's own host since 17 October 2026. https://voice.agentive.co.in/api/public/v1 keeps working with the same keys and the same answers.https://app.agentive.co.in/api/v1
CoversVoice Broadcast, Click to Call, AI Voice Agent, Voice OTP and the endpoints webhook events point back at. All of them share one base, one credential pair and one envelope.Template sends for one API campaign. Issued and managed from the Chat dashboard.
TransportHTTPS only, JSON in and JSON out. Since 17 October 2026 api.agentive.co.in refuses plain HTTP with 403 https_required and never redirects it; voice.agentive.co.in redirects it, after the request has already crossed the network in clear.HTTPS only, JSON in and JSON out.

Authentication

Voice APIsWhatsApp Business API
CredentialOne publishable key (pk_live_...) and one secret (sk_live_...) per account.One token (agcamp_...) per API campaign, so a leaked token can only send that campaign.
How to send itx-api-key and x-api-secret headers, or HTTP Basic with the publishable key as the username and the secret as the password. A secret field in the JSON body is refused by the click to call endpoints and deprecated on the others (since 17 October 2026).Authorization: Bearer <token>.
ScopeAccount-wide. Every endpoint on the Voice base accepts it. A key can carry a list of allowed addresses; see Security below.Campaign-wide. The template and number are fixed on the campaign.
Treat asBoth keys are confidential. The publishable key names your account to anyone who holds it, so keep it with the secret, on your server only.A secret. Keep it on your server only.
RotationFrom the API Access tab of the Voice dashboard. By default the old secret stops working at once; for a planned change you can keep it working for 24 hours beside the new one.From the campaign page in the Chat dashboard. The old token stops working at once.

Error envelope

Voice APIsWhatsApp Business API
Shape{ status, code: number, error_code: string, error, details, unique_id, reference_id }{ error, code: string, details: object }
What to branch onerror_code. The numeric code mirrors the HTTP status and stays for compatibility.code, which is itself the machine string.
Human sentencedetails, repeated in error so a handler written for the WhatsApp shape reads a Voice error too.error.
Extra contextNamed fields beside the envelope (lines, lines_in_use, attempts_left, retry_after_sec, balance_inr).A details object (missing, retryAfter, meta, validation).

401 and 403

Voice APIsWhatsApp Business API
401Credentials missing, unknown, or rejected. The status never confirms whether a key exists.Token missing or wrong.
403Credentials accepted, but the account is not active or the product is not enabled. Also when the key's address list does not include the calling address (ip_not_allowed, once address lists are checked), and for plain HTTP to api.agentive.co.in (https_required, since 17 October 2026). A key whose account is not active, or whose API access is not enabled, is limited on its own: 240 of those refusals a minute, then HTTP 429 rate_limited with a Retry-After.Token accepted, but the campaign is not live or the number is not connected.
404Not found, or not yours. A foreign id is never a 403, because that would confirm it exists.Not found, or not yours. Same rule.

Idempotency

Voice APIsWhatsApp Business API
KeyIdempotency-Key request header, 1 to 128 visible characters. A longer key is refused with HTTP 400.externalId in the body (the Idempotency-Key header is accepted too), up to 160 characters.
Window24 hours per account.The life of the campaign.
A repeatReplays the stored response. The one exception is a 5xx raised after the call was already handed to the network: that reply is stored as call_state_unknown with a sentence appended telling you to check the call before retrying. A 400 or 404 is stored for the 24 hours too, so once you fix the request or the dashboard setting, send it with a new key. A 401 is never stored: the credentials are checked before the key is read.HTTP 200 with duplicate: true and the earlier delivery's current status.
Replay markerIdempotent-Replayed: true, plus the original idempotency-replayed: true header.duplicate: true in the body.
Same key, different bodyHTTP 422 with idempotency_conflict.The first send stands; the second is reported as a duplicate.
Still in flightHTTP 409 with idempotency_in_progress and Retry-After.Not applicable.

Rate limits and headers

Voice APIsWhatsApp Business API
BudgetPer account: 120 reads a minute and 120 writes a minute, counted separately, so polling can never starve call placement. Recording and voicemail downloads have their own 120 a minute. Since 17 October 2026 click to call controls have their own 120 a minute too, MP3 or WAV downloads and creating a recording link count in the download budget, and playing a recording link has its own budget of 600 a minute per account. Before keys are checked, requests are also limited by where they come from, counting only requests whose keys are rejected: 240 a minute per client address and 2,400 a minute per network address; going over answers HTTP 429 rate_limited with a Retry-After. Since 17 October 2026 a request with valid keys is not refused because of other callers' rejected requests, except while one network address is sending more than 24,000 rejected requests a minute.Per campaign token: 300 requests a minute over a sliding window.
Limit headersRateLimit-Limit, RateLimit-Remaining and RateLimit-Reset, with X-RateLimit-* aliases of the same three values.None.
How long to waitRetry-After on every 429 and every 409, mirrored in the body as retry_after_sec.Retry-After on rate_limited; details.retryAfter (IST) on quiet_hours.
Capacity refusalPlace a call, Trigger a saved campaign, Send a verification code and Place an AI agent call answer HTTP 429 concurrency_limit when the account has no free line, with lines, lines_in_use and retry_after_sec in the body and a Retry-After of 5 seconds. Call-placing responses also carry X-Agentive-Lines and X-Agentive-Lines-In-Use. Since 17 October 2026 a call your team members place over the internet (the dashboard, the apps, a click to call) counts against the lines too, and a call you place with Place a call, Trigger a saved campaign or Send a verification code holds its line until its call exists, up to 60 seconds (before, 3 seconds); an AI voice agent call (Place an AI agent call, or the trigger of an AI voice agent campaign) still frees its line 3 seconds after the request. A click to call takes its line before the team member is rung (two lines on Phone Bridge, one over the internet); when none is free it answers concurrency_limit with retry_after_sec 30 and a Retry-After of 30 seconds, without the lines figures or the X-Agentive-Lines headers.Not applicable; there are no lines to exhaust.

Webhook signing

Voice APIsWhatsApp Business API
Header to verifyX-Agentive-Signature-V2: t=<unix seconds>,v2=<hex>X-Agentive-Signature: <hex>, with no prefix.
What is signedHMAC-SHA256, with the signing secret, of t, a dot, then the exact raw body.HMAC-SHA256 of the exact raw body with the endpoint's signing secret.
FreshnessReject a t more than 300 seconds from your own clock. The timestamp is inside the signed material, so a captured delivery cannot be sent again later.Nothing time-bound is signed. De-duplicate on the event id for good, and accept deliveries over HTTPS only.
ComparisonConstant time, on bytes. Reject on any mismatch, and reject a delivery with no version 2 header.Constant time, on bytes. Reject on any mismatch.
Two different signatures
The Voice APIs sign the timestamp together with the body, and you verify only X-Agentive-Signature-V2. Voice deliveries also carry the older body-only X-Agentive-Signature for receivers built before version 2; do not accept it on its own, because it proves nothing about when a body was sent. The WhatsApp signature is the body alone with no prefix. A shared handler needs one verifier per product.

Webhook delivery headers

Voice APIsWhatsApp Business API
Event nameX-Agentive-EventX-Agentive-Event
Event idX-Agentive-Event-Id, the same value as id in the body. Shared by every endpoint that receives the event.X-Agentive-Delivery, the same value as id in the body. Despite the name it is the event id, not a per-endpoint delivery id.
Delivery idX-Agentive-Delivery-Id (dlv_...), one per event per endpoint, stable across every retry.None. X-Agentive-Delivery is the Chat product's name for the event id above.
Attempt numberX-Agentive-Attempt, 1-based, counting through the whole retry schedule.None.
Attempt timeX-Agentive-Timestamp, Unix seconds at the moment of this attempt, the same value as t in the version 2 signature. Check the age against the signed t, never against this header alone.X-Agentive-Timestamp, the same timestamp as the envelope.
User agentAgentive-Webhooks/2026-06-01Agentive-Webhooks/2026-05-08, the Chat payload version.
Sent fromOne IPv4 address, 139.59.48.158, since 17 October 2026, for endpoint events, campaign and key press webhooks, and your AI voice agent's webhooks (one narrow exception is in Where webhooks come from). We will tell you at least 30 days before it changes, by email to your account admins and in these docs. Still verify the signature.No published address. Verify the signature.

Webhook retries

Voice APIsWhatsApp Business API
AttemptsNine: three fast, then six spread out.Three.
Schedule0.5 s and 2 s between the first three, then 1 min, 5 min, 30 min, 2 h, 6 h and 12 h.0 s, 2 s and 8 s.
Total windowAbout 20 hours. A delivery not accepted 21 hours after its event is not sent again: it is marked failed when its next attempt comes due. Since 17 October 2026, while an endpoint is failing, we send one waiting delivery at a time, oldest first, and hold the rest; once it accepts one again, the held deliveries already due follow a few at a time. A held delivery can therefore reach its later attempts later than the schedule above.About 10 seconds.
Timeout per attempt6 seconds.10 seconds.
What you seeThe dashboard lists the latest 50 deliveries per endpoint with the event, the latest result, the number of tries and the time in IST. Each delivery is kept for 30 days, then deleted.The campaign's Deliveries tab shows the message and its current status.

Timestamps and amounts

Voice APIsWhatsApp Business API
Time zoneIndian Standard Time, ISO 8601 with a +05:30 offset. The field is named per product: created_at_ist on a call, expires_at_ist on a verification, timestamp_ist on a webhook envelope.timestamp on the webhook envelope is UTC ISO 8601. Schedules and quiet hours are set and reported in IST.
UTC alongsidecreated_at_utc on a call, and occurred_at (UTC) plus created (Unix seconds) on a webhook envelope.The envelope timestamp is already UTC.
MoneyIndian Rupees, always. balance_inr is a number, never a formatted string.Indian Rupees, always. Amounts appear in the dashboard, not in the send API.

Versioning and field case

Voice APIsWhatsApp Business API
API versionIn the path: /api/public/v1.In the path: /api/v1.
Payload versionapi_version on every webhook event. Currently 2026-06-01.apiVersion on every webhook event. Currently 2026-05-08.
CompatibilityFields are added, never removed or redefined. Ignore fields you do not recognise.Fields are added, never removed or redefined. Ignore fields you do not recognise.
Field casesnake_case throughout, request and response.camelCase throughout, request and response.

Security

  • Every credential is a secret. That includes the Voice publishable key, whatever its name suggests: treat it exactly like the secret. Keep all keys on your server, in an environment variable or a secrets store, never in a browser, a mobile app, a spreadsheet or source control.
  • Send them only to the API. Never forward a key or a secret to any other host, and do not let an HTTP client carry them across a redirect to another host.
  • Rotate at once if one leaks. Rotate the Voice pair from the API Access tab of the Voice dashboard and a WhatsApp token from its campaign page. A leaked value must stop working immediately, so update your server in the same step. (For a planned Voice change, and only then, you can keep the old secret working for 24 hours.)
  • HTTPS only. Write https:// in the base URL in your code. A request sent over plain HTTP has already exposed its credentials before any redirect can protect it. Since 17 October 2026 api.agentive.co.in refuses plain HTTP with 403 https_required; if a secret was ever sent over plain HTTP, rotate it.
  • Restrict a key to your servers. Since 17 October 2026 a Voice key can carry up to 10 allowed addresses or ranges, set under Allowed addresses on the API Access tab. A list takes effect once address lists are checked: until then the card says address lists are not being checked and the key is accepted from any address. Use api.agentive.co.in when your key has a list: there we see your server's own address exactly. api.agentive.co.in has an IPv4 address only: list your server's public IPv4 address. See Restrict your key to your servers' addresses.
  • Webhooks come from one address. Since 17 October 2026 our webhooks (endpoint events, campaign and key press webhooks, and your AI voice agent's webhooks) are sent from 139.59.48.158 (IPv4 only), and we will tell you at least 30 days before it changes, by email to your account admins. Allow it on your firewall if you need to, but the address says where a request came from, not that it is ours: authenticate every webhook by its signature. See Where webhooks come from for the one narrow exception.
Report a vulnerability
If you find a security problem in the APIs, the webhooks or the dashboard, write to hello@agentive.co.in with the steps to reproduce it. Please do not test against accounts that are not yours. Our contact details are also published at /.well-known/security.txt.
Reading this as one platform
The habits that hold across both products: HTTPS only, JSON both ways, a stable machine code on every error, an idempotency key on every request a retry could repeat, HMAC-SHA256 on every webhook, Indian Rupees and Indian Standard Time. The habits that do not: the credential header, the envelope key names, the field case, the signature scheme and the retry schedule. Write one transport layer per product, then share everything above it.

How webhooks work

  1. Register an endpoint
    In the Voice dashboard, add up to 10 webhook endpoints, each with an https:// URL and a signing secret.
  2. Choose events
    Pick the events each endpoint should receive. An endpoint with nothing ticked receives every event of the original list; the events added on 13 October 2026 arrive only when ticked by name. See Subscribing to events.
  3. We POST the event
    When a matching event occurs we send a JSON event object to your URL, signed in the X-Agentive-Signature-V2 header.
  4. You verify and respond
    Your server checks the signature, records the event and replies with a 2xx status within 6 seconds.
  5. Every attempt is counted
    The dashboard lists recent deliveries for each endpoint with the event, the latest result, the number of tries so far and the time in IST. Each delivery is kept for 30 days, then deleted. A delivery that does not get a 2xx is retried for about 20 hours; see Retries and delivery.

Events are sent for calls and verification requests created through the API, and for other relevant calls on your account, whenever the event matches an endpoint's subscription.

Setting up an endpoint

Open the Webhooks tab in the Voice dashboard. From there you can:

  • Add an endpoint: enter an https:// URL and either supply your own signing secret or let one be generated.
  • Choose events: tick the events you want. Leaving them all unticked receives every event of the original list, not the newer ones; see Subscribing to events.
  • Inspect a sample payload for any event, so you can build your handler before the first live call.
  • Toggle an endpoint active or inactive without deleting it.
  • Send a test event to confirm your receiver and signature check work end to end.
  • View recent deliveries, the latest 50: the event, the latest result with its response code, the number of tries so far and the time in IST. Each delivery is kept for 30 days, then deleted.

The signing secret is shown in full once, when the endpoint is created or when you rotate it. Afterwards it is masked. Keep it server-side; it is what proves a request came from us.

Public HTTPS endpoints only
The endpoint URL must be a public https:// address on port 443 or 8443. Plain http://, other ports, and private, loopback, link-local and internal addresses are refused when you save the endpoint, and the address is checked again every time we deliver. A custom signing secret must be at least 32 characters, and an account can register up to 10 endpoints. The same address rule applies to every webhook address you give us, campaign and AI agent webhooks included, and it is checked on every delivery: an address saved earlier on plain http:// or another port receives nothing until you change it. Over HTTPS the event body and its signature cannot be read off the network; the version 2 signature then stops a captured delivery being sent back to you later. See Rejecting a replayed body.

Where webhooks come from

Since 17 October 2026 our webhooks come from one IPv4 address: 139.59.48.158. That covers:

If your firewall accepts HTTPS only from known sources, allow this address on the port your endpoint uses (443 or 8443). We will tell you at least 30 days before this address changes, by email to your account admins and in this reference. Webhooks are sent over IPv4 only.

If we ever cannot send from this address for a while, we do not switch to another one: endpoint events wait and are retried on the schedule in Retries and delivery, for up to 21 hours after their event, and the other webhooks keep their own few quick attempts.

One exception: an endpoint whose own address is between 159.89.160.0 and 159.89.175.255 (the network block our server sits in) receives deliveries from 159.89.167.255 instead.

The address is not proof
The address says where a request came from, not that it is ours: always verify X-Agentive-Signature-V2. See Verifying the signature.

Agentive Chat as a subscriber

When your account is connected to Agentive Chat, call activity is delivered there on its own signed subscription: a call ending, a voicemail being left and a callback being requested. Your own endpoints are unaffected. Nothing is redirected or held back, and the events on this page keep arriving exactly as they do today.

Agentive Chat turns those into triggers for Ongoing WhatsApp campaigns, so a missed call or a finished call can send an approved template with nobody touching it. The events, the conditions you can filter on and the data each one carries are listed in WhatsApp Business API, When Agentive Voice is connected.

WhatsApp delivery status has a webhook of its own, on the Chat product, and it does not behave identically to this one: a bare hex signature with no prefix, different delivery headers, and three attempts over about ten seconds instead of nine over about 20 hours. The differences are set out row by row in Platform conventions above, so a shared handler can be written with its eyes open.

Events

Events are grouped by the resource they describe. The Object column is the value of data.object for that event; branch on it when one handler covers several events. Events marked Telephony API are offered only to an account with the Telephony API (the Phone + CRM plan) and reach an endpoint only when ticked by name.

Call events describe the calls on your account, not only the ones you place through the API; via_api is true on those. An account with the AI voice agent and not voice broadcast receives events for its AI calls only; any other account, including one with neither product, receives events for all its calls. With the Telephony API, every team call's event carries the whole call record: the team member, the times, the outcome detail, the recording, the outcome your team saved, and a version to order by.

Call lifecycle

EventObjectFires when
call.initiatedcallA call you placed through the API is accepted and queued.
call.ringingcallNot sent yet. Once announced: an inbound call reached your number and is ringing your team.
call.answeredcallThe conversation began: the customer answered your call, or your team member picked up an inbound one (AI voice agent calls keep the timing they always had).
call.completedcallA call that connected has ended.
call.no_answercallThe call ended without connecting: nobody answered, or it ended before an answer. Safe to retry later.
call.busycallThe line was busy or the call was declined. A retry can succeed.
call.failedcallThe call could not be placed or connected (invalid number, network fault). Retrying is unlikely to help.
call.analysed(AI call results)Accounts with the AI voice agent only. Once per answered AI call: the summary, outcome, collected answers and transcript. Documented in the AI Voice Agent API.

After the call (Telephony API)

EventObjectFires when
call.taggedcallYour team saved or changed the call's outcome, note or callback, marked the callback done, or removed it (a removed callback reads callback_at null).
voicemail.leftcallThe caller left a voicemail. Needs voicemail on your account.
call.updatedcallThe call's record changed after its final event, for a reason the other events do not cover.

Recording

EventObjectFires when
recording.availablerecordingThe call's recording is complete and ready to download. Once per call.
recording.failedcallTelephony API. An expected recording was still missing 12 hours after the call ended.

Team member rings (Telephony API, not sent yet)

EventObjectFires when
call.member_ringingcallOnce announced: a team member is being rung for a call, so your CRM can show the caller on that person's screen.
call.member_missedcallOnce announced: that ring ended without this team member answering.

Verification

EventObjectFires when
otp.sentverificationA voice verification call is queued for delivery.
otp.verifiedverificationThe recipient entered the correct code.
otp.failedverificationThe recipient entered an incorrect code. The verification stays open until it expires or runs out of attempts.
otp.max_attemptsverificationToo many incorrect attempts. The code is locked; send a new one to retry.

Click to call

Accounts with the Telephony API only; offered in the event list only to them. Each one carries the whole click to call object, with a sequence to order them by. Payloads, ordering and samples are in the Click to Call API.

EventObjectFires when
click_to_call.member_ringingclick_to_callYour team member is being rung.
click_to_call.member_answeredclick_to_callYour team member answered.
click_to_call.customer_ringingclick_to_callWe are calling the customer.
click_to_call.customer_answeredclick_to_callThe customer answered.
click_to_call.heldclick_to_callThe customer was put on hold through the API.
click_to_call.resumedclick_to_callThe customer was taken off hold.
click_to_call.transferredclick_to_callThe team member handed the customer on to a colleague, a call menu or another number. On a move to a call menu the click to call's recording ends at the move; the call menu part is a call of its own, lane menu.
click_to_call.endedclick_to_callThe click to call is over. Sent exactly once, with the outcome.
click_to_call.taggedclick_to_callThe team member saved an outcome, a note or a callback for the call.

Subscribing to events

  • An endpoint with no events ticked receives every event of the original list: the call lifecycle events, recording.available, the verification events, call.analysed and the click to call events. It never receives an event added later.
  • The events added on 13 October 2026 reach an endpoint only when you tick them by name: call.tagged, call.updated, voicemail.left, recording.failed, and once announced call.member_ringing and call.member_missed. They are offered only to an account with the Telephony API; voicemail.left also needs voicemail and recording.failed call recording on the account.
  • None of the new events is ever sent for an AI voice agent call.
The call-menu keypress hook is separate
If your account also posts a keypress from a call menu to an automation hook, that is a per-account hook of its own with its own address, its own body shape, and a signing secret it shares with campaign webhooks rather than with the endpoints on this page. It is not one of the events on this page, it does not appear in this delivery log, and subscribing an endpoint here does not turn it on or off. It is documented under Call menu key press webhook in the Voice Broadcast API reference. Since 17 October 2026 this hook and campaign webhooks come from the same IP address as the events on this page, 139.59.48.158; see Where webhooks come from.
A call that does not connect
Every call ends with exactly one terminal event, chosen by its status and end_reason: call.no_answer when nobody answered or it ended before an answer, call.busy when the line was busy or the call was declined, and call.failed only when it could not be placed or connected. The full table is in Which terminal event.

The event envelope

Every webhook body is a single JSON object with the same outer envelope. Only the data block changes between events.

JSON
{
  "id": "evt_4b8f2c1d6a3e4f0b9d7c2a1e5f6b8c0d",
  "object": "event",
  "api_version": "2026-06-01",
  "type": "call.completed",
  "created": 1780589528,
  "occurred_at": "2026-06-04T16:12:08.512Z",
  "timestamp_ist": "2026-06-04T21:42:08.512+05:30",
  "org_id": 42,
  "reference_id": "order-99213",
  "livemode": true,
  "data": {
    "object": "call",
    "unique_id": "run_4821",
    "call_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "leg_id": null,
    "click_to_call_id": null,
    "direction": "outbound",
    "from_number": "01100000021",
    "to_number": "+919812345678",
    "status": "completed",
    "duration_sec": 42,
    "end_reason": "completed",
    "campaign_id": 4821,
    "campaign_type": "audio_blast",
    "agent_id": null,
    "reference_id": "order-99213",
    "metadata": null,
    "via_api": true,
    "charge_inr": null,
    "response": {
      "disposition": null,
      "digit": null,
      "via": null,
      "answers": null,
      "voicemail_left": false
    }
  },
  "event": "call.completed",
  "event_id": "evt_4b8f2c1d6a3e4f0b9d7c2a1e5f6b8c0d"
}

Envelope fields

FieldTypeDescription
idstring
Unique id for this event, prefixed evt_. Use it to make your handler idempotent.
Example: evt_4b8f2c1d6a3e4f0b9d7c2a1e5f6b8c0d
objectstring
Always "event".
api_versionstring
The payload version used to build this event.
Example: 2026-06-01
typestring
The event name in resource.action form.
Example: call.completed
createdinteger
When the event was generated, as a Unix epoch timestamp in seconds.
Example: 1780589528
occurred_atstring
The same instant in UTC, ISO 8601 with a Z suffix.
Example: 2026-06-04T16:12:08.512Z
timestamp_iststring
The same instant in Indian Standard Time, ISO 8601 with a +05:30 offset.
Example: 2026-06-04T21:42:08.512+05:30
org_idinteger
Your account id.
reference_idstring | null
The reference_id you supplied when you placed the call or sent the code. null if you did not send one.
livemodeboolean
Always true. There is no separate sandbox mode; see Testing.
dataobject
The event-specific record. Its object field names the resource type: call, recording, verification or, for the click to call events, click_to_call.
eventstring
Alias of type. Kept for compatibility; prefer type.
event_idstring
Alias of id. Kept for compatibility; prefer id.
Notes
  • id and event_id are the same value. Prefer id.
  • type and event are the same value. Prefer type.
  • reference_id appears both at the top level and inside data, so you can read it wherever is convenient.
  • New fields may be added over time. Ignore fields you do not recognise.

Headers

Each delivery carries these headers:

HTTP
POST /webhooks/agentive HTTP/1.1
Host: example.com
Content-Type: application/json
X-Agentive-Event: call.completed
X-Agentive-Event-Id: evt_4b8f2c1d6a3e4f0b9d7c2a1e5f6b8c0d
X-Agentive-Delivery-Id: dlv_7c1e93a04b6d48f2b0a5d3e81c9f2740
X-Agentive-Attempt: 1
X-Agentive-Timestamp: 1780589528
X-Agentive-Signature-V2: t=1780589528,v2=9c41ab2f7e05d3c6b8a1f4e2d0c9b7a6e5f4d3c2b1a09f8e7d6c5b4a3f2e1d0c
X-Agentive-Signature: sha256=4f1d0c7b2a9e8d6f5c4b3a2918e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1908e9
User-Agent: Agentive-Webhooks/2026-06-01
HeaderTypeDescription
Content-Typestring
The body is always JSON.
Example: application/json
X-Agentive-Eventstring
The event name (the same value as type in the body), so you can route without parsing the body first.
Example: call.completed
X-Agentive-Event-Idstring
The same value as id in the body. Shared by every endpoint that receives this event. De-duplicate on it.
Example: evt_4b8f2c1d6a3e4f0b9d7c2a1e5f6b8c0d
X-Agentive-Delivery-Idstring
This event on its way to this endpoint. Stable across every retry of the delivery, so it is the right key for your own delivery log. Two endpoints receiving one event get two delivery ids and one event id.
Example: dlv_7c1e93a04b6d48f2b0a5d3e81c9f2740
X-Agentive-Attemptstring
Which attempt this is, counting from 1 and continuing through the whole retry schedule. Anything above 1 means an earlier attempt did not get a 2xx from you.
Example: 1
X-Agentive-Timestampstring
Unix seconds at the moment of this attempt, so it moves between retries of the same event. It is the same value as t in X-Agentive-Signature-V2. On its own it proves nothing: check the age against the signed t, as described in Rejecting a replayed body.
Example: 1780589528
X-Agentive-Signature-V2string
t=<unix seconds>,v2=<hex>: HMAC-SHA256 of t, a dot and the raw body, keyed with the endpoint's signing secret, recomputed on every attempt. The one to verify. See Verifying the signature.
Example: t=1780589528,v2=9c41...1d0c
X-Agentive-Signaturestring
The older signature: HMAC-SHA256 of the raw body alone, with a sha256= prefix, identical on every attempt. Still sent for receivers built before version 2. Do not accept it on its own: it cannot tell a fresh delivery from a replayed one.
Example: sha256=4f1d...08e9
User-Agentstring
Identifies the delivery agent. The version is the payload version, so it changes only when api_version does.
Example: Agentive-Webhooks/2026-06-01

Verifying the signature

Always verify the signature before trusting a webhook. It proves the request came from us, that the body was not altered and that it was sent in the last five minutes. Verify X-Agentive-Signature-V2: an HMAC-SHA256, with your endpoint's signing secret, of the timestamp t, a dot and the exact raw request body, hex-encoded.

Header
X-Agentive-Signature-V2: t=1780589528,v2=9c41ab2f7e05d3c6b8a1f4e2d0c9b7a6e5f4d3c2b1a09f8e7d6c5b4a3f2e1d0c
  1. Read the raw body
    Take the request body as bytes, before any JSON parsing or re-serialising. Re-serialising can change whitespace and break the check.
  2. Check the time
    Split the header on the comma. Reject the request if t is not a number or is more than 300 seconds from your own clock.
  3. Compute the digest
    Compute HMAC-SHA256(secret, t + "." + rawBody) and hex-encode it.
  4. Compare in constant time
    Check that it has the same length in bytes as v2, then compare the two with a constant-time comparison. Reject the request on any mismatch, and when the header is missing.
Reject on mismatch
If the computed signature and the header do not match, or there is no X-Agentive-Signature-V2, respond with a 401 and do not process the event. Never run the check with an empty secret: the samples below refuse to start without one.

Rejecting a replayed body

Every delivery carries two signatures, and they do different jobs.

  • X-Agentive-Signature (the older one) covers the raw body and nothing else. It proves a body came from us, but not when: all nine attempts of one delivery carry the same value, so someone who captured a delivery could send those bytes back later and it would still check out. Do not accept it on its own.
  • X-Agentive-Signature-V2 covers the timestamp and the body, as t=<unix seconds>,v2=<hex digest> where the digest is computed over "<t>.<body>". The t is the same value as X-Agentive-Timestamp, and it is recomputed on every attempt.
Verify V2, and only V2
An age check means something only when the timestamp is inside the signed material. Against the older signature it is not a security control, because anyone replaying a body can set X-Agentive-Timestamp to whatever they like, or strip the version 2 header and hope you fall back. Verify V2, reject anything older than five minutes, and refuse a delivery without it. Every delivery carries it.

Then de-duplicate as well, never instead. Record the event id (the id field, mirrored in X-Agentive-Event-Id) and ignore anything you have already handled, so our own retries are harmless too. If one of your endpoints can lag behind another, de-duplicate on X-Agentive-Delivery-Id instead, which is unique per endpoint and stable across all nine attempts.

Node.js
// Two checks, both needed. V2 signs the timestamp WITH the body, so an age
// check against it is meaningful. De-duplication then makes our own retries
// harmless too. rawBody is the Buffer from express.raw().
const parts = {};
for (const piece of String(req.header("X-Agentive-Signature-V2") || "").split(",")) {
  const i = piece.indexOf("=");
  if (i > 0) parts[piece.slice(0, i).trim()] = piece.slice(i + 1).trim();
}
const t = Number(parts.t);

// 1. Is it ours, and is it recent? Reject anything older than five minutes.
const fresh =
  Number.isFinite(t) && Math.abs(Math.floor(Date.now() / 1000) - t) <= 300;
const expected = Buffer.from(
  crypto
    .createHmac("sha256", SIGNING_SECRET)
    .update(String(t) + ".")
    .update(rawBody)                             // the EXACT bytes received
    .digest("hex"),
  "utf8"
);
const given = Buffer.from(parts.v2 || "", "utf8");

if (!fresh || given.length !== expected.length || !crypto.timingSafeEqual(given, expected)) {
  return res.status(401).send("bad signature");
}

// 2. Have we already handled it? Our retries carry the same id.
const evt = JSON.parse(rawBody.toString("utf8"));
const eventId = evt.id;                          // also X-Agentive-Event-Id

if (await seen.has(eventId)) {
  return res.status(200).send("ok");             // already handled, do nothing
}
await seen.add(eventId, { ttlSeconds: 172800 }); // 48 h covers the retry tail

await handle(evt);
return res.status(200).send("ok");

Together the two checks mean a request is acted on only when it is genuinely ours, genuinely recent, and genuinely new.

Example handlers

Each handler reads the raw body, verifies the version 2 signature with a five minute window in constant time, then switches on type. Store the secret in an environment variable such as AGENTIVE_WEBHOOK_SECRET; every handler refuses to start without it.

import express from "express";
import crypto from "crypto";

const SECRET = process.env.AGENTIVE_WEBHOOK_SECRET;
if (!SECRET) throw new Error("AGENTIVE_WEBHOOK_SECRET is not set"); // never verify with an empty key
const TOLERANCE_SEC = 300; // five minutes

const app = express();

// Capture the RAW body so the signature is computed over the exact bytes.
app.use("/webhooks/agentive", express.raw({ type: "application/json" }));

function verifyV2(rawBody, header) {
  const parts = {};
  for (const piece of String(header || "").split(",")) {
    const i = piece.indexOf("=");
    if (i > 0) parts[piece.slice(0, i).trim()] = piece.slice(i + 1).trim();
  }
  const t = Number(parts.t);
  if (!Number.isFinite(t) || !parts.v2) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > TOLERANCE_SEC) return false;
  const expected = crypto
    .createHmac("sha256", SECRET)
    .update(String(t) + ".")
    .update(rawBody)
    .digest("hex");
  const a = Buffer.from(parts.v2, "utf8");
  const b = Buffer.from(expected, "utf8");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post("/webhooks/agentive", (req, res) => {
  // Version 2 only: a delivery without X-Agentive-Signature-V2 is refused.
  if (!verifyV2(req.body, req.header("X-Agentive-Signature-V2"))) {
    return res.status(401).send("bad signature");
  }

  const evt = JSON.parse(req.body.toString("utf8"));

  // Idempotency: skip if you have already processed evt.id.
  // Ordering: apply a call only when evt.data.version is higher than the one you hold.
  // Act on voicemail.left by its type and evt.id: it can carry the terminal event's version.
  switch (evt.type) {
    case "call.completed":
      // evt.data is a call object
      console.log("call done", evt.data.unique_id, evt.data.duration_sec);
      break;
    case "otp.verified":
      console.log("verified", evt.data.request_id, evt.reference_id);
      break;
    default:
      // Ignore events you do not handle.
      break;
  }

  res.sendStatus(200);
});

app.listen(3000);

Reproducing a signature by hand

To confirm your tooling, compute the version 2 signature for a known timestamp and body from the shell and compare it with what your handler produces. The secret is read from the environment, so it never appears in your shell history or the process list:

Shell
# AGENTIVE_WEBHOOK_SECRET must already be set in your environment.
T=1780589528
BODY='{"type":"call.completed","id":"evt_abc","created":1780589528,"data":{}}'
printf '%s.%s' "$T" "$BODY" | python3 -c '
import hashlib, hmac, os, sys
key = os.environb[b"AGENTIVE_WEBHOOK_SECRET"]
print(hmac.new(key, sys.stdin.buffer.read(), hashlib.sha256).hexdigest())'
# Compare the result with the v2= part of X-Agentive-Signature-V2 (t=$T).

Call events

Every call.* event carries a call object in data. The same fields are present on each event; fields not yet known at that point in the lifecycle are null. The samples below follow one inbound call on an account with the Telephony API: Ravi calls your number, the call menu answers, he presses 1, Arjun is rung and does not answer, Neha answers, they talk, Ravi hangs up, and Neha saves an outcome. An account without the Telephony API receives the first 19 fields of the same object, shown at the end of this section.

One record, every surface
For a team call, the server builds the event and GET /calls/{call_id} from the same call record, so an event and a read at the same version carry the same values (a team member's or call menu's name is read when the event is built and can change later). Every team-call event carries version and updated_at; keep the copy with the highest version. See Ordering and idempotency.
Webhook event

call.initiated

Fires whenA call you placed through the API was accepted and queued for dialling. This is the first event for an API-placed call. It keeps its original fields on every account (no version).

Values at this event

FieldTypeDescription
statusstring
Always "queued".
call_idstring | null
Our record id for the call, present as soon as it exists.
duration_secnull
Set on the terminal event.
end_reasonnull
Set on the terminal event.
Sample event
{
  "id": "evt_a17c2f9b4d6e4a1c8f0b3d5e7a9c1b2d",
  "object": "event",
  "api_version": "2026-06-01",
  "type": "call.initiated",
  "created": 1780589500,
  "occurred_at": "2026-06-04T16:11:40.000Z",
  "timestamp_ist": "2026-06-04T21:41:40.000+05:30",
  "org_id": 42,
  "reference_id": "order-99213",
  "livemode": true,
  "data": {
    "object": "call",
    "unique_id": "run_4821",
    "call_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "leg_id": null,
    "click_to_call_id": null,
    "direction": "outbound",
    "from_number": "01100000021",
    "to_number": "+919812345678",
    "status": "queued",
    "duration_sec": null,
    "end_reason": null,
    "campaign_id": 4821,
    "campaign_type": "audio_blast",
    "agent_id": null,
    "reference_id": "order-99213",
    "metadata": null,
    "via_api": true,
    "charge_inr": null,
    "response": {
      "disposition": null,
      "digit": null,
      "via": null,
      "answers": null,
      "voicemail_left": null
    }
  },
  "event": "call.initiated",
  "event_id": "evt_a17c2f9b4d6e4a1c8f0b3d5e7a9c1b2d"
}
Webhook event

call.ringing

Fires whenNot sent yet; it will be announced in the changelog. From then on: an inbound call reached one of your numbers (a call menu, a number that rings a team member, or a Phone Bridge number) and is ringing, about half a second after the call record is created. Never sent for an outbound call, an AI voice agent call, or a call refused at the door.

Values at this event

FieldTypeDescription
statusstring
Always "ringing".
membernull
Nobody has been rung yet. Use call.member_ringing to learn who is rung.
end_reason, end_detailnull
Set on the terminal event.
Sample event
{
  "id": "evt_d06ded082bb74e2328b20f98f7960b23",
  "object": "event",
  "api_version": "2026-06-01",
  "type": "call.ringing",
  "created": 1791872727,
  "occurred_at": "2026-10-13T06:25:27.700Z",
  "timestamp_ist": "2026-10-13T11:55:27.700+05:30",
  "org_id": 42,
  "reference_id": null,
  "livemode": true,
  "data": {
    "object": "call",
    "unique_id": "7f0c2a9e-4b1d-4c3e-9a7f-1d2e3f4a5b6c",
    "call_id": "7f0c2a9e-4b1d-4c3e-9a7f-1d2e3f4a5b6c",
    "leg_id": null,
    "click_to_call_id": null,
    "direction": "inbound",
    "from_number": "919812345678",
    "to_number": "917900000000",
    "status": "ringing",
    "duration_sec": null,
    "end_reason": null,
    "campaign_id": null,
    "campaign_type": null,
    "agent_id": null,
    "reference_id": null,
    "metadata": null,
    "via_api": false,
    "charge_inr": null,
    "response": {
      "disposition": null,
      "digit": null,
      "via": null,
      "answers": null,
      "voicemail_left": false
    },
    "created_at": "2026-10-13 06:25:27",
    "created_at_utc": "2026-10-13T06:25:27Z",
    "created_at_ist": "2026-10-13T11:55:27+05:30",
    "transcript_available": false,
    "analysis_available": false,
    "version": 1,
    "updated_at": "2026-10-13T06:25:27.214Z",
    "updated_at_ist": "2026-10-13T11:55:27.214+05:30",
    "lane": "menu",
    "end_detail": null,
    "ended_by": null,
    "network_cause": null,
    "sip_status": null,
    "handled_by": null,
    "member": null,
    "assigned_member": null,
    "customer_member": null,
    "customer_number": "+919812345678",
    "business_number": "+917900000000",
    "started_at": "2026-10-13T06:25:27.000Z",
    "started_at_ist": "2026-10-13T11:55:27.000+05:30",
    "answered_at": null,
    "answered_at_ist": null,
    "ended_at": null,
    "ended_at_ist": null,
    "talk_sec": null,
    "wait_sec": null,
    "hold_sec": 0,
    "recording_available": false,
    "recording_url": null,
    "recording": {
      "status": "processing",
      "revision": 0,
      "url": null,
      "format": null,
      "size_bytes": null,
      "duration_sec": null,
      "channels": null,
      "channel_layout": null,
      "retention_days": 60,
      "expires_at": "2026-12-12T06:25:27.000Z",
      "parts": [],
      "parts_ordered": false
    },
    "disposition": null,
    "voicemail": null,
    "menu": null,
    "ring_attempts": [],
    "transfers": [],
    "campaign": null
  },
  "event": "call.ringing",
  "event_id": "evt_d06ded082bb74e2328b20f98f7960b23"
}
Treat call.ringing as optional
Never gate your logic on it: a call can go straight from call.initiated to call.answered or to a terminal event without ringing ever arriving. Outbound calls never send it.
Webhook event

call.answered

Fires whenThe conversation began, about a second after it did. On an inbound call: your team member picked up; the call menu answering the caller is not it. On an outbound call: the customer answered, Phone Bridge included (never the team member's own pickup on their mobile). Since 17 October 2026, on a broadcast call that a key press connected to a team member on the web panel or the app, call.answered still carries the customer's answer to the broadcast, which is earlier than the call's final answered_at: the record then takes the team member's pickup (see answered_at in The call object), and the terminal event carries it (a call.updated with changed answer only when the pickup is recorded after the terminal event was sent). Sent once, and never for a call that did not connect. AI voice agent calls keep the timing they always had.

Values at this event

FieldTypeDescription
statusstring
Always "in_progress".
memberobject | null
The team member on the call: who picked up an inbound call, or who placed an outbound one (a later transfer a colleague answers changes it: the final event names that colleague).
answered_atstring
When the conversation began, with its _ist twin. On a broadcast call that a key press connected to a team member on the web panel or the app, this is still the customer's answer to the broadcast; since 17 October 2026 the record and the terminal event then take the team member's pickup (see above).
duration_secnull
Set on the terminal event. Without the Telephony API it reads 0 here, as it always has.
end_reasonnull
Set on the terminal event.
Sample event
{
  "id": "evt_1fdd9490bd698a41b5f21650483c892d",
  "object": "event",
  "api_version": "2026-06-01",
  "type": "call.answered",
  "created": 1791872759,
  "occurred_at": "2026-10-13T06:25:59.500Z",
  "timestamp_ist": "2026-10-13T11:55:59.500+05:30",
  "org_id": 42,
  "reference_id": null,
  "livemode": true,
  "data": {
    "object": "call",
    "unique_id": "7f0c2a9e-4b1d-4c3e-9a7f-1d2e3f4a5b6c",
    "call_id": "7f0c2a9e-4b1d-4c3e-9a7f-1d2e3f4a5b6c",
    "leg_id": null,
    "click_to_call_id": null,
    "direction": "inbound",
    "from_number": "919812345678",
    "to_number": "917900000000",
    "status": "in_progress",
    "duration_sec": null,
    "end_reason": null,
    "campaign_id": null,
    "campaign_type": null,
    "agent_id": null,
    "reference_id": null,
    "metadata": null,
    "via_api": false,
    "charge_inr": null,
    "response": {
      "disposition": null,
      "digit": "1",
      "via": "keypad",
      "answers": null,
      "voicemail_left": false
    },
    "created_at": "2026-10-13 06:25:27",
    "created_at_utc": "2026-10-13T06:25:27Z",
    "created_at_ist": "2026-10-13T11:55:27+05:30",
    "transcript_available": false,
    "analysis_available": false,
    "version": 5,
    "updated_at": "2026-10-13T06:25:58.431Z",
    "updated_at_ist": "2026-10-13T11:55:58.431+05:30",
    "lane": "menu",
    "end_detail": null,
    "ended_by": null,
    "network_cause": null,
    "sip_status": null,
    "handled_by": null,
    "member": {
      "id": 1042,
      "name": "Neha Sharma",
      "removed": false
    },
    "assigned_member": null,
    "customer_member": null,
    "customer_number": "+919812345678",
    "business_number": "+917900000000",
    "started_at": "2026-10-13T06:25:27.000Z",
    "started_at_ist": "2026-10-13T11:55:27.000+05:30",
    "answered_at": "2026-10-13T06:25:58.000Z",
    "answered_at_ist": "2026-10-13T11:55:58.000+05:30",
    "ended_at": null,
    "ended_at_ist": null,
    "talk_sec": null,
    "wait_sec": null,
    "hold_sec": 0,
    "recording_available": false,
    "recording_url": null,
    "recording": {
      "status": "processing",
      "revision": 0,
      "url": null,
      "format": null,
      "size_bytes": null,
      "duration_sec": null,
      "channels": null,
      "channel_layout": null,
      "retention_days": 60,
      "expires_at": "2026-12-12T06:25:27.000Z",
      "parts": [],
      "parts_ordered": false
    },
    "disposition": null,
    "voicemail": null,
    "menu": {
      "id": 356,
      "name": "Main menu",
      "key": "1"
    },
    "ring_attempts": [
      {
        "kind": "member",
        "member": {
          "id": 1057,
          "name": "Arjun Mehta",
          "removed": false
        },
        "number": null,
        "result": "no_answer",
        "rang_sec": 15
      }
    ],
    "transfers": [],
    "campaign": null
  },
  "event": "call.answered",
  "event_id": "evt_1fdd9490bd698a41b5f21650483c892d"
}

A call whose record reaches us already ended (an App Agent call synced from the phone, a call refused at the door, a call logged by hand) sends no call.ringing or call.answered, only its terminal event. A call that was answered before your first endpoint was added (or before the account had the API) never sends call.answered later, only its terminal event.

When your team member moves a call whose customer had no record of their own (a click to call, and most outgoing calls your team member placed) into a call menu, the rest of the call goes on as a record of its own (lane menu, named by transfers[].to_call_id on the call it came from). No call.ringing is sent for that record. Its call.answered is sent when a team member picks up from the menu, or when the number a menu key forwards the call to answers, never at the move. If nobody does, only its terminal event is sent: call.no_answer, or call.completed (with the move as its answered_at) when a WhatsApp key, or a key that hands the call to an AI voice agent, connected it. An incoming call moved into a call menu stays on its own record, and its events are unchanged.

Not covered yet
A call your AI voice agent moved into a call menu still sends call.answered at the move, and when a team member's own mobile (Phone Bridge) picks up from the menu, member can name the team member the menu rang first.
Webhook event

call.completed

Fires whenA call that connected has ended. Sent once, about five seconds after the end; after a transfer, once, when the customer's whole call is over. The one exception is a call your team member moved into a call menu where the rest of the call goes on as a record of its own (named in transfers[].to_call_id): that call usually sends it a few seconds after the move, at the latest when the customer's whole call is over (since 14 October 2026; before, always when the whole call was over), and the call menu's record sends its own terminal event when the customer's call ends. Use it for "call done" logic, then let call.tagged and recording.available fill in the rest.

Values at this event

FieldTypeDescription
status, end_reasonstring
"completed", "completed". On an AI voice agent call a voicemail system answered, end_reason is "voicemail".
end_detailstring
connected, whatsapp_sent (a call menu key sent a WhatsApp message) or machine_answered (an answering machine took a broadcast call).
duration_secinteger
As it has always been: the talk time on calls your team placed or that rang a team member directly, the whole record on call menu calls. Use talk_sec for the conversation and wait_sec for the time before it.
recording.statusstring
Usually processing here: the file is still being stored. recording.available follows.
responseobject
How the recipient responded on Interactive Voice calls, and the call menu key on a menu call; see the call object.
Sample event
{
  "id": "evt_9509835da2546b4edaecf49a376d51f7",
  "object": "event",
  "api_version": "2026-06-01",
  "type": "call.completed",
  "created": 1791872845,
  "occurred_at": "2026-10-13T06:27:25.900Z",
  "timestamp_ist": "2026-10-13T11:57:25.900+05:30",
  "org_id": 42,
  "reference_id": null,
  "livemode": true,
  "data": {
    "object": "call",
    "unique_id": "7f0c2a9e-4b1d-4c3e-9a7f-1d2e3f4a5b6c",
    "call_id": "7f0c2a9e-4b1d-4c3e-9a7f-1d2e3f4a5b6c",
    "leg_id": null,
    "click_to_call_id": null,
    "direction": "inbound",
    "from_number": "919812345678",
    "to_number": "917900000000",
    "status": "completed",
    "duration_sec": 113,
    "end_reason": "completed",
    "campaign_id": null,
    "campaign_type": null,
    "agent_id": null,
    "reference_id": null,
    "metadata": null,
    "via_api": false,
    "charge_inr": 0,
    "response": {
      "disposition": null,
      "digit": "1",
      "via": "keypad",
      "answers": null,
      "voicemail_left": false
    },
    "created_at": "2026-10-13 06:25:27",
    "created_at_utc": "2026-10-13T06:25:27Z",
    "created_at_ist": "2026-10-13T11:55:27+05:30",
    "transcript_available": false,
    "analysis_available": false,
    "version": 7,
    "updated_at": "2026-10-13T06:27:20.880Z",
    "updated_at_ist": "2026-10-13T11:57:20.880+05:30",
    "lane": "menu",
    "end_detail": "connected",
    "ended_by": "customer",
    "network_cause": null,
    "sip_status": null,
    "handled_by": "member",
    "member": {
      "id": 1042,
      "name": "Neha Sharma",
      "removed": false
    },
    "assigned_member": null,
    "customer_member": null,
    "customer_number": "+919812345678",
    "business_number": "+917900000000",
    "started_at": "2026-10-13T06:25:27.000Z",
    "started_at_ist": "2026-10-13T11:55:27.000+05:30",
    "answered_at": "2026-10-13T06:25:58.000Z",
    "answered_at_ist": "2026-10-13T11:55:58.000+05:30",
    "ended_at": "2026-10-13T06:27:20.000Z",
    "ended_at_ist": "2026-10-13T11:57:20.000+05:30",
    "talk_sec": 82,
    "wait_sec": 31,
    "hold_sec": 0,
    "recording_available": false,
    "recording_url": null,
    "recording": {
      "status": "processing",
      "revision": 0,
      "url": null,
      "format": null,
      "size_bytes": null,
      "duration_sec": null,
      "channels": null,
      "channel_layout": null,
      "retention_days": 60,
      "expires_at": "2026-12-12T06:25:27.000Z",
      "parts": [],
      "parts_ordered": false
    },
    "disposition": null,
    "voicemail": null,
    "menu": {
      "id": 356,
      "name": "Main menu",
      "key": "1"
    },
    "ring_attempts": [
      {
        "kind": "member",
        "member": {
          "id": 1057,
          "name": "Arjun Mehta",
          "removed": false
        },
        "number": null,
        "result": "no_answer",
        "rang_sec": 15
      },
      {
        "kind": "member",
        "member": {
          "id": 1042,
          "name": "Neha Sharma",
          "removed": false
        },
        "number": null,
        "result": "answered",
        "rang_sec": null
      }
    ],
    "transfers": [],
    "campaign": null
  },
  "event": "call.completed",
  "event_id": "evt_9509835da2546b4edaecf49a376d51f7"
}
Webhook event

call.no_answer

Fires whenThe call ended without connecting: nobody answered, nobody was available, it was outside your hours, the caller left a voicemail, or either side ended it before an answer. Safe to retry later. A terminal event.

Values at this event

FieldTypeDescription
statusstring
Always "missed".
end_reasonstring
"no_answer", or "canceled" when it ended before an answer (the caller left, your team member hung up, or the call menu ended with no valid choice).
end_detailstring
Why, from the table. The sample is an outbound call the customer did not answer.
duration_secinteger
As it has always been: usually the ringing time, the whole record on call menu calls, and 0 on Call via SIM and Phone Bridge calls. talk_sec is 0; the ringing, menu and queue time is wait_sec.
Sample event
{
  "id": "evt_3d1cceff07ca2682909d15fe571c9de4",
  "object": "event",
  "api_version": "2026-06-01",
  "type": "call.no_answer",
  "created": 1791874972,
  "occurred_at": "2026-10-13T07:02:52.700Z",
  "timestamp_ist": "2026-10-13T12:32:52.700+05:30",
  "org_id": 42,
  "reference_id": null,
  "livemode": true,
  "data": {
    "object": "call",
    "unique_id": "3c9d1e2f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
    "call_id": "3c9d1e2f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
    "leg_id": null,
    "click_to_call_id": null,
    "direction": "outbound",
    "from_number": "07900000000",
    "to_number": "9876543210",
    "status": "missed",
    "duration_sec": 36,
    "end_reason": "no_answer",
    "campaign_id": null,
    "campaign_type": null,
    "agent_id": null,
    "reference_id": null,
    "metadata": null,
    "via_api": false,
    "charge_inr": 0,
    "response": {
      "disposition": null,
      "digit": null,
      "via": null,
      "answers": null,
      "voicemail_left": false
    },
    "created_at": "2026-10-13 07:02:11",
    "created_at_utc": "2026-10-13T07:02:11Z",
    "created_at_ist": "2026-10-13T12:32:11+05:30",
    "transcript_available": false,
    "analysis_available": false,
    "version": 4,
    "updated_at": "2026-10-13T07:02:47.612Z",
    "updated_at_ist": "2026-10-13T12:32:47.612+05:30",
    "lane": "panel",
    "end_detail": "customer_no_answer",
    "ended_by": null,
    "network_cause": {
      "code": 19,
      "name": "NO_ANSWER"
    },
    "sip_status": 480,
    "handled_by": null,
    "member": {
      "id": 1042,
      "name": "Neha Sharma",
      "removed": false
    },
    "assigned_member": null,
    "customer_member": null,
    "customer_number": "+919876543210",
    "business_number": "+917900000000",
    "started_at": "2026-10-13T07:02:11.000Z",
    "started_at_ist": "2026-10-13T12:32:11.000+05:30",
    "answered_at": null,
    "answered_at_ist": null,
    "ended_at": "2026-10-13T07:02:47.000Z",
    "ended_at_ist": "2026-10-13T12:32:47.000+05:30",
    "talk_sec": 0,
    "wait_sec": 36,
    "hold_sec": 0,
    "recording_available": false,
    "recording_url": null,
    "recording": {
      "status": "none",
      "revision": 0,
      "url": null,
      "format": null,
      "size_bytes": null,
      "duration_sec": null,
      "channels": null,
      "channel_layout": null,
      "retention_days": 60,
      "expires_at": "2026-12-12T07:02:11.000Z",
      "parts": [],
      "parts_ordered": false
    },
    "disposition": null,
    "voicemail": null,
    "menu": null,
    "ring_attempts": [],
    "transfers": [],
    "campaign": null
  },
  "event": "call.no_answer",
  "event_id": "evt_3d1cceff07ca2682909d15fe571c9de4"
}
Webhook event

call.busy

Fires whenThe line was busy or the call was declined: the customer's line, your team member's, or every line on your account. A retry can succeed. A terminal event. An inbound call refused because every line on your account was in use sends it at once.

Values at this event

FieldTypeDescription
statusstring
Always "missed".
end_reasonstring
"busy" when the line was busy, "rejected" when the call was declined.
end_detailstring
all_lines_busy, member_busy, customer_busy, member_declined or customer_rejected. The sample is a refused call.
Sample event
{
  "id": "evt_e829822186f8f2cc1bfa2bbdf0add7ca",
  "object": "event",
  "api_version": "2026-06-01",
  "type": "call.busy",
  "created": 1791875404,
  "occurred_at": "2026-10-13T07:10:04.600Z",
  "timestamp_ist": "2026-10-13T12:40:04.600+05:30",
  "org_id": 42,
  "reference_id": null,
  "livemode": true,
  "data": {
    "object": "call",
    "unique_id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
    "call_id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
    "leg_id": null,
    "click_to_call_id": null,
    "direction": "inbound",
    "from_number": "919811122233",
    "to_number": "917900000001",
    "status": "missed",
    "duration_sec": 0,
    "end_reason": "busy",
    "campaign_id": null,
    "campaign_type": null,
    "agent_id": null,
    "reference_id": null,
    "metadata": null,
    "via_api": false,
    "charge_inr": 0,
    "response": {
      "disposition": null,
      "digit": null,
      "via": null,
      "answers": null,
      "voicemail_left": false
    },
    "created_at": "2026-10-13 07:10:04",
    "created_at_utc": "2026-10-13T07:10:04Z",
    "created_at_ist": "2026-10-13T12:40:04+05:30",
    "transcript_available": false,
    "analysis_available": false,
    "version": 1,
    "updated_at": "2026-10-13T07:10:04.088Z",
    "updated_at_ist": "2026-10-13T12:40:04.088+05:30",
    "lane": "direct",
    "end_detail": "all_lines_busy",
    "ended_by": "system",
    "network_cause": null,
    "sip_status": null,
    "handled_by": null,
    "member": null,
    "assigned_member": null,
    "customer_member": null,
    "customer_number": "+919811122233",
    "business_number": "+917900000001",
    "started_at": "2026-10-13T07:10:04.000Z",
    "started_at_ist": "2026-10-13T12:40:04.000+05:30",
    "answered_at": null,
    "answered_at_ist": null,
    "ended_at": "2026-10-13T07:10:04.000Z",
    "ended_at_ist": "2026-10-13T12:40:04.000+05:30",
    "talk_sec": 0,
    "wait_sec": 0,
    "hold_sec": 0,
    "recording_available": false,
    "recording_url": null,
    "recording": {
      "status": "none",
      "revision": 0,
      "url": null,
      "format": null,
      "size_bytes": null,
      "duration_sec": null,
      "channels": null,
      "channel_layout": null,
      "retention_days": 60,
      "expires_at": "2026-12-12T07:10:04.000Z",
      "parts": [],
      "parts_ordered": false
    },
    "disposition": null,
    "voicemail": null,
    "menu": null,
    "ring_attempts": [],
    "transfers": [],
    "campaign": null
  },
  "event": "call.busy",
  "event_id": "evt_e829822186f8f2cc1bfa2bbdf0add7ca"
}
Webhook event

call.failed

Fires whenThe call could not be placed or connected: an invalid number, a number that cannot take calls, a network fault, or a problem on our side. Retrying the same number is unlikely to help. A call that rang unanswered, ended before an answer or was busy fires call.no_answer or call.busy instead.

Values at this event

FieldTypeDescription
statusstring
Always "failed".
end_reasonstring
"failed". On an AI voice agent call it can also read "canceled", as before.
end_detailstring
Why, for example invalid_number (the sample), cannot_take_calls, network_failure. network_cause carries the network's standard cause when it gave one.
Sample event
{
  "id": "evt_3a387a6f4a3e03358d5959f4fa8d4bd7",
  "object": "event",
  "api_version": "2026-06-01",
  "type": "call.failed",
  "created": 1791876110,
  "occurred_at": "2026-10-13T07:21:50.100Z",
  "timestamp_ist": "2026-10-13T12:51:50.100+05:30",
  "org_id": 42,
  "reference_id": null,
  "livemode": true,
  "data": {
    "object": "call",
    "unique_id": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e",
    "call_id": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e",
    "leg_id": null,
    "click_to_call_id": null,
    "direction": "outbound",
    "from_number": "07900000001",
    "to_number": "919800000123",
    "status": "failed",
    "duration_sec": 0,
    "end_reason": "failed",
    "campaign_id": null,
    "campaign_type": null,
    "agent_id": null,
    "reference_id": null,
    "metadata": null,
    "via_api": false,
    "charge_inr": 0,
    "response": {
      "disposition": null,
      "digit": null,
      "via": null,
      "answers": null,
      "voicemail_left": false
    },
    "created_at": "2026-10-13 07:21:40",
    "created_at_utc": "2026-10-13T07:21:40Z",
    "created_at_ist": "2026-10-13T12:51:40+05:30",
    "transcript_available": false,
    "analysis_available": false,
    "version": 3,
    "updated_at": "2026-10-13T07:21:44.950Z",
    "updated_at_ist": "2026-10-13T12:51:44.950+05:30",
    "lane": "sim",
    "end_detail": "invalid_number",
    "ended_by": null,
    "network_cause": {
      "code": 1,
      "name": "UNALLOCATED_NUMBER"
    },
    "sip_status": null,
    "handled_by": null,
    "member": {
      "id": 1057,
      "name": "Arjun Mehta",
      "removed": false
    },
    "assigned_member": null,
    "customer_member": null,
    "customer_number": "+919800000123",
    "business_number": "+917900000001",
    "started_at": "2026-10-13T07:21:40.000Z",
    "started_at_ist": "2026-10-13T12:51:40.000+05:30",
    "answered_at": null,
    "answered_at_ist": null,
    "ended_at": "2026-10-13T07:21:44.000Z",
    "ended_at_ist": "2026-10-13T12:51:44.000+05:30",
    "talk_sec": 0,
    "wait_sec": 4,
    "hold_sec": 0,
    "recording_available": false,
    "recording_url": null,
    "recording": {
      "status": "processing",
      "revision": 0,
      "url": null,
      "format": null,
      "size_bytes": null,
      "duration_sec": null,
      "channels": null,
      "channel_layout": null,
      "retention_days": 60,
      "expires_at": "2026-12-12T07:21:40.000Z",
      "parts": [],
      "parts_ordered": false
    },
    "disposition": null,
    "voicemail": null,
    "menu": null,
    "ring_attempts": [],
    "transfers": [],
    "campaign": null
  },
  "event": "call.failed",
  "event_id": "evt_3a387a6f4a3e03358d5959f4fa8d4bd7"
}

Which terminal event

Every call ends with exactly one of the four terminal events, sent about five seconds after the call ends (a transferred call: once, at the true end). The event follows from status and end_reason, and data.status always equals the event's own status, so you can branch on either:

The pairing, and the event each outcome sends

statusend_reasonTerminal eventend_detail values that land here
queued, ringing, in_progressnullnone yetnull
completedcompletedcall.completedconnected, whatsapp_sent, machine_answered
missedno_answercall.no_answersent_to_voicemail, outside_hours, closed_day, team_unavailable, team_did_not_answer, member_offline, member_on_break, member_no_answer, customer_no_answer, customer_unreachable, other
missedcanceledcall.no_answerinvalid_menu_choice, no_menu_choice, caller_left_while_ringing, caller_left_on_hold, caller_left_in_queue, caller_left, member_canceled, ended_before_answer, canceled, other
missedbusycall.busyall_lines_busy, member_busy, customer_busy, other
missedrejectedcall.busymember_declined, customer_rejected, other
failedfailedcall.failednetwork_busy, number_not_set_up, network_failure, service_error, invalid_number, cannot_take_calls, member_not_reached, member_connection_failed, other

Since 13 October 2026: an inbound call nobody answered is never sent as call.completed any more, a Phone Bridge call the customer never answered is call.no_answer, and a call that ended before it was answered is call.no_answer with canceled (it was call.failed). AI voice agent calls keep their events as they were. The event is the one the call's status and end reason give when it is sent; a voicemail stored after it changes the record (see voicemail.left), never the event.

A duplicate row that a call taken in the web Agent Panel or the app can leave (its call_id starts with lk-agent-; lane other, or panel for an outgoing one) sends no event of its own: the call's real row sends them. Reads still list it.

Without the Telephony API

An account without the Telephony API receives the original 19 fields of the call object on every call event, with the corrected status, end reason and terminal event:

call.completed (an Interactive Voice call)
{
  "id": "evt_4b8f2c1d6a3e4f0b9d7c2a1e5f6b8c0d",
  "object": "event",
  "api_version": "2026-06-01",
  "type": "call.completed",
  "created": 1780589528,
  "occurred_at": "2026-06-04T16:12:08.512Z",
  "timestamp_ist": "2026-06-04T21:42:08.512+05:30",
  "org_id": 42,
  "reference_id": "order-99213",
  "livemode": true,
  "data": {
    "object": "call",
    "unique_id": "run_4821",
    "call_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "leg_id": null,
    "click_to_call_id": null,
    "direction": "outbound",
    "from_number": "01100000021",
    "to_number": "+919812345678",
    "status": "completed",
    "duration_sec": 42,
    "end_reason": "completed",
    "campaign_id": 4821,
    "campaign_type": "press1",
    "agent_id": null,
    "reference_id": "order-99213",
    "metadata": null,
    "via_api": true,
    "charge_inr": 0.6,
    "response": {
      "disposition": "interested",
      "digit": "1",
      "via": "keypad",
      "answers": null,
      "voicemail_left": false
    }
  },
  "event": "call.completed",
  "event_id": "evt_4b8f2c1d6a3e4f0b9d7c2a1e5f6b8c0d"
}

After the call

Telephony API only, never for an AI voice agent call, and sent only to an endpoint that ticks them by name. Each carries the whole call object at its version.

Webhook event

call.tagged

Fires whenThe call's outcome, note or callback time was saved or changed, or its callback was marked done or not done, or removed (a removed callback reads callback_at null and is never read as done), by anyone: a team member in the panel or the app, a reminder, Agentive CRM, an automatic outcome of an interactive call, or the App Agent. Sent two seconds after the last such change, once, with the latest version: three quick edits are one event, and one outcome is told once whatever else changes on the call meanwhile. Usually after the terminal event, and again on every later edit.

Values at this event

FieldTypeDescription
dispositionobject | null
The outcome as it stands now; see the call object. null when everything was cleared.
Sample event
{
  "id": "evt_171224f7582e1fff86c099cbd14dfffc",
  "object": "event",
  "api_version": "2026-06-01",
  "type": "call.tagged",
  "created": 1791872887,
  "occurred_at": "2026-10-13T06:28:07.400Z",
  "timestamp_ist": "2026-10-13T11:58:07.400+05:30",
  "org_id": 42,
  "reference_id": null,
  "livemode": true,
  "data": {
    "object": "call",
    "unique_id": "7f0c2a9e-4b1d-4c3e-9a7f-1d2e3f4a5b6c",
    "call_id": "7f0c2a9e-4b1d-4c3e-9a7f-1d2e3f4a5b6c",
    "leg_id": null,
    "click_to_call_id": null,
    "direction": "inbound",
    "from_number": "919812345678",
    "to_number": "917900000000",
    "status": "completed",
    "duration_sec": 113,
    "end_reason": "completed",
    "campaign_id": null,
    "campaign_type": null,
    "agent_id": null,
    "reference_id": null,
    "metadata": null,
    "via_api": false,
    "charge_inr": 0,
    "response": {
      "disposition": "interested",
      "digit": "1",
      "via": "keypad",
      "answers": null,
      "voicemail_left": false
    },
    "created_at": "2026-10-13 06:25:27",
    "created_at_utc": "2026-10-13T06:25:27Z",
    "created_at_ist": "2026-10-13T11:55:27+05:30",
    "transcript_available": false,
    "analysis_available": false,
    "version": 9,
    "updated_at": "2026-10-13T06:28:05.317Z",
    "updated_at_ist": "2026-10-13T11:58:05.317+05:30",
    "lane": "menu",
    "end_detail": "connected",
    "ended_by": "customer",
    "network_cause": null,
    "sip_status": null,
    "handled_by": "member",
    "member": {
      "id": 1042,
      "name": "Neha Sharma",
      "removed": false
    },
    "assigned_member": null,
    "customer_member": null,
    "customer_number": "+919812345678",
    "business_number": "+917900000000",
    "started_at": "2026-10-13T06:25:27.000Z",
    "started_at_ist": "2026-10-13T11:55:27.000+05:30",
    "answered_at": "2026-10-13T06:25:58.000Z",
    "answered_at_ist": "2026-10-13T11:55:58.000+05:30",
    "ended_at": "2026-10-13T06:27:20.000Z",
    "ended_at_ist": "2026-10-13T11:57:20.000+05:30",
    "talk_sec": 82,
    "wait_sec": 31,
    "hold_sec": 0,
    "recording_available": true,
    "recording_url": "https://voice.agentive.co.in/api/public/v1/calls/7f0c2a9e-4b1d-4c3e-9a7f-1d2e3f4a5b6c/recording",
    "recording": {
      "status": "available",
      "revision": 1,
      "url": "https://voice.agentive.co.in/api/public/v1/calls/7f0c2a9e-4b1d-4c3e-9a7f-1d2e3f4a5b6c/recording",
      "format": "ogg",
      "size_bytes": 452608,
      "duration_sec": 112.4,
      "channels": 2,
      "channel_layout": {
        "left": "customer",
        "right": "member"
      },
      "retention_days": 60,
      "expires_at": "2026-12-12T06:25:27.000Z",
      "parts": [
        {
          "part": 1,
          "primary": true,
          "segment": null,
          "url": "https://voice.agentive.co.in/api/public/v1/calls/7f0c2a9e-4b1d-4c3e-9a7f-1d2e3f4a5b6c/recording",
          "format": "ogg",
          "size_bytes": 452608,
          "duration_sec": 112.4,
          "channels": 2,
          "started_at": "2026-10-13T06:25:27.000Z",
          "member": null
        }
      ],
      "parts_ordered": true
    },
    "disposition": {
      "outcome": "interested",
      "note": "Wants a quote for 5 users",
      "callback_at": "2026-10-14T05:30:00.000Z",
      "callback_done_at": null,
      "callback_done_by": null,
      "tagged_at": "2026-10-13T06:28:05.000Z",
      "tagged_by": {
        "id": 1042,
        "name": "Neha Sharma",
        "removed": false
      },
      "source": "member"
    },
    "voicemail": null,
    "menu": {
      "id": 356,
      "name": "Main menu",
      "key": "1"
    },
    "ring_attempts": [
      {
        "kind": "member",
        "member": {
          "id": 1057,
          "name": "Arjun Mehta",
          "removed": false
        },
        "number": null,
        "result": "no_answer",
        "rang_sec": 15
      },
      {
        "kind": "member",
        "member": {
          "id": 1042,
          "name": "Neha Sharma",
          "removed": false
        },
        "number": null,
        "result": "answered",
        "rang_sec": null
      }
    ],
    "transfers": [],
    "campaign": null
  },
  "event": "call.tagged",
  "event_id": "evt_171224f7582e1fff86c099cbd14dfffc"
}
Webhook event

voicemail.left

Fires whenThe caller left a voicemail. Needs voicemail on your account. It is never sent before the call's terminal event (call.no_answer, or call.busy when the team member was busy), and carries the record as it is then. An endpoint can receive it with no terminal event at all: the endpoint was not yet listening when the call ended, or it does not tick the terminal event. The message is often stored a few seconds after the call ends: the terminal event then carries the reason the call was not answered in end_detail and voicemail null, and this event the record as it is now (end_detail sent_to_voicemail, the voicemail block). Key your voicemail handling on this event or on the record's voicemail block, never on the terminal event, and act on it by its type and id: it can carry the terminal event's version, so the rule "apply only a higher version" (for the call you store) must never discard it. Each delivery is retried on its own, so a retried terminal event can arrive after this event. This is decided per account: when no endpoint of the account ticks voicemail.left, an endpoint that ticks call.updated hears of the message there; when one endpoint ticks it, the others hear of the message only through it (or a read). Download the message from voicemail.url.

Values at this event

FieldTypeDescription
voicemailobject
{ left, duration_sec, url, created_at, expires_at }.
handled_bystring
Always "voicemail".
Sample event
{
  "id": "evt_4fc1805b186fd86169801e1aecb0679d",
  "object": "event",
  "api_version": "2026-06-01",
  "type": "voicemail.left",
  "created": 1791878700,
  "occurred_at": "2026-10-13T08:05:00.100Z",
  "timestamp_ist": "2026-10-13T13:35:00.100+05:30",
  "org_id": 42,
  "reference_id": null,
  "livemode": true,
  "data": {
    "object": "call",
    "unique_id": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
    "call_id": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
    "leg_id": null,
    "click_to_call_id": null,
    "direction": "inbound",
    "from_number": "09811100022",
    "to_number": "917900000001",
    "status": "missed",
    "duration_sec": 46,
    "end_reason": "no_answer",
    "campaign_id": null,
    "campaign_type": null,
    "agent_id": null,
    "reference_id": null,
    "metadata": null,
    "via_api": false,
    "charge_inr": 0,
    "response": {
      "disposition": null,
      "digit": null,
      "via": null,
      "answers": null,
      "voicemail_left": true
    },
    "created_at": "2026-10-13 08:04:12",
    "created_at_utc": "2026-10-13T08:04:12Z",
    "created_at_ist": "2026-10-13T13:34:12+05:30",
    "transcript_available": false,
    "analysis_available": false,
    "version": 5,
    "updated_at": "2026-10-13T08:04:59.402Z",
    "updated_at_ist": "2026-10-13T13:34:59.402+05:30",
    "lane": "direct",
    "end_detail": "sent_to_voicemail",
    "ended_by": "system",
    "network_cause": null,
    "sip_status": null,
    "handled_by": "voicemail",
    "member": null,
    "assigned_member": {
      "id": 1057,
      "name": "Arjun Mehta",
      "removed": false
    },
    "customer_member": null,
    "customer_number": "+919811100022",
    "business_number": "+917900000001",
    "started_at": "2026-10-13T08:04:12.000Z",
    "started_at_ist": "2026-10-13T13:34:12.000+05:30",
    "answered_at": null,
    "answered_at_ist": null,
    "ended_at": "2026-10-13T08:04:58.000Z",
    "ended_at_ist": "2026-10-13T13:34:58.000+05:30",
    "talk_sec": 0,
    "wait_sec": 46,
    "hold_sec": 0,
    "recording_available": false,
    "recording_url": null,
    "recording": {
      "status": "none",
      "revision": 0,
      "url": null,
      "format": null,
      "size_bytes": null,
      "duration_sec": null,
      "channels": null,
      "channel_layout": null,
      "retention_days": 60,
      "expires_at": "2026-12-12T08:04:12.000Z",
      "parts": [],
      "parts_ordered": false
    },
    "disposition": null,
    "voicemail": {
      "left": true,
      "duration_sec": 18,
      "url": "https://voice.agentive.co.in/api/public/v1/calls/9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d/voicemail",
      "created_at": "2026-10-13T08:04:40.000Z",
      "expires_at": "2026-12-12T08:04:40.000Z"
    },
    "menu": null,
    "ring_attempts": [],
    "transfers": [],
    "campaign": null
  },
  "event": "voicemail.left",
  "event_id": "evt_4fc1805b186fd86169801e1aecb0679d"
}
A caller still on the line
A caller who leaves a message and stays on the line to hear your closing words is still on the call: until they hang up, a read shows the call live (status ringing, ended_at null) with handled_by voicemail and the voicemail block already filled in, and no event is sent. The terminal event follows the real end, and this event about a second later with the same version (the terminal event already carries the voicemail block). If the end of such a call never reaches us, we end the call an hour after the message, with the time of the message as its ended_at; the terminal event and this event then follow. Like the terminal event, it waits while a transfer or the call's recording is still being completed.
Webhook event

call.updated

Fires whenThe call's record changed after its terminal event, in a way the other events do not report: for example a long call's final values corrected at its real end, the end of a colleague's part after a transfer, a later recording part, a voicemail stored after the call (when you do not take voicemail.left), a transcript stored, or an App Agent recording uploaded later. Changes made long after a call ended (the recording's removal at the end of its retention) are not sent: read recording.expires_at. Sent five seconds after the last change, once per resulting version.

Values at this event

FieldTypeDescription
changedstring[]
Which parts of the record changed. Treat a name you do not recognise as a change to the whole record.
Sample event
{
  "id": "evt_12cdab998e2593b6efe54e794b0e4958",
  "object": "event",
  "api_version": "2026-06-01",
  "type": "call.updated",
  "created": 1791882970,
  "occurred_at": "2026-10-13T09:16:10.050Z",
  "timestamp_ist": "2026-10-13T14:46:10.050+05:30",
  "org_id": 42,
  "reference_id": null,
  "livemode": true,
  "data": {
    "object": "call",
    "unique_id": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
    "call_id": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
    "leg_id": null,
    "click_to_call_id": null,
    "direction": "outbound",
    "from_number": "07900000000",
    "to_number": "+919812345678",
    "status": "completed",
    "duration_sec": 210,
    "end_reason": "completed",
    "campaign_id": null,
    "campaign_type": null,
    "agent_id": null,
    "reference_id": null,
    "metadata": null,
    "via_api": false,
    "charge_inr": 0,
    "response": {
      "disposition": null,
      "digit": null,
      "via": null,
      "answers": null,
      "voicemail_left": false
    },
    "created_at": "2026-10-13 09:11:02",
    "created_at_utc": "2026-10-13T09:11:02Z",
    "created_at_ist": "2026-10-13T14:41:02+05:30",
    "transcript_available": false,
    "analysis_available": false,
    "version": 11,
    "updated_at": "2026-10-13T09:16:05.020Z",
    "updated_at_ist": "2026-10-13T14:46:05.020+05:30",
    "lane": "panel",
    "end_detail": "connected",
    "ended_by": "member",
    "network_cause": null,
    "sip_status": null,
    "handled_by": "member",
    "member": {
      "id": 1057,
      "name": "Arjun Mehta",
      "removed": false
    },
    "assigned_member": null,
    "customer_member": null,
    "customer_number": "+919812345678",
    "business_number": "+917900000000",
    "started_at": "2026-10-13T09:11:02.000Z",
    "started_at_ist": "2026-10-13T14:41:02.000+05:30",
    "answered_at": "2026-10-13T09:11:09.000Z",
    "answered_at_ist": "2026-10-13T14:41:09.000+05:30",
    "ended_at": "2026-10-13T09:14:39.000Z",
    "ended_at_ist": "2026-10-13T14:44:39.000+05:30",
    "talk_sec": 210,
    "wait_sec": 7,
    "hold_sec": 0,
    "recording_available": true,
    "recording_url": "https://voice.agentive.co.in/api/public/v1/calls/2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a/recording",
    "recording": {
      "status": "available",
      "revision": 2,
      "url": "https://voice.agentive.co.in/api/public/v1/calls/2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a/recording",
      "format": "ogg",
      "size_bytes": 812544,
      "duration_sec": 210.4,
      "channels": 2,
      "channel_layout": {
        "left": "customer",
        "right": "member"
      },
      "retention_days": 60,
      "expires_at": "2026-12-12T09:11:02.000Z",
      "parts": [
        {
          "part": 1,
          "primary": false,
          "segment": 1,
          "url": "https://voice.agentive.co.in/api/public/v1/calls/2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a/recording?segment=1",
          "format": "ogg",
          "size_bytes": 214016,
          "duration_sec": 81.3,
          "channels": 1,
          "started_at": "2026-10-13T09:11:09.000Z",
          "member": {
            "id": 1042,
            "name": "Neha Sharma",
            "removed": false
          }
        },
        {
          "part": 2,
          "primary": true,
          "segment": null,
          "url": "https://voice.agentive.co.in/api/public/v1/calls/2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a/recording",
          "format": "ogg",
          "size_bytes": 812544,
          "duration_sec": 210.4,
          "channels": 2,
          "started_at": "2026-10-13T09:11:09.000Z",
          "member": null
        }
      ],
      "parts_ordered": true
    },
    "disposition": null,
    "voicemail": null,
    "menu": null,
    "ring_attempts": [],
    "transfers": [
      {
        "at": "2026-10-13T09:12:30.512Z",
        "kind": "member",
        "from_member": {
          "id": 1042,
          "name": "Neha Sharma",
          "removed": false
        },
        "to_member": {
          "id": 1057,
          "name": "Arjun Mehta",
          "removed": false
        },
        "to_menu": null,
        "to_number": null,
        "via_phone_bridge": false,
        "to_call_id": null
      }
    ],
    "campaign": null,
    "changed": [
      "recording"
    ]
  },
  "event": "call.updated",
  "event_id": "evt_12cdab998e2593b6efe54e794b0e4958"
}
changedFields it moves
outcomestatus, end_reason, end_detail, ended_by, network_cause, sip_status, duration_sec, ended_at, talk_sec, wait_sec.
answeranswered_at.
peoplemember, assigned_member.
identitydirection, the numbers, lane, campaign, campaign_id, click_to_call_id, via_api, reference_id, leg_id.
dispositiondisposition.
recordingrecording, recording_available, recording_url.
routingmenu, ring_attempts, transfers, response.
holdhold_sec.
chargecharge_inr.
transcripttranscript_available.

Recording events

recording.available carries a recording object in data; recording.failed carries the call object.

Webhook event

recording.available

Fires whenThe call's recording is complete. Sent once per call, when the call has ended, the recording is stored, no other part of it is still on its way, and nothing about it has changed for about a minute; at the latest six hours after the call ended, with what is stored by then. A later change to the files (another part, a fresh copy) raises recording.revision and is sent as call.updated; there is no second recording.available. AI voice agent calls send it as before.

Key fields in data

FieldTypeDescription
recording_urlstring
An authenticated API URL for the main file. Fetch it with your API key and secret; see Download a recording. Every other part is in parts, each with its own download address, which needs your keys too. Since 17 October 2026 your server can turn any of these files into a 10-minute link a browser plays without keys (POST /calls/{id}/recording-link), and any of them can be downloaded as MP3 or WAV by adding format=mp3 or format=wav to the query: ?format=mp3, or &format=mp3 after a part's ?segment=N.
duration_secinteger
The main file's own length in seconds, rounded, when measured.
expires_atstring
When the recording stops being available under your plan's retention. Copy it before then.
callobject
The whole call object, so one event carries the call and its recording.
Sample event
{
  "id": "evt_2151cbff69b19c6c443b8212c220db00",
  "object": "event",
  "api_version": "2026-06-01",
  "type": "recording.available",
  "created": 1791872907,
  "occurred_at": "2026-10-13T06:28:27.000Z",
  "timestamp_ist": "2026-10-13T11:58:27.000+05:30",
  "org_id": 42,
  "reference_id": null,
  "livemode": true,
  "data": {
    "object": "recording",
    "unique_id": "7f0c2a9e-4b1d-4c3e-9a7f-1d2e3f4a5b6c",
    "call_id": "7f0c2a9e-4b1d-4c3e-9a7f-1d2e3f4a5b6c",
    "leg_id": null,
    "click_to_call_id": null,
    "recording_url": "https://voice.agentive.co.in/api/public/v1/calls/7f0c2a9e-4b1d-4c3e-9a7f-1d2e3f4a5b6c/recording",
    "format": "ogg",
    "duration_sec": 112,
    "size_bytes": 452608,
    "campaign_id": null,
    "campaign_type": null,
    "reference_id": null,
    "metadata": null,
    "via_api": false,
    "version": 9,
    "updated_at": "2026-10-13T06:28:05.317Z",
    "status": "available",
    "revision": 1,
    "channels": 2,
    "channel_layout": {
      "left": "customer",
      "right": "member"
    },
    "retention_days": 60,
    "expires_at": "2026-12-12T06:25:27.000Z",
    "parts": [
      {
        "part": 1,
        "primary": true,
        "segment": null,
        "url": "https://voice.agentive.co.in/api/public/v1/calls/7f0c2a9e-4b1d-4c3e-9a7f-1d2e3f4a5b6c/recording",
        "format": "ogg",
        "size_bytes": 452608,
        "duration_sec": 112.4,
        "channels": 2,
        "started_at": "2026-10-13T06:25:27.000Z",
        "member": null
      }
    ],
    "parts_ordered": true,
    "call": {
      "object": "call",
      "unique_id": "7f0c2a9e-4b1d-4c3e-9a7f-1d2e3f4a5b6c",
      "call_id": "7f0c2a9e-4b1d-4c3e-9a7f-1d2e3f4a5b6c",
      "leg_id": null,
      "click_to_call_id": null,
      "direction": "inbound",
      "from_number": "919812345678",
      "to_number": "917900000000",
      "status": "completed",
      "duration_sec": 113,
      "end_reason": "completed",
      "campaign_id": null,
      "campaign_type": null,
      "agent_id": null,
      "reference_id": null,
      "metadata": null,
      "via_api": false,
      "charge_inr": 0,
      "response": {
        "disposition": "interested",
        "digit": "1",
        "via": "keypad",
        "answers": null,
        "voicemail_left": false
      },
      "created_at": "2026-10-13 06:25:27",
      "created_at_utc": "2026-10-13T06:25:27Z",
      "created_at_ist": "2026-10-13T11:55:27+05:30",
      "transcript_available": false,
      "analysis_available": false,
      "version": 9,
      "updated_at": "2026-10-13T06:28:05.317Z",
      "updated_at_ist": "2026-10-13T11:58:05.317+05:30",
      "lane": "menu",
      "end_detail": "connected",
      "ended_by": "customer",
      "network_cause": null,
      "sip_status": null,
      "handled_by": "member",
      "member": {
        "id": 1042,
        "name": "Neha Sharma",
        "removed": false
      },
      "assigned_member": null,
      "customer_member": null,
      "customer_number": "+919812345678",
      "business_number": "+917900000000",
      "started_at": "2026-10-13T06:25:27.000Z",
      "started_at_ist": "2026-10-13T11:55:27.000+05:30",
      "answered_at": "2026-10-13T06:25:58.000Z",
      "answered_at_ist": "2026-10-13T11:55:58.000+05:30",
      "ended_at": "2026-10-13T06:27:20.000Z",
      "ended_at_ist": "2026-10-13T11:57:20.000+05:30",
      "talk_sec": 82,
      "wait_sec": 31,
      "hold_sec": 0,
      "recording_available": true,
      "recording_url": "https://voice.agentive.co.in/api/public/v1/calls/7f0c2a9e-4b1d-4c3e-9a7f-1d2e3f4a5b6c/recording",
      "recording": {
        "status": "available",
        "revision": 1,
        "url": "https://voice.agentive.co.in/api/public/v1/calls/7f0c2a9e-4b1d-4c3e-9a7f-1d2e3f4a5b6c/recording",
        "format": "ogg",
        "size_bytes": 452608,
        "duration_sec": 112.4,
        "channels": 2,
        "channel_layout": {
          "left": "customer",
          "right": "member"
        },
        "retention_days": 60,
        "expires_at": "2026-12-12T06:25:27.000Z",
        "parts": [
          {
            "part": 1,
            "primary": true,
            "segment": null,
            "url": "https://voice.agentive.co.in/api/public/v1/calls/7f0c2a9e-4b1d-4c3e-9a7f-1d2e3f4a5b6c/recording",
            "format": "ogg",
            "size_bytes": 452608,
            "duration_sec": 112.4,
            "channels": 2,
            "started_at": "2026-10-13T06:25:27.000Z",
            "member": null
          }
        ],
        "parts_ordered": true
      },
      "disposition": {
        "outcome": "interested",
        "note": "Wants a quote for 5 users",
        "callback_at": "2026-10-14T05:30:00.000Z",
        "callback_done_at": null,
        "callback_done_by": null,
        "tagged_at": "2026-10-13T06:28:05.000Z",
        "tagged_by": {
          "id": 1042,
          "name": "Neha Sharma",
          "removed": false
        },
        "source": "member"
      },
      "voicemail": null,
      "menu": {
        "id": 356,
        "name": "Main menu",
        "key": "1"
      },
      "ring_attempts": [
        {
          "kind": "member",
          "member": {
            "id": 1057,
            "name": "Arjun Mehta",
            "removed": false
          },
          "number": null,
          "result": "no_answer",
          "rang_sec": 15
        },
        {
          "kind": "member",
          "member": {
            "id": 1042,
            "name": "Neha Sharma",
            "removed": false
          },
          "number": null,
          "result": "answered",
          "rang_sec": null
        }
      ],
      "transfers": [],
      "campaign": null
    }
  },
  "event": "recording.available",
  "event_id": "evt_2151cbff69b19c6c443b8212c220db00"
}
Webhook event

recording.failed

Fires whenTelephony API, and call recording on your account. A recording we expected for the call (it connected, or it went through a call menu or Call via SIM for a few seconds or more) was still not stored 12 hours after the call ended. Sent once. If the file arrives after all, recording.status turns available and you receive recording.available (or call.updated if it was already sent).

Values at this event

FieldTypeDescription
recording.statusstring
Always "failed".
Sample event
{
  "id": "evt_b58e408d250c67bf10cbcbf07fb2e941",
  "object": "event",
  "api_version": "2026-06-01",
  "type": "recording.failed",
  "created": 1791929012,
  "occurred_at": "2026-10-13T22:03:32.000Z",
  "timestamp_ist": "2026-10-14T03:33:32.000+05:30",
  "org_id": 42,
  "reference_id": null,
  "livemode": true,
  "data": {
    "object": "call",
    "unique_id": "6e7f8a9b-0c1d-4e2f-8a3b-4c5d6e7f8a9b",
    "call_id": "6e7f8a9b-0c1d-4e2f-8a3b-4c5d6e7f8a9b",
    "leg_id": null,
    "click_to_call_id": null,
    "direction": "inbound",
    "from_number": "919822233344",
    "to_number": "917900000000",
    "status": "completed",
    "duration_sec": 206,
    "end_reason": "completed",
    "campaign_id": null,
    "campaign_type": null,
    "agent_id": null,
    "reference_id": null,
    "metadata": null,
    "via_api": false,
    "charge_inr": 0,
    "response": {
      "disposition": null,
      "digit": "1",
      "via": "keypad",
      "answers": null,
      "voicemail_left": false
    },
    "created_at": "2026-10-13 10:00:05",
    "created_at_utc": "2026-10-13T10:00:05Z",
    "created_at_ist": "2026-10-13T15:30:05+05:30",
    "transcript_available": false,
    "analysis_available": false,
    "version": 7,
    "updated_at": "2026-10-13T22:03:31.540Z",
    "updated_at_ist": "2026-10-14T03:33:31.540+05:30",
    "lane": "menu",
    "end_detail": "connected",
    "ended_by": null,
    "network_cause": null,
    "sip_status": null,
    "handled_by": "member",
    "member": {
      "id": 1042,
      "name": "Neha Sharma",
      "removed": false
    },
    "assigned_member": null,
    "customer_member": null,
    "customer_number": "+919822233344",
    "business_number": "+917900000000",
    "started_at": "2026-10-13T10:00:05.000Z",
    "started_at_ist": "2026-10-13T15:30:05.000+05:30",
    "answered_at": "2026-10-13T10:00:19.000Z",
    "answered_at_ist": "2026-10-13T15:30:19.000+05:30",
    "ended_at": "2026-10-13T10:03:31.000Z",
    "ended_at_ist": "2026-10-13T15:33:31.000+05:30",
    "talk_sec": 192,
    "wait_sec": 14,
    "hold_sec": 0,
    "recording_available": false,
    "recording_url": null,
    "recording": {
      "status": "failed",
      "revision": 0,
      "url": null,
      "format": null,
      "size_bytes": null,
      "duration_sec": null,
      "channels": null,
      "channel_layout": null,
      "retention_days": 60,
      "expires_at": "2026-12-12T10:00:05.000Z",
      "parts": [],
      "parts_ordered": false
    },
    "disposition": null,
    "voicemail": null,
    "menu": {
      "id": 356,
      "name": "Main menu",
      "key": "1"
    },
    "ring_attempts": [
      {
        "kind": "member",
        "member": {
          "id": 1042,
          "name": "Neha Sharma",
          "removed": false
        },
        "number": null,
        "result": "answered",
        "rang_sec": null
      }
    ],
    "transfers": [],
    "campaign": null
  },
  "event": "recording.failed",
  "event_id": "evt_b58e408d250c67bf10cbcbf07fb2e941"
}

Team member rings

Not sent yet
These two events are documented now so you can plan for them. They will be switched on and announced in the changelog; until then no endpoint receives them, ticked or not.

Telephony API only, ticked by name. Each carries the call object and an offer: who is being rung, which of their rings on this call it is, for how long, and why.

Webhook event

call.member_ringing

Fires whenA team member is being rung for a call: a number that rings them, a call menu key, ring all, a queue offer, a colleague's transfer or merge, and the ring to their own mobile with Phone Bridge. Once per ring. Never for an AI voice agent hand-over or a click to call (that is click_to_call.member_ringing).

The offer

FieldTypeDescription
offer.memberobject
{ id, name } of the team member being rung.
offer.attemptinteger
1 for this member's first ring on this call, 2 for the next.
offer.ring_timeout_secinteger | null
How long they will be rung. null when the ring did not say.
offer.kindstring
direct, menu, queue, transfer, merge, phone_bridge or campaign (a team calling campaign rang them).
offer.menuobject | null
{ id, key }: the call menu and key that led here, or null.
Sample event
{
  "id": "evt_021235248ff87236d847e2167f15d1e0",
  "object": "event",
  "api_version": "2026-06-01",
  "type": "call.member_ringing",
  "created": 1791872736,
  "occurred_at": "2026-10-13T06:25:36.300Z",
  "timestamp_ist": "2026-10-13T11:55:36.300+05:30",
  "org_id": 42,
  "reference_id": null,
  "livemode": true,
  "data": {
    "object": "call",
    "unique_id": "7f0c2a9e-4b1d-4c3e-9a7f-1d2e3f4a5b6c",
    "call_id": "7f0c2a9e-4b1d-4c3e-9a7f-1d2e3f4a5b6c",
    "leg_id": null,
    "click_to_call_id": null,
    "direction": "inbound",
    "from_number": "919812345678",
    "to_number": "917900000000",
    "status": "ringing",
    "duration_sec": null,
    "end_reason": null,
    "campaign_id": null,
    "campaign_type": null,
    "agent_id": null,
    "reference_id": null,
    "metadata": null,
    "via_api": false,
    "charge_inr": null,
    "response": {
      "disposition": null,
      "digit": "1",
      "via": "keypad",
      "answers": null,
      "voicemail_left": false
    },
    "created_at": "2026-10-13 06:25:27",
    "created_at_utc": "2026-10-13T06:25:27Z",
    "created_at_ist": "2026-10-13T11:55:27+05:30",
    "transcript_available": false,
    "analysis_available": false,
    "version": 3,
    "updated_at": "2026-10-13T06:25:36.050Z",
    "updated_at_ist": "2026-10-13T11:55:36.050+05:30",
    "lane": "menu",
    "end_detail": null,
    "ended_by": null,
    "network_cause": null,
    "sip_status": null,
    "handled_by": null,
    "member": null,
    "assigned_member": {
      "id": 1057,
      "name": "Arjun Mehta",
      "removed": false
    },
    "customer_member": null,
    "customer_number": "+919812345678",
    "business_number": "+917900000000",
    "started_at": "2026-10-13T06:25:27.000Z",
    "started_at_ist": "2026-10-13T11:55:27.000+05:30",
    "answered_at": null,
    "answered_at_ist": null,
    "ended_at": null,
    "ended_at_ist": null,
    "talk_sec": null,
    "wait_sec": null,
    "hold_sec": 0,
    "recording_available": false,
    "recording_url": null,
    "recording": {
      "status": "processing",
      "revision": 0,
      "url": null,
      "format": null,
      "size_bytes": null,
      "duration_sec": null,
      "channels": null,
      "channel_layout": null,
      "retention_days": 60,
      "expires_at": "2026-12-12T06:25:27.000Z",
      "parts": [],
      "parts_ordered": false
    },
    "disposition": null,
    "voicemail": null,
    "menu": {
      "id": 356,
      "name": "Main menu",
      "key": "1"
    },
    "ring_attempts": [],
    "transfers": [],
    "campaign": null,
    "offer": {
      "member": {
        "id": 1057,
        "name": "Arjun Mehta"
      },
      "attempt": 1,
      "ring_timeout_sec": 15,
      "kind": "menu",
      "menu": {
        "id": 356,
        "key": "1"
      }
    }
  },
  "event": "call.member_ringing",
  "event_id": "evt_021235248ff87236d847e2167f15d1e0"
}
Webhook event

call.member_missed

Fires whenThat ring ended without this team member answering: another team member was rung next, someone else answered, or the call ended.

The offer

FieldTypeDescription
offer.resultstring
no_answer, declined, busy or answered_elsewhere. The other offer fields are as on call.member_ringing.
Sample event
{
  "id": "evt_fb0dacef4d412d6e75c2b6fbfd5fa0b0",
  "object": "event",
  "api_version": "2026-06-01",
  "type": "call.member_missed",
  "created": 1791872752,
  "occurred_at": "2026-10-13T06:25:52.600Z",
  "timestamp_ist": "2026-10-13T11:55:52.600+05:30",
  "org_id": 42,
  "reference_id": null,
  "livemode": true,
  "data": {
    "object": "call",
    "unique_id": "7f0c2a9e-4b1d-4c3e-9a7f-1d2e3f4a5b6c",
    "call_id": "7f0c2a9e-4b1d-4c3e-9a7f-1d2e3f4a5b6c",
    "leg_id": null,
    "click_to_call_id": null,
    "direction": "inbound",
    "from_number": "919812345678",
    "to_number": "917900000000",
    "status": "ringing",
    "duration_sec": null,
    "end_reason": null,
    "campaign_id": null,
    "campaign_type": null,
    "agent_id": null,
    "reference_id": null,
    "metadata": null,
    "via_api": false,
    "charge_inr": null,
    "response": {
      "disposition": null,
      "digit": "1",
      "via": "keypad",
      "answers": null,
      "voicemail_left": false
    },
    "created_at": "2026-10-13 06:25:27",
    "created_at_utc": "2026-10-13T06:25:27Z",
    "created_at_ist": "2026-10-13T11:55:27+05:30",
    "transcript_available": false,
    "analysis_available": false,
    "version": 4,
    "updated_at": "2026-10-13T06:25:52.120Z",
    "updated_at_ist": "2026-10-13T11:55:52.120+05:30",
    "lane": "menu",
    "end_detail": null,
    "ended_by": null,
    "network_cause": null,
    "sip_status": null,
    "handled_by": null,
    "member": null,
    "assigned_member": {
      "id": 1042,
      "name": "Neha Sharma",
      "removed": false
    },
    "customer_member": null,
    "customer_number": "+919812345678",
    "business_number": "+917900000000",
    "started_at": "2026-10-13T06:25:27.000Z",
    "started_at_ist": "2026-10-13T11:55:27.000+05:30",
    "answered_at": null,
    "answered_at_ist": null,
    "ended_at": null,
    "ended_at_ist": null,
    "talk_sec": null,
    "wait_sec": null,
    "hold_sec": 0,
    "recording_available": false,
    "recording_url": null,
    "recording": {
      "status": "processing",
      "revision": 0,
      "url": null,
      "format": null,
      "size_bytes": null,
      "duration_sec": null,
      "channels": null,
      "channel_layout": null,
      "retention_days": 60,
      "expires_at": "2026-12-12T06:25:27.000Z",
      "parts": [],
      "parts_ordered": false
    },
    "disposition": null,
    "voicemail": null,
    "menu": {
      "id": 356,
      "name": "Main menu",
      "key": "1"
    },
    "ring_attempts": [
      {
        "kind": "member",
        "member": {
          "id": 1057,
          "name": "Arjun Mehta",
          "removed": false
        },
        "number": null,
        "result": "no_answer",
        "rang_sec": 15
      }
    ],
    "transfers": [],
    "campaign": null,
    "offer": {
      "member": {
        "id": 1057,
        "name": "Arjun Mehta"
      },
      "attempt": 1,
      "ring_timeout_sec": 15,
      "kind": "menu",
      "menu": {
        "id": 356,
        "key": "1"
      },
      "result": "no_answer"
    }
  },
  "event": "call.member_missed",
  "event_id": "evt_fb0dacef4d412d6e75c2b6fbfd5fa0b0"
}

Verification events

Every otp.* event carries a verification object in data. These events pair with the Voice OTP API: send a code, then let the events tell you whether it was delivered, verified, or locked.

The code is never sent
The verification code itself is never included in any webhook.
Webhook event

otp.sent

Fires whenA voice verification call was queued for delivery.

Values at this event

FieldTypeDescription
statusstring
Always "queued".
verifiednull
Not yet known.
expires_in_secinteger
Seconds until the code expires. 600 (10 minutes) unless you set ttl on the send.
max_attemptsinteger
Allowed verify attempts.
Sample event
{
  "id": "evt_e51a6c3f8b0c8e5a2d4f7b9c1e3a5f6b",
  "object": "event",
  "api_version": "2026-06-01",
  "type": "otp.sent",
  "created": 1780590000,
  "occurred_at": "2026-06-04T16:20:00.000Z",
  "timestamp_ist": "2026-06-04T21:50:00.000+05:30",
  "org_id": 42,
  "reference_id": "signup-8841",
  "livemode": true,
  "data": {
    "object": "verification",
    "request_id": "d29b8e7a-3c41-4f0a-9b2d-7e1c5a6f8b90",
    "number": "+919812345678",
    "status": "queued",
    "verification_status": "pending",
    "verified": null,
    "attempts_left": null,
    "expires_in_sec": 300,
    "max_attempts": 3,
    "campaign_id": 5567,
    "reference_id": "signup-8841"
  },
  "event": "otp.sent",
  "event_id": "evt_e51a6c3f8b0c8e5a2d4f7b9c1e3a5f6b"
}
Webhook event

otp.verified

Fires whenThe recipient entered the correct verification code.

Values at this event

FieldTypeDescription
statusstring
Always "verified".
verification_statusstring
Always "verified".
verifiedboolean
Always true.
Sample event
{
  "id": "evt_f62b7d4a9c1d9f6b3e5a8c0d2f4b6a7c",
  "object": "event",
  "api_version": "2026-06-01",
  "type": "otp.verified",
  "created": 1780590075,
  "occurred_at": "2026-06-04T16:21:15.000Z",
  "timestamp_ist": "2026-06-04T21:51:15.000+05:30",
  "org_id": 42,
  "reference_id": "signup-8841",
  "livemode": true,
  "data": {
    "object": "verification",
    "request_id": "d29b8e7a-3c41-4f0a-9b2d-7e1c5a6f8b90",
    "number": "+919812345678",
    "status": "verified",
    "verification_status": "verified",
    "verified": true,
    "attempts_left": null,
    "expires_in_sec": null,
    "max_attempts": null,
    "campaign_id": 5567,
    "reference_id": "signup-8841"
  },
  "event": "otp.verified",
  "event_id": "evt_f62b7d4a9c1d9f6b3e5a8c0d2f4b6a7c"
}
Webhook event

otp.failed

Fires whenThe recipient entered an incorrect code. The verification is still open until it expires or runs out of attempts, so the recipient can try again.

Values at this event

FieldTypeDescription
statusstring
Always "failed".
verifiedboolean
Always false.
attempts_leftinteger
How many verify attempts remain (1 or more).
max_attemptsinteger
Allowed verify attempts.
Sample event
{
  "id": "evt_3d4e5f60718293a4b5c6d7e8f9a0b1c2",
  "object": "event",
  "api_version": "2026-06-01",
  "type": "otp.failed",
  "created": 1780590050,
  "occurred_at": "2026-06-04T16:20:50.000Z",
  "timestamp_ist": "2026-06-04T21:50:50.000+05:30",
  "org_id": 42,
  "reference_id": "signup-8841",
  "livemode": true,
  "data": {
    "object": "verification",
    "request_id": "d29b8e7a-3c41-4f0a-9b2d-7e1c5a6f8b90",
    "number": "+919812345678",
    "status": "failed",
    "verification_status": "pending",
    "verified": false,
    "attempts_left": 2,
    "expires_in_sec": null,
    "max_attempts": 3,
    "campaign_id": 5567,
    "reference_id": "signup-8841"
  },
  "event": "otp.failed",
  "event_id": "evt_3d4e5f60718293a4b5c6d7e8f9a0b1c2"
}
Webhook event

otp.max_attempts

Fires whenToo many incorrect attempts. The code is now locked and can no longer be verified. Send a new code to retry.

Values at this event

FieldTypeDescription
statusstring
Always "max_attempts".
verification_statusstring
Always "locked".
verifiedboolean
Always false.
attempts_leftinteger
Always 0.
max_attemptsinteger
Allowed verify attempts.
Sample event
{
  "id": "evt_4e5f60718293a4b5c6d7e8f9a0b1c2d3",
  "object": "event",
  "api_version": "2026-06-01",
  "type": "otp.max_attempts",
  "created": 1780590120,
  "occurred_at": "2026-06-04T16:22:00.000Z",
  "timestamp_ist": "2026-06-04T21:52:00.000+05:30",
  "org_id": 42,
  "reference_id": "signup-8841",
  "livemode": true,
  "data": {
    "object": "verification",
    "request_id": "d29b8e7a-3c41-4f0a-9b2d-7e1c5a6f8b90",
    "number": "+919812345678",
    "status": "max_attempts",
    "verification_status": "locked",
    "verified": false,
    "attempts_left": 0,
    "expires_in_sec": null,
    "max_attempts": 3,
    "campaign_id": 5567,
    "reference_id": "signup-8841"
  },
  "event": "otp.max_attempts",
  "event_id": "evt_4e5f60718293a4b5c6d7e8f9a0b1c2d3"
}

The call object

data.object is "call" for every call.* event, and for voicemail.left and recording.failed. It is the same object the reads return.

One object describes a call wherever you read it: GET /calls, GET /calls/{id} and every team-call event carry the same values for the same version. A key with the Telephony API (the Phone + CRM plan) receives every field below on every read and every event. Every other key receives the fields it always did, marked on each row, with the corrected values listed in the changelog. Field order is stable but not part of the contract; ignore fields you do not recognise.

Identity

FieldTypeDescription
objectstring
Always call.
Every key: events. Telephony API: every read too
unique_idstring
The handle to poll and match on. The click to call id (c2c_...) for the record of a call started with Click to Call (the record a click to call goes on as in a call menu keeps its own: see click_to_call_id); run_<campaign_id> for a call an API run placed (a broadcast, Interactive Voice or verification call, or a campaign you triggered through the API) and for an AI voice agent campaign call; the dial id for a call placed with POST /ai/calls; otherwise the same value as call_id. Since 13 October 2026 a call of a dashboard campaign carries its own call_id here (it used to share run_<campaign_id> with every call of the campaign).
Every key: every read and event
call_idstring
Our record id for this call. Unique for every call.
Every key: every read and event
leg_idstring | null
A second id of the same call (the phone leg), when the record is keyed on something else. null on most calls. Either id resolves on GET /calls/{id}.
Every key: every read and event
click_to_call_idstring | null
The click to call this call belongs to (c2c_...), or null. On the click to call's own record unique_id is the same id. Since 17 October 2026 the record a click to call goes on as in a call menu (lane menu, named by the click to call's transfers[].to_call_id) carries it too, with its own unique_id: a set click_to_call_id does not by itself mean unique_id is that id.
Every key: every read and event
directionstring
inbound or outbound.
Every key: every read and event
campaign_idinteger | null
The campaign or API run the call belongs to. On the events of an AI voice agent API campaign, the campaign you triggered.
Every key: every read and event
campaign_typestring | null
The kind of API run: audio_blast, press1, otp or ai_agent (also on an AI call outside any campaign). null for a dashboard campaign call and for every team call outside an API run. Use campaign.kind for a dashboard campaign.
Every key: events. Telephony API: every read too
agent_idinteger | null
The AI voice agent on an AI call. null on calls your team handled.
Every key: Get call status and events. Telephony API: List calls too
reference_idstring | null
Your reference: the reference_id you sent with a click to call or an API call. Since 13 October 2026 a click to call's calls carry it on every event and read (it was null there), and since 17 October 2026 so does the record a click to call goes on as in a call menu.
Every key: every read and event
metadataobject | null
The metadata you sent with a click to call or an API call (a number comes back as text); since 17 October 2026 also on the record a click to call goes on as in a call menu. null otherwise.
Every key: Get call status and events. Telephony API: List calls too
via_apiboolean
true when the call was placed through the API, a click to call included (since 17 October 2026 also the record a click to call goes on as in a call menu).
Every key: Get call status and events. Telephony API: List calls too

Outcome

FieldTypeDescription
statusstring
Where the call is: queued, ringing, in_progress, completed, missed or failed. Always paired with end_reason as shown in Status and end reasons.
Every key: every read and event
duration_secinteger | null
Kept as it has always been, so its meaning depends on the lane: the talk time on a connected call your team placed or that rang a team member directly (on an outgoing call handed on to a colleague who answered, the whole conversation, both parts; on records older than that correction in the changelog, only one of the parts); on a call menu call, the whole record from started_at to ended_at (with the Telephony API, talk_sec plus wait_sec), the same on every read and every event from the moment the call reads ended, except a call handed on to a colleague, whose record grows when the colleague's part ends, and, rarely, a call whose ended_at is corrected after it first reads ended (since 14 October 2026; before, a read in the first seconds after the end could show only the talk time, and the final value could be a second off the record); on a call that did not connect, usually the ringing time, but 0 on Call via SIM and Phone Bridge calls. Use talk_sec and wait_sec instead: one rule on every lane, and together the whole record from started_at to ended_at. With the Telephony API, null while the call is live.
Every key: every read and event
end_reasonstring | null
The closed reason: completed, no_answer, busy, rejected, canceled, failed or voicemail. null while the call is live.
Every key: every read and event
end_detailstring | null
The finer reason, from a closed list (see the end_detail table). null while the call is live.
Telephony API
ended_bystring | null
Who ended the call: member, customer, api (your system hung up or transferred the call through the Click to Call API; a call a colleague answered after the transfer is told by how it then ended), system (we ended it, for example a refusal or a closed menu) or ai_agent. null while the call is live and whenever it is not known (still possible on some calls that use a team member's own phone).
Telephony API
network_causeobject | null
{ code, name }: the phone network's standard cause, for example { "code": 17, "name": "USER_BUSY" }. null when the network gave none, when the call ended normally, and when your own side cancelled it.
Telephony API
sip_statusinteger | null
The final signalling status of the customer's leg, for example 486 (busy) or 487 (cancelled before an answer). Set only on calls your team places over the internet; null on every other lane.
Telephony API
handled_bystring | null
Who the caller ended with: member (a team member answered), ai_agent, voicemail (the caller left a message) or menu (a call menu key sent a WhatsApp message). null otherwise.
Telephony API
responseobject
How the recipient responded on an interactive broadcast call, and whether the caller left a voicemail: { disposition, digit, via, answers, voicemail_left }. Present on every call; disposition, digit, via and answers are null until there is a response. voicemail_left is true when the caller left a voicemail on a call your team or a call menu handled (a call menu, a team member's number, a transfer) or in a broadcast's guided flow, and false otherwise. It is null only on call.initiated and on an event sent before the call has a record (for example the end of a call placed with POST /ai/calls that never got one). A Telephony API read says true as soon as we know of the message. An event carries what we knew when it was sent: a call menu usually keeps the message before the call ends, so its terminal event says true; on a team member's number or after a transfer the message is usually stored after the call ends, so the terminal event says false, while voicemail.left and a read say true (both need the Telephony API). Without the Telephony API the events of those calls may only ever say false, and your reads do not include response. A message usually reaches us within seconds to a few minutes after the call ends; if it never does, voicemail_left can read true with no voicemail block and no voicemail.left. A call a team member's App Agent phone logged as a voicemail, or one your team logged by hand as a voicemail, also reads true, but that message is on their phone, not with us: there is no voicemail block and no voicemail.left. Calls an AI voice agent handled keep the earlier rule, on reads and events alike: true only for a guided flow's message. Since 14 October 2026; before, it was true only for a guided flow's message, so events sent before then carry false for the other messages (as may events sent within a minute of webhooks being turned on for your account), while a Telephony API read of an older call now says true.
Every key: events. Telephony API: every read too

People

FieldTypeDescription
memberobject | null
{ id, name, removed }. Outbound: the team member who placed the call, connected or not; once a colleague answers a call it was transferred to, that colleague (transfers names who handed it on, and a click to call's own member stays the member who placed it). member can therefore change during a call: call.answered names the member who placed it and the final event the colleague; apply events by version. Records from before 12 October 2026 can name the colleague even when they did not pick up. Inbound: the team member who answered, set from the moment they answer (so call.answered carries it); once a colleague answers an incoming call it was transferred to (on the panel, the app or their own phone), that colleague; on a transferred incoming call that kept no answer time (see answered_at), the team member who handed it on (the record does not keep whether the colleague then picked up). When a call goes on in a call menu as a record of its own (see answered_at), that record names its member as an incoming call does: null until a team member picks up from the menu. When the pickup is the number a menu key forwards the call to, member stays null, or names the team member the menu rang before it. null on AI calls, on broadcast calls and on inbound calls nobody answered.
Telephony API
assigned_memberobject | null
{ id, name, removed }. Inbound calls not answered yet, or never answered: the team member the call was assigned to. On a call menu that rang several members it can be any one of them; ring_attempts lists every member the call rang and what happened. null otherwise.
Telephony API
customer_memberobject | null
{ id, name } when the other party of a call your team handled is one of your own team members (for example a team member calling your office line from their own phone). Their mobile number is then not published: customer_number and the from_number or to_number it would sit in are null. null otherwise, and on AI voice agent calls.
Telephony API

Numbers

FieldTypeDescription
from_numberstring | null
The caller as stored, unchanged. Its format varies (0 and ten digits, 91 and ten digits, +91..., or ten digits): match on the last ten digits, or use customer_number and business_number.
Every key: every read and event
to_numberstring | null
The called number as stored, unchanged. Same formats as from_number.
Every key: every read and event
customer_numberstring | null
The other party in E.164 (+91 and ten digits), whatever the direction: the caller on an inbound call, the called number on an outbound one. On a call your team handled a team member's own mobile is never shown here. null when the stored value is not a phone number, and when the other party of a team call is one of your team members (customer_member). On an AI voice agent call it is the number the AI API itself returns in from_number / to_number, whoever it belongs to.
Telephony API
business_numberstring | null
Your own number in E.164: the one the customer dialled (inbound) or saw (outbound). null on the app_agent lane, where the call used the team member's own phone (with the Telephony API that phone's number is not published either: from_number on an outgoing call, to_number on an incoming one, read null).
Telephony API

Times and durations

FieldTypeDescription
created_atstring
Kept exactly as it has always been returned. Its text differs between List calls (the read store's own text) and Get call status and events (zone-less UTC text, for example 2026-10-12 06:28:29); use started_at in new code.
Every key: reads. Telephony API: events too
created_at_utcstring
The same instant, ISO 8601 with Z, to the second.
Every key: reads. Telephony API: events too
created_at_iststring
The same instant at +05:30, to the second.
Every key: reads. Telephony API: events too
started_atstring
When the call record began, ISO 8601 UTC with milliseconds. Its _ist twin is the same instant at +05:30.
Telephony API
answered_atstring | null
When the conversation began. Inbound: a team member (or the AI voice agent) picked up. Outbound: the customer answered, Phone Bridge included (not the team member's own pickup), except on a broadcast call that a key press connected to a team member on the web panel or the app: there it is when that team member picked up (since 17 October 2026; between 14 and 17 October 2026 such calls kept the customer's answer), so the message, the key press and the team member's ring count in wait_sec, and talk_sec is the conversation. A team member who takes such a call on their own mobile leaves the customer's answer. On such a call call.answered carries the customer's answer, and the terminal event carries the team member's pickup; only when the pickup is recorded after the terminal event was sent (for example a call that went on more than about 10 minutes after the team member was rung) does a call.updated (changed includes answer, sent to an endpoint that ticks call.updated) carry it instead. Every read shows it. Apply events by version. Set from the moment the call is answered (status in_progress or completed); null before that and on calls that did not connect. On a transferred call: an outgoing call keeps the customer's answer; on most incoming calls it is when the team member the call was transferred to picked up (the first conversation then counts in wait_sec), on some (an incoming Phone Bridge call among them) the first pickup. A few transferred calls recorded up to 10 October 2026 kept no answer time: there answered_at, talk_sec and wait_sec read null although the call connected. When your team member moves a call whose customer had no record of their own (a click to call, and most outgoing calls your team member placed) into a call menu, the rest of the call goes on as a record of its own (lane menu); the call it came from names it in transfers[].to_call_id. That record reads status ringing while the customer is in the menu, and its answered_at is when a team member picks up from the menu, or when the number a menu key forwards the call to answers (since 14 October 2026; before, the move itself read as the answer). One that connected with no pickup on record (a WhatsApp key, or a key that hands the call to an AI voice agent) keeps the move as its answered_at. An incoming call moved into a call menu stays on its own record, and its status and answered_at are unchanged. With an _ist twin.
Telephony API
ended_atstring | null
When the call record closed. null while it is live. On a call menu call it is when the call ended: the caller hung up, or the conversation ended, whoever hung up first. Call menu calls recorded before the correction listed in the changelog (and, rarely, a later one) close about 3 seconds after that, while the menu closed the record. On an incoming Phone Bridge call transferred to a colleague the record ends at the transfer: the colleague's conversation is not in it. A call handed to a colleague who did not answer (their ring ran out, or they declined) ends when the caller's line ends, not at the transfer: the colleague's ring and any goodbye or voicemail are in the record, so in talk_sec, and on a call menu call in duration_sec. While a call your team member handed to a colleague who takes it in the dashboard or the app goes on (a transfer made in the dashboard, in the app or through the Click to Call API), it reads status in_progress with ended_at null until the call itself ends; its version then goes up and its terminal event carries the end (since 14 October 2026; before, it read as ended at the transfer until the call's end was written). A colleague who takes calls on their own mobile is not included: that record ends at the transfer. With an _ist twin.
Telephony API
talk_secinteger | null
Whole seconds from answered_at to ended_at, hold included: the conversation. On call menu calls recorded before the correction listed in the changelog it also counts the about 3 seconds the menu took to close the record (see ended_at). 0 when the call did not connect, null while it is live and on the few transferred calls that kept no answer time (see answered_at).
Telephony API
wait_secinteger | null
Everything before the conversation (call menu, queue, ringing), and the whole record of a call nobody answered: from started_at to ended_at in whole seconds (the milliseconds of each time are not counted), minus talk_sec. So talk_sec plus wait_sec is the whole call record. null while the call is live, and on the few transferred calls that kept no answer time (see answered_at).
Telephony API
hold_secinteger
Time on hold placed from the panel, the apps or the API, in seconds. 0 when never held. A hold placed on a phone in the call itself (the caller's or the customer's phone, or a team member's own mobile) is not counted here: that time is part of talk_sec and, since 15 October 2026, of the recording.
Telephony API

Recording, outcome and routing

FieldTypeDescription
recording_availableboolean
true when recording.status is available.
Telephony API
recording_urlstring | null
The address of the main recording file (GET /calls/{call_id}/recording). Needs your keys. null unless the recording is available.
Telephony API
recordingobject
The recording block: status, every part, the stereo layout and when it expires. See below.
Telephony API
dispositionobject | null
The outcome, note and callback your team saved for the call. See below.
Telephony API
voicemailobject | null
The voicemail the caller left. See below.
Telephony API
menuobject | null
{ id, name, key }: the call menu the call went through and the key the caller pressed (key null when no key was pressed). null when no call menu was involved; a broadcast key press is in response.digit.
Telephony API
ring_attemptsobject[]
Every person or number the call rang, in order. [] when none. See below.
Telephony API
transfersobject[]
Every hand-over of the call, in order. [] when none. See below.
Telephony API
campaignobject | null
{ id, name, kind }: the campaign the call belongs to, dashboard or API. kind is audio_blast, press1, otp, ai_agent, team (a team calling campaign) or other; name is null when the campaign was deleted. null when there is no campaign.
Telephony API

Charge, transcripts and ordering

FieldTypeDescription
charge_inrnumber | null
What the call cost your balance, in rupees. AI calls: as before. Team calls: what was billed (a broadcast call billed per minute, or minutes past your plan's included daily calling allowance), else 0; null while the call is live.
Every key: Get call status and events. Telephony API: List calls too
transcript_availableboolean
true only when this key can fetch the transcript with GET /calls/{id}/transcript: an AI call for an AI key, or a team call transcribed by call transcription on an account with the Telephony API.
Every key: Get call status. Telephony API: everywhere
analysis_availableboolean
true when an AI call has its post call analysis. Always false for team calls.
Every key: Get call status. Telephony API: everywhere
versioninteger
Goes up by exactly one every time the call's record changes. Keep the copy with the highest version. 0 for a call unchanged since 13 October 2026.
Telephony API
updated_atstring
When that change was recorded, ISO 8601 UTC with milliseconds, with an _ist twin. For a call unchanged since 13 October 2026, its ended_at (or started_at).
Telephony API
lanestring
How the call was made or reached you. A closed list; see the lane table.
Telephony API
AI voice agent calls
The events of an AI voice agent call keep the fields and the timing they always had (they carry no version), on every account, and so do their status, end_reason and duration_sec. With the Telephony API, reads of an AI call carry the whole record: lane is ai_agent, member is null, agent_id names the agent and ended_by can be ai_agent. When an AI call's status and end_reason are a pair the table below does not list, its end_detail and ended_by are null.

recording

FieldTypeDescription
statusstringWhere the recording stands; see the recording status table.
revisioninteger0 until the recording is complete (recording.available is sent at that moment), 1 from then, then one higher every time the stored files change after it (another part, a fresh copy). The same on every account, whether or not it has a webhook endpoint, and kept for as long as the recording is: a recording that reads available is at least 1 (one stored before 13 October 2026 reads 1).
urlstring | nullThe main file's address. null unless available.
formatstring | nullogg, wav, m4a or mp3, from the main file. null unless available.
size_bytesinteger | nullThe main file's size. null unless available.
duration_secnumber | nullThe main file's own measured length in seconds, one decimal. null when it has not been measured (recordings stored before 13 October 2026, some phone app recordings). Never the sum of the parts: parts can overlap. Since 15 October 2026 a hold placed on a phone in the call itself (the caller's or the customer's phone, or a team member's own mobile) no longer shortens the recording: the held time is in the file. Before, that time was left out, so such a file could be shorter than the call by the time held.
channelsinteger | null2 for a stereo recording, 1 for mono. null when not measured.
channel_layoutobject | nullOn a stereo recording, which side is which: { "left": "customer", "right": "member" }, and the other way round on a Call via SIM call. null on mono or unmeasured recordings.
retention_daysintegerHow long your plan keeps recordings, in days.
expires_atstringWhen the recording stops being available: the call's start plus retention_days. Copy the audio to your own storage before this time; after it every part answers 404 recording_expired.
partsobject[]Every stored file of the call, the main one included. [] unless available. See the part table.
parts_orderedbooleantrue when every part has a known start time: parts is then sorted by when its audio began. false: parts is in stored order and no time order is claimed (calls recorded before 13 October 2026).

recording.status

ValueMeaning
availableStored and ready to download. recording_url and parts are set.
processingNot complete yet: a file is stored but another part may still come (it turns available about a minute after the last part, when recording.available is sent), or nothing is stored yet and it is still expected (the call is live, or ended less than 12 hours ago on a lane that records).
failedExpected and still missing 12 hours after the end (recording.failed is sent). A file that arrives later turns it to available.
not_recordedThis lane does not keep a recording on the call: dashboard campaign calls (a team calling campaign records), calls of an API run (audio blast, press 1, verification code), and App Agent calls until the phone app uploads one.
noneNo recording was made: an outbound call that was never answered, a refused inbound call, a call nobody answered that lasted only a few seconds, or a call that connected for under two seconds.
offCall recording is switched off on your account.
expiredPast expires_at: no longer available under your plan's retention.

recording.parts[]

FieldTypeDescription
partinteger1, 2, 3 in the order of the list.
primarybooleantrue for the main file (the one recording_url serves).
segmentinteger | nullThe value to pass as ?segment= to download this part. null for the main file.
urlstringThe part's download address, ready to use (needs your keys).
format, size_bytes, duration_sec, channelsmixedAs on the block, for this file. null when not measured.
started_atstring | nullWhen this file's audio began, ISO 8601 UTC with milliseconds: the moment the call's record shows for the start of this file (the call starting, or being answered), usually within a second of the file's first sound and sometimes a little after it. On a broadcast call that a key press connected to a team member on the web panel or the app, where answered_at is the team member's pickup, the call's own file reads the customer's answer instead, worked out from the call's end and the file's length, so up to about a second before its first sound (since 17 October 2026; such a call that was transferred keeps answered_at). A file of another leg of the call (for example the number a call was forwarded to) can read when the call began or was answered rather than when that file began. Files stored before 14 October 2026 read a whole second, up to about a second before the file's first sound. null when not known.
memberobject | null{ id, name, removed } when the part is one team member's own copy (for example the first member before a transfer). null for a recording of the whole call.

A call can have more than one file: for example a team member's own copy before a transfer and the recording of the whole call. Every one is a part, with its own download address. On a stereo recording the customer is on the left channel and your team member on the right (swapped on a Call via SIM call); read channel_layout rather than assuming it. Copy recordings before expires_at.

Every download address needs your keys. Since 17 October 2026 you can also create a 10-minute recording link for one file that a browser plays with no key, and download any file as MP3 or WAV with ?format= (MP3 and WAV).

disposition (null when nothing was saved)

FieldTypeDescription
outcomestring | nullThe outcome as saved: one of your account's outcomes, or interested / not_interested set automatically by an interactive call.
notestring | nullThe note as your team saved it.
callback_atstring | nullWhen a callback is due, ISO 8601 UTC. null when none is due, including when the reminder was removed or moved to a newer reminder without being done.
callback_done_atstring | nullWhen the callback was marked done. null while it is not, and when the reminder was removed instead: a removed callback is never read as done.
callback_done_byobject | null{ id, name, removed } of who marked it done. null while it is not done.
tagged_atstring | nullWhen the outcome was saved.
tagged_byobject | null{ id, name, removed } of the team member who saved it. null for an automatic outcome or one the phone app saved.
sourcestringmember (a team member saved it), device (the App Agent phone saved it) or system (set automatically, for example a press 1 interest).

voicemail (null when no message was left, or voicemail is not on your account)

FieldTypeDescription
leftbooleanAlways true when the block is present.
duration_secinteger | nullThe message's length in seconds.
urlstringGET /calls/{call_id}/voicemail: the audio, with your keys.
created_atstring | nullWhen the message was left.
expires_atstring | nullWhen the message is deleted (your recording retention after it was left). No event announces the deletion.

The voicemail block can be present while the call is still live: the caller left the message and is still listening to your closing words.

ring_attempts[]

FieldTypeDescription
kindstringmember (a team member was rung), queue_offer (a queue offered the call to a team member), number (an outside number you set was rung) or other.
memberobject | null{ id, name, removed } for member and queue_offer.
numberstring | nullThe outside number in E.164, for number. null when it is one of your team members' own mobiles.
resultstringSee the result table.
rang_secinteger | nullHow long it rang, in seconds. null on the attempt that was answered. A team member who declined a ring all in the dashboard or the app: the second they declined (since 11 November 2026; rarely, the whole ring's length).

ring_attempts[].result

ValueMeaning
answeredThis attempt was answered.
no_answerIt rang out.
busyThe team member was on another call, so they were not rung; on an outside number, the number was busy.
declinedThe team member declined (their phone answering busy is read as a decline). On a call menu key that rings its people all at once (ring all), a member who declines in the dashboard or the app reads declined since 11 November 2026, with rang_sec the second they declined (rarely, the whole ring's length); before, such an attempt could read the whole ring's result (stopped when the caller left, for example) and length.
offlineThe team member was offline, so they were not rung. Since 11 November 2026 also a team member who showed Available but had nothing that could ring (no app, no open dashboard, no Phone Bridge): call menus skip them.
on_breakThe team member was on a break, so they were not rung.
answered_elsewhereAnother team member answered first.
stoppedRinging stopped: the caller left, or someone else answered first.
skippedThe team member was skipped.
failedThe ring could not be placed.
otherAny other result.

transfers[]

FieldTypeDescription
atstring | nullWhen the call was handed over.
kindstringmember (to a colleague), merge (a colleague joined the call), menu (into a call menu), number (to an outside number) or other.
from_memberobject | null{ id, name, removed } of who handed it over. null when the AI voice agent did.
to_memberobject | null{ id, name, removed } for member and merge.
to_menuobject | null{ id, name } for menu.
to_numberstring | nullE.164, for number. null when it is one of your team members' own mobiles.
via_phone_bridgebooleantrue when the colleague was rung on their own mobile.
to_call_idstring | nullFor menu: the call_id of the record the call went on as in the call menu (a call whose customer had no record of their own, an outgoing call for one). Read it with GET /calls/{id}; its events carry that call_id. In the rare case the call menu could not take the call, no record is written and that read answers 404. null when the call stayed on this record, for the other kinds, and on transfers made before 14 October 2026.
Names and removed team members
Every { id, name, removed } reads the team member's current name. A team member who has since been removed from your account reads removed: true, with the name stored on the call or null. Email addresses are never on the call record; read them from GET /members.
Lifecycle
Status values follow the call through its lifecycle: queued (an API call accepted), ringing, in_progress (the conversation began), then completed. A call that did not connect ends as missed, and one that could not be placed or connected as failed.

Status and end reasons

status and end_reason are closed sets. New values are not added without a new payload version, so you can write exhaustive handling with no open-ended fallback.

status (where the call is now)

ValueMeaningWebhook event
queuedAccepted and waiting to be placed.call.initiated
ringingThe call is being placed or is ringing: the recipient's phone, or, on an inbound call, your team.call.ringing
in_progressThe conversation has begun: the customer answered your call, or your team member (or the AI voice agent) picked up an inbound one.call.answered
completedThe call connected and has ended.call.completed
missedThe call did not connect: nobody answered, the line was busy or declined, or it ended before an answer. A caller who left a voicemail is missed too, once they hang up (until then the call reads ringing).call.no_answer, call.busy
failedThe call could not be placed or connected: an invalid number, a network fault, or a refusal for a reason other than busy lines.call.failed

Transitions

FromToWhen
queuedringingWe handed the call to the network. An inbound call starts here.
ringingin_progressThe conversation began: the customer answered, or your team member picked up an inbound call.
in_progresscompletedThe call ended after being answered. end_reason is completed (or voicemail on an AI voice agent call a voicemail system answered).
queued, ringingmissedIt did not connect. end_reason is no_answer, busy, rejected or canceled.
queued, ringingfailedIt could not be placed or connected. end_reason is failed.

completed, missed and failed are terminal. A call never leaves one of them, and end_reason is null until it reaches one.

end_reason (set on a terminal status)

ValueMeaningWith status
completedThe call connected and ran to its normal close: the clip finished, the interactive flow ended, or either side hung up.completed
voicemailAI voice agent calls only: a voicemail system answered. It was detected and the call was closed.completed
no_answerNobody answered: it rang out, nobody on your team was available, it was outside your hours, or the caller left a voicemail. Safe to retry later.missed
busyThe line was busy: the customer's, your team member's, or every line on your account. A retry can succeed.missed
rejectedThe call was declined: by the customer, or by your team member on an inbound call.missed
canceledThe call ended before it connected: the caller left, your team member hung up, or a call menu ended with no valid choice.missed
failedThe call could not be placed or connected: an invalid number, a network fault, or a refusal for a reason other than busy lines.failed

The pairing, and the event each outcome sends

statusend_reasonTerminal eventend_detail values that land here
queued, ringing, in_progressnullnone yetnull
completedcompletedcall.completedconnected, whatsapp_sent, machine_answered
missedno_answercall.no_answersent_to_voicemail, outside_hours, closed_day, team_unavailable, team_did_not_answer, member_offline, member_on_break, member_no_answer, customer_no_answer, customer_unreachable, other
missedcanceledcall.no_answerinvalid_menu_choice, no_menu_choice, caller_left_while_ringing, caller_left_on_hold, caller_left_in_queue, caller_left, member_canceled, ended_before_answer, canceled, other
missedbusycall.busyall_lines_busy, member_busy, customer_busy, other
missedrejectedcall.busymember_declined, customer_rejected, other
failedfailedcall.failednetwork_busy, number_not_set_up, network_failure, service_error, invalid_number, cannot_take_calls, member_not_reached, member_connection_failed, other

Every call your team handles follows this table exactly: a missed call is never completed, and a completed call never reads failed. AI voice agent calls keep the status and end_reason they always had, which do not always pair this way (for example completed with failed after a hand-over that was not taken); on such a call end_detail and ended_by are null, and a voicemail system that answers an AI call reads completed with end_reason voicemail. A caller who leaves you a voicemail is a call nobody answered: missed, no_answer, sent_to_voicemail.

end_detail (Telephony API)

ValueCallsMeaning
connectedConnectedThe call connected.
whatsapp_sentConnectedA call menu key sent the caller a WhatsApp message; there was no conversation.
machine_answeredConnectedAn answering machine took a broadcast call.
sent_to_voicemailInboundNobody answered and the caller left a voicemail (see voicemail).
all_lines_busyInboundEvery line on your account was in use. The call was refused before it reached a call menu or a team member.
network_busyInboundThe phone network had no free line for the call. Refused before it reached a call menu or a team member.
number_not_set_upInboundThe number dialled has nothing set up to answer it.
outside_hoursInboundOutside your working hours.
closed_dayInboundA closed day, a holiday or a temporary closure.
invalid_menu_choiceInboundReserved for a caller who pressed a key the call menu does not have. Not sent today: such a call reads no_menu_choice.
no_menu_choiceInboundThe caller chose no option and the call menu ended: no key pressed, or only keys the call menu does not have.
team_unavailableInboundNobody the call could go to was available: every team member was busy, offline or on a break, so nobody was rung.
team_did_not_answerInboundThe team was rung and nobody answered (a call menu that rang team members who did not pick up or declined).
member_busyInboundThe team member was on another call.
member_declinedInbound or outboundThe team member declined the call.
member_offlineInboundThe team member was offline.
member_on_breakInboundThe team member was on a break.
caller_left_while_ringingInboundThe caller hung up while a team member was being rung.
caller_left_on_holdInboundThe caller hung up while on hold.
caller_left_in_queueInboundThe caller hung up while waiting in the queue.
caller_leftInboundThe caller hung up before anyone answered.
member_canceledOutboundYour team member ended the call before the customer answered.
member_not_reachedOutboundThe team member's own phone could not be reached.
member_no_answerOutboundThe team member did not answer their own phone, so the customer was never called (a click to call, or a call that rings the team member's own mobile first).
member_connection_failedOutboundThe team member's app or browser could not join the call.
ended_before_answerOutboundThe call ended before the customer answered (on a campaign call, the dialler stopped it).
customer_no_answerOutboundThe customer's phone rang and nobody answered, including a call that rang for a full minute (our ring limit, on an internet call and on Call via SIM).
customer_unreachableOutboundThe customer's phone was switched off, out of coverage or did not respond.
customer_busyOutboundThe customer's line was busy.
customer_rejectedOutboundThe customer declined the call.
invalid_numberOutboundThe number does not exist, or is incomplete.
cannot_take_callsOutboundThe number cannot take this call (barred, or a service number).
canceledOutboundYour system hung up a click to call through the API before the customer answered (ended_by api), as the click to call itself reads.
network_failureEitherA phone network fault stopped the call.
service_errorEitherA problem on our side stopped the call (for example an internet call our platform cut about two seconds into its ring, before 12 October 2026 09:29 IST).
otherEitherAny other reason. Read end_reason for the outcome.

end_detail is a closed list that may grow, with a note in the changelog: treat a value you do not recognise as other and read end_reason.

lane (Telephony API)

ValueMeaning
menuAn inbound call to a call menu (and a call moved into a call menu).
directAn inbound call to a number that rings a team member directly (an AI voice agent's hand-over to a team member on the web Agent Panel or the app included), and a call refused at the door (all_lines_busy, network_busy, number_not_set_up) before it reached a call menu or a team member.
panelA team member's call from the web Agent Panel or the app, over the internet.
app_agentA call on a team member's own phone with the App Agent, synced afterwards.
phone_bridgeA call that rang the team member's own mobile (Phone Bridge). Since 17 October 2026 an incoming call to your number that rang a team member's own mobile directly (not through a call menu) is found by the lane=phone_bridge filter of GET /calls, as its record reads; an earlier such call may be found under lane=direct although its record reads phone_bridge.
simCall via SIM: the team member called from their own SIM while the customer saw your number.
campaignA call of a dashboard campaign.
click_to_callA call started with the Click to Call API.
apiA call placed through the API: an API run, or an API call outside any campaign.
ai_agentAn AI voice agent call.
fallbackA call carried on a fallback route.
otherAnything else, including a duplicate row a browser or app call can leave (its call_id starts with lk-agent-; an outgoing one reads lane panel): reads list it, but it sends no event and has no recording of its own (the call's real row carries both), and an outcome a team member saved on it reaches only reads.

ended_by (Telephony API)

ValueMeaning
memberYour team member hung up, transferred the call, or declined it, or someone on your team (an admin or manager) ended it from Live Monitor. A click to call they transferred to a colleague who answered it is told by how the call then ended.
customerThe customer or caller hung up, or their side refused the call (busy or declined).
apiYour system hung up or transferred the call through the Click to Call API. When a colleague answers a call you transferred, the call goes on and ended_by tells how it then ended, or is null when that is not known. A call you moved to a call menu or to an outside number, or that no colleague answered, still reads api.
systemWe ended it: a refusal at the door, a closed or ended call menu, the hand-off to voicemail, the dialler stopping a campaign call, a network fault, or our support team ending the call from Live Monitor.
ai_agentThe AI voice agent ended the call.
nullLive, or not known. Still possible on some calls that use a team member's own phone, where the network does not say which side hung up: for example Call via SIM, an outgoing Phone Bridge call the customer hung up, a campaign call connected to a team member's own mobile, or a call handed to a colleague's own mobile. Since 14 October 2026 a call that came in through a call menu or straight to a team member reads customer when the caller hung up, and member when your team member's app or browser left the call while the caller was still on; before, such calls often read null. Since 14 October 2026 a call menu call the caller hung up usually reads customer from its first read as ended; before, reads in the first 3 seconds or so after it ended could still say null. Since 15 October 2026 an incoming call a team member answered on their own phone (through a call menu, a queue, ring without a menu or straight to them) reads member when they hung up on it, and so does an outgoing Phone Bridge call they hung up; a call their own phone network ended reads the same. Before, such calls read null. Since 15 October 2026 a call someone on your team (an admin or manager) ended from Live Monitor reads member, and a call our support team ended reads system; before, they read null, or customer on a call answered in the app or browser.

network_cause (Telephony API)

codenameMeaning
1UNALLOCATED_NUMBERThe number does not exist.
3NO_ROUTE_DESTINATIONThe network has no route to the number.
17USER_BUSYThe phone was busy.
18NO_USER_RESPONSEThe phone did not respond (switched off or out of coverage).
19NO_ANSWERThe phone rang and nobody answered.
20SUBSCRIBER_ABSENTThe phone is not reachable.
21CALL_REJECTEDThe call was declined.
22NUMBER_CHANGEDThe number has changed.
27DESTINATION_OUT_OF_ORDERThe phone is out of service.
28INVALID_NUMBER_FORMATThe number is incomplete or malformed.
29FACILITY_REJECTEDThe network refused the call.
31NORMAL_UNSPECIFIEDThe network ended the call without a reason.
34NORMAL_CIRCUIT_CONGESTIONThe network was congested.
38NETWORK_OUT_OF_ORDERThe network was out of order.
41NORMAL_TEMPORARY_FAILUREA temporary network failure.
42SWITCH_CONGESTIONThe network was congested.
44REQUESTED_CHAN_UNAVAILNo line was available on the network.
52OUTGOING_CALL_BARREDCalls of this kind are barred.
54INCOMING_CALL_BARREDThe number does not accept calls.
57BEARERCAPABILITY_NOTAUTHThe number cannot take this kind of call.
79SERVICE_NOT_IMPLEMENTEDThe number cannot take calls (a service number, or blocked by its network).
88INCOMPATIBLE_DESTINATIONThe number cannot take this kind of call.
102RECOVERY_ON_TIMER_EXPIREThe network timed out.
111PROTOCOL_ERRORA network signalling error.
127INTERWORKINGA network interworking error.

Only these standard causes are published. A normal end, your own side's cancel and any other value read null; the outcome is always in end_reason and end_detail.

Corrected on 13 October 2026
Before this date a team call could read a pair the table above rules out: a missed dial as missed with completed, an answered call menu call as completed with failed, a voicemail call with no status at all. Every read and every event now follows the table, for every account. AI voice agent calls keep their values.

The simpler call_status on a run id

GET /calls/run_<id> keeps an older, smaller call_status vocabulary, unchanged so existing integrations keep working. Read it through this mapping, or read the call object on the same response, which carries the full set above.

call_statusMeansNote
queuedqueuedSame meaning.
ringingringingSame meaning.
answeredin_progressThe same state under an older name.
completedcompletedSame meaning.
failedmissed or failedThis one value covers both. Read end_reason, or the call object's status, to tell a call that rang unanswered from one that could not be placed.
No status called no_answer or busy
Those are end_reason values, not statuses. A call that rang unanswered and one that was busy both carry the status missed, and the reason is in end_reason. The webhook event name tells you the same thing without reading either field.

You can branch either on the event type or on data.status and data.end_reason; they are kept in step, because data.status is the event's own status. The same values are returned by List calls and Get call status for the same call.

Corrected in September 2026
Two events used to carry the wrong status. A call that rang unanswered or was busy could arrive as "failed" instead of "missed", and a call that genuinely could not be placed could arrive as "missed" instead of "failed", depending on which part of the network raised the event. The values are now derived from the event name, so call.no_answer and call.busy are always missed and call.failed is always failed. If your handler worked around the old inconsistency by reading end_reason instead, it keeps working unchanged.

Identifiers

Seven identifiers move between your system and ours. Only one of them is the handle you poll and match on; the rest are for correlation, for fetching a specific artefact, or for retry safety.

The seven ids

IdentifierWhat it isWhere you get itWhat you poll withIn webhooks
unique_idThe handle for the thing you just created. This is the id to keep.The unique_id field of the response that placed the call or sent the code, and of every read and event of a call. For a call nobody placed through the API (an inbound call, your team's own call, a dashboard campaign call) it is the call_id.Yes. GET /calls/:unique_id.data.unique_id on every call.* and recording.available event.
run idThe unique_id shape of a call an API run placed: run_<campaign_id>. Since 13 October 2026 only API runs (and AI voice agent campaigns) use it: a dashboard campaign's calls carry their own call_id, and its run_ id answers 404.Returned by POST /calls (types audio_blast and press1) and by POST /campaigns/:id/trigger, including an AI voice agent campaign.Yes. It is a unique_id.data.unique_id. On a broadcast run its digits are data.campaign_id; on an AI voice agent run data.campaign_id is the campaign you triggered.
request_idA verification request. The same value as that request's unique_id. The alias otp_id is accepted in a verify body.Returned by POST /otp/send and by POST /calls with type: "otp".Yes. GET /calls/:request_id.data.request_id on every otp.* event.
click to call idOne click to call (c2c_ and 32 hex characters). It is also the unique_id of the call it places (its own call record; the record it goes on as in a call menu keeps its own unique_id).The unique_id of POST /click-to-call.Yes. GET /click-to-call/:id for the click to call; GET /calls/:id and its recording for the call.data.id on click_to_call.*; data.unique_id on its own call record's events. data.click_to_call_id is on those and, since 17 October 2026, on its call menu record's events too: match on data.unique_id.
call_idOur record id for one call, unique for every call.Every read and event of a call: GET /calls, the call object on GET /calls/:unique_id, and data.call_id.It resolves on GET /calls/:unique_id, and it is the unique_id of a call nobody placed through the API. Use it for the recording, voicemail, transcript and analysis of a specific call, and as the key of a call in your own store.data.call_id, null only on a call.initiated sent before the record exists.
leg_idA second id for the same call, present only when the record is keyed on something other than the phone leg. On a call placed with POST /ai/calls it is the dial id, the same value as unique_id. Added September 2026 beside an unchanged unique_id.GET /calls, the call object on GET /calls/:unique_id, and the call and recording objects in webhooks. null on most calls.Not the id to poll with, though it resolves on GET /calls/:unique_id too.data.leg_id.
reference_idYour own correlation key. We never interpret it and it never de-duplicates anything.You send it. Up to 120 characters; control characters are stripped.No. It is echoed, not addressable.On the envelope as reference_id and again inside data.
Idempotency-KeyYour retry key for one logical request. 1 to 128 visible characters (a longer key is refused), stored for 24 hours.You send it as a request header.No. It addresses a stored response, not a resource.Never sent.

Ids we generate for delivery

IdentifierWhat it isWhere you get itWhat you poll withIn webhooks
event idOne webhook event (evt_...). The same value reaches every endpoint subscribed to it, and repeats across retries.The event body's id (aliased event_id).No. De-duplicate your handler on it.id in the body and X-Agentive-Event-Id in the headers.
delivery idOne event on its way to one endpoint (dlv_...). Stable across every retry of that delivery.The X-Agentive-Delivery-Id header on the delivery itself.No. Record it in your own log, and quote it when you ask us about a specific delivery.X-Agentive-Delivery-Id in the headers.
Some calls carry two ids
A call placed with POST /ai/calls has no run, so we return the dial id when you place it while the record itself is keyed on the conversation. That dial id is the call's unique_id on every webhook event and on every read: the call list, GET /calls/:unique_id, the transcript, the analysis and the recording. call_id is the record id, and leg_id is the dial id again. Either id resolves on GET /calls/:unique_id, so an id you stored earlier keeps working.
One rule to remember
Poll with the unique_id the placing response gave you, and match webhooks on data.unique_id. Everything else is either yours (reference_id, Idempotency-Key) or ours to hand you for a specific artefact (call_id, event id, delivery id).

The recording object

data.object is "recording" for the recording.available event. Every account receives these fields:

FieldTypeDescription
objectstring
Always "recording".
unique_idstring
The call's public id, the same value Get call status returns and the call events carry.
call_idstring
Our record id for the call this recording belongs to.
leg_idstring | null
The same second id the call object carries, or null. Match on unique_id.
click_to_call_idstring | null
The click to call this call belongs to, or null. Since 17 October 2026 also set on the recording of the record a click to call goes on as in a call menu, whose unique_id and call_id are its own and whose audio is the call menu part of the call: the click to call's own recording is the one whose unique_id is the click to call id.
recording_urlstring
An authenticated API URL for the main file. Fetch it with your API key and secret; see Download a recording. It streams the audio; it never redirects.
formatstring
The audio format of the main file: usually "ogg", else "wav", "m4a" or "mp3".
duration_secinteger | null
The main file's own length in seconds, rounded, when it has been measured; otherwise the call's duration_sec.
size_bytesinteger | null
The main file's size in bytes.
campaign_idinteger | null
The campaign or API run the call belongs to; for an AI voice agent API campaign, the campaign you triggered. null otherwise.
campaign_typestring | null
audio_blast, press1, otp or ai_agent: the same value the call events carry.
reference_idstring | null
Your correlation key, the same value the call events carry.
metadataobject | null
The metadata you sent when you placed the call through the API (a number comes back as text). null otherwise.
via_apiboolean
true when the call was placed through the API, the same value the call events carry.

An account with the Telephony API also receives the whole recording block and the call:

FieldTypeDescription
version, updated_atinteger, string
The call's version and updated_at at this event. Apply it only when the version is higher than the one you hold.
statusstring
Always available on this event.
revisioninteger
0 until the recording is complete (recording.available is sent at that moment), 1 from then, then one higher every time the stored files change after it (another part, a fresh copy). The same on every account, whether or not it has a webhook endpoint, and kept for as long as the recording is: a recording that reads available is at least 1 (one stored before 13 October 2026 reads 1).
channelsinteger | null
2 for a stereo recording, 1 for mono. null when not measured.
channel_layoutobject | null
On a stereo recording, which side is which: { "left": "customer", "right": "member" }, and the other way round on a Call via SIM call. null on mono or unmeasured recordings.
retention_daysinteger
How long your plan keeps recordings, in days.
expires_atstring
When the recording stops being available: the call's start plus retention_days. Copy the audio to your own storage before this time; after it every part answers 404 recording_expired.
partsobject[]
Every stored file of the call, the main one included. [] unless available. See the part table.
parts_orderedboolean
true when every part has a known start time: parts is then sorted by when its audio began. false: parts is in stored order and no time order is claimed (calls recorded before 13 October 2026).
callobject
The whole call object at this version, so one event carries the call and its recording.
recording.available without the Telephony API
{
  "id": "evt_2c3d4e5f60718293a4b5c6d7e8f9a0b1",
  "object": "event",
  "api_version": "2026-06-01",
  "type": "recording.available",
  "created": 1780589575,
  "occurred_at": "2026-06-04T16:12:55.000Z",
  "timestamp_ist": "2026-06-04T21:42:55.000+05:30",
  "org_id": 42,
  "reference_id": "order-99213",
  "livemode": true,
  "data": {
    "object": "recording",
    "unique_id": "run_4821",
    "call_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "leg_id": null,
    "click_to_call_id": null,
    "recording_url": "https://voice.agentive.co.in/api/public/v1/calls/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/recording",
    "format": "ogg",
    "duration_sec": 42,
    "size_bytes": 126976,
    "campaign_id": 4821,
    "campaign_type": "audio_blast",
    "reference_id": "order-99213",
    "metadata": null,
    "via_api": true
  },
  "event": "recording.available",
  "event_id": "evt_2c3d4e5f60718293a4b5c6d7e8f9a0b1"
}
Downloading the audio
The recording_url points at Download a recording. Call it with your API key and secret (every part's url needs them too); it streams the audio and supports HTTP Range requests. Add ?segment=N (a part's segment) for an earlier part. Copy what you need before expires_at. Since 17 October 2026 your server can turn any of these files into a 10-minute link a browser plays without keys (Create a recording link), and any of them can be downloaded as MP3 or WAV by adding format=mp3 or format=wav to the query (for example ?format=mp3, or &format=mp3 after ?segment=N; see Download a recording).

The verification object

data.object is "verification" for otp.sent, otp.verified, otp.failed and otp.max_attempts.

FieldTypeDescription
objectstring
Always "verification".
request_idstring
The verification request id returned by Send a code.
numberstring
The recipient's number in E.164 form.
Example: +919812345678
statusstring
queued on otp.sent, verified on otp.verified, failed on otp.failed, max_attempts on otp.max_attempts.
verification_statusstring
Where the verification stands, independent of which event you are looking at: pending while it is still open (both otp.sent and otp.failed), verified once the correct code is entered, and locked when the attempt allowance is spent. Branch on this rather than on status if you want the state of the verification rather than the meaning of the event.
verifiedboolean | null
null on otp.sent, true on otp.verified, false on otp.failed and otp.max_attempts.
attempts_leftinteger | null
Remaining verify attempts. Present on otp.failed (1 or more) and otp.max_attempts (0).
expires_in_secinteger | null
Seconds until the code expires. Present on otp.sent.
Example: 600
max_attemptsinteger | null
Allowed verify attempts. Present on otp.sent, otp.failed and otp.max_attempts.
campaign_idinteger | null
The delivery run, if any.
reference_idstring | null
Your correlation key.

Responding to a webhook

Reply with any 2xx status once you have safely received the event; 200 with an empty body is fine. Reply quickly and do the heavy work asynchronously: each attempt has a 6 second timeout, and a slow endpoint is treated as a failed attempt.

Your responseWhat we do
2xxMarked delivered. No further attempts for this event.
3xxNot followed. Counted as a failed attempt and retried, so a signed body is never forwarded to another host.
4xx or 5xxCounted as a failed attempt and retried, for up to nine attempts over about 20 hours.
No reply within 6 sCounted as a failed attempt and retried.
Connection errorCounted as a failed attempt and retried.

Return 2xx only after you have durably accepted the event (written it to a queue or a database). If you return 2xx and then crash, the event is not resent.

Retries and delivery

A delivery is one event on its way to one endpoint. It gets nine attempts over about 20 hours: three quick ones for a receiver that is briefly busy, then six spread out for one that is down. Every attempt sends the same body, with a version 2 signature recomputed for that attempt's timestamp, under the same X-Agentive-Delivery-Id, with an increasing X-Agentive-Attempt and a fresh X-Agentive-Timestamp.

AttemptSent after the previous attemptNote
1ImmediatelyAs soon as the event is generated.
20.5 seconds
32 secondsEnd of the fast path.
41 minute
55 minutes
630 minutes
72 hours
86 hours
912 hoursThe last attempt, about 20 hours 36 minutes after the first. After this the delivery is marked failed.
Headers on the third attempt
X-Agentive-Event: call.completed
X-Agentive-Event-Id: evt_4b8f2c1d6a3e4f0b9d7c2a1e5f6b8c0d
X-Agentive-Delivery-Id: dlv_7c1e93a04b6d48f2b0a5d3e81c9f2740
X-Agentive-Attempt: 3
X-Agentive-Timestamp: 1780589531
X-Agentive-Signature-V2: t=1780589531,v2=2d7e9a0c4f1b8e6d3a5c7f9b0e2d4a6c8f1b3e5d7a9c0f2e4b6d8a1c3e5f7b9d
X-Agentive-Signature: sha256=4f1d0c7b2a9e8d6f5c4b3a2918e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1908e9
  • Each attempt has a 6 second timeout. A slow endpoint is a failed attempt.
  • A delivery succeeds as soon as your endpoint returns a 2xx, and no further attempts are made.
  • The delivery is written down before the first attempt, so a restart on our side cannot lose it. A delivery left mid-flight by a restart is picked up and continued.
  • When an endpoint has failed the three quick attempts for five events in a row, new events for it skip the quick attempts and start at the one minute step, until one attempt succeeds.
  • Since 17 October 2026, while your endpoint is failing (no answer, a timeout, a 408, 429 or 503 status, or three failed answers in a row) we send one waiting delivery at a time, oldest first, and hold the rest. Once your endpoint accepts one again, the held deliveries that are already due follow right away, a few at a time, and a delivery whose next attempt is still ahead waits for that attempt. A held delivery can therefore reach its later attempts later than the schedule above. A delivery not accepted 21 hours after its event is not sent again: it is marked failed when its next attempt comes due, whatever its number of attempts. A refusal of one delivery (another 4xx, or a single 5xx) does not hold the others.
  • After the ninth attempt the delivery is marked failed and no further attempt is made. Recover a missed event from the API: poll Get call status for a specific call, or page through List calls (with the Telephony API, its change feed updated_since returns every call that changed). Build your system so a missed webhook is not the only way you learn a call's outcome.

What the dashboard shows

The Webhooks tab in the Voice dashboard lists the latest 50 deliveries under each endpoint, newest first, one row per event per endpoint. Each delivery is kept for 30 days, then deleted. Each row carries four columns:

ColumnWhat it tells you
EventThe event name.
ResultDelivered with the HTTP status your endpoint returned; Retrying, with the status of the last try and the time of the next one, while the delivery is on its retry schedule; or Failed once no try is left, with the last status. A Failed row with no status code means a network error or a timeout.
TriesHow many attempts have been made so far, out of nine.
When (IST)When the event was generated, in Indian Standard Time.
A delivery still being retried reads as Retrying
A delivery inside its retry schedule reads Retrying until an attempt succeeds (Delivered) or the ninth fails (Failed). Watch the Tries count climb, and refresh to see it settle.
Kept for 30 days
We keep each delivery and the status code your endpoint returned for 30 days, then delete it. Deleting an endpoint deletes its delivery history too. To recover an older event, read the call: Get call status for one call, or List calls (with the Telephony API, its change feed updated_since returns every call that changed). Keep your own log, keyed on X-Agentive-Delivery-Id, for as long as you need it.

An event delivered to three endpoints is three rows under three endpoints, each retrying on its own schedule, so a healthy endpoint is never held back by a broken one. Match a row to what your receiver saw through the event name and the time; your own log, keyed on X-Agentive-Delivery-Id, is the precise record.

Ordering and idempotency

  • At least once. The same id (evt_...) is sent to every endpoint that receives a given event, and is repeated across all nine attempts of that delivery. Treat an event as already handled if you have seen its id before. If one endpoint of yours is behind another, de-duplicate on X-Agentive-Delivery-Id instead, which is unique per endpoint.
  • Ordering is not guaranteed. Events may arrive out of order, and the retry tail widens the gap: a call.answered your endpoint refused could land hours after the call.completed it accepted.
  • Apply only a higher version. Every team-call event carries data.version, which goes up by one with every change to the call. Per call_id, keep the version you hold and apply an event (or a read) only when its version is higher. An equal version carries the same facts; only a team member's or a call menu's current name can differ. voicemail.left can carry the same version as the terminal event before it: store the call by this rule, but act on the event itself by its type and id. Without the Telephony API, and on AI voice agent calls, order by the envelope's created and the status field instead.
  • The API is the source of truth. When in doubt, read the call with Get call status; it returns the same object at the latest version.
  • A call typically produces this sequence: call.initiated (API-placed calls only), then call.answered and call.completed if it connects, or one of call.no_answer, call.busy or call.failed if it does not; then recording.available once the recording is complete, and call.tagged when your team saves an outcome (either can come first). Build your logic around the terminal event rather than the intermediate ones.
  • Request idempotency. The call-placing endpoints accept an Idempotency-Key header, so a network retry with the same key replays the original response instead of placing a second call (and producing a second stream of events). See Idempotency in the Voice Broadcast reference.

Testing

From the Webhooks tab in the Voice dashboard:

  • View sample payloads shows the exact body for each event, so you can build and unit-test your handler before any live traffic.
  • Send test event delivers a sample call.completed to a single endpoint. The body is built by the same code as a live delivery and signed the same way, right down to the event id shape, so you can confirm your receiver and signature verification end to end. The dashboard reports the response code and attempts.

To tell a test apart from real traffic it carries "test": true inside data and a reference_id of test-reference. Its unique_id is run_0 and its campaign_id is 0, neither of which can belong to a real call:

Test event
{
  "id": "evt_9f8e7d6c5b4a39281706f5e4d3c2b1a0",
  "object": "event",
  "api_version": "2026-06-01",
  "type": "call.completed",
  "created": 1780591200,
  "occurred_at": "2026-06-04T16:40:00.000Z",
  "timestamp_ist": "2026-06-04T22:10:00.000+05:30",
  "org_id": 42,
  "reference_id": "test-reference",
  "livemode": true,
  "data": {
    "object": "call",
    "unique_id": "run_0",
    "call_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "leg_id": null,
    "click_to_call_id": null,
    "direction": "outbound",
    "from_number": "01100000021",
    "to_number": "+919812345678",
    "status": "completed",
    "duration_sec": 42,
    "end_reason": "completed",
    "campaign_id": 0,
    "campaign_type": "audio_blast",
    "agent_id": null,
    "reference_id": "test-reference",
    "metadata": null,
    "via_api": true,
    "charge_inr": null,
    "response": {
      "disposition": null,
      "digit": null,
      "via": null,
      "answers": null,
      "voicemail_left": null
    },
    "test": true
  },
  "event": "call.completed",
  "event_id": "evt_9f8e7d6c5b4a39281706f5e4d3c2b1a0"
}
No separate test mode
There is no separate test or sandbox mode: livemode is always true, and the only marker on a manually sent test event is the data.test flag above (never present on real events). A request-bin style URL is a quick way to inspect the raw body, headers and signature during integration.

Versioning

  • Every event carries api_version. The current version is 2026-06-01.
  • We may add new fields to the envelope or to any data object at any time without changing the version. Your handler must ignore fields it does not recognise.
  • We may add new event types. A new event reaches an endpoint only when it is ticked by name; an endpoint with nothing ticked keeps receiving the original list. Still switch on type and ignore events you do not handle.
  • A value is changed in place only where it was wrong, and every such correction is listed, with its date, in the changelog.
  • A removed or renamed field is a breaking change and would come with a new api_version. We do not change the meaning of an existing field in place.

Security checklist

Before you go live

  • Verify X-Agentive-Signature-V2 on every request; reject anything that does not match, is older than five minutes or does not carry it.
  • Compare signatures in constant time, after checking their byte lengths match.
  • De-duplicate on id before you act on an event, so a retry changes nothing. Check age against the signed t, never against X-Agentive-Timestamp alone.
  • Use the raw request body for the HMAC, not a re-serialised object.
  • Keep the signing secret server-side, and refuse to start a receiver without it; rotate it from the dashboard if it is ever exposed.
  • Serve the endpoint over HTTPS in production. It is the only thing that stops a body and its signature being read off the network and sent back to you.
  • If your firewall limits who may call your endpoint, allow 139.59.48.158 (since 17 October 2026; see Where webhooks come from); never accept a delivery on its address alone.
  • Return 2xx only after you have durably accepted the event.
  • Per call, apply an event only when its version is higher than the one you hold; act on voicemail.left by its type and id, since it can carry the terminal event's version.
  • Reconcile against List calls so a dropped delivery cannot leave a call unaccounted for.

Quick start

Five steps from an empty endpoint to a verified, live event stream. You need a Voice API key and secret from the Voice dashboard and a public HTTPS URL.

  1. Add an endpoint
    In the Voice dashboard, open Webhooks, add your https:// URL and copy the signing secret into an environment variable such as AGENTIVE_WEBHOOK_SECRET. Leave the event list empty to receive the original events, or tick the ones you want (the newer ones only arrive when ticked).
  2. Deploy a receiver
    Start from one of the example handlers. It must read the raw body, verify the signature in constant time and return 200 within 6 seconds.
  3. Send a test event
    Click Send test event on the endpoint. The delivery log should show a 200. If it shows 401, your signature check is reading a parsed body instead of the raw bytes.
  4. Place a real call to your own number
    Use the Voice Broadcast API with a number you can answer. Within a minute or two your endpoint receives call.initiated, a terminal event, and, when the call was recorded, recording.available, all sharing the same data.unique_id.
    curl -X POST https://voice.agentive.co.in/api/public/v1/calls \
      -H "x-api-key: pk_live_..." \
      -H "x-api-secret: sk_live_..." \
      -H "Content-Type: application/json" \
      -d '{
        "type": "audio_blast",
        "number": "9812345678",
        "audio_id": 12,
        "reference_id": "webhook-test-1"
      }'
  5. Store the event id and reconcile
    Persist each id before you act on it, and poll Get call status for any call whose terminal event has not arrived, so a dropped delivery never leaves a call unresolved.

Next steps