Skip to main content

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 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
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:
ColumnDescription
NumberThe phone number (with country code)
SourceThe telephony integration the number belongs to (e.g., Twilio, PolyAI)
Assigned variantWhich 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 or US phone number
  3. For US numbers, you can optionally specify an area code
  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 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
Deleting a live number removes it immediately. Calls to that number will stop reaching your agent.
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

Buy a number

Step-by-step guide for purchasing a phone number

Variant management

Configure variants for multi-site deployments

Twilio integration

Connect your existing Twilio account

Outbound calling

Configure proactive outbound calls
Last modified on April 20, 2026