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

---

Source: https://developers.dvaarik.com/docs/telephony · every page as one file: https://developers.dvaarik.com/docs.md