Voice Broadcast API

As an alternative to the two headers, you may send the credentials with HTTP Basic auth, using the publishable key as the username and the secret as the password. This is the familiar curl -u form. When an x-api-key header is present it takes precedence; otherwise the Basic credentials are used.

curl https://voice.agentive.co.in/api/public/v1/account \
  -u pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx:sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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 always means the credentials were accepted and the account or the product is not entitled.

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.

Five more appear only on POST /otp/verify: incorrect_code, max_attempts, code_expired, code_used and verification_not_found.

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.

A call your account has no free line for is refused, never queued: HTTP 429 with error_code: "concurrency_limit", lines, lines_in_use and a Retry-After of 5 seconds. That way you always know what happened, instead of waiting on a call that was silently parked.

X-Agentive-Lines: 10
X-Agentive-Lines-In-Use: 2

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
}

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.

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.

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"
  }'

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

{
  "type": "press1",
  "number": "9812345678",
  "campaign_id": 4822,
  "reference_id": "promo-march"
}

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.

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.

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" }'

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

Balance (402), calling-hours and idempotency conflicts (409, 422), rate limits and the line refusal (429) behave exactly as on Place a call. 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."

Check the current state of a call you placed. Pass the unique_id from the placement response. A raw call_id from List calls and a verification request_id both resolve here too, each with its own response shape, all three described below.

curl https://voice.agentive.co.in/api/public/v1/calls/run_4821 \
  -H "x-api-key: pk_live_..." \
  -H "x-api-secret: sk_live_..."

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

{
  "status": "success",
  "code": 200,
  "unique_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "reference_id": "order-99213",
  "details": "completed",
  "call_status": "completed",
  "duration_sec": 42,
  "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-04T21:42:08+05:30",
    "created_at_ist": "2026-06-04T21:42:08+05:30",
    "created_at_utc": "2026-06-04T16:12:08Z",
    "agent_id": null,
    "transcript_available": false,
    "analysis_available": false
  }
}

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.

Page through the calls on your account, most recent first. This returns the full call object for each call, with the enumerated status and end_reason values, so you can reconcile call results in bulk instead of polling each call by id.

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_..."

{
  "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"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 137,
    "total_pages": 3
  }
}

The response carries only the public call object fields. end_reason is always one of the enumerated end reasons.

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

# 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

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

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.

curl https://voice.agentive.co.in/api/public/v1/campaigns \
  -H "x-api-key: pk_live_..." \
  -H "x-api-secret: sk_live_..."

{
  "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 }
  ]
}

Return your account's current wallet balance in INR. Useful as a pre-flight check before a large run. Requires the wallet feature on your account.

curl https://voice.agentive.co.in/api/public/v1/account \
  -H "x-api-key: pk_live_..." \
  -H "x-api-secret: sk_live_..."

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

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.

A replayed response carries two headers with the same meaning: Idempotent-Replayed: true, the platform-wide name, and idempotency-replayed: true, the original one, kept so existing clients keep working.

HTTP/1.1 200 OK
Content-Type: application/json
Idempotent-Replayed: true
idempotency-replayed: 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/1.1 409 Conflict
Retry-After: 2

{
  "status": "error",
  "code": 409,
  "unique_id": null,
  "reference_id": "order-99213",
  "details": "A request with this Idempotency-Key is still being processed. Retry in a moment.",
  "error": "A request with this Idempotency-Key is still being processed. Retry in a moment.",
  "error_code": "idempotency_in_progress",
  "retry_after_sec": 2
}

The same key with a different request body returns HTTP 422 with error_code: "idempotency_conflict". A new request needs a new key.

And a repeat of a key whose first answer was an unknown outcome replays that answer with a second sentence appended, spelling out what to do before you dial again:

{
  "status": "error",
  "code": 502,
  "unique_id": null,
  "reference_id": "order-99213",
  "details": "Could not place the call right now. Please retry. The call may or may not have been placed. Check the call with GET /calls/{unique_id} before retrying, or retry with a new Idempotency-Key.",
  "error": "Could not place the call right now. Please retry. The call may or may not have been placed. Check the call with GET /calls/{unique_id} before retrying, or retry with a new Idempotency-Key.",
  "error_code": "call_state_unknown"
}

