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.
Billing
All calls are billed in INR against your account balance. Voice broadcast, Interactive Voice and verification calls bill at your account's rate, with a one-minute minimum per answered call and per-second billing after the first minute. Interactive Voice calls that accept spoken responses carry a small per-minute surcharge. Check your balance any time with Get account balance.
One base URL, four references
This page covers calls, campaigns, call history, recordings and balance. Verification codes have their own reference, the Voice OTP API, AI voice agent calls have the AI Voice Agent API, and real-time call events are delivered by Telephony Webhooks instead of polling. All four share the base URL, credentials, envelope, error codes and rate limits described here.
API access is enabled per account
If you get a 403 saying the API is not enabled, contact support. Each endpoint also requires its product to be enabled on your account: the call and campaign endpoints need the voice broadcast features, recording download needs call recording, and voicemail downloads need the Telephony API and voicemail. A request against a product that is not enabled returns HTTP 403 with "This feature is not enabled for your account."

Platform conventions

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

Base URLs

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

Authentication

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

Error envelope

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

401 and 403

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

Idempotency

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

Rate limits and headers

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

Webhook signing

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

Webhook delivery headers

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

Webhook retries

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

Timestamps and amounts

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

Versioning and field case

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

Security

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

Base URL

Every endpoint path on this page is relative to this base URL. The Voice OTP API uses the same base.

Base URL
https://api.agentive.co.in/api/public/v1

Since 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.

CredentialWhat it isHow to send it
Publishable keyNames 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 keyYour 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-menus and everything under them) refuse a secret field in the JSON body with HTTP 400, error_code validation_error, field secret, retryable false, even when the x-api-secret header is sent too. Send the secret in the x-api-secret header 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 no secret gets no such header.

Example: authenticated request

cURL
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
curl https://voice.agentive.co.in/api/public/v1/account \
  -u pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx:sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Keep the secret server-side
Never embed the secret key in a browser, mobile app, or any client a customer can inspect. All requests must be over HTTPS: always write https://. 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_code ip_not_allowed; details names 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: call https://api.agentive.co.in/api/public/v1 from 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.
403 from an address not on the list
{
  "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

StatusCodeerror_codeWhen
401401missing_credentialsNo publishable key sent.details: "Missing API key. Send your publishable key in the x-api-key header."
401401invalid_credentialsUnknown publishable key.details: "Invalid API credentials."
401401invalid_credentialsKnown key, wrong or missing secret.details: "Invalid API credentials."
403403account_inactiveAccount is not active.details: "This account is not active. Please contact support."
403403api_disabledAPI access not enabled for the account.details: "The API is not enabled for this account. Please contact support."
403403feature_disabledThe 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.

Changed in September 2026
A known publishable key sent with a wrong secret used to return HTTP 403. It now returns 401, with the same "Invalid API credentials." sentence. If your client branches on 403 to mean "bad secret", move that branch to 401. Nothing else about the response changed.

Response format

Every response is JSON and uses one consistent envelope.

JSON
{
  "status": "success",
  "code": 200,
  "unique_id": "run_4821",
  "reference_id": "order-99213",
  "details": "Call queued."
}

Envelope fields

FieldTypeDescription
statusstring
"success" or "error".
codenumber
A numeric result code. Mirrors the HTTP status (see Error codes).
unique_idstring | null
Our identifier for the resource created by this call. Use it with Get call status.
reference_idstring | null
Echoes the reference_id you sent, so you can correlate the response with your own records. null if you did not send one.
detailsstring
A short human-readable description of the result.
error_codestring
Error responses only. A stable machine string naming the exact condition. Branch on this rather than on details. See Error codes.
errorstring
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).

HTTP status
A successful request returns HTTP 200 with 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.

