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, Vobiz, and Vonage when you add its API key and secret). 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.

Vobiz#

Credentials: Auth ID (starts with MA_ or SA_) and Auth token, both on the Vobiz console overview. Style: answer URL.

Create a Vobiz application whose Answer URL is https://api.developers.dvaarik.com/inbound/vobiz/{number_id}/{guard} (POST) and link the number to it. Vobiz fetches XML from it and opens the stream. Vobiz does not sign its requests in a way we can check, so the guard in the URL is the lock: keep the URL private.

Vonage#

Credentials: the voice Application ID and that application's private.key (paste the whole file). Add the account's API key and secret only to import numbers. Add the signature secret (API settings) and keep Use signed webhooks on in the application: we then check that every request really comes from Vonage and refuse anything else. Style: answer URL.

Set the application's Answer URL to one of your numbers' https://api.developers.dvaarik.com/inbound/vonage/{number_id}/{guard}. A Vonage application has one Answer URL for all its numbers, so every number linked to it that you connect here answers with its own agent.

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.

Hand a call to a person#

On Twilio and Plivo lines, an agent can transfer a live call to a person you list on the agent. Our charge stops at the transfer; your carrier bills the call to the person. Lines on other carriers, Telnyx included for now, do not transfer. See Transfer to a person.