whatsapp is null for one reason only: no WhatsApp message was owed for this attempt. So do not read whatsapp.sent without checking that whatsapp is present. When it is present and sent is false, error names the reason: frequency_suppressed, not_connected, locked, no_template, bad_number, send_refused, network or pending. It is a closed set: send_refused means the message itself was refused, and the wording of that refusal is not published in the event.

pending is the one value that is not a final outcome. It means the send was still in flight when we sent the event: we wait up to 8 seconds after the attempt ends for the message to settle, and past that we report the attempt rather than hold the event back. The message may still go out afterwards, so read the final outcome for that contact on the campaign page.

{
  "id": "evt_9f3c1a7b40d25e86c1b4",
  "type": "campaign.attempt_end",
  "event": "attempt_end",
  "created": 1780589528,
  "timestamp_ist": "2026-06-04T21:42:08.412+05:30",
  "test": false,
  "org_id": 42,
  "campaign": {
    "id": 412,
    "name": "Renewal interactive voice",
    "mode": "progressive",
    "dial_type": "broadcast_dtmf",
    "parent_campaign_id": null
  },
  "contact": {
    "id": 90218,
    "phone": "+919812345678",
    "name": "Neha Sharma",
    "email": "neha@example.com"
  },
  "attempt": {
    "attempt_no": 1,
    "outcome": "interested",
    "amd_result": "HUMAN",
    "duration_sec": 24,
    "ended_at": "2026-06-04T16:12:08.412Z",
    "call_uuid": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "disposition": "interested",
    "end_reason": "NORMAL_CLEARING"
  },
  "press": { "digit": "1", "action": "whatsapp", "via": "keypad" },
  "flow_answers": null,
  "whatsapp": { "sent": true, "suppressed": false, "error": null }
}

Sent when a team member sets a disposition on a call from this campaign. It carries the same envelope fields (id, type, event, created, timestamp_ist, test and org_id), the same campaign and contact objects as campaign.attempt_end (contact is { "id": null } when the attempt has no contact row), a call object with uuid, disposition, disposition_by and notes, and set_at. Its legacy event value stays disposition_set.

{
  "id": "evt_2d70b915ee4a3c68f0a1",
  "type": "campaign.disposition_set",
  "event": "disposition_set",
  "created": 1780590114,
  "timestamp_ist": "2026-06-04T21:51:54.077+05:30",
  "test": false,
  "org_id": 42,
  "campaign": {
    "id": 412,
    "name": "Renewal interactive voice",
    "mode": "progressive",
    "dial_type": "broadcast_dtmf",
    "parent_campaign_id": null
  },
  "contact": {
    "id": 90218,
    "phone": "+919812345678",
    "name": "Neha Sharma",
    "email": "neha@example.com"
  },
  "call": {
    "uuid": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "disposition": "callback",
    "disposition_by": 41,
    "notes": "Wants a call back on Monday"
  },
  "set_at": "2026-06-04T16:21:54.077Z"
}

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);

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.

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.

The Test button on the call menu page sends one signed sample to the address in the box (whether or not it has been saved yet) so you can check your receiver end to end. It is the same body with test true, an id prefixed evt_test_, a call_uuid of all zeros, the caller +919876543210, to_number your account's first number (or empty if you have not chosen one yet), and key 1 labelled Sales. It is one attempt with an 8 second window, and it does not touch the last delivery result shown on the page.

{
  "id": "evt_test_3a9c5e17b0d4f2861c7e",
  "type": "ivr.keypress",
  "event": "ivr.keypress",
  "created": 1780591402,
  "timestamp_ist": "2026-06-04T22:13:22.000+05:30",
  "test": true,
  "data": {
    "call_uuid": "00000000-0000-0000-0000-000000000000",
    "from_number": "+919876543210",
    "to_number": "01100000042",
    "flow_id": 128,
    "flow_name": "Main office menu",
    "key_path": "1",
    "key_label": "Sales"
  }
}

• Headers. 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.