Skip to main content
A phone number routes calls to an agent only after you assign a published agent version to it. Each number has two independent slots — one for inbound calls and one for outbound calls — so the same number can answer with one agent and dial out with another, or use the same agent for both. Assignment is performed by the agent version publish endpoint. Publishing a version both marks it as live and deploys it onto the inbound and/or outbound slots of the numbers you name in the request.

​
The two-slot model

Every number stores two assignment slots: The slots are independent. Setting one direction never touches the other unless you explicitly target both. An empty slot means no agent handles that direction for that number.
Only published versions are assignable. The publish endpoint sets the version’s published flag to true before it writes the assignment, so deploying a version always publishes it in the same call.

​
Assign a version

Call the publish endpoint with the version you want live, the numbers to deploy to, and the direction.
The endpoint requires the agents:manage scope and returns the list of updated PhoneNumber records.
Publishing is blocked while a version’s instructions are being generated, and when the instructions are stale (dirty) and have not been manually edited — regenerate first. Both cases return 400.

​
Direction values

​
Unassign a version

To remove an agent from a number, send the numbers under unassign_phone_numbers with the direction to clear. Only slots currently pointing at a version of this agent are cleared — slots holding a different agent are left untouched.
You can assign and unassign in the same request by including both phone_numbers and unassign_phone_numbers. The response combines both result sets, deduplicated by number.

​
Editing from the Phone Numbers page

The Phone Numbers page provides an edit dialog as an alternate entry point to the same flow. For each number you pick an agent and version per side (Inbound and Outbound), and selecting None clears that side. Behind the dialog, choosing a version calls the same publish endpoint, and clearing a side calls the same unassign path — so the result is identical to driving the API directly.

Creating an agent

Build and publish the agent version you assign to a number.

Telephony overview

How numbers, calls, and agents fit together.