Attach a Number to an Agent

Overview

The platform telephony plane (client.telephony.*) maps your phone numbers to voice agents on backend-core’s /api/v2/platform/telephony/* surface. The primary flow is attach a number to an agent — what telephony calls the Leg-B termination (Unpod’s SuperSBC routes the inbound call through to your agent on LiveKit). You list your org’s numbers, then attach one or many to an agent. The underlying voice bridge is resolved for you (hidden) — you work with numbers and agents, not bridges.

This plane (client.telephony.*) is distinct from the Speech Stack management plane at client.numbers / client.trunks. The telephony plane is Org-Handle-scoped and requires proxy/JWT auth — it is not reachable in direct/Bearer mode.

Concepts

Concept	What it is
Leg B (agent attach)	SuperSBC → agent/LiveKit. The primary flow — `numbers.attach(..., agent_id=...)`.
Leg A (BYO carrier)	Your own SIP carrier → SuperSBC. The carrier leg is the hardcoded SuperSBC default today; bringing your own carrier (`client.telephony.trunks.`) is future/beta*.
`agent_id`	The agent handle a number routes to. Optional — attach now, bind an agent later.
Bridge	The voice bridge a number rides on. Auto-resolved and hidden — one number maps to one bridge.

Authenticate

The telephony plane is org-scoped. Authenticate with a JWT and your org handle:

import asyncio
from unpod import AsyncClient, JWTAuth

async def main():
    async with AsyncClient(auth=JWTAuth("<jwt>", org_handle="acme")) as client:
        numbers = await client.telephony.numbers.list()
        for n in numbers:
            print(n.number, n.status)

asyncio.run(main())

List Numbers

numbers = await client.telephony.numbers.list()

Number fields

Every verb on this plane takes the E.164 number — the internal id is not exposed.

Field	Type	Description
`number`	`str \| None`	E.164 format, e.g. `+14155550100`
`status`	`str \| None`	`not_assigned` (attachable), `assigned`, or `closed`

Attach Numbers to an Agent

Map one or more numbers to an agent by E.164 number (not id — Django resolves it). The bridge is resolved automatically; each number reports its own outcome (partial-success), so one bad number never fails the rest.

import asyncio
from unpod import AsyncClient, JWTAuth

async def main():
    async with AsyncClient(auth=JWTAuth("<jwt>", org_handle="acme")) as client:
        nums = await client.telephony.numbers.list()
        res = await client.telephony.numbers.attach(
            [n.number for n in nums[:2]],
            agent_id="asst_sales",
        )
        print(res.agent_id, res.message)
        for r in res.numbers:
            print(r.number, r.connection_state, "ok" if r.ok else r.error)

asyncio.run(main())

Result fields

Field	Type	Description
`agent_id`	`str \| None`	The agent the numbers were bound to (echoes the request).
`numbers`	`list[NumberResult]`	Per-number outcome (see below).
`message`	`str \| None`	Human-readable summary.

Each NumberResult:

Field	Type	Description
`number_id`	`int`	The number’s ID.
`number`	`str \| None`	E.164, on success.
`connection_state`	`str \| None`	Lifecycle state (e.g. `NOT_LINKED`, `PENDING_VERIFY`).
`agent_id`	`str \| None`	The bound agent, on success.
`ok`	`bool`	`True` if this number was attached.
`error`	`str \| None`	Why it failed, when `ok` is `False`.

The agent attach returns the per-number lifecycle — there is no carrier origin_endpoint. That belongs to the BYO-carrier (Leg-A) path below.

`agent_id` is optional

Omit agent_id to wire a number for agent use without binding an agent yet — bind one later by calling attach again with the same number and an agent_id:

# provision now, bind later
await client.telephony.numbers.attach(["+14155550100"])
# ...later
await client.telephony.numbers.attach(["+14155550100"], agent_id="asst_sales")

Attach to a pipe instead of an agent

Pass attach_type="pipeline" with a pipe_id to terminate the number on a Speech Pipe rather than an agent. attach_type defaults to "agent".

await client.telephony.numbers.attach(
    ["+14155550100"], attach_type="pipeline", pipe_id="pipe_xyz",
)

Detach Numbers

Release numbers by E.164 number — the inverse of attach. The termination, agent, and pipe are read from the stored record. The number is released, not deleted, so it stays available for a later re-attach.

res = await client.telephony.numbers.detach(["+14155550100"])
for r in res.numbers:
    print(r.number, "released" if r.ok else r.error)

Check the Lifecycle

overview = await client.telephony.overview()
for row in overview:
    print(row.number, row.agent_id, row.connection_state, row.in_sync)

Bring Your Own Carrier (Leg A) — Future / Beta

Bringing your own SIP carrier (client.telephony.trunks.*) wires the Leg-A carrier leg. Today that leg is the hardcoded SuperSBC default, so this surface is future/beta — prefer the agent attach above for production. When enabled, the flow is: create a trunk, attach numbers, and point your carrier at the returned origin endpoint.

# future / beta — BYO SIP carrier (Leg A)
trunk = await client.telephony.trunks.create(
    name="My Carrier", sip_url="sip:carrier.net",
    username="u", password="p", source_ips=["203.0.113.10"],
)
res = await client.telephony.trunks.attach_numbers(trunk.id, number_ids=[1, 2])
print(res.origin_endpoint.ingress)  # point your carrier here

Common Patterns

Attach the first available number to an agent

import asyncio
from unpod import AsyncClient, JWTAuth

async def attach_first(agent_id: str) -> None:
    async with AsyncClient(auth=JWTAuth("<jwt>", org_handle="acme")) as client:
        nums = await client.telephony.numbers.list()
        if not nums:
            raise RuntimeError("No numbers available")
        res = await client.telephony.numbers.attach([nums[0].number], agent_id=agent_id)
        row = res.numbers[0]
        print("attached" if row.ok else f"failed: {row.error}", nums[0].number)

asyncio.run(attach_first("asst_sales"))

Attach many numbers to one agent

import asyncio
from unpod import AsyncClient, JWTAuth

async def attach_all(numbers: list[str], agent_id: str) -> None:
    async with AsyncClient(auth=JWTAuth("<jwt>", org_handle="acme")) as client:
        res = await client.telephony.numbers.attach(numbers, agent_id=agent_id)
        ok = [r.number for r in res.numbers if r.ok]
        bad = [(r.number_id, r.error) for r in res.numbers if not r.ok]
        print("attached:", ok)
        if bad:
            print("failed:", bad)

asyncio.run(attach_all(["+14155550100", "+14155550101"], "asst_sales"))

Overview

Space View

Studio View

Dev Platform

Self-Hosting

Attach a Number to an Agent

Overview

Concepts

Authenticate

List Numbers

Number fields

Attach Numbers to an Agent

Result fields

`agent_id` is optional

Attach to a pipe instead of an agent

Detach Numbers

Check the Lifecycle

Bring Your Own Carrier (Leg A) — Future / Beta

Common Patterns

Attach the first available number to an agent

Attach many numbers to one agent

Next Steps

Agents

Numbers

​Overview

​Concepts

​Authenticate

​List Numbers

​Number fields

​Attach Numbers to an Agent

​Result fields

​agent_id is optional

​Attach to a pipe instead of an agent

​Detach Numbers

​Check the Lifecycle

​Bring Your Own Carrier (Leg A) — Future / Beta

​Common Patterns

​Attach the first available number to an agent

​Attach many numbers to one agent

​Next Steps

Agents

Numbers

Overview

Concepts

Authenticate

List Numbers

Number fields

Attach Numbers to an Agent

Result fields

`agent_id` is optional

Attach to a pipe instead of an agent

Detach Numbers

Check the Lifecycle

Bring Your Own Carrier (Leg A) — Future / Beta

Common Patterns

Attach the first available number to an agent

Attach many numbers to one agent

Next Steps