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

# Phone numbers

> Add, manage, and track phone numbers used by your agent.

Phone number management is available under **Configure > Numbers** once a telephony integration has been established between your telephony provider and PolyAI.

Use the Numbers page to add, delete, and assign phone numbers across your agent's environments. Numbers are grouped by environment – sandbox, pre-release, and live – so you can manage test and production numbers separately.

## Prerequisites

* A telephony integration must be configured between your provider and PolyAI (SIP peering, Twilio, etc.)
* Your account must have the appropriate [access permissions](/user-management/access-control-scope)

If no integration exists yet, the page displays a message asking you to contact the PolyAI team.

## Viewing numbers

Navigate to **Configure > Numbers** to see all phone numbers for your project, grouped into collapsible sections by environment:

* **Sandbox** – numbers for testing your latest saved version
* **Pre-release** – numbers for pre-production validation
* **Live** – numbers serving production traffic

Each section displays a table with:

| Column               | Description                                                                                                               |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Number**           | The phone number (with country code)                                                                                      |
| **Source**           | The telephony integration the number belongs to (e.g., Twilio, PolyAI)                                                    |
| **Assigned variant** | Which [variant](/variant-management/introduction) handles calls on this number (only shown if your project uses variants) |

Each environment section also shows **SIP addresses** (main and fallback) that you can copy for use in your telephony configuration.

## Adding a number

1. Select **Number** (the add button) in the environment section where you want the number
2. Choose the number type:
   * **UK** or **US** phone number
3. For US numbers, you can optionally specify an **area code**
4. If your project uses [variants](/variant-management/introduction), optionally assign the number to a variant
5. Select **Add**

Phone numbers are purchased through PolyAI's telephony infrastructure. You can also connect an existing Twilio number – select that option in the modal and follow the instructions.

## Assigning a variant

If your project uses [variants](/variant-management/introduction), you can assign or reassign a variant to any number:

1. Open the actions menu (three-dot icon) on a number row
2. Select **Reassign variant**
3. Choose the variant from the list
4. Select **Assign**

Variants must be published to the target environment before they can be assigned. If no variants are available, publish the project first.

## Deleting a number

1. Open the actions menu on a number row
2. Select **Delete number**
3. Confirm the deletion

<Warning>
  Deleting a live number removes it immediately. Calls to that number will stop reaching your agent.
</Warning>

## Variant-related callouts

The Numbers page displays contextual messages when variant changes affect your numbers:

* **New variant added** – publish the project so you can assign the new variant to numbers
* **Variant deleted** – some assigned variants were removed; publish to see the changes
* **Draft variants** – your project now uses variants; publish so you can assign them

## Fallback and routing configuration

Fallback routing and advanced telephony settings (language, SIP REFER/INVITE configuration, per-route fallback numbers) are not configured through the Numbers UI. These are managed at the infrastructure level by PolyAI. Contact your PolyAI account manager if you need to:

* Configure a fallback number for when the agent is unavailable
* Set up language-specific routing
* Configure SIP REFER or INVITE handoff behavior

## Related pages

<CardGroup cols={2}>
  <Card title="Buy a number" icon="cart-shopping" href="/telephony/how-to-buy-number">
    Step-by-step guide for purchasing a phone number
  </Card>

  <Card title="Variant management" icon="code-branch" href="/variant-management/introduction">
    Configure variants for multi-site deployments
  </Card>

  <Card title="Twilio integration" icon="phone" href="/telephony/twilio/introduction">
    Connect your existing Twilio account
  </Card>

  <Card title="Outbound calling" icon="phone-arrow-up-right" href="/telephony/outbound-calling">
    Configure proactive outbound calls
  </Card>
</CardGroup>