# Phone Numbers and Caller ID

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.

## What you'll need

- **Tenant admin.** Adding, editing and deleting numbers is a tenant-admin
  surface. If you hold `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.

## Find the page

**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.

### Default Country Code

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.

## Add a number

Click **Add Number**. The form has two tabs.

### Search & Purchase

The usual path — buy a number and have the SIP trunking configured for you.

1. **Search Available Numbers**: choose a **Country** (United States or
   Canada), optionally an **Area Code**, and how many **Results** to show.
2. Click **Search Numbers**.
3. Under **LiveKit Options**, decide on **Enable Krisp Noise Cancellation** —
   AI noise cancellation on inbound calls. Leave it on unless you have a
   reason not to; call audio from mobiles and speakerphones is the main input
   your agent works from.
4. Pick a number from **Available Numbers** and purchase it.

### Manual Configuration

For a number you already own on a carrier you already have. You supply the
SIP details yourself:

- **Phone Number**
- **Termination URI**
- **SIP Trunk User Name** and **SIP Trunk Password**
- **Nickname (Optional)**
- **Enable Krisp Noise Cancellation**

Get these from whoever holds the number. A wrong termination URI shows up as
calls that ring and never connect.

## Configure a number

Click **Edit** on a row. **Phone Configuration** holds the fields above plus:

- **Campaign SMS rate (msgs/sec, optional)** — the outbound throttle for
  campaign sends on this number. Leave it blank for the safe long-code
  default; raise it for a toll-free or short code.
- **Allow Inbound SMS** — configures the number in Twilio to receive incoming
  texts. Required if an agent should be able to receive a reply to something it
  sent, including a reply routed back into a live voice call.
- **Google Ads destination number** — turn this on if this is the number you
  entered in Google Ads as a message asset, call asset or Local Services call
  destination. Every call and text landing here is then attributed to Google
  Ads. Use a number reserved for ads if you want the attribution to stay
  clean.
- **Also receives forwarded calls** — turn this on if another phone line
  forwards calls to this number, then list those lines under **Forwarded
  from**. See the next section for what it changes.

## Forwarded calls and caller ID

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.

## Outbound Caller ID

The **Outbound Caller ID** card decides what a recipient sees when this number
places a call. By default they see the number itself.

1. **Display as** — leave it on **Use this number itself (+1…)**, or pick a
   different number from the list of verified caller IDs.
2. To use a number you have not verified yet, click **Verify a new number**
   and prove you own it. Until then it will not appear in the list — this is a
   carrier requirement, not a Karmaflow.ai one, and it exists to stop caller-ID
   spoofing.
3. **Display name (CNAM)** — up to 64 characters, e.g. "Karmaflow.ai Sales". It
   is sent alongside whichever number is in use.

Two things worth knowing about CNAM:

- **Carriers may override or ignore it**, US mobile networks especially. Treat
  it as a request, not a guarantee.
- **It is set on the number, not on the agent.** Changing it changes what
  every agent using this number displays. The agent form's **Telephony** tab
  shows you the current caller ID and CNAM for the selected number, with a
  link straight to this page, precisely so nobody changes it without seeing
  who else is affected.

## Assign a number to an agent

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…**.

### Inbound routing, and the one-agent rule

```mermaid
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](/help/voice-agents/testing-and-promotion).

## Troubleshooting

- **The number dropdown on the agent form is empty.** No numbers are
  provisioned. The field links to this page; a tenant admin has to add one.
- **I can see the Phone Numbers row in Settings but not Add Number.** You are
  not a tenant admin.
- **Callers reach a dead line.** Check **Used By** on the number, that the
  agent holding it is **Inbound**, and that it has been promoted.
- **Promotion was refused over the phone number.** Another production inbound
  agent already holds it. Free it there first.
- **Recipients see a different number than I configured.** Check **Display
  as** on the number itself rather than the agent — caller ID is per number.
- **The display name never shows.** Carrier CNAM behaviour, particularly on US
  mobile. Nothing in the product can force it.
- **The agent's texts get no replies.** **Allow Inbound SMS** is off on the
  number it texts from.
- **The agent saved my own business number as a caller's phone, or texted my
  front desk.** The call was forwarded from one of your lines. On the number it
  landed on, turn on **Also receives forwarded calls** and add that line under
  **Forwarded from**.
- **The agent keeps confirming the caller's number on a number that takes
  forwarded calls.** **Also receives forwarded calls** is on with no lines
  listed, so it cannot tell a forwarded call from a direct one. List the
  forwarding lines under **Forwarded from**.

## Next steps

- [Create a Voice Agent](/help/voice-agents/creating-campaigns)
- [Placing Outbound Calls](/help/voice-agents/campaign-usage)
- [Transfers, Forwarding and the Duty Roster](/help/voice-agents/transfers-and-escalation)
- [Phone System Integration (PBX / 3CX)](/help/voice-agents/phone-system-integration)