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.
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
Enter your endpoint
Open
Administration → Integrations → Self-service APIand 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 setsWEBHOOK_ALLOW_PRIVATE=yes).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.Send a test
Send a test posts the action
pingwith empty values,flow0 and acall_idstarting withtest-. Answer{"result":"ok"}; the dashboard shows what your server answered and what it would say.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.
| Setting | Rule |
|---|---|
| Action | Starts with a lowercase letter, then lowercase letters, digits, ., _ or -; up to 41 characters. Example: card.activate. |
| Results | 1 to 6 per block, unique, a lowercase letter then lowercase letters, digits or _; up to 24 characters. Every result must be connected. |
| Value names | A lowercase letter then lowercase letters, digits or _; up to 24 characters. Example: card_last4. |
| Collect digits | Exactly 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.
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-Signaturestringv1=+ hex HMAC-SHA256 of{timestamp}.{raw body}, keyed with yourss_…secret.User-AgentstringVoip9-SelfService/1.0
Body
eventstring- Always
ivr.lookup. actionstring- The action set on the block, e.g.
card.activate, orpingfrom 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
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 happens | Branch the call takes |
|---|---|
2xx, JSON, result is one of the block's results | That result's branch, after playing say if there is one. |
2xx, JSON, result is not on the block | No answer / error |
2xx, but no result string, or not JSON | No answer / error |
| Any other status, including 3xx (redirects are not followed) | No answer / error |
| No answer within 5 seconds, or the connection fails | No answer / error |
| No Self-service API set up, or its URL fails the address check | No 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.
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}1import hashlib, hmac, os, time2 3SECRET = os.environ["VOIP9_SELFSERVICE_SECRET"].encode() # ss_…4 5def verified(headers, raw_body: bytes) -> bool:6 ts = headers.get("X-Voip9-Timestamp", "")7 sig = headers.get("X-Voip9-Signature", "")8 expected = "v1=" + hmac.new(SECRET, ts.encode() + b"." + raw_body, hashlib.sha256).hexdigest()9 return ts.isdigit() and abs(time.time() - int(ts)) < 300 and hmac.compare_digest(sig, expected)1<?php2function voip9_verified(string $rawBody): bool {3 $secret = getenv('VOIP9_SELFSERVICE_SECRET'); // ss_…4 $ts = $_SERVER['HTTP_X_VOIP9_TIMESTAMP'] ?? '';5 $sig = $_SERVER['HTTP_X_VOIP9_SIGNATURE'] ?? '';6 $expected = 'v1=' . hash_hmac('sha256', $ts . '.' . $rawBody, $secret);7 return abs(time() - (int) $ts) < 300 && hash_equals($expected, $sig);8}9 10$body = file_get_contents('php://input');11if (!voip9_verified($body)) { http_response_code(401); exit; }12$req = json_decode($body, true);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.
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)1import hashlib, hmac, json, logging, os, time2from flask import Flask, request, abort, jsonify3 4import core_banking as core # your own systems5 6SECRET = os.environ["VOIP9_SELFSERVICE_SECRET"].encode() # ss_…7app = Flask(__name__)8 9 10def verified() -> bool:11 ts = request.headers.get("X-Voip9-Timestamp", "")12 sig = request.headers.get("X-Voip9-Signature", "")13 expected = "v1=" + hmac.new(SECRET, ts.encode() + b"." + request.get_data(), hashlib.sha256).hexdigest()14 return ts.isdigit() and abs(time.time() - int(ts)) < 300 and hmac.compare_digest(sig, expected)15 16 17def card_activate(values, caller):18 customer = core.find_by_cnic(values["cnic"])19 if not customer:20 return {"result": "not_found"}21 if core.too_many_attempts(values["cnic"]):22 return {"result": "locked"}23 if customer.mobile != caller: # only from the registered mobile24 return {"result": "not_found"}25 card = next((c for c in customer.cards if c.last4 == values["card_last4"]), None)26 if not card:27 core.count_failed_attempt(values["cnic"])28 return {"result": "not_found"}29 if card.status == "active":30 return {"result": "already_active"}31 core.activate_card(card.id)32 return {"result": "ok", "say": f"Your card ending {card.last4} is now active. Please set your PIN at any ATM."}33 34 35def account_balance(values, caller):36 customer = core.find_by_cnic(values["cnic"])37 if not customer:38 return {"result": "not_found"}39 if core.too_many_attempts(values["cnic"]):40 return {"result": "locked"}41 if not core.check_tpin(customer.id, values["tpin"]):42 core.count_failed_attempt(values["cnic"])43 return {"result": "wrong_tpin"}44 rupees, paisa = core.available_balance(customer.primary_account)45 return {"result": "ok", "say": f"Your available balance is {rupees:,} rupees and {paisa} paisa."}46 47 48HANDLERS = {49 "ping": lambda values, caller: {"result": "ok"},50 "card.activate": card_activate,51 "account.balance": account_balance,52}53 54 55@app.post("/voip9/ivr")56def ivr():57 if not verified():58 abort(401)59 body = json.loads(request.get_data())60 handler = HANDLERS.get(body["action"])61 if handler is None:62 return jsonify(result="error") # not one of the block's answers: error branch63 try:64 return jsonify(handler(body["values"], body["caller"]))65 except Exception as e:66 logging.error("%s %s %s", body["action"], body["call_id"], e) # never log body["values"]67 abort(500)Try it with curl
Sign a request yourself to test your server before connecting it to a live IVR.
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
| Flow | Collect digits | Action | Answers |
|---|---|---|---|
| Debit card activation | cnic (13), card_last4 (4) | card.activate | ok · 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) twice | tpin.request_otp | otp_sent · not_found · not_registered_number |
| Balance / mini statement | cnic (13), tpin (4, sensitive) | account.balance | ok (with say) · wrong_tpin · locked · not_found |
| Block a lost card (automated) | cnic (13), tpin (4, sensitive) | card.block | blocked · wrong_tpin · not_found |
| Loan instalment (microfinance) | cnic (13) or loan number | loan.next_instalment | ok (with say) · not_found |
| Hospital appointment | mr_number (MR / patient number) | appointment.next | ok (with say) · none · not_found |
| University fee status | student_id or challan number | fee.status | paid · 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.