The model
Three objects make up the telephony layer:| Object | What it is |
|---|---|
| Phone number | A purchased or imported number with independent inbound and outbound agent slots. Belongs to one trunk. |
| Trunk | A SIP trunk that connects your org to a carrier. Either Anyreach-managed (Twilio) or bring-your-own-carrier (BYOC). |
| Inbound routing config | An optional per-org workflow that decides which agent answers an incoming call at call time. |
/core/phone-numbers) has two slots that are set independently:
| Field | Type | Default | Description |
|---|---|---|---|
inbound_agent_version_id | string | none | Agent version that answers calls to this number. |
outbound_agent_version_id | string | none | Agent version used when this number places calls. |
trunk_id | string | required | The trunk that carries calls for this number. |
outbound_shareable | bool | false | Whether the number can be used as caller ID by other agents. |
sip:<agent-uuid>@<host>, and LiveKit bridges the carrier leg to the agent leg.
Trunks: managed vs BYOC
Every number sits on a trunk. There are two kinds.| Managed (Twilio) | BYOC | |
|---|---|---|
| Provider | Anyreach-operated Twilio account | Your own SIP carrier |
managed_account_id | set | not set |
| How numbers are added | Bought through Anyreach (purchase-number) | Imported onto the trunk you create |
| Created/edited via API | No — managed trunks are provisioned by Anyreach | Yes — POST /core/trunks |
| Best for | Getting started quickly with US local numbers | Keeping existing carrier contracts and numbers |
| Field | Type | Default | Description |
|---|---|---|---|
address | string | required | Carrier SIP host to send calls to. |
auth_username | string | required | SIP auth username. |
auth_password | string | required | SIP auth password. |
transport | enum | UDP | SIP transport. |
media_encryption | enum | NONE | Media encryption setting. |
Getting numbers
There are two ways to get a number onto a trunk:- Buy (managed)
- Import (BYOC, advanced)
Search the shared Anyreach Twilio account and purchase a number. Search defaults to
country_code US and number type local; the search filters voice, SMS, MMS capability, area code, region, and postal code. Purchased numbers land on your managed trunk automatically.Inbound routing
Once a number has an inbound agent version, every call to it reaches that agent. For static routing, that is all you need — the number maps to one agent. For dynamic routing, configure an inbound routing config for the org. It runs aworkflow_definition at call time to pick the agent, with a fallback_agent_id / fallback_agent_version used when the workflow does not select one. There is one config per org, and it has an enabled flag (default true).
| When to use | Choose |
|---|---|
| Each number always answers with the same agent | Static — set inbound_agent_version_id on the number |
| The answering agent depends on caller, time, or other logic | Dynamic — enable an inbound routing config |
Next steps
Buy a number
Search the Anyreach Twilio account and purchase a US local, voice-enabled number.
Assign agents to numbers
Set the inbound and outbound agent-version slots on a number.
Inbound routing
Route incoming calls statically or with a routing workflow.
SIP and BYOC
Bring your own carrier with a SIP trunk and import existing numbers.