HTTPMeaningWhen it happens
200SuccessThe request was accepted.
400Bad requestA 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).
401UnauthorizedThe credentials were rejected: no key, an unknown key, or a wrong secret. On POST /otp/verify it also reports an incorrect code.
402Balance too lowYour balance cannot cover the call. Nothing was created. Top up and retry.
403ForbiddenThe 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).
404Not foundThe 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.
409ConflictOutside 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.
415Unsupported bodyThe 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).
422Idempotency key reuseThe same Idempotency-Key was sent with a different request body. A new request needs a new key.
429Too many requestsA limit was hit: your request budget, a per-number cap, a daily cap, or your account's lines. Every 429 carries Retry-After.
502Upstream problemWe could not place the call. If we do not know whether it went out, error_code is call_state_unknown.
503Temporarily unavailableBriefly unavailable on our side. Safe to retry after Retry-After.
503Phone network busyerror_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_codeHTTPMeans
missing_credentials401No publishable key was sent.
invalid_credentials401The key is unknown, or the secret does not match it.
account_inactive403The account is not active.
api_disabled403API access is not enabled for the account.
feature_disabled403The product this endpoint belongs to is not enabled.
validation_error400, 422A field is missing, unknown or unusable.
invalid_number400The destination is not a valid Indian mobile number, or (since 17 October 2026) carries another country code.
invalid_caller_id400caller_id is not yours, or is not enabled for voice broadcast.
invalid_code400A supplied verification code is not 4 to 8 digits.
calling_hours409Outside the 9:00 AM to 9:00 PM IST window.
idempotency_in_progress409The first request with this key is still running.
idempotency_conflict422This key was used with a different body.
rate_limited429Your per-minute request budget is spent.
number_flood429Too many calls to one destination number.
daily_cap429POST /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_limit429Your account has no free line.
ai_concurrency_limit409Your AI call channels are all busy.
whatsapp_locked403The campaign sends a WhatsApp message and WhatsApp is not on your plan.
whatsapp_not_connected409No WhatsApp account is connected to this account yet.
whatsapp_template_required400The campaign has no WhatsApp account and approved template saved on it.
number_locked429Too many wrong codes for this number; send and verify are locked for it.
insufficient_balance402Your balance cannot cover the call.
not_found404No such resource on your account.
recording_expired404The recording passed your plan's retention and is no longer available.
voicemail_expired404The voicemail passed your retention and is no longer available.
invalid_cursor400A cursor sent with different filters, or one that is not ours.
updated_since_too_old400updated_since is earlier than the start of the change feed.
conflict409A state conflict with no more specific name. Read details and Retry-After.
upstream_error502We could not place the call, and it was not placed.
call_state_unknown502We asked the network to place the call and lost track of it.
service_unavailable503Briefly unavailable on our side, or your calling-hours setting could not be read (retry_after_sec 30); nothing was placed.
network_busy503Every line of the phone network your calling number uses is in use. Nothing was placed; retry after Retry-After (15 seconds).
ip_not_allowed403Your 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_required403The 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_converting503The 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_failed500This 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_link401A recording link that is not ours, or was changed. Since 17 October 2026.
link_expired403The recording link is past its expiry. Create a new link. Since 17 October 2026.
link_revoked403The 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

JSON
{
  "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.

LimitWindowScopeerror_codeRetry-After
240 failed requests1 minuteClient addressrate_limitedUp 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 checks1 minutePublishable key and client addressrate_limitedUp 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 requests1 minuteAccountrate_limitedUp to 60 seconds.
120 write requests1 minuteAccountrate_limitedUp to 60 seconds. Counted separately from reads, so a polling loop can never starve call placement.
120 recording and voicemail downloads1 minuteAccountrate_limitedUp 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 plays1 minuteAccountrate_limitedPlaying 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 matched1 minuteKeyrate_limitedSince 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 number10 minutesAccount and destination numbernumber_floodUp to 600 seconds.
Your linesWhile calls are liveAccountconcurrency_limit5 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.

Headers on every response
RateLimit-Limit: 120
RateLimit-Remaining: 117
RateLimit-Reset: 41
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 41

When you exceed a request limit you receive HTTP 429 with:

JSON
{
  "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.

Headers on a call-placing response
X-Agentive-Lines: 10
X-Agentive-Lines-In-Use: 2
HTTP
HTTP/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
}
What queued means
A call reported as 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.

Per-number call cap
All calls placed through the API to the same destination number (broadcast, Interactive Voice and verification calls alike) are capped at 3 calls per 10 minutes per account. Exceeding it returns HTTP 429 with error_code: "number_flood". A 429 always means wait; only 502 and 503 are safe to retry straight away.
Verification calls carry more limits
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.

EndpointPurpose
POST /callsPlace a recorded, Interactive Voice or verification call to one number.
POST /campaigns/:id/triggerRun a saved campaign for one number.
GET /calls/:unique_idPoll the status of a call you placed.
GET /callsPage through your call history with filters.
GET /calls/:unique_id/recordingDownload a call recording, or one of its parts.
GET /calls/:unique_id/voicemailDownload the voicemail a caller left (Telephony API).
POST /calls/:unique_id/recording-linkCreate a 10-minute link a browser plays without your keys.
GET /recording-links/:tokenPlay a recording link, with no key.
GET /calls/:unique_id/transcriptRead a transcribed team call (Telephony API with call transcription).
GET /campaignsList the campaigns you can trigger.
GET /accountRead your balance in INR, your lines and your products.

Place a call

POST/calls

Place 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

HeaderTypeRequiredDescription
x-api-keystringRequired
Your publishable key (pk_live_...). See Authentication.
x-api-secretstringRequired
Your secret key (sk_live_...). Keep it server-side.
Content-TypestringRequired
Always application/json.
Idempotency-KeystringOptional
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

FieldTypeRequiredDescription
typestringRequired
One of audio_blast, press1, otp. See Call types.
Example: audio_blast
numberstringRequired
The recipient's Indian mobile number. See Phone number format.
Example: 9812345678
campaign_idnumberRequired
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
codestringOptional
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.
lengthnumberOptional
Not accepted with otp: the code length is set on your authentication campaign. Sending it answers 400 validation_error.
ttlnumberOptional
Not accepted with otp: how long the code stays valid is set on your authentication campaign. Sending it answers 400 validation_error.
max_attemptsnumberOptional
otp only. Verify attempts allowed for this code. Default 3. Values outside 1 to 10 are clamped into range.
messagestringOptional
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_idstringOptional
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)

