Telephony Configs & Numbers overview

A telephony configuration is a saved provider account (Twilio, Vobiz, Tata Smartflo, …) — its credentials, its name, and whether it's the org's default for outbound. Under each config sit the phone numbers (DIDs) you own on that account. This section covers the CRUD API for both, plus how a phone number gets an inbound agent attached.

Two ways to route inbound

Attaching an agent to a phone number here (inbound_agent_uuid) is the persistent, dashboard-style path. The other path is an inbound binding created with POST /call type=inbound, which stores an inline agent snapshot. Bindings win over phone-number attachments for the same number. Use phone numbers for saved agents; use bindings for API-first transient agents. Twilio/Vobiz bindings take inline credentials; Tata Smartflo bindings resolve credentials from the saved config (the number must be added here first) — see Smartflo setup.

The object model

Organization
└── Telephony Configuration        (config_id)   — a provider account + credentials
    ├── Phone Number               (phone_number_id) — a DID you own
    │   └── inbound_agent_uuid ────────────────────┐  points at a saved Agent
    └── Phone Number ...                           │
                                                   ▼
                                              Agent (id + uuid)

Endpoints

Everything is under /api/v1/organizations. All require X-API-Key.

Configurations

Method	Path	Purpose
`GET`	`/telephony-configs`	List your configs, each with a phone-number count.
`POST`	`/telephony-configs`	Create a config from provider credentials.
`GET`	`/telephony-configs/{config_id}`	Config detail (masked credentials; Smartflo WSS URL).
`PUT`	`/telephony-configs/{config_id}`	Update name / rotate credentials (provider is immutable).
`POST`	`/telephony-configs/{config_id}/set-default-outbound`	Make this the org's default outbound config.
`DELETE`	`/telephony-configs/{config_id}`	Delete (409 if still referenced by a number/campaign).

Phone numbers (nested under a config)

Method	Path	Purpose
`GET`	`/telephony-configs/{config_id}/phone-numbers`	List the numbers added to this config.
`GET`	`/telephony-configs/{config_id}/available-numbers`	List DIDs the provider account exposes (not yet added).
`POST`	`/telephony-configs/{config_id}/phone-numbers`	Add a number; optionally attach an inbound agent.
`GET`	`/telephony-configs/{config_id}/phone-numbers/{phone_number_id}`	Number detail.
`PUT`	`/telephony-configs/{config_id}/phone-numbers/{phone_number_id}`	Swap / clear the inbound agent, toggle active.
`POST`	`/telephony-configs/{config_id}/phone-numbers/{phone_number_id}/set-default-caller`	Mark as default caller ID for outbound.
`DELETE`	`/telephony-configs/{config_id}/phone-numbers/{phone_number_id}`	Remove the number.

The IDs you'll use

Config/number path params are numeric; agents are addressed by UUID

The config and phone-number resources are keyed on numeric integer IDs (path params). But an agent is always addressed by its UUID — both here (inbound_agent_uuid in the add/update-number body) and on POST /call. An agent has both a numeric id and a uuid (POST /agents returns both), but for inbound attachment you send the uuid.

ID	Type	Where it comes from	Where you use it
`config_id`	int	`POST /telephony-configs` response `id`, or `GET /telephony-configs`	Path param on every config/number endpoint.
`phone_number_id`	int	`POST .../phone-numbers` response `id`, or the list endpoint	Path param on number get/update/delete.
`inbound_agent_uuid`	string	An agent's `uuid` from `POST /agents` / `GET /agents`	Body of add/update-number to route inbound calls to a saved agent.
`agentId` (UUID)	string	An agent's `uuid`	Also the `POST /call` body — same UUID used for inbound attachment above.

Scenario: create an agent and route a number to it (all via API)

1. POST /agents                         → { "id": 42, "uuid": "550e8400-…", … }
2. POST /telephony-configs/{id}/phone-numbers   (or PUT to an existing number)
        body: { "address": "+14155550100", "inbound_agent_uuid": "550e8400-…" }
        → auto-registers the inbound webhook on the provider
3. PATCH /agents/{uuid}                   → edit the agent anytime; changes apply
                                           on the next inbound call (resolved fresh)

Step 2 uses the agent's uuid (550e8400-…) as inbound_agent_uuid — not the numeric id. The same uuid is what you'd pass as agentId on POST /call to place an outbound call with that agent.

Inbound Bindings — API-first transient inbound routing
Place an outbound call — dial from a config's number
Tata Smartflo setup — streaming-native specifics