Carrier accounts

A carrier account is the credential Talqing uses to reach a phone network on your behalf; every phone number hangs off one. You connect an account you already have — the carrier relationship and invoice stay yours. Four carriers are supported:

Carrier (`provider`)	`account_info`	`credentials`	Work in the carrier’s console
`plivo`	`auth_id`	`auth_token`	None
`twilio`	`account_sid`	`auth_token`	None
`vobiz`	`auth_id`	`auth_token`	None
`exotel`	`account_sid`, `region`, `subdomain` (+ optional outbound edge fields)	`api_key`, `api_token`	One Flow per region, before inbound works

GET /v1/telephony/providers returns the exact field keys, labels, defaults and hints the dashboard renders.

Connecting an account

Two calls: create records the credential and validates it against the carrier; provision builds the carrier-side objects (the outbound identity Talqing dials with, and inbound routing for every region the account already has numbers in).

curl -sS https://api.talqing.com/v1/telephony/accounts \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "plivo",
    "display_name": "Plivo production",
    "account_info": { "auth_id": "MAZDKXNJYWMWJHYZJHZT" },
    "credentials": { "auth_token": "your-auth-token" }
  }'

curl -sS -X POST https://api.talqing.com/v1/telephony/accounts/3f9a1c72-5d84-4e0b-9a13-6c2e8b7f4d51/provision \
  -H "Authorization: Bearer $TALQING_API_KEY"

const account = await talqing.telephony.accounts.create({
  createTelephonyAccountRequest: {
    provider: "plivo",
    display_name: "Plivo production",
    account_info: { auth_id: "MAZDKXNJYWMWJHYZJHZT" },
    credentials: { auth_token: "your-auth-token" },
  },
});
await talqing.telephony.accounts.provision({ account_id: account.id });

account = talqing.telephony.accounts.create(
    provider="plivo",
    display_name="Plivo production",
    account_info={"auth_id": "MAZDKXNJYWMWJHYZJHZT"},
    credentials={"auth_token": "your-auth-token"},
)
talqing.telephony.accounts.provision(account["id"])

display_name must be unique in the workspace (max 120 characters). Omit it and the account takes its name at the carrier.
A second account with the same carrier identity (Plivo/Vobiz Auth ID, Twilio/Exotel Account SID) is a 409.
A credential the carrier rejects still creates the account, in error with the carrier’s message on status_message. Fix it with a PATCH.
Provision is idempotent: it converges the carrier side rather than creating duplicates. Run it again after replacing credentials. Importing a number with provision: true also provisions a connected account for you.

Credentials become workspace secrets

A plaintext credential is stored as a workspace secret named <PROVIDER>_<FIELD> (PLIVO_AUTH_TOKEN, EXOTEL_API_TOKEN), suffixed if the name is taken, and the account keeps only the reference. You can pass your own reference instead:

{ "credentials": { "auth_token": "{{secrets.PLIVO_AUTH_TOKEN}}" } }

Reads return only the {{secrets.NAME}} map, never a resolved value. A PATCH to credentials merges, so you can rotate one key without resending the others.

Account statuses

`status`	Meaning	What to do
`pending`	Recorded, not yet validated.	Nothing; resolves within the create call.
`connected`	The credential works; the carrier side is not built. Dashboard: Setup incomplete.	Provision.
`provisioning`	Provisioning is running.	Wait.
`ready`	Fully set up. Numbers can be imported, assigned and dialled from.	—
`error`	The last operation failed; `status_message` has the carrier’s reason.	Fix the cause, provision again.
`disabled`	You disabled it.	`PATCH` `status: "connected"`, then provision each number.

PATCH accepts only disabled and connected for status.

Disabling an account tears down inbound routing for every number on it, immediately. The numbers stay active (outbound still checks the account, so they cannot dial either) and show status_message “Carrier disabled…”. Re-enabling does not restore routing: run POST /v1/telephony/phone-numbers/{number_id}/provision on each number. Each keeps its assigned agent.

Setup steps in the carrier’s console

