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.
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 APIs | WhatsApp Business API | |
|---|---|---|
| Base URL | https://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 |
| Covers | Voice 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. |
| Transport | HTTPS 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 APIs | WhatsApp Business API | |
|---|---|---|
| Credential | One 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 it | x-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>. |
| Scope | Account-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 as | Both 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. |
| Rotation | From 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 APIs | WhatsApp Business API | |
|---|---|---|
| Shape | { status, code: number, error_code: string, error, details, unique_id, reference_id } | { error, code: string, details: object } |
| What to branch on | error_code. The numeric code mirrors the HTTP status and stays for compatibility. | code, which is itself the machine string. |
| Human sentence | details, repeated in error so a handler written for the WhatsApp shape reads a Voice error too. | error. |
| Extra context | Named 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 APIs | WhatsApp Business API | |
|---|---|---|
| 401 | Credentials missing, unknown, or rejected. The status never confirms whether a key exists. | Token missing or wrong. |
| 403 | Credentials 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. |
| 404 | Not 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 APIs | WhatsApp Business API | |
|---|---|---|
| Key | Idempotency-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. |
| Window | 24 hours per account. | The life of the campaign. |
| A repeat | Replays 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 marker | Idempotent-Replayed: true, plus the original idempotency-replayed: true header. | duplicate: true in the body. |
| Same key, different body | HTTP 422 with idempotency_conflict. | The first send stands; the second is reported as a duplicate. |
| Still in flight | HTTP 409 with idempotency_in_progress and Retry-After. | Not applicable. |
Rate limits and headers
| Voice APIs | WhatsApp Business API | |
|---|---|---|
| Budget | Per 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 headers | RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset, with X-RateLimit-* aliases of the same three values. | None. |
| How long to wait | Retry-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 refusal | Place 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 APIs | WhatsApp Business API | |
|---|---|---|
| Header to verify | X-Agentive-Signature-V2: t=<unix seconds>,v2=<hex> | X-Agentive-Signature: <hex>, with no prefix. |
| What is signed | HMAC-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. |
| Freshness | Reject 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. |
| Comparison | Constant time, on bytes. Reject on any mismatch, and reject a delivery with no version 2 header. | Constant time, on bytes. Reject on any mismatch. |
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 APIs | WhatsApp Business API | |
|---|---|---|
| Event name | X-Agentive-Event | X-Agentive-Event |
| Event id | X-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 id | X-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 number | X-Agentive-Attempt, 1-based, counting through the whole retry schedule. | None. |
| Attempt time | X-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 agent | Agentive-Webhooks/2026-06-01 | Agentive-Webhooks/2026-05-08, the Chat payload version. |
| Sent from | One 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 APIs | WhatsApp Business API | |
|---|---|---|
| Attempts | Nine: three fast, then six spread out. | Three. |
| Schedule | 0.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 window | About 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 attempt | 6 seconds. | 10 seconds. |
| What you see | The 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 APIs | WhatsApp Business API | |
|---|---|---|
| Time zone | Indian 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 alongside | created_at_utc on a call, and occurred_at (UTC) plus created (Unix seconds) on a webhook envelope. | The envelope timestamp is already UTC. |
| Money | Indian 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 APIs | WhatsApp Business API | |
|---|---|---|
| API version | In the path: /api/public/v1. | In the path: /api/v1. |
| Payload version | api_version on every webhook event. Currently 2026-06-01. | apiVersion on every webhook event. Currently 2026-05-08. |
| Compatibility | Fields 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 case | snake_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 403https_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.
How webhooks work
- Register an endpointIn the Voice dashboard, add up to 10 webhook endpoints, each with an
https://URL and a signing secret. - Choose eventsPick 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.
- We POST the eventWhen a matching event occurs we send a JSON event object to your URL, signed in the
X-Agentive-Signature-V2header. - You verify and respondYour server checks the signature, records the event and replies with a 2xx status within 6 seconds.
- Every attempt is countedThe 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.
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:
- The endpoint events on this page, including a test event you send from the dashboard.
- Campaign webhooks.
- The call menu key press webhook.
- Your AI voice agent's own webhook and its call events.
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.
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
| Event | Object | Fires when |
|---|---|---|
| call.initiated | call | A call you placed through the API is accepted and queued. |
| call.ringing | call | Not sent yet. Once announced: an inbound call reached your number and is ringing your team. |
| call.answered | call | The 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.completed | call | A call that connected has ended. |
| call.no_answer | call | The call ended without connecting: nobody answered, or it ended before an answer. Safe to retry later. |
| call.busy | call | The line was busy or the call was declined. A retry can succeed. |
| call.failed | call | The 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)
| Event | Object | Fires when |
|---|---|---|
| call.tagged | call | Your 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.left | call | The caller left a voicemail. Needs voicemail on your account. |
| call.updated | call | The call's record changed after its final event, for a reason the other events do not cover. |
Recording
| Event | Object | Fires when |
|---|---|---|
| recording.available | recording | The call's recording is complete and ready to download. Once per call. |
| recording.failed | call | Telephony API. An expected recording was still missing 12 hours after the call ended. |
Team member rings (Telephony API, not sent yet)
| Event | Object | Fires when |
|---|---|---|
| call.member_ringing | call | Once announced: a team member is being rung for a call, so your CRM can show the caller on that person's screen. |
| call.member_missed | call | Once announced: that ring ended without this team member answering. |
Verification
| Event | Object | Fires when |
|---|---|---|
| otp.sent | verification | A voice verification call is queued for delivery. |
| otp.verified | verification | The recipient entered the correct code. |
| otp.failed | verification | The recipient entered an incorrect code. The verification stays open until it expires or runs out of attempts. |
| otp.max_attempts | verification | Too 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.
| Event | Object | Fires when |
|---|---|---|
click_to_call.member_ringing | click_to_call | Your team member is being rung. |
click_to_call.member_answered | click_to_call | Your team member answered. |
click_to_call.customer_ringing | click_to_call | We are calling the customer. |
click_to_call.customer_answered | click_to_call | The customer answered. |
click_to_call.held | click_to_call | The customer was put on hold through the API. |
click_to_call.resumed | click_to_call | The customer was taken off hold. |
click_to_call.transferred | click_to_call | The 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.ended | click_to_call | The click to call is over. Sent exactly once, with the outcome. |
click_to_call.tagged | click_to_call | The 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.analysedand 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 announcedcall.member_ringingandcall.member_missed. They are offered only to an account with the Telephony API;voicemail.leftalso needs voicemail andrecording.failedcall recording on the account. - None of the new events is ever sent for an AI voice agent call.
139.59.48.158; see Where webhooks come from.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.
{
"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
| Field | Type | Description |
|---|---|---|
| id | string | Unique id for this event, prefixed evt_. Use it to make your handler idempotent.Example: evt_4b8f2c1d6a3e4f0b9d7c2a1e5f6b8c0d |
| object | string | Always "event". |
| api_version | string | The payload version used to build this event. Example: 2026-06-01 |
| type | string | The event name in resource.action form.Example: call.completed |
| created | integer | When the event was generated, as a Unix epoch timestamp in seconds. Example: 1780589528 |
| occurred_at | string | The same instant in UTC, ISO 8601 with a Z suffix. Example: 2026-06-04T16:12:08.512Z |
| timestamp_ist | string | The same instant in Indian Standard Time, ISO 8601 with a +05:30 offset. Example: 2026-06-04T21:42:08.512+05:30 |
| org_id | integer | Your account id. |
| reference_id | string | null | The reference_id you supplied when you placed the call or sent the code. null if you did not send one. |
| livemode | boolean | Always true. There is no separate sandbox mode; see Testing. |
| data | object | The event-specific record. Its object field names the resource type: call, recording, verification or, for the click to call events, click_to_call. |
| event | string | Alias of type. Kept for compatibility; prefer type. |
| event_id | string | Alias of id. Kept for compatibility; prefer id. |
idandevent_idare the same value. Preferid.typeandeventare the same value. Prefertype.reference_idappears both at the top level and insidedata, 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:
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| Header | Type | Description |
|---|---|---|
| Content-Type | string | The body is always JSON. Example: application/json |
| X-Agentive-Event | string | 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-Id | string | 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-Id | string | 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-Attempt | string | 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-Timestamp | string | 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-V2 | string | 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-Signature | string | 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-Agent | string | 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.
X-Agentive-Signature-V2: t=1780589528,v2=9c41ab2f7e05d3c6b8a1f4e2d0c9b7a6e5f4d3c2b1a09f8e7d6c5b4a3f2e1d0c- Read the raw bodyTake the request body as bytes, before any JSON parsing or re-serialising. Re-serialising can change whitespace and break the check.
- Check the timeSplit the header on the comma. Reject the request if
tis not a number or is more than 300 seconds from your own clock. - Compute the digestCompute
HMAC-SHA256(secret, t + "." + rawBody)and hex-encode it. - Compare in constant timeCheck 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.
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-V2covers the timestamp and the body, ast=<unix seconds>,v2=<hex digest>where the digest is computed over"<t>.<body>". Thetis the same value asX-Agentive-Timestamp, and it is recomputed on every attempt.
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.
// 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:
# 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.
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.call.initiated
Values at this event
| Field | Type | Description |
|---|---|---|
| status | string | Always "queued". |
| call_id | string | null | Our record id for the call, present as soon as it exists. |
| duration_sec | null | Set on the terminal event. |
| end_reason | null | Set on the terminal 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"
}call.ringing
Values at this event
| Field | Type | Description |
|---|---|---|
| status | string | Always "ringing". |
| member | null | Nobody has been rung yet. Use call.member_ringing to learn who is rung. |
| end_reason, end_detail | null | Set on the terminal 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"
}call.initiated to call.answered or to a terminal event without ringing ever arriving. Outbound calls never send it.call.answered
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
| Field | Type | Description |
|---|---|---|
| status | string | Always "in_progress". |
| member | object | 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_at | string | 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_sec | null | Set on the terminal event. Without the Telephony API it reads 0 here, as it always has. |
| end_reason | null | Set on the terminal 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.
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.call.completed
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
| Field | Type | Description |
|---|---|---|
| status, end_reason | string | "completed", "completed". On an AI voice agent call a voicemail system answered, end_reason is "voicemail". |
| end_detail | string | connected, whatsapp_sent (a call menu key sent a WhatsApp message) or machine_answered (an answering machine took a broadcast call). |
| duration_sec | integer | 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.status | string | Usually processing here: the file is still being stored. recording.available follows. |
| response | object | How the recipient responded on Interactive Voice calls, and the call menu key on a menu call; see the call object. |
{
"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"
}call.no_answer
Values at this event
| Field | Type | Description |
|---|---|---|
| status | string | Always "missed". |
| end_reason | string | "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_detail | string | Why, from the table. The sample is an outbound call the customer did not answer. |
| duration_sec | integer | 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. |
{
"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"
}call.busy
Values at this event
| Field | Type | Description |
|---|---|---|
| status | string | Always "missed". |
| end_reason | string | "busy" when the line was busy, "rejected" when the call was declined. |
| end_detail | string | all_lines_busy, member_busy, customer_busy, member_declined or customer_rejected. The sample is a refused call. |
{
"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"
}call.failed
Values at this event
| Field | Type | Description |
|---|---|---|
| status | string | Always "failed". |
| end_reason | string | "failed". On an AI voice agent call it can also read "canceled", as before. |
| end_detail | string | Why, for example invalid_number (the sample), cannot_take_calls, network_failure. network_cause carries the network's standard cause when it gave one. |
{
"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
| status | end_reason | Terminal event | end_detail values that land here |
|---|---|---|---|
| queued, ringing, in_progress | null | none yet | null |
| completed | completed | call.completed | connected, whatsapp_sent, machine_answered |
| missed | no_answer | call.no_answer | sent_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 |
| missed | canceled | call.no_answer | invalid_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 |
| missed | busy | call.busy | all_lines_busy, member_busy, customer_busy, other |
| missed | rejected | call.busy | member_declined, customer_rejected, other |
| failed | failed | call.failed | network_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:
{
"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.
call.tagged
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
| Field | Type | Description |
|---|---|---|
| disposition | object | null | The outcome as it stands now; see the call object. null when everything was cleared. |
{
"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"
}voicemail.left
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
| Field | Type | Description |
|---|---|---|
| voicemail | object | { left, duration_sec, url, created_at, expires_at }. |
| handled_by | string | Always "voicemail". |
{
"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"
}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.call.updated
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
| Field | Type | Description |
|---|---|---|
| changed | string[] | Which parts of the record changed. Treat a name you do not recognise as a change to the whole record. |
{
"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"
}| changed | Fields it moves |
|---|---|
| outcome | status, end_reason, end_detail, ended_by, network_cause, sip_status, duration_sec, ended_at, talk_sec, wait_sec. |
| answer | answered_at. |
| people | member, assigned_member. |
| identity | direction, the numbers, lane, campaign, campaign_id, click_to_call_id, via_api, reference_id, leg_id. |
| disposition | disposition. |
| recording | recording, recording_available, recording_url. |
| routing | menu, ring_attempts, transfers, response. |
| hold | hold_sec. |
| charge | charge_inr. |
| transcript | transcript_available. |
Recording events
recording.available carries a recording object in data; recording.failed carries the call object.
recording.available
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
| Field | Type | Description |
|---|---|---|
| recording_url | string | 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_sec | integer | The main file's own length in seconds, rounded, when measured. |
| expires_at | string | When the recording stops being available under your plan's retention. Copy it before then. |
| call | object | The whole call object, so one event carries the call and its recording. |
{
"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"
}recording.failed
recording.status turns available and you receive recording.available (or call.updated if it was already sent).Values at this event
| Field | Type | Description |
|---|---|---|
| recording.status | string | Always "failed". |
{
"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
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.
call.member_ringing
click_to_call.member_ringing).The offer
| Field | Type | Description |
|---|---|---|
| offer.member | object | { id, name } of the team member being rung. |
| offer.attempt | integer | 1 for this member's first ring on this call, 2 for the next. |
| offer.ring_timeout_sec | integer | null | How long they will be rung. null when the ring did not say. |
| offer.kind | string | direct, menu, queue, transfer, merge, phone_bridge or campaign (a team calling campaign rang them). |
| offer.menu | object | null | { id, key }: the call menu and key that led here, or null. |
{
"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"
}call.member_missed
The offer
| Field | Type | Description |
|---|---|---|
| offer.result | string | no_answer, declined, busy or answered_elsewhere. The other offer fields are as on call.member_ringing. |
{
"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.
otp.sent
Values at this event
| Field | Type | Description |
|---|---|---|
| status | string | Always "queued". |
| verified | null | Not yet known. |
| expires_in_sec | integer | Seconds until the code expires. 600 (10 minutes) unless you set ttl on the send. |
| max_attempts | integer | Allowed verify attempts. |
{
"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"
}otp.verified
Values at this event
| Field | Type | Description |
|---|---|---|
| status | string | Always "verified". |
| verification_status | string | Always "verified". |
| verified | boolean | Always true. |
{
"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"
}otp.failed
Values at this event
| Field | Type | Description |
|---|---|---|
| status | string | Always "failed". |
| verified | boolean | Always false. |
| attempts_left | integer | How many verify attempts remain (1 or more). |
| max_attempts | integer | Allowed verify attempts. |
{
"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"
}otp.max_attempts
Values at this event
| Field | Type | Description |
|---|---|---|
| status | string | Always "max_attempts". |
| verification_status | string | Always "locked". |
| verified | boolean | Always false. |
| attempts_left | integer | Always 0. |
| max_attempts | integer | Allowed verify attempts. |
{
"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
| Field | Type | Description |
|---|---|---|
| object | string | Always Every key: events. Telephony API: every read toocall. |
| unique_id | string | The handle to poll and match on. The click to call id ( Every key: every read and eventc2c_...) 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). |
| call_id | string | Our record id for this call. Unique for every call. Every key: every read and event |
| leg_id | string | null | A second id of the same call (the phone leg), when the record is keyed on something else. Every key: every read and eventnull on most calls. Either id resolves on GET /calls/{id}. |
| click_to_call_id | string | null | The click to call this call belongs to ( Every key: every read and eventc2c_...), 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. |
| direction | string | inbound or outbound. |
| campaign_id | integer | 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_type | string | null | The kind of API run: Every key: events. Telephony API: every read tooaudio_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. |
| agent_id | integer | null | The AI voice agent on an AI call. Every key: Get call status and events. Telephony API: List calls toonull on calls your team handled. |
| reference_id | string | null | Your reference: the Every key: every read and eventreference_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. |
| metadata | object | null | The Every key: Get call status and events. Telephony API: List calls toometadata 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. |
| via_api | boolean | 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). |
Outcome
| Field | Type | Description |
|---|---|---|
| status | string | Where the call is: Every key: every read and eventqueued, ringing, in_progress, completed, missed or failed. Always paired with end_reason as shown in Status and end reasons. |
| duration_sec | integer | 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 Every key: every read and eventstarted_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. |
| end_reason | string | null | The closed reason: Every key: every read and eventcompleted, no_answer, busy, rejected, canceled, failed or voicemail. null while the call is live. |
| end_detail | string | null | The finer reason, from a closed list (see the end_detail table). Telephony APInull while the call is live. |
| ended_by | string | null | Who ended the call: Telephony APImember, 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). |
| network_cause | object | 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. |
| sip_status | integer | 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; Telephony APInull on every other lane. |
| handled_by | string | null | Who the caller ended with: Telephony APImember (a team member answered), ai_agent, voicemail (the caller left a message) or menu (a call menu key sent a WhatsApp message). null otherwise. |
| response | object | How the recipient responded on an interactive broadcast call, and whether the caller left a voicemail: Every key: events. Telephony API: every read too{ 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. |
People
| Field | Type | Description |
|---|---|---|
| member | object | 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. |
| assigned_member | object | 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. |
| customer_member | object | 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. |
Numbers
| Field | Type | Description |
|---|---|---|
| from_number | string | null | The caller as stored, unchanged. Its format varies ( Every key: every read and event0 and ten digits, 91 and ten digits, +91..., or ten digits): match on the last ten digits, or use customer_number and business_number. |
| to_number | string | null | The called number as stored, unchanged. Same formats as Every key: every read and eventfrom_number. |
| customer_number | string | null | The other party in E.164 ( Telephony API+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. |
| business_number | string | null | Your own number in E.164: the one the customer dialled (inbound) or saw (outbound). Telephony APInull 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). |
Times and durations
| Field | Type | Description |
|---|---|---|
| created_at | string | 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 Every key: reads. Telephony API: events too2026-10-12 06:28:29); use started_at in new code. |
| created_at_utc | string | The same instant, ISO 8601 with Every key: reads. Telephony API: events tooZ, to the second. |
| created_at_ist | string | The same instant at Every key: reads. Telephony API: events too+05:30, to the second. |
| started_at | string | When the call record began, ISO 8601 UTC with milliseconds. Its Telephony API_ist twin is the same instant at +05:30. |
| answered_at | string | 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 Telephony APIwait_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. |
| ended_at | string | null | When the call record closed. Telephony APInull 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. |
| talk_sec | integer | null | Whole seconds from Telephony APIanswered_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). |
| wait_sec | integer | null | Everything before the conversation (call menu, queue, ringing), and the whole record of a call nobody answered: from Telephony APIstarted_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). |
| hold_sec | integer | Time on hold placed from the panel, the apps or the API, in seconds. Telephony API0 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. |
Recording, outcome and routing
| Field | Type | Description |
|---|---|---|
| recording_available | boolean | true when recording.status is available. |
| recording_url | string | null | The address of the main recording file ( Telephony APIGET /calls/{call_id}/recording). Needs your keys. null unless the recording is available. |
| recording | object | The recording block: status, every part, the stereo layout and when it expires. See below. Telephony API |
| disposition | object | null | The outcome, note and callback your team saved for the call. See below. Telephony API |
| voicemail | object | null | The voicemail the caller left. See below. Telephony API |
| menu | object | 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. |
| ring_attempts | object[] | Every person or number the call rang, in order. Telephony API[] when none. See below. |
| transfers | object[] | Every hand-over of the call, in order. Telephony API[] when none. See below. |
| campaign | object | 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. |
Charge, transcripts and ordering
| Field | Type | Description |
|---|---|---|
| charge_inr | number | 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 Every key: Get call status and events. Telephony API: List calls too0; null while the call is live. |
| transcript_available | boolean | 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. |
| analysis_available | boolean | true when an AI call has its post call analysis. Always false for team calls. |
| version | integer | Goes up by exactly one every time the call's record changes. Keep the copy with the highest Telephony APIversion. 0 for a call unchanged since 13 October 2026. |
| updated_at | string | When that change was recorded, ISO 8601 UTC with milliseconds, with an Telephony API_ist twin. For a call unchanged since 13 October 2026, its ended_at (or started_at). |
| lane | string | How the call was made or reached you. A closed list; see the lane table. Telephony API |
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
| Field | Type | Description |
|---|---|---|
| status | string | Where the recording stands; see the recording status table. |
| revision | integer | 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). |
| url | string | null | The main file's address. null unless available. |
| format | string | null | ogg, wav, m4a or mp3, from the main file. null unless available. |
| size_bytes | integer | null | The main file's size. null unless available. |
| duration_sec | number | null | The 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. |
| channels | integer | null | 2 for a stereo recording, 1 for mono. null when not measured. |
| channel_layout | object | 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_days | integer | How long your plan keeps recordings, in days. |
| expires_at | string | 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. |
| parts | object[] | Every stored file of the call, the main one included. [] unless available. See the part table. |
| parts_ordered | boolean | 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). |
recording.status
| Value | Meaning |
|---|---|
| available | Stored and ready to download. recording_url and parts are set. |
| processing | Not 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). |
| failed | Expected and still missing 12 hours after the end (recording.failed is sent). A file that arrives later turns it to available. |
| not_recorded | This 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. |
| none | No 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. |
| off | Call recording is switched off on your account. |
| expired | Past expires_at: no longer available under your plan's retention. |
recording.parts[]
| Field | Type | Description |
|---|---|---|
| part | integer | 1, 2, 3 in the order of the list. |
| primary | boolean | true for the main file (the one recording_url serves). |
| segment | integer | null | The value to pass as ?segment= to download this part. null for the main file. |
| url | string | The part's download address, ready to use (needs your keys). |
| format, size_bytes, duration_sec, channels | mixed | As on the block, for this file. null when not measured. |
| started_at | string | null | When 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. |
| member | object | 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)
| Field | Type | Description |
|---|---|---|
| outcome | string | null | The outcome as saved: one of your account's outcomes, or interested / not_interested set automatically by an interactive call. |
| note | string | null | The note as your team saved it. |
| callback_at | string | null | When 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_at | string | null | When 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_by | object | null | { id, name, removed } of who marked it done. null while it is not done. |
| tagged_at | string | null | When the outcome was saved. |
| tagged_by | object | null | { id, name, removed } of the team member who saved it. null for an automatic outcome or one the phone app saved. |
| source | string | member (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)
| Field | Type | Description |
|---|---|---|
| left | boolean | Always true when the block is present. |
| duration_sec | integer | null | The message's length in seconds. |
| url | string | GET /calls/{call_id}/voicemail: the audio, with your keys. |
| created_at | string | null | When the message was left. |
| expires_at | string | null | When 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[]
| Field | Type | Description |
|---|---|---|
| kind | string | member (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. |
| member | object | null | { id, name, removed } for member and queue_offer. |
| number | string | null | The outside number in E.164, for number. null when it is one of your team members' own mobiles. |
| result | string | See the result table. |
| rang_sec | integer | null | How 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
| Value | Meaning |
|---|---|
| answered | This attempt was answered. |
| no_answer | It rang out. |
| busy | The team member was on another call, so they were not rung; on an outside number, the number was busy. |
| declined | The 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. |
| offline | The 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_break | The team member was on a break, so they were not rung. |
| answered_elsewhere | Another team member answered first. |
| stopped | Ringing stopped: the caller left, or someone else answered first. |
| skipped | The team member was skipped. |
| failed | The ring could not be placed. |
| other | Any other result. |
transfers[]
| Field | Type | Description |
|---|---|---|
| at | string | null | When the call was handed over. |
| kind | string | member (to a colleague), merge (a colleague joined the call), menu (into a call menu), number (to an outside number) or other. |
| from_member | object | null | { id, name, removed } of who handed it over. null when the AI voice agent did. |
| to_member | object | null | { id, name, removed } for member and merge. |
| to_menu | object | null | { id, name } for menu. |
| to_number | string | null | E.164, for number. null when it is one of your team members' own mobiles. |
| via_phone_bridge | boolean | true when the colleague was rung on their own mobile. |
| to_call_id | string | null | For 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. |
{ 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.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)
| Value | Meaning | Webhook event |
|---|---|---|
| queued | Accepted and waiting to be placed. | call.initiated |
| ringing | The call is being placed or is ringing: the recipient's phone, or, on an inbound call, your team. | call.ringing |
| in_progress | The conversation has begun: the customer answered your call, or your team member (or the AI voice agent) picked up an inbound one. | call.answered |
| completed | The call connected and has ended. | call.completed |
| missed | The 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 |
| failed | The 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
| From | To | When |
|---|---|---|
| queued | ringing | We handed the call to the network. An inbound call starts here. |
| ringing | in_progress | The conversation began: the customer answered, or your team member picked up an inbound call. |
| in_progress | completed | The call ended after being answered. end_reason is completed (or voicemail on an AI voice agent call a voicemail system answered). |
| queued, ringing | missed | It did not connect. end_reason is no_answer, busy, rejected or canceled. |
| queued, ringing | failed | It 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)
| Value | Meaning | With status |
|---|---|---|
| completed | The call connected and ran to its normal close: the clip finished, the interactive flow ended, or either side hung up. | completed |
| voicemail | AI voice agent calls only: a voicemail system answered. It was detected and the call was closed. | completed |
| no_answer | Nobody 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 |
| busy | The line was busy: the customer's, your team member's, or every line on your account. A retry can succeed. | missed |
| rejected | The call was declined: by the customer, or by your team member on an inbound call. | missed |
| canceled | The call ended before it connected: the caller left, your team member hung up, or a call menu ended with no valid choice. | missed |
| failed | The 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
| status | end_reason | Terminal event | end_detail values that land here |
|---|---|---|---|
| queued, ringing, in_progress | null | none yet | null |
| completed | completed | call.completed | connected, whatsapp_sent, machine_answered |
| missed | no_answer | call.no_answer | sent_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 |
| missed | canceled | call.no_answer | invalid_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 |
| missed | busy | call.busy | all_lines_busy, member_busy, customer_busy, other |
| missed | rejected | call.busy | member_declined, customer_rejected, other |
| failed | failed | call.failed | network_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)
| Value | Calls | Meaning |
|---|---|---|
| connected | Connected | The call connected. |
| whatsapp_sent | Connected | A call menu key sent the caller a WhatsApp message; there was no conversation. |
| machine_answered | Connected | An answering machine took a broadcast call. |
| sent_to_voicemail | Inbound | Nobody answered and the caller left a voicemail (see voicemail). |
| all_lines_busy | Inbound | Every line on your account was in use. The call was refused before it reached a call menu or a team member. |
| network_busy | Inbound | The phone network had no free line for the call. Refused before it reached a call menu or a team member. |
| number_not_set_up | Inbound | The number dialled has nothing set up to answer it. |
| outside_hours | Inbound | Outside your working hours. |
| closed_day | Inbound | A closed day, a holiday or a temporary closure. |
| invalid_menu_choice | Inbound | Reserved 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_choice | Inbound | The caller chose no option and the call menu ended: no key pressed, or only keys the call menu does not have. |
| team_unavailable | Inbound | Nobody the call could go to was available: every team member was busy, offline or on a break, so nobody was rung. |
| team_did_not_answer | Inbound | The team was rung and nobody answered (a call menu that rang team members who did not pick up or declined). |
| member_busy | Inbound | The team member was on another call. |
| member_declined | Inbound or outbound | The team member declined the call. |
| member_offline | Inbound | The team member was offline. |
| member_on_break | Inbound | The team member was on a break. |
| caller_left_while_ringing | Inbound | The caller hung up while a team member was being rung. |
| caller_left_on_hold | Inbound | The caller hung up while on hold. |
| caller_left_in_queue | Inbound | The caller hung up while waiting in the queue. |
| caller_left | Inbound | The caller hung up before anyone answered. |
| member_canceled | Outbound | Your team member ended the call before the customer answered. |
| member_not_reached | Outbound | The team member's own phone could not be reached. |
| member_no_answer | Outbound | The 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_failed | Outbound | The team member's app or browser could not join the call. |
| ended_before_answer | Outbound | The call ended before the customer answered (on a campaign call, the dialler stopped it). |
| customer_no_answer | Outbound | The 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_unreachable | Outbound | The customer's phone was switched off, out of coverage or did not respond. |
| customer_busy | Outbound | The customer's line was busy. |
| customer_rejected | Outbound | The customer declined the call. |
| invalid_number | Outbound | The number does not exist, or is incomplete. |
| cannot_take_calls | Outbound | The number cannot take this call (barred, or a service number). |
| canceled | Outbound | Your 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_failure | Either | A phone network fault stopped the call. |
| service_error | Either | A 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). |
| other | Either | Any 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)
| Value | Meaning |
|---|---|
| menu | An inbound call to a call menu (and a call moved into a call menu). |
| direct | An 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. |
| panel | A team member's call from the web Agent Panel or the app, over the internet. |
| app_agent | A call on a team member's own phone with the App Agent, synced afterwards. |
| phone_bridge | A 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. |
| sim | Call via SIM: the team member called from their own SIM while the customer saw your number. |
| campaign | A call of a dashboard campaign. |
| click_to_call | A call started with the Click to Call API. |
| api | A call placed through the API: an API run, or an API call outside any campaign. |
| ai_agent | An AI voice agent call. |
| fallback | A call carried on a fallback route. |
| other | Anything 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)
| Value | Meaning |
|---|---|
| member | Your 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. |
| customer | The customer or caller hung up, or their side refused the call (busy or declined). |
| api | Your 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. |
| system | We 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_agent | The AI voice agent ended the call. |
| null | Live, 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)
| code | name | Meaning |
|---|---|---|
| 1 | UNALLOCATED_NUMBER | The number does not exist. |
| 3 | NO_ROUTE_DESTINATION | The network has no route to the number. |
| 17 | USER_BUSY | The phone was busy. |
| 18 | NO_USER_RESPONSE | The phone did not respond (switched off or out of coverage). |
| 19 | NO_ANSWER | The phone rang and nobody answered. |
| 20 | SUBSCRIBER_ABSENT | The phone is not reachable. |
| 21 | CALL_REJECTED | The call was declined. |
| 22 | NUMBER_CHANGED | The number has changed. |
| 27 | DESTINATION_OUT_OF_ORDER | The phone is out of service. |
| 28 | INVALID_NUMBER_FORMAT | The number is incomplete or malformed. |
| 29 | FACILITY_REJECTED | The network refused the call. |
| 31 | NORMAL_UNSPECIFIED | The network ended the call without a reason. |
| 34 | NORMAL_CIRCUIT_CONGESTION | The network was congested. |
| 38 | NETWORK_OUT_OF_ORDER | The network was out of order. |
| 41 | NORMAL_TEMPORARY_FAILURE | A temporary network failure. |
| 42 | SWITCH_CONGESTION | The network was congested. |
| 44 | REQUESTED_CHAN_UNAVAIL | No line was available on the network. |
| 52 | OUTGOING_CALL_BARRED | Calls of this kind are barred. |
| 54 | INCOMING_CALL_BARRED | The number does not accept calls. |
| 57 | BEARERCAPABILITY_NOTAUTH | The number cannot take this kind of call. |
| 79 | SERVICE_NOT_IMPLEMENTED | The number cannot take calls (a service number, or blocked by its network). |
| 88 | INCOMPATIBLE_DESTINATION | The number cannot take this kind of call. |
| 102 | RECOVERY_ON_TIMER_EXPIRE | The network timed out. |
| 111 | PROTOCOL_ERROR | A network signalling error. |
| 127 | INTERWORKING | A 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.
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_status | Means | Note |
|---|---|---|
| queued | queued | Same meaning. |
| ringing | ringing | Same meaning. |
| answered | in_progress | The same state under an older name. |
| completed | completed | Same meaning. |
| failed | missed or failed | This 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. |
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.
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
| Identifier | What it is | Where you get it | What you poll with | In webhooks |
|---|---|---|---|---|
| unique_id | The 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 id | The 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_id | A 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 id | One 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_id | Our 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_id | A 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_id | Your 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-Key | Your 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
| Identifier | What it is | Where you get it | What you poll with | In webhooks |
|---|---|---|---|---|
| event id | One 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 id | One 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. |
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.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:
| Field | Type | Description |
|---|---|---|
| object | string | Always "recording". |
| unique_id | string | The call's public id, the same value Get call status returns and the call events carry. |
| call_id | string | Our record id for the call this recording belongs to. |
| leg_id | string | null | The same second id the call object carries, or null. Match on unique_id. |
| click_to_call_id | string | 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_url | string | 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. |
| format | string | The audio format of the main file: usually "ogg", else "wav", "m4a" or "mp3". |
| duration_sec | integer | null | The main file's own length in seconds, rounded, when it has been measured; otherwise the call's duration_sec. |
| size_bytes | integer | null | The main file's size in bytes. |
| campaign_id | integer | null | The campaign or API run the call belongs to; for an AI voice agent API campaign, the campaign you triggered. null otherwise. |
| campaign_type | string | null | audio_blast, press1, otp or ai_agent: the same value the call events carry. |
| reference_id | string | null | Your correlation key, the same value the call events carry. |
| metadata | object | null | The metadata you sent when you placed the call through the API (a number comes back as text). null otherwise. |
| via_api | boolean | 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:
| Field | Type | Description |
|---|---|---|
| version, updated_at | integer, string | The call's version and updated_at at this event. Apply it only when the version is higher than the one you hold. |
| status | string | Always available on this event. |
| revision | integer | 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). |
| channels | integer | null | 2 for a stereo recording, 1 for mono. null when not measured. |
| channel_layout | object | 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_days | integer | How long your plan keeps recordings, in days. |
| expires_at | string | 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. |
| parts | object[] | Every stored file of the call, the main one included. [] unless available. See the part table. |
| parts_ordered | boolean | 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). |
| call | object | The whole call object at this version, so one event carries the call and its recording. |
{
"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"
}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.
| Field | Type | Description |
|---|---|---|
| object | string | Always "verification". |
| request_id | string | The verification request id returned by Send a code. |
| number | string | The recipient's number in E.164 form. Example: +919812345678 |
| status | string | queued on otp.sent, verified on otp.verified, failed on otp.failed, max_attempts on otp.max_attempts. |
| verification_status | string | 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. |
| verified | boolean | null | null on otp.sent, true on otp.verified, false on otp.failed and otp.max_attempts. |
| attempts_left | integer | null | Remaining verify attempts. Present on otp.failed (1 or more) and otp.max_attempts (0). |
| expires_in_sec | integer | null | Seconds until the code expires. Present on otp.sent.Example: 600 |
| max_attempts | integer | null | Allowed verify attempts. Present on otp.sent, otp.failed and otp.max_attempts. |
| campaign_id | integer | null | The delivery run, if any. |
| reference_id | string | 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 response | What we do |
|---|---|
2xx | Marked delivered. No further attempts for this event. |
3xx | Not followed. Counted as a failed attempt and retried, so a signed body is never forwarded to another host. |
4xx or 5xx | Counted as a failed attempt and retried, for up to nine attempts over about 20 hours. |
| No reply within 6 s | Counted as a failed attempt and retried. |
| Connection error | Counted 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.
| Attempt | Sent after the previous attempt | Note |
|---|---|---|
| 1 | Immediately | As soon as the event is generated. |
| 2 | 0.5 seconds | |
| 3 | 2 seconds | End of the fast path. |
| 4 | 1 minute | |
| 5 | 5 minutes | |
| 6 | 30 minutes | |
| 7 | 2 hours | |
| 8 | 6 hours | |
| 9 | 12 hours | The last attempt, about 20 hours 36 minutes after the first. After this the delivery is marked failed. |
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_sincereturns 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:
| Column | What it tells you |
|---|---|
| Event | The event name. |
| Result | Delivered 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. |
| Tries | How many attempts have been made so far, out of nine. |
| When (IST) | When the event was generated, in Indian Standard Time. |
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 itsidbefore. If one endpoint of yours is behind another, de-duplicate onX-Agentive-Delivery-Idinstead, which is unique per endpoint. - Ordering is not guaranteed. Events may arrive out of order, and the retry tail widens the gap: a
call.answeredyour endpoint refused could land hours after thecall.completedit accepted. - Apply only a higher version. Every team-call event carries
data.version, which goes up by one with every change to the call. Percall_id, keep the version you hold and apply an event (or a read) only when itsversionis higher. An equal version carries the same facts; only a team member's or a call menu's current name can differ.voicemail.leftcan carry the sameversionas the terminal event before it: store the call by this rule, but act on the event itself by its type andid. Without the Telephony API, and on AI voice agent calls, order by the envelope'screatedand thestatusfield 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), thencall.answeredandcall.completedif it connects, or one ofcall.no_answer,call.busyorcall.failedif it does not; thenrecording.availableonce the recording is complete, andcall.taggedwhen 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-Keyheader, 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.completedto 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:
{
"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"
}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 is2026-06-01. - We may add new fields to the envelope or to any
dataobject 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
typeand 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-V2on 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
idbefore you act on an event, so a retry changes nothing. Check age against the signedt, never againstX-Agentive-Timestampalone. - 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
versionis higher than the one you hold; act onvoicemail.leftby its type andid, 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.
- Add an endpointIn the Voice dashboard, open Webhooks, add your
https://URL and copy the signing secret into an environment variable such asAGENTIVE_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). - Deploy a receiverStart from one of the example handlers. It must read the raw body, verify the signature in constant time and return 200 within 6 seconds.
- Send a test eventClick 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.
- Place a real call to your own numberUse 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 samedata.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" }' - Store the event id and reconcilePersist each
idbefore 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
The events on this page describe calls and verification codes created through the Voice APIs. WhatsApp message delivery has its own webhook, documented with the WhatsApp Business API.
Send approved WhatsApp template messages with media and buttons from your own systems, tag contacts, and get delivery status on a webhook.
Read the referencePlace recorded voice calls, trigger a saved campaign for one number, poll call status, list calls and download recordings.
Read the referenceConnect your team member and a customer from your CRM or app: we ring your team member first, then the customer, with live status, call control and signed events.
Read the referenceHave your AI voice agent call a customer from your own code, pass the details it should use, and get the transcript, analysis and recording back.
Read the referenceRead a one-time code out to a customer over a phone call and verify it, with expiry and attempt limits handled for you.
Read the reference