Developers / Self-service APIAll pages
Developers

Self-service API

Let callers do things themselves in your IVR (activate a card, hear a balance, check the next appointment), answered by your own system during the call. Voip9 passes on what the caller typed and follows your answer; it never decides by itself.

Your server answers in
5 seconds
Answers per block
Up to 6, plus error
Spoken reply
Up to 600 characters
Signature
Same as webhooks

How it works

Two IVR blocks work together. Collect digits asks the caller to type a number, for example a 13-digit CNIC or the last 4 digits of a card, and stores it under a name such as cnic. Check with your system then sends an action name and the collected values to your HTTPS endpoint and continues the call on the branch named by your answer: ok, not_found, locked, or whatever answers you defined on the block. Anything else, no answer within 5 seconds, or an error, takes the block's No answer / error branch, usually to an agent.

CallerCallerAsterisk (IVR)Asterisk (IVR)DashboardDashboardYour serverYour servertypes CNIC, card digitsCollect digits blocks1lookup: org, flow, block, digitsinternal, on the same server2Reads the PUBLISHED block: its action and the values it may sendPOST ivr.lookup (signed)card.activate · 5 s timeout4200 {"result":"ok","say":"…"}5result must be one of the block's answers; say becomes audiook + audio file7plays: Your card ending 4821 is now active8continues on branch ok9
Activating a card: the dashboard signs the request, checks your answer against the block, and turns say into speech.

The request is built from the published version of the IVR. Only an Admin who publishes a flow decides which action is called and which values leave the system; a caller cannot change either.

Setting up

  1. Enter your endpoint

    Open Administration → Integrations → Self-service API and enter your HTTPS URL. It must pass the same address check as webhooks: https://, no credentials in the URL, and a public address (unless the installation sets WEBHOOK_ALLOW_PRIVATE=yes).

  2. Copy the signing secret

    The first save creates a signing secret (ss_…), shown once. New signing secret replaces it; the old one stops working immediately. Removing the Self-service API makes every Check with your system block take its error branch.

  3. Send a test

    Send a test posts the action ping with empty values, flow 0 and a call_id starting with test-. Answer {"result":"ok"}; the dashboard shows what your server answered and what it would say.

  4. Build the IVR

    In the IVR builder add Collect digits blocks, one per value, then a Check with your system block. On it set the action (for example card.activate), tick the values to send, and list the results your server may answer. Each result becomes an output to connect, plus No answer / error. Publish the flow.

SettingRule
ActionStarts with a lowercase letter, then lowercase letters, digits, ., _ or -; up to 41 characters. Example: card.activate.
Results1 to 6 per block, unique, a lowercase letter then lowercase letters, digits or _; up to 24 characters. Every result must be connected.
Value namesA lowercase letter then lowercase letters, digits or _; up to 24 characters. Example: card_last4.
Collect digitsExactly N digits (13 for a CNIC, 4 for a PIN) or a range, 1 to 20 digits. The caller can end early with #.

The request

One POST per Check with your system block reached in a call. There are no retries: the caller is waiting.

What your server receivesHTTP
1POST /voip9/ivr HTTP/1.12Host: api.yourbank.example3Content-Type: application/json4User-Agent: Voip9-SelfService/1.05X-Voip9-Event: ivr.lookup6X-Voip9-Delivery: 1794690641.2867X-Voip9-Timestamp: 17946906508X-Voip9-Signature: v1=8a41d07c…c2f09 10{11  "event": "ivr.lookup",12  "action": "card.activate",13  "values": { "cnic": "3520212345671", "card_last4": "4821" },14  "caller": "+923001234567",15  "call_id": "1794690641.286",16  "organization": "sunrisemb",17  "flow": 12,18  "timestamp": "2026-11-15T10:24:10.512Z"19}

Headers

X-Voip9-Eventstring
Always ivr.lookup.
X-Voip9-Deliverystring
The call_id. Several lookups in one call share it.
X-Voip9-Timestampinteger
Unix time in seconds when the request was sent.
X-Voip9-Signaturestring
v1= + hex HMAC-SHA256 of {timestamp}.{raw body}, keyed with your ss_… secret.
User-Agentstring
Voip9-SelfService/1.0