setup_steps on an account lists remaining carrier work, and setup_complete is true when every step is done. Each step has key, title, detail, numbered instructions (each with optional url and a copy_value to paste), doc_url, done, user_confirmable and region. Only Exotel has a step you perform: Plivo, Twilio and Vobiz are fully API-driven and return no console steps. A user_confirmable step cannot be read back over any API, so you confirm it yourself, naming the step’s region:

{ "console_setup_confirmed": true, "console_setup_region": "in" }

sent as PATCH /v1/telephony/accounts/{account_id}. The two fields go together. Confirming a region with no numbers yet is refused (the step only appears once the region’s first number is provisioned). Confirming sets can_inbound: true on every non-disabled number on the account in that region; sending false reverses it. Any other carrier answers 400.

While an Exotel region’s step is outstanding, inbound calls to that region’s numbers do not work — they import with can_inbound: false, read readiness: "needs_carrier_setup" and cannot be assigned an agent. Outbound works throughout. Read setup_steps, not status.

Per-carrier fields

Plivo

auth_id (form MAxxxxxxxx) and auth_token, both on the Plivo console home page. No console steps.

Twilio

account_sid (form ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx) and auth_token, both on the Twilio console home page. No console steps.

Vobiz

auth_id (form MA_XXXXXXXX) and auth_token, both on the Vobiz console home page. No console steps.

Exotel

Field	Target	Default	Notes
`account_sid`	`account_info`	—	Exotel’s API Settings page.
`api_key`, `api_token`	`credentials`	—	Exotel’s API Settings page.
`region`	`account_info`	`Mumbai`	As shown in the Exotel console. Recorded for reference only; unrelated to Talqing’s `us`/`in` regions.
`subdomain`	`account_info`	`api.in.exotel.com`	The API host shown in the Exotel console. A wrong value fails as “Authorization failed”.
`outbound_edge_host`	`account_info`	`in.voip.exotel.com`	Optional. Exotel’s outbound SIP edge for India, from their Network & Firewall Configuration page. Change only if your account is outside India.
`outbound_edge_port`	`account_info`	`443`	Optional. `443` for TLS, `5070` for TCP.
`outbound_transport`	`account_info`	`tls`	Optional. `tls` or `tcp`; Exotel does not support UDP.

The console step. Exotel hands an incoming call only to a Flow, so your numbers need a Flow that passes the call to Talqing — one per account per region, not per number.

Create a Custom App

In Exotel’s App Bazaar, under Custom Apps, click Create.

Add the Connect applet

Drag Connect from Voice Applets onto Call Start. Keep “Configure using flow builder here” selected and leave both Primary URL boxes empty.

Point it at Talqing

Under Dial Whom, pick Dial phone number(s), paste the step’s copy_value (it begins sip: and is specific to your account and region), and save the Flow.

Attach your numbers

In ExoPhones, click Assign ExoPhones to Flow, tick every number in that region and the Flow, then Attach Flow. A number still showing “Install an App” is not connected.

Confirm it

PATCH the account with console_setup_confirmed: true and the step’s console_setup_region, or press confirm in the dashboard.

Disconnecting an account

DELETE /v1/telephony/accounts/{account_id} is permanent.

Every number on the account must be disabled first, or it fails with disable all phone numbers on this account before deleting it.
Talqing removes the carrier-side objects it created before deleting the account. If the carrier refuses (expired credential, outage) the delete fails with 502 and nothing is removed — restore the credential and retry. Nothing you built yourself in the carrier console is touched.

Phone numbers

Import the numbers this account owns and put an agent on one.

Troubleshooting

Credential expiry, setup that will not finish, numbers stuck in error.

Get started

Build

Guides

Carrier accounts

Connecting an account

Credentials become workspace secrets

Account statuses

Setup steps in the carrier’s console

Per-carrier fields

Disconnecting an account

Next

Phone numbers

Troubleshooting

​Connecting an account

​Credentials become workspace secrets

​Account statuses

​Setup steps in the carrier’s console

​Per-carrier fields

​Disconnecting an account

​Next

Phone numbers

Troubleshooting

Connecting an account

Credentials become workspace secrets

Account statuses

Setup steps in the carrier’s console

Per-carrier fields

Disconnecting an account

Next