Buy or connect a number, set what recipients see when agents call out, allow inbound SMS, and see which agents use which line.
Phone numbers are the lines your voice and SMS agents answer and call from. They are workspace-level infrastructure, not part of an agent — one number can be referenced by a voice agent, an SMS agent and a task agent, and the page below is where you see who is using what.
agents:voice:manage but are not a tenant admin, you
can select an existing number on an agent but not create one — ask an
admin, or use the link the agent form shows beside the empty dropdown.Settings (the gear icon) → Channels → Phone Numbers
(/admin/tenants/settings/phone-numbers).
The page opens on a Default Country Code field, then a table of your numbers:
| Column | Shows |
|---|---|
| Phone Number | The number in E.164 form |
| Termination URI | The SIP endpoint the number terminates on |
| SIP Trunk User Name | The trunk credential in use |
| Nickname | Your own label — what shows in the agent form's dropdown |
| Used By | Which agents currently reference this number |
| Actions | Edit, delete and per-number tools |
Read "Used By" before you change or delete anything. It is the only place that tells you what a number breaking would break.
The country code at the top is applied when a number is entered without one —
so a contact stored as 4165551234 is dialled correctly. Set it once, for the
country you call most.
Click Add Number. The form has two tabs.
The usual path — buy a number and have the SIP trunking configured for you.
For a number you already own on a carrier you already have. You supply the SIP details yourself:
Get these from whoever holds the number. A wrong termination URI shows up as calls that ring and never connect.
Click Edit on a row. Phone Configuration holds the fields above plus:
When a call reaches a Karmaflow number directly, the caller ID is the caller's own number and the agent uses it: it can save the caller as a contact with that number and text them a confirmation without asking. When a call is forwarded to a Karmaflow number from one of your own lines, many carriers and PBXs replace the caller ID with your line. The agent would then save your business number as the caller's phone, or text your own front desk.
To prevent that, click Edit on the number the calls are forwarded to, turn on Also receives forwarded calls, and list the lines that forward to it under Forwarded from, one per line with the country code. On every call landing on that number the agent then decides by the caller ID:
| Caller ID | What the agent does |
|---|---|
| One of the Forwarded from lines | Treats it as your own line. Asks the caller which number to text, never uses the caller ID. |
| Any other number | Treats it as the caller's own, a direct call. |
| The toggle is on but no lines are listed | Cannot tell, so it confirms the number with the caller before texting, reading back only the last digits. |
With the toggle off, every call on that number is treated as a direct call. Your Karmaflow numbers and verified caller IDs are always recognised as your own lines, so you do not need to list them. In every case the agent saves the caller as a contact with the name and email they give; only texting waits for a number.
Nothing else about the call changes. Transfers, the duty roster and the agent's answers work as before. The call's page shows how the caller ID was treated on its From row: From when it was used, From (your forwarding line) when it matched a listed line, From (caller ID not relied on) when it was uncertain.
The Outbound Caller ID card decides what a recipient sees when this number places a call. By default they see the number itself.
Two things worth knowing about CNAM:
Numbers are selected on the agent, not handed out from this page.
| Agent type | Where | Field |
|---|---|---|
| Voice | Telephony tab | Voice Phone Number — the line it answers or calls from |
| Voice | Telephony tab | SMS Number — the number it texts from |
| SMS | The agent's own settings | Its primary texting number |
| Chat / Task | The agent's own settings | An optional text number |
For a voice agent, assigning a Voice Phone Number is what flips the header badge from Not deployable yet to Approved · +1….
flowchart LR
A["Caller dials<br/>+1 555 0100"] --> B["Number's routing<br/>record"]
B --> C["The one PROMOTED<br/>inbound voice agent<br/>holding that number"]
C --> D["Call is answered"]
E["Draft agent<br/>with the same number"] -.->|"never receives<br/>a real call"| D
An inbound number can be live on only one production voice agent at a time. Promoting a second inbound agent that holds the same number is refused, with the conflict named — that is deliberate, because "which agent answers?" has to have exactly one answer.
Practical consequence: to hand a line from one agent to another, change the number on the old agent and promote that change, then assign it to the new one and promote.
Draft agents never receive real inbound calls at all, whatever number they hold. Test them with Talk to your agent or Simulate Call — see Testing, Drafts and Going Live.