Voice Broadcast API
Voice Broadcast API
Place recorded and Interactive Voice calls, trigger saved campaigns, and read call results from your own systems over a JSON REST API.
- Base URL
- https://api.agentive.co.in/api/public/v1
- Format
- JSON over HTTPS
- Auth
- x-api-key + x-api-secret
Introduction
The Voice Broadcast API gives your application programmatic access to the same calling stack that powers the dashboard. Place a single recorded or Interactive Voice call, run a saved campaign for one number, poll the result of any call you started, page through your call history, and download recordings. With the Telephony API it also reads every call your team makes and takes, as a complete call record you can keep in sync with a change feed.
Every amount is in Indian Rupees (INR). Every timestamp is in Indian Standard Time (IST), in ISO 8601 format. Every request is authenticated with a publishable key and a secret, and every response uses one consistent JSON envelope so your integration code stays simple.
When to use it
- Send an order confirmation, a delivery alert or a payment reminder as a recorded voice call straight from your backend.
- Run an Interactive Voice call (press 1) and act on the key the recipient presses, or bridge them to your team.
- Trigger a campaign configured in the dashboard for one number at a time, from a CRM, a form submit or a workflow tool.
- Reconcile results: poll a call, list calls in bulk, download the recording, and check your balance before a large run.
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.
Base URL
Every endpoint path on this page is relative to this base URL. The Voice OTP API uses the same base.
https://api.agentive.co.in/api/public/v1Since 17 October 2026 the API has its own host, api.agentive.co.in, which answers only the API and only over HTTPS. https://voice.agentive.co.in/api/public/v1 keeps working with the same keys and the same answers, and the samples on this page that use it work unchanged on either host. Use api.agentive.co.in when your key has an address list: there we see your server's own address exactly. The API host has an IPv4 address only.
Authentication
Every request must be authenticated with two credentials issued to your account.
| Credential | What it is | How to send it |
|---|---|---|
| Publishable key | Names your account on every request. Starts with pk_live_. Despite the name, treat it as confidential and keep it with the secret. | x-api-key request header |
| Secret key | Your account's private proof. Starts with sk_live_. Treat it like a password. | x-api-secret request header (preferred), or the HTTP Basic password (below). A secret field in the JSON body is refused by the Click to Call API and deprecated here (since 17 October 2026, below). |
View and rotate both keys from the API tab in your Voice dashboard. The secret is shown in full exactly once, when it is first generated or rotated. It is stored hashed on our side, so it can never be shown again, by you or by us. If you lose it, rotate to get a new one.
When you rotate you choose what happens to the old secret:
- Stop the old secret now (the default). You get a new publishable key and a new secret, and the old pair stops working at once. Use this if the secret may have leaked.
- Keep the old secret working for 24 hours, so you can move your servers to the new secret without a gap. Your publishable key stays the same; only the secret changes, so the one value to update is the secret. For 24 hours your key works with either secret. Only one previous secret is ever kept: rotating again ends the first grace at once. While the grace runs the API tab shows when it ends, with a Stop it now button.
The API tab also shows when your key was last used (to the minute).
The header form is recommended because it keeps the secret out of request bodies and most log formats. If you send the secret in both the header and the body, the header value is used, except on the Click to Call API, which refuses a body secret even then. There is a single set of live credentials per account; both keys begin with a _live_ prefix and every call is processed against your live account.
The secret in the request body
Since 17 October 2026. Request bodies are often written to logs by CRMs, monitoring tools and retry queues, so:
- The Click to Call API endpoints (
/click-to-call,/members,/call-menusand everything under them) refuse asecretfield in the JSON body with HTTP 400,error_codevalidation_error,fieldsecret,retryablefalse, even when thex-api-secretheader is sent too. Send the secret in thex-api-secretheader or as the HTTP Basic password; both keep working there. - Every other endpoint, those on this page included, still accepts it, and its response then carries the header
Deprecation: @1792175400(17 October 2026, RFC 9745). Move the secret to the header; a body that carries nosecretgets no such header.
Example: authenticated request
curl https://voice.agentive.co.in/api/public/v1/calls \
-H "x-api-key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "x-api-secret: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "type": "audio_blast", "number": "9812345678", "campaign_id": 4821 }'HTTP Basic authentication
As an alternative to the two headers, you may send the credentials with HTTP Basic auth, using the publishable key as the username and the secret as the password. This is the familiar curl -u form. When an x-api-key header is present it takes precedence; otherwise the Basic credentials are used.
curl https://voice.agentive.co.in/api/public/v1/account \
-u pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx:sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxhttps://. Since 17 October 2026 api.agentive.co.in refuses a plain HTTP request with HTTP 403 and error_code https_required and never redirects it, because by the time a redirect is answered your request (and your secret) has already crossed the network unencrypted. voice.agentive.co.in still redirects plain HTTP to HTTPS, so a request sent there over http:// has also already crossed the network in clear: never call either host over http://. If you ever sent your secret over plain HTTP, to either host, rotate it. If a key is exposed, rotate it from the dashboard at once. To make a leaked key useless anywhere else, list your servers' addresses (below).Restrict your key to your servers' addresses
Since 17 October 2026 you can list up to 10 IPv4 or IPv6 addresses or ranges (for example 49.36.10.20 or 49.36.10.0/24) under Allowed addresses on the API tab. A list takes effect once we check address lists: until then the card says "Address lists are not being checked right now." and your key is accepted from any address. While lists are checked, a key with a list is accepted only from those addresses; with an empty list (the default) it is accepted from any address.
- The list is checked after your key and secret. A wrong secret is still answered
401 invalid_credentials, whatever the list says. - It covers every endpoint, recording and voicemail downloads included, except playing a recording link: the link is created only from a listed address and plays from any device (see Play a recording link).
- A request from any other address is refused with HTTP 403 and
error_codeip_not_allowed;detailsnames the address we saw, so you can add it. A request whose address we could not confirm is refused the same way and names no address: callhttps://api.agentive.co.in/api/public/v1from your server. An address shared by many customers' web services (such as the addresses of our own dashboard's web service) is never confirmed and cannot be listed: list your own server's address. - Private, local and very wide ranges are not accepted: use /8 or narrower for IPv4, /16 or narrower for IPv6. The list stays in force when you rotate your secret.
- The API host has an IPv4 address only: list your server's public IPv4 address.
{
"status": "error",
"code": 403,
"unique_id": null,
"reference_id": null,
"details": "This API key is not allowed from your address (203.0.113.9). Add it under Allowed addresses in API Access, or call from an allowed server.",
"error_code": "ip_not_allowed",
"error": "This API key is not allowed from your address (203.0.113.9). Add it under Allowed addresses in API Access, or call from an allowed server."
}Authentication failures
| Status | Code | error_code | When |
|---|---|---|---|
| 401 | 401 | missing_credentials | No publishable key sent.details: "Missing API key. Send your publishable key in the x-api-key header." |
| 401 | 401 | invalid_credentials | Unknown publishable key.details: "Invalid API credentials." |
| 401 | 401 | invalid_credentials | Known key, wrong or missing secret.details: "Invalid API credentials." |
| 403 | 403 | account_inactive | Account is not active.details: "This account is not active. Please contact support." |
| 403 | 403 | api_disabled | API access not enabled for the account.details: "The API is not enabled for this account. Please contact support." |
| 403 | 403 | feature_disabled | The endpoint's product is not enabled for the account.details: "This feature is not enabled for your account." |
The wording and the status are intentionally the same for an unknown key and a wrong secret, so a caller cannot learn whether a key exists by watching which code comes back. 401 always means the credentials were rejected; 403 means the credentials were accepted and the account or the product is not entitled, or (while address lists are checked) the calling address is not on the key's list (ip_not_allowed). The one exception is https_required: a plain HTTP request to api.agentive.co.in is refused with 403 before its credentials are read.
Response format
Every response is JSON and uses one consistent envelope.
{
"status": "success",
"code": 200,
"unique_id": "run_4821",
"reference_id": "order-99213",
"details": "Call queued."
}Envelope fields
| Field | Type | Description |
|---|---|---|
| status | string | "success" or "error". |
| code | number | A numeric result code. Mirrors the HTTP status (see Error codes). |
| unique_id | string | null | Our identifier for the resource created by this call. Use it with Get call status. |
| reference_id | string | null | Echoes the reference_id you sent, so you can correlate the response with your own records. null if you did not send one. |
| details | string | A short human-readable description of the result. |
| error_code | string | Error responses only. A stable machine string naming the exact condition. Branch on this rather than on details. See Error codes. |
| error | string | Error responses only. The same sentence as details, under the key the WhatsApp Business API uses, so one handler can read both products. |
Successful responses may include extra fields alongside the envelope. These are documented per endpoint (for example call_status and duration_sec on Get call status, and data plus pagination on the list endpoints).
status: "success". A failed request returns the matching HTTP error status (400, 401, 402, 403, 404, 409, 415, 422, 429, or 5xx) with status: "error", and the same value in the code field. A body that is not valid JSON answers 400, and a body that is not UTF-8 or uses an encoding we cannot read answers 415, both as JSON with error_code validation_error (since 17 October 2026; before, an HTML page). Since 17 October 2026 every answer carries Cache-Control: no-store (a recording or voicemail download, and a recording link, private, no-store).Error codes
Every error carries three things: the HTTP status, the numeric code that mirrors it, and a string error_code naming the exact condition. Branch on error_code. The numeric code is kept for compatibility and the sentence in details (repeated in error) is for your logs, never for a customer.
| HTTP | Meaning | When it happens |
|---|---|---|
| 200 | Success | The request was accepted. |
| 400 | Bad request | A required field is missing or invalid (a malformed number, an unknown type, a missing campaign_id, a campaign with no recording, or a supplied code that is not 4 to 8 digits), or the body is not valid JSON (since 17 October 2026, a JSON error; before, an HTML page). |
| 401 | Unauthorized | The credentials were rejected: no key, an unknown key, or a wrong secret. On POST /otp/verify it also reports an incorrect code. |
| 402 | Balance too low | Your balance cannot cover the call. Nothing was created. Top up and retry. |
| 403 | Forbidden | The credentials were accepted but the account is not active, API access is not enabled, the endpoint's product is not enabled, or the key's address list does not include the calling address (ip_not_allowed, while address lists are checked). Also a request that came over plain HTTP to api.agentive.co.in (https_required, since 17 October 2026). |
| 404 | Not found | The campaign, call or verification does not exist for your account, or the call has no recording. A foreign id is a 404, never a 403. |
| 409 | Conflict | Outside calling hours, or a request with the same Idempotency-Key is still in flight, or the account's AI channels are all busy. Every 409 carries Retry-After. |
| 415 | Unsupported body | The request body is not in UTF-8, or uses a Content-Encoding we cannot read: send it uncompressed, or gzip or deflate compressed (error_code validation_error; a JSON error since 17 October 2026, before an HTML page). |
| 422 | Idempotency key reuse | The same Idempotency-Key was sent with a different request body. A new request needs a new key. |
| 429 | Too many requests | A limit was hit: your request budget, a per-number cap, a daily cap, or your account's lines. Every 429 carries Retry-After. |
| 502 | Upstream problem | We could not place the call. If we do not know whether it went out, error_code is call_state_unknown. |
| 503 | Temporarily unavailable | Briefly unavailable on our side. Safe to retry after Retry-After. |
| 503 | Phone network busy | error_code network_busy, retryable true, Retry-After: 15. Every line of the phone network your calling number uses is in use right now, so nothing was placed, no run was created and nobody was rung. Retry after the pause with the same Idempotency-Key. Can be answered by POST /calls, POST /campaigns/{id}/trigger, POST /otp/send, POST /ai/calls and POST /click-to-call: handle it like any retryable refusal. |
error_code values
A closed set. New values are added only with a note in the changelog, so a client may treat an unknown one as a generic failure of its HTTP class.
| error_code | HTTP | Means |
|---|---|---|
| missing_credentials | 401 | No publishable key was sent. |
| invalid_credentials | 401 | The key is unknown, or the secret does not match it. |
| account_inactive | 403 | The account is not active. |
| api_disabled | 403 | API access is not enabled for the account. |
| feature_disabled | 403 | The product this endpoint belongs to is not enabled. |
| validation_error | 400, 422 | A field is missing, unknown or unusable. |
| invalid_number | 400 | The destination is not a valid Indian mobile number, or (since 17 October 2026) carries another country code. |
| invalid_caller_id | 400 | caller_id is not yours, or is not enabled for voice broadcast. |
| invalid_code | 400 | A supplied verification code is not 4 to 8 digits. |
| calling_hours | 409 | Outside the 9:00 AM to 9:00 PM IST window. |
| idempotency_in_progress | 409 | The first request with this key is still running. |
| idempotency_conflict | 422 | This key was used with a different body. |
| rate_limited | 429 | Your per-minute request budget is spent. |
| number_flood | 429 | Too many calls to one destination number. |
| daily_cap | 429 | POST /ai/calls only (AI Voice Agent API): the calling pool numbers you call from reached their daily limit. Placing a call here never answers it. |
| concurrency_limit | 429 | Your account has no free line. |
| ai_concurrency_limit | 409 | Your AI call channels are all busy. |
| whatsapp_locked | 403 | The campaign sends a WhatsApp message and WhatsApp is not on your plan. |
| whatsapp_not_connected | 409 | No WhatsApp account is connected to this account yet. |
| whatsapp_template_required | 400 | The campaign has no WhatsApp account and approved template saved on it. |
| number_locked | 429 | Too many wrong codes for this number; send and verify are locked for it. |
| insufficient_balance | 402 | Your balance cannot cover the call. |
| not_found | 404 | No such resource on your account. |
| recording_expired | 404 | The recording passed your plan's retention and is no longer available. |
| voicemail_expired | 404 | The voicemail passed your retention and is no longer available. |
| invalid_cursor | 400 | A cursor sent with different filters, or one that is not ours. |
| updated_since_too_old | 400 | updated_since is earlier than the start of the change feed. |
| conflict | 409 | A state conflict with no more specific name. Read details and Retry-After. |
| upstream_error | 502 | We could not place the call, and it was not placed. |
| call_state_unknown | 502 | We asked the network to place the call and lost track of it. |
| service_unavailable | 503 | Briefly unavailable on our side, or your calling-hours setting could not be read (retry_after_sec 30); nothing was placed. |
| network_busy | 503 | Every line of the phone network your calling number uses is in use. Nothing was placed; retry after Retry-After (15 seconds). |
| ip_not_allowed | 403 | Your key has an address list and the calling address is not on it, or we could not confirm the calling address. See Restrict your key. Sent only while address lists are checked (a list can be saved since 17 October 2026). Carries no retryable field: retrying from the same place cannot succeed. |
| https_required | 403 | The request came over plain HTTP to api.agentive.co.in. Use https://, and rotate your secret if it was sent over plain HTTP. Carries no retryable field. Since 17 October 2026. |
| recording_converting | 503 | The MP3 or WAV copy is still being made (or waiting for its turn). Retry after the Retry-After seconds (retryable: true). Since 17 October 2026. |
| conversion_failed | 500 | This recording cannot be converted to the format asked. Retrying will not help (retryable: false): omit format to download the file as stored. Since 17 October 2026. |
| invalid_link | 401 | A recording link that is not ours, or was changed. Since 17 October 2026. |
| link_expired | 403 | The recording link is past its expiry. Create a new link. Since 17 October 2026. |
| link_revoked | 403 | The API secret that created the link no longer works (rotated without a grace, its grace ended, or revoked). Create a new link. Since 17 October 2026. |
Five more appear only on POST /otp/verify: incorrect_code, max_attempts, code_expired, code_used and verification_not_found.
The split between 429 and 5xx matters for retry logic. A 429 means a limit was hit, so wait for Retry-After. A 502 or 503 means a problem on our side, so a retry after a short pause is right, with one exception: call_state_unknown means we do not know whether the call went out, so poll before you retry. Error responses never include internal infrastructure detail.
Example error response
{
"status": "error",
"code": 400,
"unique_id": null,
"reference_id": "order-99213",
"details": "A valid Indian mobile number is required.",
"error_code": "invalid_number",
"error": "A valid Indian mobile number is required."
}Rate limits
Nine limits protect the shared calling network. Each one refuses with HTTP 429, names itself in error_code, and says how long to wait in both the Retry-After header and the body's retry_after_sec.
| Limit | Window | Scope | error_code | Retry-After |
|---|---|---|---|---|
| 240 failed requests | 1 minute | Client address | rate_limited | Up to 60 seconds. Only requests whose keys are rejected count, so a working integration never meets it. Since 17 October 2026 a request with valid keys is not refused because of other callers' rejected requests, except while one network address sends more than 24,000 rejected requests a minute. Also 2,400 a minute per network address. |
| 20 failed credential checks | 1 minute | Publishable key and client address | rate_limited | Up to 60 seconds. Guards a key against someone guessing its secret. A request with the correct secret is always let through, so nobody can lock your integration out. |
| 120 read requests | 1 minute | Account | rate_limited | Up to 60 seconds. |
| 120 write requests | 1 minute | Account | rate_limited | Up to 60 seconds. Counted separately from reads, so a polling loop can never starve call placement. |
| 120 recording and voicemail downloads | 1 minute | Account | rate_limited | Up to 60 seconds. Counted apart from the reads, so copying recordings never starves call polling. Since 17 October 2026 a download in MP3 or WAV (format) and creating a recording link count here too (never in the budget of the requests that place calls). |
| 600 recording link plays | 1 minute | Account | rate_limited | Playing a recording link counts apart from your downloads (since 17 October 2026). A browser makes a request when it loads a file and another on every seek, so a page that lists many recordings should use preload="none" on its players. |
| 240 refusals of a key whose secret matched | 1 minute | Key | rate_limited | Since 17 October 2026. Counts requests refused after the key and secret were checked: the account is not active, its API access is not enabled, or (while address lists are checked) the calling address is not on the key's list. These are not counted in the failed-request limit by address. |
| 3 calls to one number | 10 minutes | Account and destination number | number_flood | Up to 600 seconds. |
| Your lines | While calls are live | Account | concurrency_limit | 5 seconds. |
The RateLimit-* headers on a response describe the per-account bucket for that request's method: a GET reports the read bucket, a POST the write bucket. The X-RateLimit-* headers carry the same three values under the older names, so use whichever your client already reads.
RateLimit-Limit: 120
RateLimit-Remaining: 117
RateLimit-Reset: 41
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 41When you exceed a request limit you receive HTTP 429 with:
{
"status": "error",
"code": 429,
"unique_id": null,
"reference_id": null,
"details": "Too many requests. Please slow down and retry shortly.",
"error": "Too many requests. Please slow down and retry shortly.",
"error_code": "rate_limited",
"retry_after_sec": 60
}Click to call controls (hang up, keypad, hold, unhold and transfer) have their own budget of 120 a minute per account (since 17 October 2026), counted apart from starting a click to call, so keypad tones on many live calls never stop you placing the next one; see the Click to Call API. An address that keeps sending recording links that are not ours is slowed down with HTTP 429. Converting recordings to MP3 or WAV is also bounded by a queue of its own, apart from these budgets (see MP3 and WAV); a full queue never delays a download without format.
Your lines
A line is one call your account can have live at the same time. It is the number you bought, and everything on the account draws from it: inbound calls, calls your team makes, campaign dials, AI calls and every call you place through this API. Read it any time from Get account balance, which returns lines and lines_in_use. Responses to call-placing requests (POST /calls, POST /campaigns/:id/trigger and POST /otp/send) also carry X-Agentive-Lines and X-Agentive-Lines-In-Use, whether the call was admitted or refused, so a run can pace itself without an extra request. The read endpoints do not send them.
Since 17 October 2026 a call a team member places over the internet (the dashboard, the apps, a click to call) counts too; before, only their Phone Bridge calls (two lines) and Call via SIM calls (one line) counted. A call you place with Place a call, Trigger a saved campaign or Send a verification code holds its line from the request 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, as before.
A call your account has no free line for is refused, never queued: HTTP 429 with error_code: "concurrency_limit", lines, lines_in_use and a Retry-After of 5 seconds. That way you always know what happened, instead of waiting on a call that was silently parked.
X-Agentive-Lines: 10
X-Agentive-Lines-In-Use: 2HTTP/1.1 429 Too Many Requests
Retry-After: 5
X-Agentive-Lines: 10
X-Agentive-Lines-In-Use: 10
{
"status": "error",
"code": 429,
"unique_id": null,
"reference_id": "order-99213",
"details": "All 10 lines on this account are in use. Retry in a few seconds.",
"error": "All 10 lines on this account are in use. Retry in a few seconds.",
"error_code": "concurrency_limit",
"lines": 10,
"lines_in_use": 10,
"retry_after_sec": 5
}queued has been accepted and is waiting only for the network to place it. It is never waiting for a free line, because a request with no free line is refused before anything is created. So queued always means the call is on its way.AI voice agent calls carry a second, narrower cap inside your lines, reported with HTTP 409 and error_code: "ai_concurrency_limit". See the AI Voice Agent API.
error_code: "number_flood". A 429 always means wait; only 502 and 503 are safe to retry straight away.POST /calls with type: "otp" is the same request as Send a code and is held to the verification limits as well: at least 30 seconds between two sends to one number, at most 10 in 24 hours, and a number lock after 10 wrong codes in an hour. They are listed in full on the Voice OTP page.Endpoints
The write endpoints place a call and trigger a saved campaign. The read endpoints fetch a single call's status, list your calls, download a recording, list your campaigns, and report your account balance.
| Endpoint | Purpose |
|---|---|
| POST /calls | Place a recorded, Interactive Voice or verification call to one number. |
| POST /campaigns/:id/trigger | Run a saved campaign for one number. |
| GET /calls/:unique_id | Poll the status of a call you placed. |
| GET /calls | Page through your call history with filters. |
| GET /calls/:unique_id/recording | Download a call recording, or one of its parts. |
| GET /calls/:unique_id/voicemail | Download the voicemail a caller left (Telephony API). |
| POST /calls/:unique_id/recording-link | Create a 10-minute link a browser plays without your keys. |
| GET /recording-links/:token | Play a recording link, with no key. |
| GET /calls/:unique_id/transcript | Read a transcribed team call (Telephony API with call transcription). |
| GET /campaigns | List the campaigns you can trigger. |
| GET /account | Read your balance in INR, your lines and your products. |
Place a call
/callsPlace a single outbound call immediately. The type field selects what happens on the call: audio_blast plays a clip from your audio library and ends, press1 plays a clip and then acts on the key the recipient presses, and otp reads a verification code out to the recipient. The response is the standard envelope with unique_id set to the queued call's id.
Headers
| Header | Type | Required | Description |
|---|---|---|---|
| x-api-key | string | Required | Your publishable key ( pk_live_...). See Authentication. |
| x-api-secret | string | Required | Your secret key ( sk_live_...). Keep it server-side. |
| Content-Type | string | Required | Always application/json. |
| Idempotency-Key | string | Optional | A key unique to this logical request, 1 to 128 visible ASCII characters. A longer key is refused with HTTP 400. Send one on every request so a network retry can never place a second billed call. See Idempotency. Example: order-99213-call-1 |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| type | string | Required | Example: audio_blast |
| number | string | Required | The recipient's Indian mobile number. See Phone number format. Example: 9812345678 |
| campaign_id | number | Required | Which campaign this call is for. Required for audio_blast and press1, and it must be a campaign of that same type on your account. The campaign holds the recording, the caller number, what each keypress does and every other setting; your request supplies the number to call. Optional for otp, where omitting it uses your account's authentication campaign.Example: 412 |
| code | string | Optional | otp only. Supply your own code: 4 to 8 digits, nothing else. Anything shorter, longer or non-numeric is refused with HTTP 400 and invalid_code. If you omit it, a code is generated for you. |
| length | number | Optional | Not accepted with otp: the code length is set on your authentication campaign. Sending it answers 400 validation_error. |
| ttl | number | Optional | Not accepted with otp: how long the code stays valid is set on your authentication campaign. Sending it answers 400 validation_error. |
| max_attempts | number | Optional | otp only. Verify attempts allowed for this code. Default 3. Values outside 1 to 10 are clamped into range. |
| message | string | Optional | Not accepted with otp: the spoken message is set on your authentication campaign. Sending message, length, ttl or caller_id with otp answers 400 validation_error. |
| reference_id | string | Optional | Your own correlation key. Echoed back and included in webhooks. See Reference IDs. Example: order-99213 |
Request
curl 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" \
-H "Idempotency-Key: order-99213-call-1" \
-d '{
"type": "audio_blast",
"number": "9812345678",
"campaign_id": 4821,
"reference_id": "order-99213"
}'Response (audio_blast and press1)
{
"status": "success",
"code": 200,
"unique_id": "run_4821",
"reference_id": "order-99213",
"details": "Call queued."
}Errors
| Status | Code | error_code | When | What to do |
|---|---|---|---|---|
| 400 | 400 | invalid_number | number is missing, malformed, or not an Indian mobile number. A number with too many digits is refused this way too (since 17 October 2026; before, its last ten digits were dialled).details: "A valid Indian mobile number is required." | Send a 10-digit mobile number beginning with 6, 7, 8 or 9. See Phone number format. |
| 400 | 400 | invalid_number | number carries another country code, for example +44 or 00977 (since 17 October 2026; before, its last ten digits were dialled, which could call an unrelated number).details: "Only Indian numbers can be called." | Send an Indian mobile number; see Phone number format. |
| 400 | 400 | validation_error | type is unknown, campaign_id is missing on a audio_blast or press1 call, the campaign has no recording yet, or the request tries to set something the campaign owns. | Use one of the three call types and name a campaign of that type. Change the recording, the caller number or what a keypress does on the campaign itself. |
| 404 | 404 | not_found | The campaign_id is not on your account, or the campaign has been deleted. Deleting a campaign stops every call for it, on this endpoint and on the trigger endpoint alike.details: "Campaign not found." | Check the id in your dashboard. If you deleted the campaign, create it again and use the new id. |
| 400 | 400 | validation_error | The campaign is switched off. Pausing or stopping a campaign stops every call for it. A campaign sitting in draft or completed is normal for API use and keeps working.details: "That campaign is paused. Start it again in your dashboard before placing calls for it." or the same wording for a stopped campaign. | Start the campaign again in your dashboard, then resend. |
| 400 | 400 | validation_error | The campaign's recording has been deleted since it was set up. We refuse rather than accept a call that would go out silent.details: "The recording this campaign plays is no longer in your audio library." | Add a recording to the campaign, then place the call. |
| 400 | 400 | invalid_caller_id | What the campaign picked has stopped being usable since it was set up. We refuse rather than call from some other number without telling you.details: "The number this campaign calls from is no longer available for voice broadcast on your account." or "The rotational pool this campaign uses is not available on your account any more." | Open the campaign, pick a caller number or a rotational pool again, and resend. |
| 400 | 400 | invalid_code | type: "otp" with a code that is not 4 to 8 digits. | Send 4 to 8 digits, or omit code and let one be generated. |
| 401 | 401 | invalid_credentials | The publishable key is unknown, or the secret does not match it.details: "Invalid API credentials." | Check both headers. Before September 2026 a known key with a wrong secret returned 403; it now returns 401 like every other credential failure. |
| 402 | 402 | insufficient_balance | Your balance is below the minimum needed to place a call. Checked before anything is created, so nothing was queued and nothing was charged. The body carries balance_inr and minimum_balance_inr. From September 2026 that minimum is this call's own per-call rate on your account rather than a flat figure, so the pre-flight refuses only what the dialler itself would have refused a moment later. | Top up and retry with the same Idempotency-Key. |
| 403 | 403 | feature_disabled | Voice broadcast is not enabled for your account.details: "This feature is not enabled for your account." | Contact support to enable it. |
| 409 | 409 | calling_hours | The request arrived outside calling hours. Verification calls are exempt. | Queue the call and retry from 9:00 AM IST. Retry-After says how long that is. |
| 409 | 409 | idempotency_in_progress | A request with the same Idempotency-Key is still being processed. | Wait for Retry-After (2 seconds) and retry with the same key. |
| 422 | 422 | idempotency_conflict | The same Idempotency-Key was sent with a different request body. | Use a fresh key for a new request. |
| 429 | 429 | rate_limited | You went past your account's per-minute request budget. | Retry-After is up to 60 seconds. Pace with the RateLimit headers. |
| 429 | 429 | number_flood | More than 3 calls to this destination number in 10 minutes. | Retry-After is up to 600 seconds. |
| 429 | 429 | concurrency_limit | Your account has no free line for this call. The body carries lines and lines_in_use. | Retry-After is 5 seconds. Watch X-Agentive-Lines-In-Use to pace a run. |
| 502 | 502 | upstream_error | The calling network refused the request outright.details: "Could not place the call right now. Please retry." | Retry after a short pause with the same Idempotency-Key. If that reply comes back as call_state_unknown, stop and follow that row instead: a 502 is never proof on its own that nothing was dialled. |
| 502 | 502 | call_state_unknown | We asked the network to place the call and then lost track of it, so we cannot say whether it went out. The first reply carries the sentence quoted here; replaying the same Idempotency-Key returns it with a second sentence appended: "The call may or may not have been placed. Check the call with GET /calls/{unique_id} before retrying, or retry with a new Idempotency-Key."details: "Could not place the call right now. Please retry." | Do not blind-retry. Poll Get call status with the unique_id, or choose a fresh key deliberately. |
| 503 | 503 | service_unavailable | The service is briefly unavailable, or your account's calling-hours setting could not be read, so the calling window could not be checked. In that case retry_after_sec is 30. Nothing was placed. | Retry after Retry-After with the same Idempotency-Key. |
| 503 | 503 | network_busy | Every line of the phone network your calling number uses is in use right now. Nothing was placed, no run was created and nobody was rung. | Retry after Retry-After (15 seconds) with the same Idempotency-Key. |
Call types
| type | What it does | Required fields |
|---|---|---|
| audio_blast | Plays the campaign's recording to the number, then ends. | number, campaign_id |
| press1 | Places an Interactive Voice call: plays the campaign's recording, then acts on the key the recipient presses (connect them onward, capture their response, record an opt-out, or send an approved WhatsApp template). Everything it does, including spoken yes/no responses and guided flow steps, is whatever the campaign is set up to do. | number, campaign_id |
| otp | Places a verification call that reads out a code. A shortcut to the same call the Voice OTP API sends. | number |
Interactive Voice (press1) example body
{
"type": "press1",
"number": "9812345678",
"campaign_id": 4822,
"reference_id": "promo-march"
}campaign_id; your request supplies the number to call. That is also why those calls show up under the campaign in your dashboard, alongside everything else it has sent.For the otp type the response carries request_id and expires_in_sec and is identical to Send a code in the Voice OTP API, which also documents how to verify the code the recipient enters.
Idempotency-Key header. Send one on every request so a network retry can never place a second billed call. See Idempotency.Trigger a saved campaign
/campaigns/:id/triggerRun an existing API campaign for a single number. Identical in effect to POST /calls with a campaign_id; use whichever shape suits your client. The trigger uses the campaign exactly as configured in your dashboard, including its audio clips, response mode (keypad, keypad plus spoken yes/no, or spoken only), guided flow steps, voicemail detection, ring timeout, custom response labels, key map and wait times, and caller number. Audio Blast, Interactive Voice and AI voice agent campaigns can be triggered this way; the response is the usual run_... id. A campaign whose response action is WhatsApp sends its template after the call; the trigger is refused when WhatsApp is locked or not connected on the account (see the errors below). Verification-code campaigns are sent with the Voice OTP API instead.
Headers
| Header | Type | Required | Description |
|---|---|---|---|
| x-api-key | string | Required | Your publishable key ( pk_live_...). See Authentication. |
| x-api-secret | string | Required | Your secret key ( sk_live_...). Keep it server-side. |
| Content-Type | string | Required | Always application/json. |
| Idempotency-Key | string | Optional | A key unique to this logical request, 1 to 128 visible ASCII characters. A longer key is refused with HTTP 400. Send one on every request so a network retry can never place a second billed call. See Idempotency. Example: order-99213-call-1 |
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | number | Required | The numeric id of the campaign to trigger. Find it with List campaigns. Example: 57 |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| number | string | Required | The recipient's Indian mobile number. See Phone number format. Example: 9812345678 |
| reference_id | string | Optional | Your own correlation key. Echoed back and included in webhooks. Example: lead-5567 |
Request
curl https://voice.agentive.co.in/api/public/v1/campaigns/57/trigger \
-H "x-api-key: pk_live_..." \
-H "x-api-secret: sk_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: lead-5567-call-1" \
-d '{ "number": "9812345678", "reference_id": "lead-5567" }'Response
{
"status": "success",
"code": 200,
"unique_id": "run_4822",
"reference_id": "lead-5567",
"details": "Call queued."
}Errors
| Status | Code | error_code | When | What to do |
|---|---|---|---|---|
| 400 | 400 | invalid_number | number is missing, malformed, or not an Indian mobile number. A number with too many digits is refused this way too (since 17 October 2026; before, its last ten digits were dialled).details: "A valid Indian mobile number is required." | Send an Indian mobile number; see Phone number format. |
| 400 | 400 | invalid_number | number carries another country code, for example +44 or 00977 (since 17 October 2026; before, its last ten digits were dialled, which could call an unrelated number).details: "Only Indian numbers can be called." | Send an Indian mobile number; see Phone number format. |
| 404 | 404 | not_found | The campaign id does not exist on your account, or is not an API campaign.details: "Campaign not found." | Pick an id from List campaigns. |
| 400 | 400 | validation_error | The campaign is a verification-code campaign.details: "This is a verification-code campaign. Use the OTP endpoints to send a code." | Send the code with the Voice OTP API. |
| 400 | 400 | validation_error | The campaign type cannot be triggered for one number.details: "This campaign type cannot be triggered for a single number." | Use an Audio Blast or Interactive Voice campaign. |
| 400 | 400 | validation_error | The request sent variables to an Audio Blast or Interactive Voice campaign. Only an AI voice agent campaign takes them.details: "This campaign type does not take variables." | Leave variables out of the request. |
| 400 | 400 | validation_error | The request sent metadata to an Audio Blast or Interactive Voice campaign. Only an AI voice agent campaign takes it.details: "This campaign type does not take metadata." | Leave metadata out of the request. Use reference_id to match the call to your records. |
| 400 | 400 | validation_error | The campaign has no audio clip configured.details: "This campaign has no audio configured." | Attach an audio clip to the campaign in the dashboard. |
| 400 | 400 | validation_error | An AI voice agent campaign whose agent has been removed or paused. See the AI Voice Agent API.details: "This campaign has no active agent configured." | Reattach an active agent to the campaign in the dashboard. |
| 409 | 409 | ai_concurrency_limit | An AI voice agent campaign when the account's AI channels are all busy. This is a second, narrower cap inside your account's lines.details: "All your AI call channels are in use. Retry when a call finishes." | Retry-After is 5 seconds. Placing a non-AI call is unaffected. |
| 403 | 403 | whatsapp_locked | The campaign sends a WhatsApp message after the call, and WhatsApp is not part of this account's plan.details: "WhatsApp is locked on this account. Add WhatsApp to your plan, upgrade to a yearly phone plan, or move to Phone + CRM." | Add WhatsApp to the plan, upgrade to a yearly phone plan, or move to Phone + CRM. |
| 409 | 409 | whatsapp_not_connected | The plan allows WhatsApp, but no WhatsApp account is connected yet.details: "Connect Agentive Chat on the Integrations page before using WhatsApp in a campaign." | Connect Agentive Chat on the Integrations page. |
| 400 | 400 | whatsapp_template_required | The campaign uses the WhatsApp action but has no account and approved template saved on it.details: "Pick the WhatsApp account and an approved template for this campaign first." | Pick an account and an approved template on the campaign in the dashboard. |
| 503 | 503 | network_busy | Every line of the phone network your calling number uses is in use right now. Nothing was placed, no run was created and nobody was rung. | Retry after Retry-After (15 seconds) with the same Idempotency-Key. |
Balance (402), calling-hours and idempotency conflicts (409, 422), rate limits and the line refusal (429) behave exactly as on Place a call (an AI voice agent campaign's balance rule is on its own page, linked below). Like every billed POST endpoint, the trigger accepts an Idempotency-Key header (see Idempotency).
An AI voice agent campaign is triggered the same way and also takes variables and metadata; it is documented in the AI Voice Agent API. A recorded-message or Interactive Voice campaign refuses both: variables with HTTP 400 and "This campaign type does not take variables.", and metadata with HTTP 400 and "This campaign type does not take metadata."
Get call status
/calls/:unique_idRead one call: the state of a call you placed, or any call of your account. Pass the unique_id from the placement response, or any id a read or an event gave you (a call_id, a leg_id, a click to call id). A verification request_id resolves here too. Each has its own response shape, described below. With the Telephony API the call object is the whole call record.
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| unique_id | string | Required | The unique_id returned when you placed the call, for example run_4821, or any id a read or an event gave you for the call: its call_id, its leg_id, or a click to call id (c2c_...). A run_ id means an API run; a dashboard campaign's calls are read by their own call_id. Must belong to your account.Example: run_4821 |
Request
curl https://voice.agentive.co.in/api/public/v1/calls/run_4821 \
-H "x-api-key: pk_live_..." \
-H "x-api-secret: sk_live_..."Response (a run id, for example run_4821)
{
"status": "success",
"code": 200,
"unique_id": "run_4821",
"reference_id": "order-99213",
"details": "answered",
"call_status": "answered",
"duration_sec": 17,
"call_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"end_reason": null,
"call": {
"unique_id": "run_4821",
"call_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"leg_id": null,
"direction": "outbound",
"from_number": "01100000021",
"to_number": "+919812345678",
"status": "in_progress",
"end_reason": null,
"duration_sec": 17,
"campaign_id": 4821,
"reference_id": "order-99213",
"created_at": "2026-06-04T21:42:08+05:30",
"created_at_ist": "2026-06-04T21:42:08+05:30",
"created_at_utc": "2026-06-04T16:12:08Z"
}
}Response fields
| Field | Type | Description |
|---|---|---|
| call_status | string | The call's current state in the older, smaller vocabulary: queued, ringing, answered, completed or failed. Unchanged, except that a call that has ended never reads queued. The mapping to the full set is in Call status and end reasons. |
| duration_sec | number | null | The call record's length in seconds (on a run, 0 for a call that did not connect). |
| call_id | string | null | Our record id for the call this run placed. Use it for that leg's recording. |
| end_reason | string | null | Why the call ended, from the enumerated end reasons. null while the call is still running. Read this to tell a call_status of failed that rang unanswered from one that never connected. |
| reference_id | string | null | The reference_id you sent when you placed the call. |
| call | object | null | The full call object with the enumerated status and end_reason values, once the call exists. |
Errors
| Status | Code | error_code | When | What to do |
|---|---|---|---|---|
| 404 | 404 | not_found | The unique_id does not exist or does not belong to your account.details: "Call not found." or "Not found." | Check the id you stored from the placement response. |
Response (a raw call id)
When the path is a call id (a call_id from List calls, or any id an event gave you), call is the call object, and call_status, duration_sec, via_api and metadata are repeated beside it. Without the Telephony API the call carries these fields:
{
"status": "success",
"code": 200,
"unique_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"reference_id": "order-99213",
"details": "completed",
"call": {
"unique_id": "run_4821",
"call_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"leg_id": null,
"direction": "outbound",
"from_number": "01100000021",
"to_number": "+919812345678",
"status": "completed",
"end_reason": "completed",
"duration_sec": 42,
"campaign_id": 4821,
"reference_id": "order-99213",
"created_at": "2026-06-04 16:12:08",
"created_at_ist": "2026-06-04T21:42:08+05:30",
"created_at_utc": "2026-06-04T16:12:08Z",
"click_to_call_id": null,
"agent_id": null,
"transcript_available": false,
"analysis_available": false,
"via_api": true,
"metadata": null,
"charge_inr": 0
},
"call_status": "completed",
"duration_sec": 42,
"via_api": true,
"metadata": null
}Extra fields on call
| Field | Type | Description |
|---|---|---|
| duration_sec | number | null | The call record's length in seconds, menu, ringing and hold included (talk_sec on the full record is the conversation). Also returned beside the envelope. |
| agent_id | number | null | The AI voice agent that handled the call. null for a recorded or Interactive Voice call, and for any call a person handled. |
| transcript_available | boolean | Whether this key can fetch a transcript of the call with GET /calls/:unique_id/transcript. |
| via_api, metadata, charge_inr | mixed | As on the call object: placed through the API, the metadata you sent, and what the call cost your balance. |
| analysis_available | boolean | Whether an analysis of this call has been produced. |
Response (a call id, with the Telephony API)
The same read on an account with the Telephony API: the call object is the whole record, the same one the events carry at the same version.
{
"status": "success",
"code": 200,
"unique_id": "7f0c2a9e-4b1d-4c3e-9a7f-1d2e3f4a5b6c",
"reference_id": null,
"details": "completed",
"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
},
"call_status": "completed",
"duration_sec": 113,
"via_api": false,
"metadata": null
}A click to call id (c2c_...) whose customer has not been called yet answers a short call object built from the click to call: the team member did not answer reads missed / no_answer, declined missed / rejected, cancelled missed / canceled, an invalid number failed / failed, and one still ringing your team member queued. A run_ id reads an API run or a verification run; a dashboard campaign's calls are read by their own call_id.
A verification request id from the Voice OTP API resolves here too. For those the response carries verification_status (the closed set pending, verified, failed, locked, expired, undeliverable), the original call_status, plus verified, attempts, max_attempts and expires_at_ist. The Voice OTP reference documents that shape.
List calls
/callsPage through the calls on your account, most recent first, each as a call object with the enumerated status and end_reason values, so you can reconcile call results in bulk instead of polling each call by id. With the Telephony API it is also your call history sync: a change feed (updated_since), a cursor, and filters by team member, reference, lane, recording and outcome. See Syncing your call history.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| page | number | Optional | The page of results to return. Default 1. Not with cursor or updated_since. |
| per_page | number | Optional | Results per page. Default 50, maximum 100. |
| direction | string | Optional | Filter by inbound or outbound. |
| status | string | Optional | Filter by a call status: queued, ringing, in_progress, completed, failed, or missed. It matches the status each call reads, so a filter never returns a call whose status differs. |
| from | string | Optional | Include calls created on or after this ISO 8601 date or timestamp. A value with an offset is used exactly; one without a time zone is read as IST. Example: 2026-06-01 |
| to | string | Optional | Include calls created before this ISO 8601 date or timestamp, read like from. Example: 2026-06-30T23:59:59+05:30 |
| number | string | Optional | Match calls where this number appears as either the caller or the recipient. Example: 9812345678 |
| order | string | Optional | Telephony API. desc (the default, newest first) or asc. asc pages with a cursor. |
| cursor | string | Optional | Telephony API. The pagination.next_cursor of the previous page, sent with the same filters. Opaque: never build or change one. A cursor sent with other filters answers 400 invalid_cursor. |
| updated_since | string | Optional | Telephony API. The change feed: every call whose record changed at or after this ISO 8601 time, oldest change first, up to the walk's pagination.watermark. An earlier time than the feed's start answers 400 updated_since_too_old: use from and to for older calls.Example: 2026-10-13T07:29:30.000Z |
| member_id | number | Optional | Telephony API. Calls this team member placed, answered or missed. A call they handed on to a colleague who answered it is listed under that colleague, not under them (its transfers name both). |
| reference_id | string | Optional | Telephony API. Calls carrying this reference_id (up to 120 characters), and the calls of an API run you started with it. Since 17 October 2026 a click to call's reference_id also returns the record it goes on as in a call menu, for the first 50 click to calls placed with that reference_id (for a later one, filter by its click_to_call_id). |
| click_to_call_id | string | Optional | Telephony API. The calls of one click to call (c2c_ and 32 hex characters): its own record (unique_id the click to call id) and, since 17 October 2026, the record it goes on as in a call menu (its own unique_id). |
| lane | string | Optional | |
| has_recording | boolean | Optional | Telephony API. true for calls with a stored recording, false for the rest. |
| end_detail | string | Optional | Telephony API. One end_detail value. lane, has_recording and end_detail need from and to at most 31 days apart, or updated_since; otherwise 400 validation_error. |
Request
curl "https://voice.agentive.co.in/api/public/v1/calls?per_page=50&direction=outbound&status=completed" \
-H "x-api-key: pk_live_..." \
-H "x-api-secret: sk_live_..."Response (page numbers, without the Telephony API)
{
"status": "success",
"code": 200,
"data": [
{
"unique_id": "run_4821",
"call_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"leg_id": null,
"direction": "outbound",
"from_number": "01100000021",
"to_number": "+919812345678",
"status": "completed",
"end_reason": "completed",
"duration_sec": 42,
"campaign_id": 4821,
"reference_id": "order-99213",
"created_at": "2026-06-04T21:42:08+05:30",
"created_at_ist": "2026-06-04T21:42:08+05:30",
"created_at_utc": "2026-06-04T16:12:08Z",
"click_to_call_id": null
}
],
"pagination": {
"page": 1,
"per_page": 50,
"total": 137,
"total_pages": 3
}
}Response fields
| Field | Type | Description |
|---|---|---|
| data | object[] | A page of call objects. |
| pagination.page, total, total_pages | number | null | The page, the calls matching your filters and the number of pages. For a status, number, lane, end_detail or has_recording search, total is a count kept for up to 30 seconds and corrected by the page it comes with: see the paragraph on searches below this table. null in cursor and feed modes, which never count. |
| pagination.per_page | number | Results per page for this response. |
| pagination.has_more | boolean | Telephony API. Whether another page follows. |
| pagination.next_cursor | string | null | Telephony API. Pass it as cursor, with the same filters, for the next page. null in page number mode and on the last page. |
| pagination.watermark | string | Telephony API, feed mode only. The upper end of this walk (30 seconds behind our clock, fixed for every page of the walk). Store it and pass it as updated_since next time. |
| warnings | object[] | Present when the request carried a query parameter we do not know: { code: "unknown_parameter", parameter }, also sent as the X-Agentive-Warning header. Parameters starting with _ are always allowed. |
Response (the change feed, with the Telephony API)
{
"status": "success",
"code": 200,
"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 11:55:27.214+05:30",
"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
}
],
"pagination": {
"page": null,
"per_page": 100,
"total": null,
"total_pages": null,
"next_cursor": "eyJtIjoiZiIsImsiOiIxNzkxODcyODg1MzE3In0.Hq2L9xR4",
"has_more": true,
"watermark": "2026-10-13T07:29:30.000Z"
}
}warnings and the X-Agentive-Warning header, and will later be refused with 400 validation_error (announced in the changelog). The Telephony API parameters above are unknown parameters for any other key. Unknown values of direction and status are refused already.A request that uses number, status, cursor, updated_since or one of the Telephony API filters can answer 503 service_unavailable with retryable: true and Retry-After: 30 while call history search is briefly unavailable; plain page number reads keep working. Retry after the pause. end_reason is always one of the enumerated end reasons.
A search the index cannot answer on its own (status, number, lane, end_detail, has_recording) runs two at a time per account, and four across the platform: a third at the same moment answers 503 with retryable: true and Retry-After: 5 ("Another search of your call history is running"). Page through such a search one request at a time. The calls on a page are read when you ask, so a call that has just changed state is on the matching list at once. The search's count is taken once and kept for 30 seconds, and the total and total_pages you receive are that count corrected by the page they come with: on the page that holds the last match they are exact, and while another page follows (has_more is true with the Telephony API; with any key, page is below total_pages) they count at least one call after this page. A page past the last match answers no calls, has_more false, and a total no higher than the calls before it, which can trail calls added or changed in the last 30 seconds. A page 10,000 calls or more past that total is answered at once with no calls (since 14 October 2026; before, a page at or past a count kept from up to 30 seconds earlier was answered with no calls, so a call could be missing from a status list for up to 30 seconds after it changed state).
Download a call recording
/calls/:unique_id/recordingDownload the audio recording of a call. The API streams the file itself: HTTP 200 with the audio as the body and a Content-Type of audio/ogg or audio/wav, depending on how the recording was stored, or audio/mpeg / audio/wav when you ask for MP3 or WAV with format (since 17 October 2026). It never redirects you to another address. Send a Range header to fetch part of the file (HTTP 206); a range outside the file answers HTTP 416 with Content-Range: bytes */<file size>. The path takes any id of the call: its unique_id (a click to call's c2c_ id included), call_id or leg_id. The samples authenticate with HTTP Basic, which an HTTP client never forwards to another host, and you should never send your secret anywhere but this API. Requires call recording to be enabled on your account.
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| unique_id | string | Required | The unique_id returned when you placed the call, for example run_4821, or any id a read or an event gave you for the call: its call_id, its leg_id, or a click to call id (c2c_...). A run_ id means an API run; a dashboard campaign's calls are read by their own call_id. Must belong to your account.Example: run_4821 |
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| segment | number | Optional | An earlier part of the recording: the segment of one of recording.parts. Without it you get the main file (the one recording_url names).Example: 1 |
| format | string | Optional | Since 17 October 2026. mp3 or wav: the recording converted to that format (see MP3 and WAV). Without it you get the file as stored (Ogg Opus for almost every call). Any other value answers 400 validation_error on field format.Example: mp3 |
Request
# The API streams the audio. Basic auth: key as user, secret as password.
curl "https://voice.agentive.co.in/api/public/v1/calls/run_4821/recording" \
-u "$AGENTIVE_KEY:$AGENTIVE_SECRET" \
--output call-4821.oggResponse (no recording available)
{
"status": "error",
"code": 404,
"unique_id": null,
"reference_id": null,
"details": "No recording is available for this call.",
"error": "No recording is available for this call.",
"error_code": "not_found"
}Errors
| Status | Code | error_code | When | What to do |
|---|---|---|---|---|
| 404 | 404 | not_found | The id is not a call of your account (a dashboard campaign's run_ id included).details: "Call not found." | Use the call's call_id or the unique_id an event or a read gave you. |
| 404 | 404 | not_found | No file is stored for the call: it was not recorded, or it is still being stored.details: "No recording is available for this call." | Wait for the recording.available event, or check that the call reached completed. |
| 403 | 403 | feature_disabled | Call recording is not enabled for your account.details: "This feature is not enabled for your account." | Contact support to enable call recording. |
| 404 | 404 | not_found | The call has no part with that segment number.details: "Segment not found." | Read recording.parts for the segments that exist. |
| 404 | 404 | recording_expired | Past the recording's expires_at. Every part answers this.details: "This recording has passed your plan's retention and is no longer available." | Copy recordings before expires_at. |
| 416 | 416 | validation_error | The Range asked for lies outside the file, or cannot be read. A range past the end carries Content-Range: bytes */<file size> (since 14 October 2026) whenever we know the file's size. The body's unique_id names the call: the same unique_id that Get call status answers for the id in your path (since 14 October 2026; before, null). Every other error here keeps unique_id null. | Send one range inside the file, or no Range header. |
| 400 | 400 | validation_error | format is not mp3 or wav (field format; since 17 October 2026). | Send format=mp3 or format=wav, or omit format for the file as stored. |
| 422 | 422 | validation_error | The recording is too long to convert (field format; since 17 October 2026). | Omit format. |
| 500 | 500 | conversion_failed | The recording cannot be converted to that format (retryable: false; since 17 October 2026). | Omit format. |
| 502 | 502 | upstream_error | The recording could not be read right now. With format, the answer also carries retryable: true and Retry-After: 5 (since 17 October 2026); a download without format (a recording link without one included) carries neither. | Retry a little later. |
| 503 | 503 | recording_converting | The MP3 or WAV copy is still being made, or still waiting for its turn in the queue, after 15 seconds (since 17 October 2026). | Retry after Retry-After. The copy goes on being made meanwhile. |
| 503 | 503 | service_unavailable | The conversion queue is full (5 requests already waiting for your account, or the platform's queue), or converting is not possible right now (retryable: true; since 17 October 2026). | Retry a little later, or omit format. |
# Part 1 of a call recorded in two parts (recording.parts[0].segment is 1).
curl "https://voice.agentive.co.in/api/public/v1/calls/7f0c2a9e-4b1d-4c3e-9a7f-1d2e3f4a5b6c/recording?segment=1" \
-u "$AGENTIVE_KEY:$AGENTIVE_SECRET" \
--output call-part-1.ogg{
"status": "error",
"code": 404,
"unique_id": null,
"reference_id": null,
"details": "This recording has passed your plan's retention and is no longer available.",
"error": "This recording has passed your plan's retention and is no longer available.",
"error_code": "recording_expired"
}MP3 and WAV
Since 17 October 2026 format=mp3 or format=wav sends the recording (or the part segment names) converted, for players and tools that do not play Ogg:
- MP3: 16 kHz, constant bit rate, 32 kbps per channel; WAV: 8 kHz 16-bit PCM, the telephone line's own rate. A WAV is always converted, a recording stored as WAV included. A stereo recording stays stereo, with each side on its own channel (
channel_layoutstill applies); a mono one stays mono. The file carries no tags. - The first request for a recording in a format makes the copy: it usually answers at once, but a long call can take some seconds, and a request that waits more than 15 seconds answers HTTP 503
recording_convertingwith aRetry-After(retryable: true): retry then, the copy goes on being made. Repeat requests are served from the copy, kept for a day after its last use. Rangeworks as on the stored file, on the converted file's own size.- Converting is bounded. At most 2 recordings are converted at a time across the whole platform, and at most 2 for one account. A further request with
formatwaits in a queue (up to 5 waiting for your account, and 20 across the platform): if its copy is not ready within 15 seconds, waiting included, it answers HTTP 503recording_convertingwith aRetry-After, and the copy goes on being made. Only a full queue (your account's 5, or the platform's), or a server that cannot convert right now, answers HTTP 503service_unavailable(retryable: true): retry a little later. A download withoutformatis never refused by any of this. - A recording too large to convert answers HTTP 422 on field
format: one longer than about 4 hours for most calls (stored compressed), but already one longer than about 30 minutes when it was stored as WAV (the limit is the size of the stored file, 64 MB). A recording that cannot be converted answers HTTP 500conversion_failed(retryable: false). Omitformatfor either.
# --retry 5 also retries the 503 recording_converting answer of a long call, after its Retry-After.
curl --fail --retry 5 "https://voice.agentive.co.in/api/public/v1/calls/run_4821/recording?format=mp3" \
-u "$AGENTIVE_KEY:$AGENTIVE_SECRET" \
--output call-4821.mp3recording_url and, with the Telephony API, every part. Recordings stop being available at their expires_at (your plan's retention): copy what you keep before then. Downloads have their own budget of 120 a minute, which downloads with format and creating a recording link share (since 17 October 2026); see Rate limits.menu) with its own recording; the first call names it in transfers[].to_call_id. When no lane menu call starts at the move (some calls placed from older app versions), the call keeps one recording for the whole call, the call menu part included. A call that came in and was moved to a call menu keeps one recording for the whole call.Download a voicemail
/calls/:unique_id/voicemailTelephony API, with voicemail on your account. Download the message a caller left on the call, streamed exactly like a recording (200, 206 for a Range, 416, never a redirect). The call's voicemail block and the voicemail.left event carry this address. The path takes any id of the call. Messages are deleted at their expires_at. Downloads share the recording budget of 120 a minute. Since 17 October 2026 ?format=mp3 or ?format=wav sends the message converted, exactly as for a recording (see MP3 and WAV, the same answers and errors).
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| unique_id | string | Required | The unique_id returned when you placed the call, for example run_4821, or any id a read or an event gave you for the call: its call_id, its leg_id, or a click to call id (c2c_...). A run_ id means an API run; a dashboard campaign's calls are read by their own call_id. Must belong to your account.Example: run_4821 |
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| format | string | Optional | Since 17 October 2026. mp3 or wav: the message converted to that format, exactly as for a recording. Without it you get the file as stored.Example: mp3 |
Request
# The API streams the audio. Basic auth: key as user, secret as password.
curl "https://voice.agentive.co.in/api/public/v1/calls/9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d/voicemail" \
-u "$AGENTIVE_KEY:$AGENTIVE_SECRET" \
--output voicemail.oggResponse (no voicemail on the call)
{
"status": "error",
"code": 404,
"unique_id": null,
"reference_id": null,
"details": "No voicemail was left on this call.",
"error": "No voicemail was left on this call.",
"error_code": "not_found"
}Errors
| Status | Code | error_code | When | What to do |
|---|---|---|---|---|
| 404 | 404 | not_found | The caller left no message (or the id is not a call of your account).details: "No voicemail was left on this call." | |
| 404 | 404 | voicemail_expired | The message is past its expires_at and is no longer available. | Copy voicemails before expires_at. |
| 403 | 403 | feature_disabled | The key is not a Telephony API key, or voicemail is not on your account.details: "This feature is not enabled for your account." | |
| 416 | 416 | validation_error | The Range asked for lies outside the message, or cannot be read. The same answer as a recording's 416, Content-Range and unique_id included. | Send one range inside the message, or no Range header. |
# --retry 5 also retries the 503 recording_converting answer of a long message, after its Retry-After.
curl --fail --retry 5 "https://voice.agentive.co.in/api/public/v1/calls/9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d/voicemail?format=mp3" \
-u "$AGENTIVE_KEY:$AGENTIVE_SECRET" \
--output voicemail.mp3Create a recording link
/calls/:unique_id/recording-linkSince 17 October 2026. A link that plays one recording (or one part of it, optionally as MP3 or WAV) without your keys, valid for at most 10 minutes. Create it on your server, then give the URL to the page that plays it: an agent's browser plays the call with no proxy on your side and no API secret in your front-end code. Requires call recording on your account; the same calls, parts and retention as Download a call recording. Counted in the download budget.
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| unique_id | string | Required | The unique_id returned when you placed the call, for example run_4821, or any id a read or an event gave you for the call: its call_id, its leg_id, or a click to call id (c2c_...). A run_ id means an API run; a dashboard campaign's calls are read by their own call_id. Must belong to your account.Example: run_4821 |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| segment | number | Optional | A part of the recording, as ?segment= on the download. Without it, the main file.Example: 1 |
| format | string | Optional | mp3 or wav, as ?format= on the download. Without it, the file as stored.Example: mp3 |
| expires_in_sec | number | Optional | How long the link plays: a whole number from 60 to 600. Default 600 (10 minutes). Example: 600 |
Request
// On your server: never send the secret to the browser.
const auth = Buffer.from(`${process.env.AGENTIVE_KEY}:${process.env.AGENTIVE_SECRET}`).toString("base64");
const res = await fetch(
`https://voice.agentive.co.in/api/public/v1/calls/${callId}/recording-link`,
{
method: "POST",
headers: { Authorization: `Basic ${auth}`, "Content-Type": "application/json" },
body: JSON.stringify({ format: "mp3" }),
}
);
const { data } = await res.json();
// Hand data.url to the page, e.g. <audio controls preload="none" src="..."></audio>Response
{
"status": "success",
"code": 200,
"unique_id": "7f0c2a9e-4b1d-4c3e-9a7f-1d2e3f4a5b6c",
"reference_id": null,
"details": "Recording link created.",
"data": {
"url": "https://voice.agentive.co.in/api/public/v1/recording-links/rl1.eyJvIjo0Mi...Q.8kQ2...xY",
"expires_at": "2026-10-17T10:10:00.000Z",
"expires_in_sec": 600,
"segment": null,
"format": "mp3",
"content_type": "audio/mpeg",
"ready": true
}
}Response fields
| Field | Type | Description |
|---|---|---|
| data.url | string | The link. Treat it like a password for its few minutes: anyone holding it can play that one recording from any device until expires_at. |
| data.expires_at | string | When it stops playing: at most 10 minutes from now, and never later than the recording's own expires_at. |
| data.expires_in_sec | number | How long the link plays, in seconds. |
| data.segment | number | null | The part the link plays; null for the main file. |
| data.format | string | null | mp3 or wav when the link plays a converted copy; null for the file as stored. |
| data.content_type | string | The Content-Type the link answers with: audio/mpeg, audio/wav or audio/ogg. |
| data.ready | boolean | true when the file can be played at once. With format, the copy is started when the link is created: false means it is still being made (a long call), and the link answers 503 recording_converting with a Retry-After until it is ready (an <audio> element does not retry by itself: wait, or retry the play). |
Errors
| Status | Code | error_code | When | What to do |
|---|---|---|---|---|
| 404 | 404 | not_found | As the download: the call is not on your account, it has no recording (or not yet), or no part has that segment. | |
| 404 | 404 | recording_expired | The recording passed your plan's retention. | Copy recordings before expires_at. |
| 403 | 403 | feature_disabled | Call recording is not enabled for your account. | |
| 400 | 400 | validation_error | segment, format or expires_in_sec is not valid. | Send a segment that exists, mp3 or wav, and a whole number of seconds from 60 to 600. |
| 422 | 422 | validation_error | With format: the recording is too long to convert (field format). | Create the link without format. |
| 500 | 500 | conversion_failed | With format: the recording could never be converted to that format. | Create the link without format. A full conversion queue does not stop the link being made: it answers with ready false. |
A link stops playing at expires_at, and also as soon as the API secret that created it stops working: rotating the secret with no grace, the end of a 24-hour grace, or revoking the previous secret. During a grace rotation a link made with the previous secret keeps playing until its own expiry. A link also stops when the recording passes its retention, when call recording or the API is switched off for your account, or when the recording's stored file changes. Every creation and every play is logged on our side.
While address lists are checked (see Restrict your key to your servers' addresses), a key with a list creates a link only from an allowed address, like every keyed request; the link itself plays from any device (that is what it is for: your agents' browsers).
Play a recording link
/recording-links/:tokenSince 17 October 2026. The url of Create a recording link, requested with no key. Answers like a download: HTTP 200 with the audio, 206 for a Range, 416 for a range outside the file, with the Content-Type of the file (audio/mpeg, audio/wav or audio/ogg). Any web page may play it (<audio src>, or fetch() from any origin: the answer allows every origin and exposes Content-Range, Content-Length and Accept-Ranges). The answer carries Cache-Control: private, no-store.
Errors
| Status | Code | error_code | When | What to do |
|---|---|---|---|---|
| 401 | 401 | invalid_link | Not a link of ours, or changed. | |
| 403 | 403 | link_expired | Past expires_at. | Create a new link. |
| 403 | 403 | link_revoked | The secret that created it no longer works. | Create a new link. |
| 403 | 403 | account_inactive api_disabled feature_disabled | The account, its API or its call recording is no longer on. | |
| 404 | 404 | not_found | The recording's stored file changed since the link was made. A call or part that is gone answers as the download does, for example "Call not found." or "Segment not found."details: "This link no longer matches the recording. Create a new link." | Create a new link. |
| 404 | 404 | recording_expired | The recording passed its retention. | |
| 429 | 429 | rate_limited | The account's link-play budget (600 a minute) is spent; or the same link was refused many times in a minute (for example an expired link played again and again); or many refused links, or links that are not ours, came from your address. | Wait for Retry-After; create a new link if this one has expired. |
| 503 | 503 / 500 / 502 | recording_converting conversion_failed upstream_error | A link with format: the copy is still being made, or cannot be made, answered as the download answers it. See MP3 and WAV. | |
| 503 | 503 | service_unavailable | A link with format while MP3 and WAV copies are not available on our side (retryable: true, Retry-After 30). | Retry later, or create a new link without format. |
| 503 | 500 / 503 | service_unavailable | The recording could not be played right now (retryable: true). | Retry. |
Treat a link like the recording itself: anyone who has it can play it until expires_at, and its plays count in your account's link-play budget. If a link leaks, rotate your API secret with Stop the old secret now (see Authentication): every link it created stops at once.
Each request is checked on its own, a Range request included: a player must load, play and seek before expires_at. After it, create a new link.
Get a team call transcript
/calls/:unique_id/transcriptTelephony API, with call transcription on your account. The conversation of a team call your account transcribed, turn by turn. AI voice agent calls have their own transcript on this route, documented in the AI Voice Agent API. transcript_available on the call says whether there is one; a call with none answers 404 with "No transcript is available for this call."
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| unique_id | string | Required | The unique_id returned when you placed the call, for example run_4821, or any id a read or an event gave you for the call: its call_id, its leg_id, or a click to call id (c2c_...). A run_ id means an API run; a dashboard campaign's calls are read by their own call_id. Must belong to your account.Example: run_4821 |
Request
curl "https://voice.agentive.co.in/api/public/v1/calls/7f0c2a9e-4b1d-4c3e-9a7f-1d2e3f4a5b6c/transcript" \
-u "$AGENTIVE_KEY:$AGENTIVE_SECRET"Response
{
"status": "success",
"code": 200,
"data": {
"unique_id": "7f0c2a9e-4b1d-4c3e-9a7f-1d2e3f4a5b6c",
"call_id": "7f0c2a9e-4b1d-4c3e-9a7f-1d2e3f4a5b6c",
"leg_id": null,
"turns": [
{ "role": "member", "text": "Namaste, Neha bol rahi hoon, Sales se.", "speaker": null },
{ "role": "customer", "text": "Haan, mujhe paanch users ke liye quote chahiye tha.", "speaker": null },
{ "role": "member", "text": "Bilkul, main aaj hi WhatsApp par bhej deti hoon.", "speaker": null }
],
"language": "hi",
"created_at": "2026-10-13 06:29:51",
"created_at_ist": "2026-10-13T11:59:51+05:30"
}
}Response fields
| Field | Type | Description |
|---|---|---|
| data.unique_id, call_id, leg_id | string | The call's ids. |
| data.turns[].role | string | member (your team member's side), customer, or speaker when the recording was mono and the voices were told apart by speaker number. |
| data.turns[].text | string | What was said. |
| data.turns[].speaker | number | null | The speaker's number on a speaker turn, else null. |
| data.language | string | null | The language the transcription found. |
| data.created_at, created_at_ist | string | When the transcript was made. |
List campaigns
/campaignsList the campaigns on your account that can be triggered through the API. Use a campaign id from this list with Trigger a saved campaign.
Request
curl https://voice.agentive.co.in/api/public/v1/campaigns \
-H "x-api-key: pk_live_..." \
-H "x-api-secret: sk_live_..."Response
{
"status": "success",
"code": 200,
"data": [
{ "id": 57, "name": "March promo", "type": "audio_blast", "status": "active", "press1_action": null },
{ "id": 61, "name": "Renewal interactive voice", "type": "press1", "status": "active", "press1_action": "whatsapp" },
{ "id": 72, "name": "Signup verification", "type": "otp", "status": "active", "press1_action": null }
]
}Response fields
| Field | Type | Description |
|---|---|---|
| id | number | The campaign id. Use it with Trigger a saved campaign. |
| name | string | The name you gave the campaign. |
| type | string | One of audio_blast (Audio Blast), press1 (Interactive Voice), otp (verification) or ai_agent (an AI voice agent takes the conversation). audio_blast and press1 can be triggered from Trigger a saved campaign. otp campaigns are configured here but delivered with the Voice OTP API, and ai_agent campaigns are not available through the API at present. |
| status | string | The campaign's current state. |
| press1_action | string | null | For press1 campaigns: connect, interest or whatsapp. null for other types. |
Get account balance
/accountReturn your account's current balance in INR, your lines and the products your key can use. Useful as a pre-flight check before a large run. Answers 200 for every valid key; balance_inr is null when the wallet is not on your account.
Request
curl https://voice.agentive.co.in/api/public/v1/account \
-H "x-api-key: pk_live_..." \
-H "x-api-secret: sk_live_..."Response
{
"status": "success",
"code": 200,
"data": {
"balance_inr": 1842.5,
"currency": "INR",
"lines": 10,
"lines_in_use": 2
}
}Response fields
| Field | Type | Description |
|---|---|---|
| data.balance_inr | number | null | Your current wallet balance, in Indian Rupees. null when the wallet is not on your account (it used to answer 403). |
| data.currency | string | Always "INR". |
| data.lines | number | The number of calls your account can have live at the same time. Incoming calls, campaign and API calls, and the calls your team members place from the dashboard, the apps or the Click to Call API all count against it: a Phone Bridge call (one a team member places on their own mobile, or an incoming call that rings a team member's mobile straight from your number or that a colleague hands to them there) and an incoming call sent on to your fallback number hold two lines, and so does an Interactive Voice (press1) call you place with Place a call or Trigger a saved campaign while it is being placed; any other call holds one (a call menu call answered on a team member's mobile, a call a menu key sends on to another number, and a Call via SIM call included). A call a team member places from the dashboard or the apps is refused before the other person is dialled when the calls ringing or connected on your account and the calls being placed right now leave no line for it, counted against your line limit plus any extra line allowance your account carries. That count leaves out AI voice agent calls answered on your numbers and calls a campaign or the API is still dialling, so it can differ from lines_in_use. Since 17 October 2026 a call a team member places over the internet (the dashboard, the apps, a click to call) counts too; before, only their Phone Bridge calls (two lines) and Call via SIM calls (one line) counted. |
| data.lines_in_use | number | How many of those lines are in use right now, counted as the API counts them before it places a call: calls ringing or connected (campaign and API calls still ringing their number and AI voice agent calls included), click to calls whose team member is still being rung, and calls being placed right now. A call you place with Place a call, Trigger a saved campaign or Send a verification code holds its line from the request until its call exists, up to 60 seconds (since 17 October 2026; before, 3 seconds); an AI voice agent call (Place an AI agent call, or the trigger of an AI voice agent campaign) frees its line 3 seconds after the request, as before. |
The call object
List calls returns a data array of call objects, and Get call status returns one under call. The same object is in the call.* webhook events.
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.reference_id is filled on every read for any call we can resolve it for, so a list or a poll gives you back the key you sent. Calls placed before September 2026 may still show null there.
Syncing your call history
With the Telephony API your system can hold a complete, current copy of every call on the account, the ones your team makes and takes included, with three tools: a one-time backfill, the change feed and webhooks. The feed misses nothing; webhooks are fast. Use both.
- Backfill onceNote the time, then read your history in one day windows:
GET /calls?from=2026-10-01&to=2026-10-02&order=asc, followingpagination.next_cursoruntilhas_moreis false, then the next day. Download recordings with their own budget of 120 a minute as you go. - Follow the change feedEvery minute or two, call
GET /calls?updated_since=<time>starting from the time you noted. It returns every call whose record changed at or after that time, oldest change first, a call inserted late with an earlier start included. Walk it to the end, then storepagination.watermarkand pass it asupdated_sincenext time. - Keep the newest versionA call can appear in more than one walk, and in a webhook too. Store each call by
call_idand apply a copy only when itsversionis higher than the one you hold. - Add webhooks for speedSubscribe to the call events,
call.tagged,recording.availableand the others you need. They arrive within seconds; the feed catches anything a webhook missed.
// Run every minute or two. state.since starts at the time you finished your backfill.
const auth = "Basic " + Buffer.from(
`${process.env.AGENTIVE_KEY}:${process.env.AGENTIVE_SECRET}`
).toString("base64");
async function syncCalls(state) {
let cursor = null;
let watermark = null;
do {
const params = new URLSearchParams({ updated_since: state.since, per_page: "100" });
if (cursor) params.set("cursor", cursor);
const res = await fetch(`https://voice.agentive.co.in/api/public/v1/calls?${params}`, {
headers: { Authorization: auth },
});
if (res.status === 503 || res.status === 429) return; // try again on the next run
const body = await res.json();
for (const call of body.data) {
// Apply only a newer version of a call you already hold.
const held = await db.versionOf(call.call_id);
if (held === null || call.version > held) await db.saveCall(call);
}
cursor = body.pagination.next_cursor;
watermark = body.pagination.watermark;
if (!body.pagination.has_more) break;
} while (cursor);
if (watermark) state.since = watermark; // the next run starts here
}- The feed starts on 13 October 2026. Calls that have not changed since then are found with
fromandto, not withupdated_since. - A cursor belongs to the filters it was issued with. Send the same filters with it, and do not store cursors for later: start a new walk instead.
- A 503 with
Retry-After: 30during a walk means try again shortly; your stored watermark is still right.
Call 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.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).Which number the recipient sees
The campaign decides, and only the campaign. You pick it once when you set the campaign up, and every call that campaign places comes from what you picked. You cannot set it per request, and nothing overrides it or stands in for it later. It works the same whether you place the call with POST /calls or trigger the campaign directly.
- If the campaign names one of your numbers, that number is used and the recipient sees your own line. Only your numbers enabled for voice broadcast can be picked.
- If the campaign names a rotational pool, the call goes out from a number in that pool, and the pool rotates across its numbers and paces them on your behalf.
- If what the campaign picked stops being usable(the number is switched off for broadcast, quarantined, or the pool is withdrawn), the request is refused with HTTP 400 and
invalid_caller_id, telling you to open the campaign and pick again. Your calls are never quietly moved to some other number: you would not know it had happened, and neither would the customer seeing an unfamiliar caller. - If your account has no broadcast number and no pool at all, the request is refused with HTTP 400 and "No number on your account is enabled for voice broadcast. Ask your account manager to enable one, then retry." Retrying will not help until a number is enabled.
Phone number format
Send Indian mobile numbers in any of these forms; they are all normalised:
- 10-digit local:
9812345678 - With the leading 0:
09812345678 - With country code:
919812345678(also91 0 98123 45678) - With plus prefix:
+919812345678(also+91 0 98123 45678) - With the international prefix:
0091 98123 45678
Spaces, dashes, dots and brackets are ignored.
POST /calls, POST /campaigns/{id}/trigger, POST /otp/send and POST /ai/calls, a number with another country code (for example +44…, +1…, +971…, 00977…) is refused with HTTP 400, error_code invalid_number and "Only Indian numbers can be called.", and a number with too many digits as an invalid number (since 17 October 2026; before, the last ten digits were dialled, which could call an unrelated number). An invalid number answers error_code invalid_number and the sentence above, except on POST /ai/calls, which answers validation_error for it as before, with "A valid Indian mobile to_number is required." The number of POST /otp/verify sent without a request_id is refused with "A valid Indian mobile number is required." (invalid_number) whatever the reason, a number with another country code included (since 17 October 2026); sent with a request_id, the number is not checked: the request decides.Reference IDs
reference_id is an optional string you attach to any request, such as an order number, ticket id, or signup id. It is:
- echoed back in the response
reference_idfield, and - included in every webhook for the call.
Use it to match our events back to your own records without storing our ids. Reference IDs are capped at 120 characters; control characters are stripped. A reference_id never deduplicates anything; use an Idempotency-Key for retry safety.
Calling hours
Calls that reach a customer with a message are placed between 9:00 AM and 9:00 PM IST, every day. This applies to Audio Blast and Interactive Voice calls, whether you place them with POST /calls or by triggering a saved campaign. A request that arrives outside those hours is refused with HTTP 409 and a message naming the hours, so your system can queue it and retry in the morning rather than believing the call was placed. If your account's calling-hours setting cannot be read at that moment, the request is refused too, never placed: HTTP 503 with service_unavailable and retry_after_sec 30. Retry after 30 seconds with the same Idempotency-Key.
otp type, and POST /otp/send in the Voice OTP API) work around the clock, because a login or payment code has to reach someone whenever they are signing in.If your account has been approved for extended hours, your calls are not restricted and you will not see the 409.
Idempotency
Four endpoints accept an Idempotency-Key header: POST /calls, POST /campaigns/:id/trigger, and POST /otp/send and POST /otp/verify in the Voice OTP API. Send a unique key with each logical request, and a network retry can never place a second billed call: if a request times out or the connection drops, resend the same request with the same key.
curl 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" \
-H "Idempotency-Key: order-99213-call-1" \
-d '{ "type": "audio_blast", "number": "9812345678", "campaign_id": 4821, "reference_id": "order-99213" }'The key is 1 to 128 visible ASCII characters; a longer key is refused with HTTP 400 rather than cut short. Use something unique per action, such as a UUID or your own order id plus an attempt marker. Keys are scoped to your account and live for 24 hours.
What is stored and replayed
A key is consumed only by a response that decided the request. Everything else releases it, so the same key is the right thing to retry with.
| Response | Stored? | What a retry with the same key does |
|---|---|---|
2xx | Yes | Replays the original response. No second call is placed. |
400 | Yes | Replays the same validation error for 24 hours, even after you fix the body or the campaign in the dashboard. Send the fixed request with a new key. |
401 on verify | Yes | Replays the incorrect-code response, because the attempt was already spent. |
404 | Yes | Replays the not-found response for 24 hours. Once the id or the dashboard setting is fixed, send the request with a new key. |
422 | Yes | Replays the conflict. The key is bound to the first body it saw. |
402 | No | Top up, then resend with the same key. The call is attempted. |
403 | No | Once the entitlement is in place, resend with the same key. |
409 | No | Wait for Retry-After, then resend with the same key. |
429 | No | Wait for Retry-After, then resend with the same key. |
5xx before we placed the call | No | Resend with the same key. Nothing was placed. |
502 call_state_unknown | Yes | Replays the same answer. Poll GET /calls/:unique_id, or choose a fresh key deliberately. |
error_code: "call_state_unknown", so a blind retry can never double-dial. Poll Get call status with the unique_id you were given; only place a second call with a fresh key once you have seen that the first one did not happen.Replay and in-flight
A replayed response carries two headers with the same meaning: Idempotent-Replayed: true, the platform-wide name, and idempotency-replayed: true, the original one, kept so existing clients keep working.
HTTP/1.1 200 OK
Content-Type: application/json
Idempotent-Replayed: true
idempotency-replayed: trueReusing a key while the first request is still running returns HTTP 409 with error_code: "idempotency_in_progress" and Retry-After: 2, for as long as that first request is in flight. If our side restarts mid-request the key is released at once, so a retry is never stuck behind a request that will never finish.
HTTP/1.1 409 Conflict
Retry-After: 2
{
"status": "error",
"code": 409,
"unique_id": null,
"reference_id": "order-99213",
"details": "A request with this Idempotency-Key is still being processed. Retry in a moment.",
"error": "A request with this Idempotency-Key is still being processed. Retry in a moment.",
"error_code": "idempotency_in_progress",
"retry_after_sec": 2
}The same key with a different request body returns HTTP 422 with error_code: "idempotency_conflict". A new request needs a new key.
And a repeat of a key whose first answer was an unknown outcome replays that answer with a second sentence appended, spelling out what to do before you dial again:
{
"status": "error",
"code": 502,
"unique_id": null,
"reference_id": "order-99213",
"details": "Could not place the call right now. Please retry. The call may or may not have been placed. Check the call with GET /calls/{unique_id} before retrying, or retry with a new Idempotency-Key.",
"error": "Could not place the call right now. Please retry. The call may or may not have been placed. Check the call with GET /calls/{unique_id} before retrying, or retry with a new Idempotency-Key.",
"error_code": "call_state_unknown"
}reference_id remains a correlation echo only; it never de-duplicates anything. Use the Idempotency-Key header for retry safety and reference_id to match calls back to your records.
id (evt_...) you can use to ignore repeats. See Ordering and idempotency in the webhook reference.Campaign webhooks
A campaign can push its own results to a URL of yours. You set that URL on the campaign in your dashboard, and it belongs to that campaign alone. It is separate from the account-level Telephony Webhooks, which cover every call on the account and have their own endpoints, retry schedule and delivery log. Campaign webhooks report campaign work: one event when an attempt on a contact is final, and one when a team member sets a disposition.
Campaigns you run from the dashboard fire these events. A campaign you start through Trigger a saved campaign does not: every API trigger runs as its own child of the campaign, and those children do not inherit the campaign's webhook URL. For API-driven calls, use the account-level Telephony Webhooks instead.
The two events
| Event | When it is sent |
|---|---|
| campaign.attempt_end | One per contact, when the attempt on that contact is final. Never on a retry, so a contact you dial three times produces one event, at the end. |
| campaign.disposition_set | When a team member sets a disposition on a call from this campaign. |
Headers
| Header | Type | Description |
|---|---|---|
| Content-Type | string | The body is always JSON. Example: application/json |
| User-Agent | string | Fixed, and the same string campaign webhooks have always sent, so an allow-list built on it keeps working. Do not use it as proof the event is ours: check X-Agentive-Signature-V2 for that.Example: agentive-voice-webhook/1.0 |
| X-Agentive-Event | string | The dotted event name, the same value as type in the body, so you can route without parsing the body first.Example: campaign.attempt_end |
| X-Agentive-Event-Id | string | The same value as id in the body. De-duplicate on it.Example: evt_9f3c1a7b40d25e86c1b4 |
| X-Agentive-Timestamp | string | Unix seconds at the moment we sent the event, alongside created in the body. It is stamped once per event, so a retry carries the same value as the first attempt, and it can be a second later than created. Do not treat the two as byte-equal.Example: 1780589528 |
| X-Agentive-Signature | string | The older, body-only signature: sha256= followed by the hex HMAC-SHA256 of the raw body, keyed with your account's webhook signing secret. It is still sent for receivers built before version 2, but it cannot prove when a body was sent, so do not accept it on its own. The secret is shown on the campaign page and is shared with your call menu key press webhook, so one account has one secret and one verification routine. Both signature headers are absent only when the account has no signing secret, which happens only on a database fault, so an unsigned delivery is never a normal one. See Verifying the signature.Example: sha256=4f1d...08e9 |
| X-Agentive-Signature-V2 | string | t= the same Unix seconds as X-Agentive-Timestamp, a comma, then v2= the hex HMAC-SHA256 of the timestamp, a dot and the raw body (t + "." + body), keyed with the same secret. Version 1 signs the body alone, so it is the same however many times the event is sent; version 2 binds the timestamp into what is signed, which is what makes a replay window mean anything. Verify this one only, reject a t more than five minutes from your clock, and refuse a delivery without it. See Verifying the signature.Example: t=1780589528,v2=9c41...7e05 |
campaign.attempt_end
Payload
| Field | Type | Description |
|---|---|---|
| id | string | The event id ( evt_ and 20 hex characters). Stable for this event. De-duplicate on it. The sample the Test button sends is prefixed evt_test_ instead, so it can never collide with a real event id. |
| type | string | The dotted event name, campaign.attempt_end. Branch on this. |
| event | string | The legacy name, which keeps the value attempt_end so existing handlers keep working. |
| created | number | Unix seconds at the moment we sent the event. |
| timestamp_ist | string | The same instant in Indian Standard Time, ISO 8601 with milliseconds and a +05:30 offset. Example: 2026-06-04T21:42:08.412+05:30 |
| test | boolean | false on a real attempt, true only for the sample the Test button on the campaign page sends. |
| org_id | number | Your account id. |
| campaign | object | id, name, mode (the pacing mode), dial_type and parent_campaign_id. dial_type is the internal campaign type (broadcast_dtmf, broadcast_audio, human_pool, ai_agent or auth_otp), not the type value that List campaigns returns. |
| contact | object | id, phone, name and email of the contact this attempt dialled. |
| attempt | object | attempt_no, outcome, amd_result, duration_sec, ended_at, call_uuid, disposition and end_reason. The first five are unchanged from the older unsigned payload. end_reason here is the raw carrier hangup cause recorded on the call row (for example NORMAL_CLEARING or USER_BUSY), not the shorter end reason of the call object, and it is null when no cause was recorded. |
| press | object | null | What the recipient chose: digit, action (connect, interest, whatsapp, decline or none) and via (keypad or voice). The whole object is null when nothing was pressed or said, and it is always null on a guided-flow campaign, where the answers are reported in flow_answers instead. action is none when this campaign gives the key no meaning: a recipient can press anything on their handset, and a digit that is not in the campaign's key map does nothing, so it is reported as a keypress that did nothing rather than as the campaign's own action. Handle none as a real value rather than a missing one, and do not create a lead from it. |
| flow_answers | object | null | For a guided flow, the answer to each question keyed q0, q1 and so on, each yes, no or none. none is a question that ran out of retries with no reply, so handle three values, not two. null when the campaign has no flow. |
| object | null | sent, suppressed and error, present only when a WhatsApp message was actually owed for this attempt. null otherwise, which is the common case even on a WhatsApp campaign: the campaign has no WhatsApp action, or the recipient did not choose it. A send that was owed but had not finished by the time we sent the event is still an object, reported as error "pending". |
event field keeps the value attempt_end. Branch on type for the dotted name.whatsapp is null for one reason only: no WhatsApp message was owed for this attempt. So do not read whatsapp.sent without checking that whatsapp is present. When it is present and sent is false, error names the reason: frequency_suppressed, not_connected, locked, no_template, bad_number, send_refused, network or pending. It is a closed set: send_refused means the message itself was refused, and the wording of that refusal is not published in the event.
pending is the one value that is not a final outcome. It means the send was still in flight when we sent the event: we wait up to 8 seconds after the attempt ends for the message to settle, and past that we report the attempt rather than hold the event back. The message may still go out afterwards, so read the final outcome for that contact on the campaign page.
{
"id": "evt_9f3c1a7b40d25e86c1b4",
"type": "campaign.attempt_end",
"event": "attempt_end",
"created": 1780589528,
"timestamp_ist": "2026-06-04T21:42:08.412+05:30",
"test": false,
"org_id": 42,
"campaign": {
"id": 412,
"name": "Renewal interactive voice",
"mode": "progressive",
"dial_type": "broadcast_dtmf",
"parent_campaign_id": null
},
"contact": {
"id": 90218,
"phone": "+919812345678",
"name": "Neha Sharma",
"email": "neha@example.com"
},
"attempt": {
"attempt_no": 1,
"outcome": "interested",
"amd_result": "HUMAN",
"duration_sec": 24,
"ended_at": "2026-06-04T16:12:08.412Z",
"call_uuid": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"disposition": "interested",
"end_reason": "NORMAL_CLEARING"
},
"press": { "digit": "1", "action": "whatsapp", "via": "keypad" },
"flow_answers": null,
"whatsapp": { "sent": true, "suppressed": false, "error": null }
}campaign.disposition_set
Sent when a team member sets a disposition on a call from this campaign. It carries the same envelope fields (id, type, event, created, timestamp_ist, test and org_id), the same campaign and contact objects as campaign.attempt_end (contact is { "id": null } when the attempt has no contact row), a call object with uuid, disposition, disposition_by and notes, and set_at. Its legacy event value stays disposition_set.
{
"id": "evt_2d70b915ee4a3c68f0a1",
"type": "campaign.disposition_set",
"event": "disposition_set",
"created": 1780590114,
"timestamp_ist": "2026-06-04T21:51:54.077+05:30",
"test": false,
"org_id": 42,
"campaign": {
"id": 412,
"name": "Renewal interactive voice",
"mode": "progressive",
"dial_type": "broadcast_dtmf",
"parent_campaign_id": null
},
"contact": {
"id": 90218,
"phone": "+919812345678",
"name": "Neha Sharma",
"email": "neha@example.com"
},
"call": {
"uuid": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"disposition": "callback",
"disposition_by": 41,
"notes": "Wants a call back on Monday"
},
"set_at": "2026-06-04T16:21:54.077Z"
}Verifying the signature
Verify before you trust an event, using X-Agentive-Signature-V2 only. It carries t=<unix seconds>,v2=<hex>. Split it on the comma, take the value of t, and reject the event if t is more than five minutes from your own clock. Then compute the HMAC-SHA256 of the string t, a dot, and the raw request body, keyed with your account's webhook signing secret, hex-encode it and compare it to v2 with a timing-safe comparison, after checking the two are the same length in bytes. Parse the body only after the comparison passes, and read the raw bytes rather than a re-serialised object: any change to spacing or key order changes the signature.
Refuse a delivery that has no version 2 header, and do not fall back to X-Agentive-Signature. That older header signs the body alone, so anyone who captured one delivery could send the same body again later with a fresh timestamp and it would still check out; version 2 puts the timestamp inside what is signed, so the five minute window holds. Every delivery carries both headers, so a version 2 only receiver misses nothing. Never run the check with an empty secret: the samples refuse to start without one.
import crypto from "crypto";
import express from "express";
const app = express();
// Capture the RAW body: the signature covers the exact bytes we sent.
app.use("/webhooks/agentive-campaign", express.raw({ type: "application/json" }));
const TOLERANCE_SEC = 300; // reject anything older than five minutes
// Compare byte lengths first: timingSafeEqual throws on unequal lengths, and a
// multi-byte character can make two strings of equal length differ in bytes.
function safeEqual(a, b) {
const x = Buffer.from(String(a), "utf8");
const y = Buffer.from(String(b), "utf8");
return x.length === y.length && crypto.timingSafeEqual(x, y);
}
// Version 2: t=<unix seconds>,v2=<hex>. HMAC-SHA256 over t, a dot, then the raw body.
function verifyV2(secret, rawBody, header) {
if (!secret) return false; // never verify with an empty key
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");
return safeEqual(parts.v2, expected);
}
// Version 2 only. A delivery without X-Agentive-Signature-V2 is refused: the
// older X-Agentive-Signature signs the body alone and cannot prove freshness.
function verifySignature(secret, rawBody, headers) {
return verifyV2(secret, rawBody, headers["x-agentive-signature-v2"]);
}
const SECRET = process.env.AGENTIVE_WEBHOOK_SECRET;
if (!SECRET) throw new Error("AGENTIVE_WEBHOOK_SECRET is not set");
app.post("/webhooks/agentive-campaign", (req, res) => {
if (!verifySignature(SECRET, req.body, req.headers)) {
return res.status(401).send("bad signature");
}
const evt = JSON.parse(req.body.toString("utf8"));
// De-duplicate on evt.id, then branch on evt.type.
if (evt.type === "campaign.attempt_end") {
console.log(evt.contact.phone, evt.attempt.outcome, evt.whatsapp?.sent);
} else if (evt.type === "ivr.keypress") {
// from_number is the caller's number as the carrier presented it:
// match on its last ten digits.
console.log(evt.data.from_number.slice(-10), evt.data.key_path, evt.data.key_label);
}
res.sendStatus(200);
});
app.listen(3000);Delivery
We POST once and retry once more after 2 seconds if your endpoint returns 5xx, does not answer within 6 seconds, or cannot be reached at all. A 4xx is not retried. Only a 2xx counts as delivered. There is no delivery log for campaign webhooks; the campaign page shows the last delivery result and a Test button that sends one signed sample with test: true.
So answer with any 2xx as soon as you have stored the event, and do your own work afterwards. Because an event can arrive twice, key your handler on id.
Since 17 October 2026 these webhooks come from one IPv4 address, 139.59.48.158, the same as the account webhooks. If your firewall accepts HTTPS only from known sources, allow this address. We will tell you at least 30 days before this address changes, by email to your account admins and in the webhook 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: these webhooks keep their own few quick attempts (the one retry above). See where webhooks come from for the details and the one exception. The address says where a request came from, not that it is ours: still verify the signature.
Redirects. We follow at most one. If your address answers 3xx we read Location, resolve it against the address we called, and put the result through the same address check every delivery makes: it must be a public http or https address. When it passes we repeat the same POST to it, with the same headers and the same signed body, so what you receive still verifies. Anything else ends the delivery, and it is not retried: a Location we cannot deliver to, a 3xx that gives us no usable Location, or a second redirect. The campaign page names which of the three it was. Each request gets its own 6 second window, so a followed redirect does not eat the first request's time.
Save the final address rather than one that redirects. A hop costs a round trip on every event, and any change to where it points stops delivery until you update the campaign.
Call menu key press webhook
A call menu can post every key a caller presses to a URL of yours: one event per key press, as the caller moves through the menu. The event is sent off the call path. The caller is already on their way to the department, the message or the WhatsApp template that key leads to, and a slow or failing endpoint never delays the call.
You set the URL on the call menu itself, under Call menu > Advanced > Key press webhook. The same page shows your account's webhook signing secret, which this hook shares with campaign webhooks: one account, one secret, one verification routine. It is not one of the events on the account-level Telephony Webhooks page, and it does not appear in that delivery log.
ivr.keypress
Payload
| Field | Type | Description |
|---|---|---|
| id | string | The event id ( evt_ and 20 hex characters). Stable for this event. De-duplicate on it. The sample the Test button sends is prefixed evt_test_ instead, so it can never collide with a real event id. |
| type | string | The dotted event name, ivr.keypress. Branch on this. |
| event | string | The same value, ivr.keypress, kept alongside type for a handler that reads event. |
| created | number | Unix seconds at the moment we sent the event, the same value as X-Agentive-Timestamp. |
| timestamp_ist | string | The same instant in Indian Standard Time, ISO 8601 with milliseconds and a +05:30 offset. Example: 2026-06-04T22:12:22.518+05:30 |
| test | boolean | false on a real key press, true only for the sample the Test button on the call menu page sends. |
| data | object | The key press. Its fields are in the next table. |
The data object
| Field | Type | Description |
|---|---|---|
| call_uuid | string | The call the key was pressed on, as the uuid on its call record. All zeros on the test sample. Example: c7d2e1f0-4a3b-4c5d-8e9f-0a1b2c3d4e5f |
| from_number | string | The number the caller called from, as the carrier presented it. It can arrive as +91 and ten digits, 91 and ten digits, 0091 and ten digits, 0 and ten digits, or the ten digits alone (today the wire carries 91 and the ten digits), so match on the last ten digits rather than on the whole string. +919876543210 on the test sample.Example: 919812345678 |
| to_number | string | The number the caller dialled, as the carrier presented it and the edge passed it on (whitespace trimmed). Today that is 91 and the ten digits. Never match on the whole string; match on the last ten digits. On the test sample only it is your account's first number in the stored national form (0 and the ten digits), or empty when the account holds no number yet.Example: 911100000042 |
| flow_id | number | The id of the call menu the key was pressed on. Example: 128 |
| flow_name | string | The name of that call menu, as shown in your dashboard. Example: Main office menu |
| key_path | string | Which key was pressed. On the main menu it is the digit alone, for example 1. On a sub-menu the path is dash-joined from the top, so 2-1 is key 1 on the menu that key 2 opened. One event is sent for each press, so a caller who reaches 2-1 produces an event for 2 and then one for 2-1. 1 on the test sample.Example: 2-1 |
| key_label | string | The label you gave that key on the call menu. Empty when the key has no label. Sales on the test sample.Example: Support |
{
"id": "evt_5b8e02d94c17a3f6e0d2",
"type": "ivr.keypress",
"event": "ivr.keypress",
"created": 1780591342,
"timestamp_ist": "2026-06-04T22:12:22.518+05:30",
"test": false,
"data": {
"call_uuid": "c7d2e1f0-4a3b-4c5d-8e9f-0a1b2c3d4e5f",
"from_number": "919812345678",
"to_number": "911100000042",
"flow_id": 128,
"flow_name": "Main office menu",
"key_path": "2-1",
"key_label": "Support"
}
}The test sample
The Test button on the call menu page sends one signed sample to the address in the box (whether or not it has been saved yet) so you can check your receiver end to end. It is the same body with test true, an id prefixed evt_test_, a call_uuid of all zeros, the caller +919876543210, to_number your account's first number (or empty if you have not chosen one yet), and key 1 labelled Sales. It is one attempt with an 8 second window, and it does not touch the last delivery result shown on the page.
{
"id": "evt_test_3a9c5e17b0d4f2861c7e",
"type": "ivr.keypress",
"event": "ivr.keypress",
"created": 1780591402,
"timestamp_ist": "2026-06-04T22:13:22.000+05:30",
"test": true,
"data": {
"call_uuid": "00000000-0000-0000-0000-000000000000",
"from_number": "+919876543210",
"to_number": "01100000042",
"flow_id": 128,
"flow_name": "Main office menu",
"key_path": "1",
"key_label": "Sales"
}
}Headers, verification and delivery
- Headers. The same set as a campaign webhook, including both signatures. See Headers.
- Verification. The same secret and the same routine: HMAC-SHA256 of the raw body for version 1, and of the timestamp, a dot and the raw body for version 2. See Verifying the signature.
- Delivery. The same rule: one POST, one retry after 2 seconds on a 5xx, a timeout or an unreachable address, a 4xx is final, only a 2xx counts, and at most one redirect is followed. See Delivery. The call menu page shows the last delivery result: the time, the HTTP status or that there was no answer, and the reason when it failed. Since 17 October 2026 these webhooks come from one IPv4 address,
139.59.48.158, the same as the account webhooks, and we will tell you at least 30 days before it changes; see where webhooks come from. Still verify the signature.
Voice OTP
Sending a one-time code over a phone call and verifying what the recipient enters is documented in its own reference, the Voice OTP API. It uses the same base URL, credentials, envelope, error codes and rate limits as this page and adds two endpoints:
POST /otp/sendplaces a call that reads the code out and returns arequest_id.POST /otp/verifychecks the code the recipient gives you, with expiry and attempt limits handled for you.
The otp type on Place a call is a shortcut to the same verification call.
Quick start
- Copy your credentialsOpen the API tab in your Voice dashboard and copy your publishable key and secret. Reveal the secret once and store it securely.
- Pick an audio clipUpload or choose a clip in your audio library and note its id.
- Place a test call to your own numbercURL
curl 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": "98XXXXXXXX", "campaign_id": 4821, "reference_id": "test-1" }' - Poll the resultNote the
unique_idfrom the response and check its status:cURLcurl https://voice.agentive.co.in/api/public/v1/calls/run_XXXX \ -H "x-api-key: pk_live_..." \ -H "x-api-secret: sk_live_..." - Go event-drivenTo receive call results automatically instead of polling, set up a webhook. Then send an Idempotency-Key on every billed request before you go live.
Next steps
Continue with the references that share this base URL and account.