JSON
{
  "status": "success",
  "code": 200,
  "unique_id": "run_4821",
  "reference_id": "order-99213",
  "details": "Call queued."
}

Errors

StatusCodeerror_codeWhenWhat to do
400400invalid_numbernumber 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.
400400invalid_numbernumber 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.
400400validation_errortype 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.
404404not_foundThe 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.
400400validation_errorThe 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.
400400validation_errorThe 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.
400400invalid_caller_idWhat 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.
400400invalid_codetype: "otp" with a code that is not 4 to 8 digits.Send 4 to 8 digits, or omit code and let one be generated.
401401invalid_credentialsThe 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.
402402insufficient_balanceYour 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.
403403feature_disabledVoice broadcast is not enabled for your account.details: "This feature is not enabled for your account."Contact support to enable it.
409409calling_hoursThe 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.
409409idempotency_in_progressA request with the same Idempotency-Key is still being processed.Wait for Retry-After (2 seconds) and retry with the same key.
422422idempotency_conflictThe same Idempotency-Key was sent with a different request body.Use a fresh key for a new request.
429429rate_limitedYou went past your account's per-minute request budget.Retry-After is up to 60 seconds. Pace with the RateLimit headers.
429429number_floodMore than 3 calls to this destination number in 10 minutes.Retry-After is up to 600 seconds.
429429concurrency_limitYour 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.
502502upstream_errorThe 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.
502502call_state_unknownWe 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.
503503service_unavailableThe 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.
503503network_busyEvery 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

typeWhat it doesRequired fields
audio_blastPlays the campaign's recording to the number, then ends.number, campaign_id
press1Places 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
otpPlaces 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

JSON
{
  "type": "press1",
  "number": "9812345678",
  "campaign_id": 4822,
  "reference_id": "promo-march"
}
The campaign is the configuration
A broadcast or Interactive Voice call is always a campaign's call. The recording, the caller number, what each keypress does and every other setting live on the campaign you name in 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.

Retries are safe with an Idempotency-Key
This endpoint accepts an 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

POST/campaigns/:id/trigger

Run 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

HeaderTypeRequiredDescription
x-api-keystringRequired
Your publishable key (pk_live_...). See Authentication.
x-api-secretstringRequired
Your secret key (sk_live_...). Keep it server-side.
Content-TypestringRequired
Always application/json.
Idempotency-KeystringOptional
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

ParameterTypeRequiredDescription
idnumberRequired
The numeric id of the campaign to trigger. Find it with List campaigns.
Example: 57

Request body

FieldTypeRequiredDescription
numberstringRequired
The recipient's Indian mobile number. See Phone number format.
Example: 9812345678
reference_idstringOptional
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

JSON
{
  "status": "success",
  "code": 200,
  "unique_id": "run_4822",
  "reference_id": "lead-5567",
  "details": "Call queued."
}

Errors