Body

eventstring
Always ivr.lookup.
actionstring
The action set on the block, e.g. card.activate, or ping from the test button.
valuesobject
Only the values this block is set to send, by their names. Digits only (anything else is removed), at most 20 digits. An empty string when the caller did not enter one.
callerstring
The calling number as received from your carrier, up to 32 characters. It may be empty or withheld. Use it to check the customer's registered mobile.
call_idstring
The call's id in the phone system, up to 64 characters.
organizationstring
Your organization's id (slug) in Voip9.
flowinteger
The IVR menu's id. 0 for the test button.
timestampstring
When the request was built, ISO 8601 UTC.

Your answer

What you send backHTTP
1HTTP/1.1 200 OK2Content-Type: application/json3 4{ "result": "ok", "say": "Your card ending 4821 is now active. Please set your PIN at any ATM." }

Body

resultstringrequired
One of the results listed on the block. The call continues on that branch.
saystring
Spoken to the caller in your organization's voice before the call moves on, e.g. a balance or an appointment time. Trimmed and cut at 600 characters. It is synthesised for that call only and the audio is deleted after 10 minutes. Needs a speech provider set up; without one, nothing is said and the call simply continues.

How the answer picks the branch

What happensBranch the call takes
2xx, JSON, result is one of the block's resultsThat result's branch, after playing say if there is one.
2xx, JSON, result is not on the blockNo answer / error
2xx, but no result string, or not JSONNo answer / error
Any other status, including 3xx (redirects are not followed)No answer / error
No answer within 5 seconds, or the connection failsNo answer / error
No Self-service API set up, or its URL fails the address checkNo answer / error

The reason for an error (timeout, HTTP status, unknown result) is written to the dashboard's log with the organization, flow and action, never with the values.

Verifying the signature

Exactly as for webhooks, with the ss_… secret: compute the HMAC over the raw body, compare in constant time, and reject requests whose timestamp is more than 5 minutes old. One verifier can serve both if you pass the right secret.

verify.jsJavaScript
1import crypto from "node:crypto"2 3// rawBody: the request body as a Buffer, before JSON parsing4export function verified(req, rawBody, secret = process.env.VOIP9_SELFSERVICE_SECRET) {5  const ts = req.headers["x-voip9-timestamp"] ?? ""6  const sig = req.headers["x-voip9-signature"] ?? ""7  const expected = "v1=" + crypto.createHmac("sha256", secret).update(`${ts}.`).update(rawBody).digest("hex")8  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 3009  return fresh && sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))10}

Example server

A complete receiver for a bank IVR with two self-service actions. card.activate expects the values cnic and card_last4 and the results ok, not_found, already_active, locked. account.balance expects cnic and a sensitive tpin and the results ok, wrong_tpin, locked, not_found. Replace core with calls to your own systems.

