{problem}

}

{line.role}: {line.text}

); } ``` `status` moves `idle → requesting-mic → connecting → live → ended`, or to `error`. `mute(true)` silences the microphone at the source. `elapsedSeconds` and `minutesBilled` let a page show the running cost. ## What the key cannot do There is no list, no read, no configuration, and no outbound dial behind a publishable key. `POST /v2/browser/sessions` returns four fields — `session_id`, `ws_url`, `expires_in_seconds`, `max_duration_seconds` — and nothing about your project, your rate, your wallet, or your pipeline. Two refusals are deliberately vague, and the SDK stays vague with them. An unfunded wallet and a dead speech provider are both `503`, separated only by a machine code, because a visitor who could tell those apart would be reading your business over your shoulder. A wrong agent, a foreign agent, and an agent that never existed are one `404`, so a scraped key cannot be walked across your project. | Code | Cause | | --- | --- | | `MicPermissionDenied` | the visitor refused the prompt, or policy blocked it | | `MicUnavailable` | no device, or the page is not on HTTPS | | `InvalidKey` | `401` — unknown or revoked key | | `OriginNotAllowed` | `403` — this origin is not on the key's list | | `AgentNotFound` | `404` — wrong or foreign agent | | `InvalidRequest` | `422` — usually a missing prompt variable | | `RateLimited` | `429`, or close `4429` | | `TemporarilyUnavailable` | `503`, or close `1013` | | `ProviderUnavailable` | `503`, or close `4453` | | `SessionEnded` | close `4401`, `4404`, `4408`, `4409` | | `NetworkError` | nothing came back, or the socket dropped | Every one carries a sentence you may show a visitor as-is, plus `status`, `closeCode`, `serverCode` and `retryAfterSeconds` for your logs. ## Origins An origin is `scheme://host[:port]` — no path, no query, no credentials. `https://acme.com` and `https://acme.com:443` are the same origin and both work. Up to 20 per key. A key with **no** origins refuses every request, which is the safe state for a key you have not finished setting up; the console says so on the row. The one wildcard is a loopback port — `http://localhost:*` and `http://127.0.0.1:*` — because you cannot know which port your dev server will pick, and the alternative is that everybody develops with the allowlist switched off. **Origins cannot be edited.** There is no route that changes them, on purpose: where a key may run is part of what the key is. To change the list, create a key with the origins you want, redeploy the page with the new value, then revoke the old key. Rotating a key keeps its origins and limits and replaces only the value — that is the tool for "this key leaked", not for "this key should run somewhere else". ## Limits Every limit has a conservative default, so a key created without touching any of them is already bounded. There is no unlimited value; the smallest is 1, which makes "no traffic at all" something you express by revoking the key. | Limit | Default | Range | | --- | --- | --- | | Concurrent sessions | 3 | 1–50 | | Sessions per minute (whole key) | 10 | 1–120 | | Sessions per minute (one visitor) | 5 | 1–60 | | Longest call, seconds | 300 | 1–3600 | The effective ceiling on one call is the **minimum** of the key's, the agent's and the project's. A key cannot raise a limit set anywhere else. A project may hold up to 10 live browser keys, a separate budget from your project keys, so minting call buttons cannot exhaust your server-key allowance. ## Billing A browser call is not a cheaper call. It runs through the same admission, the same verified [provider pipeline](/docs/providers), the same project concurrency lease and the same wallet hold as a call from your own server, and it settles the same way: whole connected minutes, **rounded up**, at $0.005 per minute. One second is one minute; sixty-one seconds is two. See [Billing](/docs/billing). A browser call has no carrier in the path, so there is nothing to record and no recording reference on the call. `store_transcript` still applies, on the same 90-day window as any other call. `minutesBilled` on the call object is `ceil(elapsedSeconds / 60)` — the honest number to show a visitor while they talk. The settled figure on the call record, visible under [Calls](/console/calls), is the one you are charged. ## The socket, if you are not using the SDK `ws_url` already carries the session's single-use token; do not append one. Send raw PCM16 mono at 16 kHz as binary frames and play the raw PCM16 mono at 24 kHz that comes back. JSON control frames are `ready`, `transcript` (`{role, text}`), `interrupted` (drop everything you have queued — this is barge-in), `turn_complete`, `error`, and `session_ended`. Send `{"type":"stop"}` to hang up. The close codes are the ones in the table above. # Telephony (BYO carrier) ## Connect a carrier you already pay for `GET /console/v2/projects/{project_id}/carriers/catalog` (or `GET /v2/carriers/catalog`) lists the connectable carriers with the exact credential fields to render and, per carrier, whether it **fetches an answer URL** or **takes a stream URL**. The console form is generated from it. `POST .../carriers` with `{ "provider", "name", "credentials" }` verifies the credentials against the carrier straight away. A `201` is returned either way: `status` is `verified` or `invalid` with `last_error`, and a rejected credential is never stored. `POST .../carriers/{connection_id}/verify` re-checks stored credentials, or replaces them when given a body — only if the carrier accepts the replacement. `DELETE` forgets the credentials and disables every number on the connection; your carrier account is never touched. ## Numbers `POST .../carriers/{connection_id}/numbers/import` pulls the numbers your account holds (Twilio, Plivo, Exotel, Telnyx). `POST .../carriers/{connection_id}/numbers` attaches one E.164 number by hand for a carrier that cannot list them (FreJun/Teler). Each number row carries `answer_url` **or** `stream_url` — the exact string to paste into your carrier — plus `inbound_agent_id`, `inbound_enabled`, and `outbound_enabled`. `PATCH .../carriers/numbers/{number_id}` binds an active agent (`inbound_agent_id`), switches answering on or off (`inbound_enabled`), and allows or forbids dialling from the number (`outbound_enabled`). Inbound requires a verified connection and a bound agent. `DELETE` forgets the number locally. ## Carrier setup guides The URLs below are the pattern; the console shows the concrete per-number value with its guard segment. `{number_id}` and `{guard}` are minted by Dvaarik. ### Twilio Credentials: Account SID and Auth token (Twilio Console home). Style: answer URL. Paste `https://api.developers.dvaarik.com/inbound/twilio/{number_id}/{guard}` into the number's **Voice → A call comes in → Webhook** (GET or POST both work). Twilio fetches TwiML from it and opens a bidirectional media stream to Dvaarik. ### Plivo Credentials: Auth ID and Auth token (Plivo console overview). Style: answer URL. Create a Plivo application whose **Answer URL** is `https://api.developers.dvaarik.com/inbound/plivo/{number_id}/{guard}` and assign the number to it. Plivo fetches XML from it and opens the stream. ### Exotel Credentials: Account SID, API key, API token, and the API host (`api.in.exotel.com` for accounts in India). Style: stream URL. In the number's app flow, point the **Voicebot** applet at `wss://api.developers.dvaarik.com/inbound/exotel/stream/{number_id}/{guard}`. Exotel connects the bidirectional stream directly. ### FreJun / Teler Credentials: API token and, for Teler-branded accounts, the API base URL. Style: stream URL. Numbers are attached by hand. Set the application's stream URL to `wss://api.developers.dvaarik.com/inbound/frejun/stream/{number_id}/{guard}`. ### Telnyx Credentials: API key (Telnyx portal → API Keys) and webhook public key (Account Settings → Keys & Credentials → Public Key — Telnyx signs every webhook with it and no API returns it, so it must be pasted). Add the Call Control Application ID only if you also want to dial out; inbound works without it. Style: answer URL. Telnyx binds the webhook to the Call Control **Application**, not to the phone number, so several numbers answered by different agents need one application each. On first connect: create the application in your Telnyx portal, connect the account here, import your numbers, then paste each number's `https://api.developers.dvaarik.com/inbound/telnyx/{number_id}/{guard}` into that number's own application. Telnyx signs the webhook body itself (Ed25519 over `timestamp|body`, not the URL) and an outbound call dials bare — Dvaarik starts the audio stream only once Telnyx reports the call answered, so nothing is charged while the phone is still ringing. ## Outbound `POST /v2/voice/sessions/outbound` dials `to` from `from`, which must be a number on a verified connection with `outbound_enabled`. The carrier bills the leg; Dvaarik bills connected minutes, rounded up. Verify TRAI/DND and 140-series obligations with your carrier before dialling Indian numbers. # Webhooks ## Endpoints Console: `/console/v2/projects/{project_id}/webhooks`. Machine: `/v2/projects/{project_id}/webhooks` with `webhook:read` to list and `webhook:write` to create, test or disable (the path project must match the key's project). `POST` with `{ "name", "url", "event_types" }` creates an endpoint. The URL must be public HTTPS on port 443 with no credentials or fragment. Event types are a closed set for this voice release: `call.completed`, `call.failed`, `webhook.ping`, and the wildcards `call.*`, `webhook.*`, `*`. The `201` contains `signing_secret` **once**; no route returns it again. Up to 10 endpoints per project. `GET` lists endpoints (`include_disabled=true` to see disabled ones, which keep `secret_hint` and `revision`). `DELETE .../{endpoint_id}` disables the endpoint, bumps its revision, and cancels queued deliveries. `POST .../{endpoint_id}/test` queues a signed `webhook.ping` and returns `202` with `delivery_id` and `queued` — recorded, not yet sent. `GET .../dead-letters` lists deliveries that exhausted their retries with `event_type`, `endpoint_id`, `attempts`, `max_attempts`, and `last_error`; payloads are not retained on terminal rows. ## Delivery and signature Every delivery is an HTTP `POST` with a JSON body and these headers: | Header | Value | | --- | --- | | `X-Webhook-Event` | the event name, e.g. `call.completed` | | `X-Webhook-Timestamp` | unix seconds when the delivery was signed | | `X-Webhook-Signature` | `t=,v1=` | | `X-Webhook-Delivery` | the delivery id; deduplicate retries on it | | `X-Dvaarik-Event`, `X-Dvaarik-Signature` | legacy aliases; `sha256=` over the body alone — do not build new verifiers on them | The signed bytes are `"."` and the key is the endpoint's signing secret. Verify before parsing, compare in constant time, and reject a timestamp outside your tolerance window (five minutes is usual) to stop replays. Respond `2xx` promptly; anything else is retried with backoff and then dead-lettered. ```js import { createHmac, timingSafeEqual } from "node:crypto"; export function verifyDvaarikWebhook(req, secret, toleranceSeconds = 300) { const parts = Object.fromEntries(String(req.get("X-Webhook-Signature") ?? "").split(",").map((kv) => kv.split("="))); const timestamp = req.get("X-Webhook-Timestamp"); if (!parts.t || !parts.v1 || parts.t !== timestamp) return false; if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) return false; const expected = createHmac("sha256", secret).update(`${timestamp}.`).update(req.body).digest("hex"); const a = Buffer.from(expected, "hex"), b = Buffer.from(parts.v1, "hex"); return a.length === b.length && timingSafeEqual(a, b); } ``` ```python import hmac, hashlib, time def verify_dvaarik_webhook(headers, raw_body: bytes, secret: str, tolerance_s=300) -> bool: parts = dict(kv.split("=", 1) for kv in headers.get("X-Webhook-Signature", "").split(",") if "=" in kv) timestamp = headers.get("X-Webhook-Timestamp", "") if not parts.get("t") or not parts.get("v1") or parts["t"] != timestamp: return False if abs(time.time() - int(timestamp)) > tolerance_s: return False expected = hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, parts["v1"]) ``` The agent-level `webhook_url` (set on the agent) is signed the same way with the agent's own `webhook_secret`. # Billing ## One rate, prepaid in USD `GET /console/v2/billing/rate` returns the rate on its own: `rate_nano_usd_per_minute: "5000000"` (**$0.005 per connected minute** — half a cent), `metering_basis: "connected_minute_rounded_up"`, and a `rate_version`. Every call rounds up to the next full minute. Cost is `ceil(connected_seconds / 60) × rate` in integer nano-USD; a 59-second call costs $0.005 (1 minute), a 61-second call costs $0.01 (2 minutes), and a 10-minute call costs $0.05. Read the rate from this route rather than hard-coding it. A published rate change is a new `rate_version`; sessions already admitted keep the version they froze. ## Pure pay as you go There is no monthly platform fee, no minimum spend, no seat fee, no commitment, and no contract. You top up a prepaid wallet with whatever amount you want, you spend what you use, and whatever is left stays yours. Connected voice minutes are the only metered thing on this platform. Dvaarik charges nothing for: - creating projects, agents, or API keys; - the console; - the SDKs (`@dvaarik/node`, `dvaarik`, `@dvaarik/web`); - webhook delivery, retries, and dead letters; - the [playground](/playground), beyond its own connected minutes — a playground call is a real call, billed at the same rate as any other; - post-call analysis. Insights run on **your** model under **your** provider account, so that provider bills you for those tokens and Dvaarik adds nothing on top; - **text and chat.** We sell voice minutes only. A website chat bot built on your own model costs you nothing from us. `GET /console/v2/billing/summary?project_id=…` returns the account wallet — `balance_nano_usd`, `held_nano_usd`, `spendable_nano_usd`, `lifetime_topup_nano_usd`, `low_balance_threshold_nano_usd`, `low_balance` — together with the rate and the project's concurrency, request-rate, and maximum-session limits. The wallet belongs to the account; it is reported against one project. ## Holds and settlement A session places a hold for its maximum duration when admitted. It is refused with `402` when the spendable balance cannot cover that hold. When the session ends, the hold is released and the connected seconds are settled exactly once. `GET /console/v2/billing/transactions?limit=50&offset=0` lists the ledger newest first; `amount_nano_usd` is null on archival rows from before USD. ## Top up 1. `GET /console/v2/billing/quote?amount_usd_cents=2500` — no fee, no markup: one cent buys exactly 10,000,000 nano-USD. Bounds are $10 to $2,000. 2. `POST /console/v2/billing/topup` with `{ "amount_usd_cents", "project_id" }` creates a Razorpay USD order and records it first; the response carries `order_id` and `razorpay_key_id`, which the console hands to Razorpay Checkout. `502` means the gateway did not create an order; `503` means the order could not be recorded and no checkout was returned. 3. The payment webhook credits the wallet. The console polls the summary until `lifetime_topup_nano_usd` grows; a successful Checkout alone is never treated as credit. Whether international cards are accepted depends on Razorpay international-payment enablement for the Dvaarik merchant account; the console reports the gateway's answer rather than assuming it. ## Receipts `GET /console/v2/billing/invoices` lists receipts for paid top-ups; `GET /console/v2/billing/invoices/{invoice_id}.pdf` returns the PDF. A receipt exists only once a payment has landed. ## What we store Storage is not a line on your bill here, because there is almost nothing of yours on our disks. **Call recordings live in your own phone company's account.** When an agent has `record_calls` enabled, Dvaarik asks your carrier to record the call. The audio is written into your own carrier account under your own carrier plan. Dvaarik stores only the carrier's reference to that recording, so you fetch the audio from your carrier with your own credentials. We pay nothing to store it, and you are not charged twice for storing it. **Browser calls have no recording.** A browser call has no carrier in the path, so there is no carrier to record it and no recording reference on the call. **Transcripts live in the Dvaarik database for 90 days and are then deleted.** `store_transcript` controls whether one is written at all; `retention_days` cannot extend a transcript past that 90-day window. Pull anything you need to keep — through the API or your call webhook — inside it. **The insight block survives the transcript.** The short post-call summary produced by `insight_config` stays on the call record after the transcript is deleted: it is small, and it is your business record of what the call was about. It is generated on your own model, on your own provider account. ## Estimate the per-minute cost before you build The platform fee is exact and published — $0.005 per connected minute, rounded up to the next minute. What you cannot know from this API alone is what your *chosen* speech, language-model, voice, or realtime provider will charge for that same minute, because that is billed by them, on your account, at whatever rate you negotiated. The console's cost-estimate card (agent create/edit, the agent list, and the [pricing](/pricing) calculator) renders a breakdown — Listen / Think / Speak or Realtime, your carrier's rate typed in by hand, and the platform fee — from a small table of public list prices in `src/lib/providerListPrices.ts`, dated and sourced per provider. It is always an estimate: only the platform fee row is exact, computed from the same nano-USD constants as the rest of this page; every provider row can drift the moment that provider changes its own price list. # SDKs ## Three official SDKs | Package | Language | Install | Door | | --- | --- | --- | --- | | `@dvaarik/node` | TypeScript / JavaScript, Node 20+ | `npm install @dvaarik/node` | machine | | `dvaarik` | Python 3.9+ | `pip install dvaarik` | machine | | `@dvaarik/web` | TypeScript / JavaScript, browser | `npm install @dvaarik/web` | browser | The two **server** SDKs wrap the machine door: the `/v2/*` routes that authenticate with a project key (`X-Api-Key: dvk_live_…`). Neither wraps the `/console/*` routes, which take an account browser session and do not belong on a server. `@dvaarik/web` is the odd one out and is described [below](#dvaarikweb-browser-calls). They share one shape on purpose — the same namespaces, the same error hierarchy, the same retry and idempotency rules, the same pagination helper, and the same webhook verifier — so a team running one service in Node and another in Python reads one mental model. Neither SDK is required: every operation is an ordinary HTTPS request, documented on the [API reference](/docs/api-reference). The Node package runs on any fetch-capable runtime (Bun, Deno, Cloudflare Workers, Vercel Edge) and ships ESM, CommonJS, and type declarations. The Python package ships a sync `Dvaarik` and an async `AsyncDvaarik` over one transport, with a `py.typed` marker and `httpx` as its only dependency. > **Release status.** The source lives in the platform repository under `sdk/typescript`, `sdk/python` and `sdk/web`. Publishing to npm and PyPI is a manual release step; until the first publish lands, install from those directories. ## 60-second quickstart Create an agent, ring a number, verify the delivery that reports the result. You need a project API key from [Projects and keys](/docs/projects-and-keys), a `verified` [provider account](/docs/providers), and a [carrier number](/docs/telephony) with outbound enabled. ```ts import { Dvaarik } from "@dvaarik/node"; const client = new Dvaarik({ apiKey: process.env.DVAARIK_API_KEY!, // never hard-code this projectId: process.env.DVAARIK_PROJECT_ID!, // fills the webhook routes' path }); // 1 — Create an agent. `webhook_secret` comes back exactly once: store it. const { agent, webhook_secret } = await client.agents.create({ name: "Reception", prompt: "You are the receptionist for Blue Orchid Salon. Book appointments.", greeting: "Blue Orchid, how can I help?", pipeline_mode: "cascade", pipeline_config: { stt: "sarvam", llm: "gemini", tts: "elevenlabs" }, language: "en-IN", }); // 2 — Ring a customer. The idempotency key is what makes a timed-out request // safe to send again: the repeat returns the first call with // `duplicate: true` instead of dialling twice. const { session, duplicate } = await client.voiceSessions.createOutbound( { agent_id: agent.id, to: "+919876543210", from: "+911140000000" }, { idempotencyKey: orderId }, ); // 3 — Verify the delivery. RAW BYTES, before any JSON parsing. app.post("/webhooks/dvaarik", express.raw({ type: "application/json" }), async (req, res) => { try { const delivery = await client.webhooks.verify(req.body, req.headers, webhook_secret); if (delivery.event === "call.completed") handle(delivery.payload); res.sendStatus(200); } catch { res.sendStatus(400); // bad signature, or outside the five-minute window } }); ``` ```python import os from dvaarik import Dvaarik, DvaarikWebhookSignatureError client = Dvaarik( api_key=os.environ["DVAARIK_API_KEY"], # never hard-code this project_id=os.environ["DVAARIK_PROJECT_ID"], # fills the webhook routes' path ) # 1 — Create an agent. webhook_secret comes back exactly once: store it. created = client.agents.create({ "name": "Reception", "prompt": "You are the receptionist for Blue Orchid Salon. Book appointments.", "greeting": "Blue Orchid, how can I help?", "pipeline_mode": "cascade", "pipeline_config": {"stt": "sarvam", "llm": "gemini", "tts": "elevenlabs"}, "language": "en-IN", }) agent, webhook_secret = created.agent, created.webhook_secret # 2 — Ring a customer. The idempotency key makes a timed-out request safe to # send again: the repeat comes back duplicate=True instead of dialling twice. result = client.voice_sessions.create_outbound( {"agent_id": agent.id, "to": "+919876543210", "from": "+911140000000"}, idempotency_key=order_id, ) # 3 — Verify the delivery. RAW BYTES, before any JSON parsing. @app.post("/webhooks/dvaarik") async def dvaarik_webhook(request: Request) -> Response: try: delivery = client.webhooks.verify(await request.body(), request.headers, webhook_secret) except DvaarikWebhookSignatureError: return Response(status_code=400) if delivery.event == "call.completed": handle(delivery.payload) return Response(status_code=200) ``` Deduplicate on `delivery.deliveryId` / `delivery.delivery_id`: retries of the same delivery reuse it. ## Namespaces | Node | Python | Routes | | --- | --- | --- | | `client.agents` | `client.agents` | `/v2/agents` — list, create, get, update, delete, rotate secret | | `client.voiceSessions` | `client.voice_sessions` | `/v2/voice/sessions` and `/outbound` — list, create, get | | `client.providerAccounts` | `client.provider_accounts` | `/v2/provider-accounts` — list, save, get, probe, rotate, disconnect | | `client.carriers` | `client.carriers` | `/v2/carriers` — list, catalog, create, get, verify, disconnect | | `client.carrierNumbers` | `client.carrier_numbers` | `/v2/carriers/numbers` — list, attach, import, update, delete | | `client.webhooks` | `client.webhooks` | `/v2/projects/{project_id}/webhooks` — list, create, disable, test, dead letters, **verify** | | `client.projects` | `client.projects` | `/v2/projects` — account token, not a project key | | `client.apiKeys` | `client.api_keys` | `/v2/api-keys` — account token, not a project key | `projects`, `apiKeys` and the provider catalogue are the account door: minting a project or a key is account administration that a project-scoped key deliberately cannot do. Construct a second client with an account access token for those, and calling one without it fails locally rather than sending a request that would come back `401`. ## What both SDKs do for you - **Typed errors.** One base carrying `status` and the request id, with a class per status: auth (401/403), payment required (402), not found (404), conflict (409), validation (422, exposing the field errors), rate limit (429, exposing `Retry-After`), and server (5xx). See [Errors](/docs/errors). - **Retries.** Exponential backoff with jitter on `429`, `502` and `503` only, honouring `Retry-After`. A `POST` is never retried unless you supplied an idempotency key — an outbound call that timed out may already be ringing. - **Pagination.** `iterate()` walks a limit/offset list route as an async iterator, with `pages()`, `all()` and a `maxItems` bound. - **Webhook verification.** The timestamped HMAC described in [Webhooks](/docs/webhooks), including the replay-window check, in one call. - **Rate-limit visibility.** `client.rateLimit` / `client.rate_limit` reports the `X-RateLimit-*` headers from the most recent response, so you can pace against `remaining` instead of waiting to be refused. Money stays an integer nano-USD **string** in both SDKs. Parse it with `BigInt` in JavaScript and `int` in Python; never with `Number` or `float`. The platform fee is $0.005 per connected minute, rounded up to the next minute — see [Billing](/docs/billing). ## `@dvaarik/web` — browser calls The browser SDK is not a fourth client with the same shape. It runs in a public web page with a **publishable** key (`pk_live_…`), and the only route that key can reach is `POST /v2/browser/sessions` — one voice call, on one agent, from an origin on the key's list. So it has no namespaces, no pagination and no webhook verifier: none of those belong in a page a stranger can view the source of. What it has instead is a microphone, a socket, and a call button. ```html ``` ```ts import { DvaarikCall } from "@dvaarik/web"; const call = new DvaarikCall({ publishableKey: "pk_live_…", agentId: "…" }); call.on("status", (status) => render(status)); // idle → live → ended call.on("transcript", (line) => append(line)); // { role, text, final } call.on("error", (error) => show(error.message)); // a sentence, already visitor-safe button.addEventListener("click", () => call.start()); ``` Zero runtime dependencies, ESM + CommonJS + a single-file `