StatusCodeerror_codeWhenWhat to do
400400invalid_numbernumber 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.
400400invalid_numbernumber 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.
404404not_foundThe campaign id does not exist on your account, or is not an API campaign.details: "Campaign not found."Pick an id from List campaigns.
400400validation_errorThe 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.
400400validation_errorThe 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.
400400validation_errorThe 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.
400400validation_errorThe 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.
400400validation_errorThe campaign has no audio clip configured.details: "This campaign has no audio configured."Attach an audio clip to the campaign in the dashboard.
400400validation_errorAn 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.
409409ai_concurrency_limitAn 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.
403403whatsapp_lockedThe 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.
409409whatsapp_not_connectedThe 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.
400400whatsapp_template_requiredThe 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.
503503network_busyEvery 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

GET/calls/:unique_id

Read 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

ParameterTypeRequiredDescription
unique_idstringRequired
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)

JSON
{
  "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

FieldTypeDescription
call_statusstring
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_secnumber | null
The call record's length in seconds (on a run, 0 for a call that did not connect).
call_idstring | null
Our record id for the call this run placed. Use it for that leg's recording.
end_reasonstring | 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_idstring | null
The reference_id you sent when you placed the call.
callobject | null
The full call object with the enumerated status and end_reason values, once the call exists.

Errors

StatusCodeerror_codeWhenWhat to do
404404not_foundThe 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:

JSON
{
  "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

FieldTypeDescription
duration_secnumber | 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_idnumber | 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_availableboolean
Whether this key can fetch a transcript of the call with GET /calls/:unique_id/transcript.
via_api, metadata, charge_inrmixed
As on the call object: placed through the API, the metadata you sent, and what the call cost your balance.
analysis_availableboolean
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.

JSON
{
  "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.

Listing calls in bulk
This endpoint reports a single call you started. To page through your call history (including inbound calls), use List calls, which returns the richer call object with the enumerated status and end_reason values.

List calls

GET/calls

Page 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

ParameterTypeRequiredDescription
pagenumberOptional
The page of results to return. Default 1. Not with cursor or updated_since.
per_pagenumberOptional
Results per page. Default 50, maximum 100.
directionstringOptional
Filter by inbound or outbound.
statusstringOptional
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.
fromstringOptional
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
tostringOptional
Include calls created before this ISO 8601 date or timestamp, read like from.
Example: 2026-06-30T23:59:59+05:30
numberstringOptional
Match calls where this number appears as either the caller or the recipient.
Example: 9812345678
orderstringOptional
Telephony API. desc (the default, newest first) or asc. asc pages with a cursor.
cursorstringOptional
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_sincestringOptional
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_idnumberOptional
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_idstringOptional
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_idstringOptional
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).
lanestringOptional
Telephony API. One lane, for example menu or sim.
has_recordingbooleanOptional
Telephony API. true for calls with a stored recording, false for the rest.
end_detailstringOptional
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)

JSON
{
  "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

FieldTypeDescription
dataobject[]
A page of call objects.
pagination.page, total, total_pagesnumber | 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_pagenumber
Results per page for this response.
pagination.has_moreboolean
Telephony API. Whether another page follows.
pagination.next_cursorstring | 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.watermarkstring
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.
warningsobject[]
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)

JSON
{
  "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"
  }
}
Unknown parameters are reported, and will be refused
A query parameter this route does not know used to be ignored silently, which returned an unfiltered page that looked like an answer. It is now reported in 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

GET/calls/:unique_id/recording

Download 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

ParameterTypeRequiredDescription
unique_idstringRequired
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

ParameterTypeRequiredDescription
segmentnumberOptional
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
formatstringOptional
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.ogg

Response (no recording available)