ivr-server.js (Express)JavaScript
1import crypto from "node:crypto"2import express from "express"3 4import { core } from "./core-banking.js" // your own systems5 6const SECRET = process.env.VOIP9_SELFSERVICE_SECRET // ss_… (Integrations → Self-service API)7const app = express()8 9function verified(req) {10  const ts = req.header("X-Voip9-Timestamp") ?? ""11  const sig = req.header("X-Voip9-Signature") ?? ""12  const expected = "v1=" + crypto.createHmac("sha256", SECRET).update(`${ts}.`).update(req.body).digest("hex")13  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 30014  return fresh && sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))15}16 17const handlers = {18  // the dashboard's "Send a test" button19  ping: async () => ({ result: "ok" }),20 21  // Collect digits: cnic (13), card_last4 (4)  ->  answers: ok · not_found · already_active · locked22  "card.activate": async ({ values, caller }) => {23    const customer = await core.findByCnic(values.cnic)24    if (!customer) return { result: "not_found" }25    if (await core.tooManyAttempts(values.cnic)) return { result: "locked" }26    if (customer.mobile !== caller) return { result: "not_found" } // only from the registered mobile27    const card = customer.cards.find((c) => c.last4 === values.card_last4)28    if (!card) {29      await core.countFailedAttempt(values.cnic)30      return { result: "not_found" }31    }32    if (card.status === "active") return { result: "already_active" }33    await core.activateCard(card.id)34    return { result: "ok", say: `Your card ending ${card.last4} is now active. Please set your PIN at any ATM.` }35  },36 37  // Collect digits: cnic (13), tpin (4, sensitive)  ->  answers: ok · wrong_tpin · locked · not_found38  "account.balance": async ({ values }) => {39    const customer = await core.findByCnic(values.cnic)40    if (!customer) return { result: "not_found" }41    if (await core.tooManyAttempts(values.cnic)) return { result: "locked" }42    if (!(await core.checkTpin(customer.id, values.tpin))) {43      await core.countFailedAttempt(values.cnic)44      return { result: "wrong_tpin" }45    }46    const { rupees, paisa } = await core.availableBalance(customer.primaryAccount)47    return { result: "ok", say: `Your available balance is ${rupees.toLocaleString("en-PK")} rupees and ${paisa} paisa.` }48  },49}50 51app.post("/voip9/ivr", express.raw({ type: "application/json" }), async (req, res) => {52  if (!verified(req)) return res.status(401).end()53  const body = JSON.parse(req.body.toString("utf8"))54  const handler = handlers[body.action]55  if (!handler) return res.json({ result: "error" }) // not one of the block's answers: the call takes its error branch56  try {57    res.json(await handler(body))58  } catch (e) {59    console.error(body.action, body.call_id, e.message) // log the action and call, never body.values60    res.status(500).end() // the call takes the error branch, usually to an agent61  }62})63 64app.listen(8443)

Try it with curl

Sign a request yourself to test your server before connecting it to a live IVR.

Send a signed test requestShell
1SECRET='ss_…'2TS=$(date +%s)3BODY='{"event":"ivr.lookup","action":"account.balance","values":{"cnic":"3520212345671","tpin":"1234"},"caller":"+923001234567","call_id":"test-1","organization":"sunrisemb","flow":12,"timestamp":"2026-11-15T10:24:10.512Z"}'4SIG="v1=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')"5 6curl -s https://api.yourbank.example/voip9/ivr \7  -H "Content-Type: application/json" \8  -H "X-Voip9-Timestamp: $TS" -H "X-Voip9-Signature: $SIG" \9  -d "$BODY"10# {"result":"ok","say":"Your available balance is 25,340 rupees and 50 paisa."}

Example flows

FlowCollect digitsActionAnswers
Debit card activationcnic (13), card_last4 (4)card.activateok · not_found · already_active · locked
TPIN generation (OTP sent by your system to the registered mobile)cnic (13); then otp (6, sensitive), new tpin (4, sensitive) twicetpin.request_otpotp_sent · not_found · not_registered_number
Balance / mini statementcnic (13), tpin (4, sensitive)account.balanceok (with say) · wrong_tpin · locked · not_found
Block a lost card (automated)cnic (13), tpin (4, sensitive)card.blockblocked · wrong_tpin · not_found
Loan instalment (microfinance)cnic (13) or loan numberloan.next_instalmentok (with say) · not_found
Hospital appointmentmr_number (MR / patient number)appointment.nextok (with say) · none · not_found
University fee statusstudent_id or challan numberfee.statuspaid · unpaid (with say) · not_found

Sensitive data

  • Your system decides. Voip9 never checks a CNIC, card or PIN itself; it passes on what the caller typed and follows your answer.
  • Count failed attempts per CNIC or card on your side and answer locked after 3, as card PINs do at an ATM.
  • Check the caller number against the customer's registered mobile for actions that need it (TPIN generation, activation).
  • Verify the signature and the timestamp on every request, and only accept the actions your IVR uses.
  • Keep card blocking as the first option of a bank IVR and reachable without full verification, with an agent fallback (SBP: card block first, within one minute).
  • Log your answers, not the values: PINs and OTPs must not end up in your logs either.
  • The say text is customer data: it is turned into audio for that call only, in its own folder with a random name, and deleted after 10 minutes.

Next steps