> ## Documentation Index
> Fetch the complete documentation index at: https://help.callaro.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Adding phone numbers

# Adding phone numbers

In the app, phone numbers are managed under **Connectivity → Phone numbers**. The list subtitle states they are **reference numbers (Twilio-managed or BYOT)** and that routing comes from your CRM/telephony layer; associations support UX and reporting.

![Add phone number page in Callaro.](https://mintcdn.com/callaro-docs/1fJs_sKJdgiwY8nj/images/phone-numbers/add-number.png?fit=max\&auto=format\&n=1fJs_sKJdgiwY8nj\&q=85\&s=ef715e69ff1123477435de7afa2c76cb)

**What the static should show:** The **Phone numbers** page with the **Phone numbers** header, **Search numbers...**, optional filters when attributes exist, table columns (**Number**, **Status**, **Inbound Agent**, **Provider**, **Name**, **Created**), and primary **Add number** (when your role can write the workspace).

## List page

* **Tenant required:** Without a tenant selected (for roles that need one), you see **Select a tenant to view and manage phone numbers.**
* **Superadmin:** An extra **Tenant** column appears when listing across tenants.
* **Status column:** Renders a badge from API status (success style when active, otherwise neutral). A **Twilio** outline badge appears for platform-managed numbers.
* **Number** cells link to the phone number detail page (monospace display).
* **Inbound Agent** shows the agent name or **Unassigned**.
* **Provider** shows telephony connection name and provider, or **—** if missing.
* Pagination and search sync via the table’s query params (page, per\_page, search, plus structured filters when enabled).

![GIF media slot](https://mintcdn.com/callaro-docs/1fJs_sKJdgiwY8nj/images/phone-numbers/slot-01.gif?s=9d22d8189ffb46944510dac802ed703d)

**What the GIF should show:** Opening **Add number**, choosing **Purchase from Twilio** or **Add manually**, completing configure, and landing on the new number’s detail page.

## Add flow

Header: **Add phone number** (or **Number added** on success). Back to the list is available from the first step and the completion step.

### Step 1 — Choose source

* **Purchase from Twilio** — Shown only if an **active** telephony connection with provider Twilio exists. Card title **Purchase from Twilio**; description mentions search/buy and automatic webhook configuration.
* **Add manually** — Always available. Description: register an existing number from any provider (Twilio, Plivo, mCube, Exotel, and other BYOT connections).
* **Plivo** — When an active Plivo telephony connection exists, you can import or register a Plivo DID and point the Plivo Application Answer URL at `/api/v1/webhooks/telephony/plivo`. Plivo minutes stay on your Plivo account (BYOT).
* If Twilio is not connected: helper text explains you must add a Twilio telephony connection first.

### Twilio path — Search (sub-step 1 of 3)

Card **Search available numbers** with:

* **Country** and **Number type** (options depend on loaded countries from the add-number flow).
* Optional **Area code** and **Contains** filters.
* **Search available** (available tab) or **Load my Twilio numbers** (owned tab).
* Tabs: **Available to purchase** | **In your Twilio account** (owned list supports **Refresh**; rows show **Already imported** vs **Not in app yet**).
* Select a row, then **Continue with `{number}`**.

Confirm dialogs:

* **Purchase:** warns of Twilio charges and webhook configuration.
* **Import owned:** warns that voice webhook and status callback will be updated and may break other integrations.

### Manual path (sub-step 1 of 2)

Card **Add number manually**:

* **Phone number (E.164)** (placeholder +14155551212 style).
* **Telephony connection** (active connections only).
* **Next: Configure number** is disabled until both E.164 and connection are set.

### Configure number (assign step)

Card **Configure number** with context-specific description (purchase vs import vs manual).

* Twilio flows show an alert **Twilio webhook configuration** (Voice URL and Status Callback set automatically; import may replace existing integrations).
* **Label (name)** — optional.
* **Inbound call agent** — optional; **No agent (assign later)** / active agents from the agent list.
* **Allowed inbound countries** / **Allowed outbound countries** — multi-select; empty means no restriction (helper text on screen).
* Primary action: **Purchase & configure**, **Import & configure**, or **Add number** (manual add).
* Vendor-specific fields (e.g. mCube executive number) appear for manual BYOT flows when the vendor exposes extra phone fields.

### Done

Success card **Phone number added** with **View number**, **Go to campaigns**, and **Add another** (resets the wizard).

![Video media slot](https://mintcdn.com/callaro-docs/1fJs_sKJdgiwY8nj/media/phone-numbers/slot-01.mp4?fit=max\&auto=format\&n=1fJs_sKJdgiwY8nj\&q=85\&s=77953cfa28b118fc3b17ddf123876665)

**What the video should show:** Full path from list → **Add number** → manual registration with connection + agent → **View number** on detail.

## Detail page

The detail view includes:

* Header card: **E.164**, **status** badge, **Twilio-managed** vs **BYOT** badge, label/provider/country/type line.
* **Activate** / **Deactivate**, **Release number** (Twilio-managed only, destructive confirm), **Re-sync from Twilio** when a Twilio SID exists.
* Sections with per-section **Save**: **Label**, **Inbound call agent**, **Allowed inbound countries**, **Allowed outbound countries**, **Configuration** (telephony connection; read-only text for platform-managed purchased numbers), optional provider fields, webhook URL copy when exposed, **Configure webhooks on `{provider}`** when the vendor supports webhook config in-app.
* **Campaign Health** table when campaign number health is present (campaign link, pool status, attempts, answered, answer rate, weight).

## Edit screen

The same underlying detail experience is used after an access check; the header may read **Edit phone number** with a back link to the detail.

## Common mistakes

1. **No Twilio purchase card** — Add an active Twilio telephony connection first.
2. **Import breaks another app** — The import confirm dialog states webhooks will change; read it before confirming.
3. **Wrong workspace** — Tenant must match; permission errors show **Resource not available** with a way back to the list.

## Related articles

* [Assigning phone numbers to a campaign](https://help.callaro.ai/campaigns/assigning-phone-numbers.md)
* [Number rotation](https://help.callaro.ai/phone-numbers/number-rotation.md)
* [Sticky number assignment](https://help.callaro.ai/phone-numbers/sticky-number-assignment.md)
* [What to do if a number gets flagged as spam](https://help.callaro.ai/phone-numbers/spam-flagged-numbers.md)
* [Wizard Step 2: Telephony](https://help.callaro.ai/campaigns/wizard-step-2-telephony.md) (campaign number pool)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.