JSON
{
  "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

StatusCodeerror_codeWhenWhat to do
404404not_foundThe 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.
404404not_foundNo 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.
403403feature_disabledCall recording is not enabled for your account.details: "This feature is not enabled for your account."Contact support to enable call recording.
404404not_foundThe call has no part with that segment number.details: "Segment not found."Read recording.parts for the segments that exist.
404404recording_expiredPast 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.
416416validation_errorThe 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.
400400validation_errorformat 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.
422422validation_errorThe recording is too long to convert (field format; since 17 October 2026).Omit format.
500500conversion_failedThe recording cannot be converted to that format (retryable: false; since 17 October 2026).Omit format.
502502upstream_errorThe 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.
503503recording_convertingThe 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.
503503service_unavailableThe 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.
An earlier part
# 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
Response (past the recording's retention)
{
  "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_layout still 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_converting with a Retry-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.
  • Range works 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 format waits 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 503 recording_converting with a Retry-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 503 service_unavailable (retryable: true): retry a little later. A download without format is 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 500 conversion_failed (retryable: false). Omit format for either.
As MP3
# --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.mp3
Get notified when it is ready
A recording is complete about a minute after its last part is stored. To be notified the moment it is, subscribe to the recording.available webhook, which carries this endpoint's address as recording_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.
A call moved to a call menu
A call your team placed and then moved to a call menu is usually two calls: its own recording ends at the move, and the call menu part (a team member who answers inside the menu included) is a call of its own (lane 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

GET/calls/:unique_id/voicemail

Telephony 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

ParameterTypeRequiredDescription
unique_idstringRequired
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

ParameterTypeRequiredDescription
formatstringOptional
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.ogg

Response (no voicemail on the call)

JSON
{
  "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

StatusCodeerror_codeWhenWhat to do
404404not_foundThe caller left no message (or the id is not a call of your account).details: "No voicemail was left on this call."
404404voicemail_expiredThe message is past its expires_at and is no longer available.Copy voicemails before expires_at.
403403feature_disabledThe key is not a Telephony API key, or voicemail is not on your account.details: "This feature is not enabled for your account."
416416validation_errorThe 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.
As MP3
# --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.mp3

Get a team call transcript

GET/calls/:unique_id/transcript

Telephony 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

ParameterTypeRequiredDescription
unique_idstringRequired
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
curl "https://voice.agentive.co.in/api/public/v1/calls/7f0c2a9e-4b1d-4c3e-9a7f-1d2e3f4a5b6c/transcript" \
  -u "$AGENTIVE_KEY:$AGENTIVE_SECRET"

Response

JSON
{
  "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

FieldTypeDescription
data.unique_id, call_id, leg_idstring
The call's ids.
data.turns[].rolestring
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[].textstring
What was said.
data.turns[].speakernumber | null
The speaker's number on a speaker turn, else null.
data.languagestring | null
The language the transcription found.
data.created_at, created_at_iststring
When the transcript was made.

List campaigns

GET/campaigns

List 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

JSON
{
  "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

FieldTypeDescription
idnumber
The campaign id. Use it with Trigger a saved campaign.
namestring
The name you gave the campaign.
typestring
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.
statusstring
The campaign's current state.
press1_actionstring | null
For press1 campaigns: connect, interest or whatsapp. null for other types.

Get account balance

GET/account

Return 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

JSON
{
  "status": "success",
  "code": 200,
  "data": {
    "balance_inr": 1842.5,
    "currency": "INR",
    "lines": 10,
    "lines_in_use": 2
  }
}

Response fields

FieldTypeDescription
data.balance_inrnumber | null
Your current wallet balance, in Indian Rupees. null when the wallet is not on your account (it used to answer 403).
data.currencystring
Always "INR".
data.linesnumber
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_usenumber
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

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

Outcome

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

People

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

Numbers

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

Times and durations

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

Recording, outcome and routing

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

Charge, transcripts and ordering

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

recording

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

recording.status

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

recording.parts[]

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

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

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

disposition (null when nothing was saved)

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

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

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

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

ring_attempts[]

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

ring_attempts[].result

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

transfers[]

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

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.

  1. Backfill once
    Note the time, then read your history in one day windows: GET /calls?from=2026-10-01&to=2026-10-02&order=asc, following pagination.next_cursor until has_more is false, then the next day. Download recordings with their own budget of 120 a minute as you go.
  2. Follow the change feed
    Every 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 store pagination.watermark and pass it as updated_since next time.
  3. Keep the newest version
    A call can appear in more than one walk, and in a webhook too. Store each call by call_id and apply a copy only when its version is higher than the one you hold.
  4. Add webhooks for speed
    Subscribe to the call events, call.tagged, recording.available and 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
}
Why the feed runs 30 seconds behind
The watermark is 30 seconds behind our clock, and a walk never returns a change newer than its watermark. A change takes a moment to become visible to the feed; the delay means a walk never steps past a change that is still on its way. A webhook usually reaches you before the feed lists the same change.
  • The feed starts on 13 October 2026. Calls that have not changed since then are found with from and to, not with updated_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: 30 during 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)

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

Transitions

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

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

end_reason (set on a terminal status)

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

The pairing, and the event each outcome sends

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

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

end_detail (Telephony API)

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

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

lane (Telephony API)

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

ended_by (Telephony API)

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

network_cause (Telephony API)

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

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

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

The simpler call_status on a run id

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

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

Identifiers

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

The seven ids

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

Ids we generate for delivery

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

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.
A team line is never used
A number your team answers calls on is never used as a broadcast caller ID, even if it is the only number on the account, and even if it was set on the campaign before it became a team line. If that is all you have, ask your account manager for a broadcast number or a rotational pool.

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 (also 91 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.

Mobile numbers only
The mobile number must begin with 6, 7, 8, or 9. Landline and clearly invalid numbers are rejected with HTTP 400 and "A valid Indian mobile number is required."
Indian numbers only
On 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_id field, 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.

Verification codes are the exception
Verification calls (the 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
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.

ResponseStored?What a retry with the same key does
2xxYesReplays the original response. No second call is placed.
400YesReplays 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 verifyYesReplays the incorrect-code response, because the attempt was already spent.
404YesReplays the not-found response for 24 hours. Once the id or the dashboard setting is fixed, send the request with a new key.
422YesReplays the conflict. The key is bound to the first body it saw.
402NoTop up, then resend with the same key. The call is attempted.
403NoOnce the entitlement is in place, resend with the same key.
409NoWait for Retry-After, then resend with the same key.
429NoWait for Retry-After, then resend with the same key.
5xx before we placed the callNoResend with the same key. Nothing was placed.
502 call_state_unknownYesReplays the same answer. Poll GET /calls/:unique_id, or choose a fresh key deliberately.
One case where the same key is not the answer
If a failure happens after we asked the network to place your call, we cannot say whether it went out. That response is stored and replayed as 502 with 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
HTTP/1.1 200 OK
Content-Type: application/json
Idempotent-Replayed: true
idempotency-replayed: true

Reusing 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
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:

JSON
{
  "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.

Webhook events are de-dupable
Each webhook event carries a stable 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

EventWhen it is sent
campaign.attempt_endOne 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_setWhen a team member sets a disposition on a call from this campaign.

Headers

HeaderTypeDescription
Content-Typestring
The body is always JSON.
Example: application/json
User-Agentstring
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-Eventstring
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-Idstring
The same value as id in the body. De-duplicate on it.
Example: evt_9f3c1a7b40d25e86c1b4
X-Agentive-Timestampstring
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-Signaturestring
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-V2string
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

FieldTypeDescription
idstring
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.
typestring
The dotted event name, campaign.attempt_end. Branch on this.
eventstring
The legacy name, which keeps the value attempt_end so existing handlers keep working.
creatednumber
Unix seconds at the moment we sent the event.
timestamp_iststring
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
testboolean
false on a real attempt, true only for the sample the Test button on the campaign page sends.
org_idnumber
Your account id.
campaignobject
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.
contactobject
id, phone, name and email of the contact this attempt dialled.
attemptobject
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.
pressobject | 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_answersobject | 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.
whatsappobject | 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".
Compatibility
The top-level 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.

JSON
{
  "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.

JSON
{
  "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

FieldTypeDescription
idstring
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.
typestring
The dotted event name, ivr.keypress. Branch on this.
eventstring
The same value, ivr.keypress, kept alongside type for a handler that reads event.
creatednumber
Unix seconds at the moment we sent the event, the same value as X-Agentive-Timestamp.
timestamp_iststring
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
testboolean
false on a real key press, true only for the sample the Test button on the call menu page sends.
dataobject
The key press. Its fields are in the next table.

The data object

FieldTypeDescription
call_uuidstring
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_numberstring
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_numberstring
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_idnumber
The id of the call menu the key was pressed on.
Example: 128
flow_namestring
The name of that call menu, as shown in your dashboard.
Example: Main office menu
key_pathstring
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_labelstring
The label you gave that key on the call menu. Empty when the key has no label. Sales on the test sample.
Example: Support
JSON
{
  "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.

JSON
{
  "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/send places a call that reads the code out and returns a request_id.
  • POST /otp/verify checks 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

  1. Copy your credentials
    Open the API tab in your Voice dashboard and copy your publishable key and secret. Reveal the secret once and store it securely.
  2. Pick an audio clip
    Upload or choose a clip in your audio library and note its id.
  3. Place a test call to your own number
    cURL
    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" }'
  4. Poll the result
    Note the unique_id from the response and check its status:
    cURL
    curl https://voice.agentive.co.in/api/public/v1/calls/run_XXXX \
      -H "x-api-key: pk_live_..." \
      -H "x-api-secret: sk_live_..."
  5. Go event-driven
    To 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