Phone numbers

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

Phone number management is available under Voice > 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 – Staging and Live – so you can manage test and production numbers separately. Sandbox has no phone numbers because it holds many versions at once. Test in Sandbox with an in-app call or simulation tests.

Prerequisites

• A telephony integration must be configured between your provider and PolyAI (SIP peering, Twilio, etc.)
• Your account must have the appropriate access permissions

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

Viewing numbers

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

• Staging – numbers for testing a Branch the way a customer would, before you publish (Branches and Sub-branches modes only)
• Live – numbers serving production traffic

If a Sandbox section still appears, it lists numbers left over from the old deployment system. Remove any that remain.

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 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, US, or Canada (CA) phone number
3. For US and Canada numbers, you can optionally specify a 3-digit area code. Both countries share the North American Numbering Plan (NANP), so area code selection works identically.
4. If your project uses variants, 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, 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 are available in an environment once a version that contains them is running there. Publish to Live, or move the Branch to Staging. If no variants are available, publish first.

Deleting a number

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

Deleting a Live number removes it immediately. Calls to that number will stop reaching your agent.

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
• Unpublished 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

Buy a number

Step-by-step guide for purchasing a phone number

Variants

Configure variants for multi-site deployments

Twilio integration

Connect your existing Twilio account

Outbound calling

Configure proactive outbound calls