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

# Manage numbers

> View, route and delete the phone numbers connected to your agent from the Telephony tab.

Every phone number connected to your agent is listed in Agent Studio under **Integrations** > **Telephony**. Use this tab to add numbers, choose the environment and variant each one reaches, and delete numbers you no longer need.

> [!NOTE]
>
> The **Numbers** tab on the Voice page has been replaced by the **Telephony** tab. Handoffs moved with it: click **Handoffs** on the Telephony tab to open them.

## The numbers table

The tab lists each connection with its numbers. A SIP trunk or contact center connection appears as a card that you can expand to see its numbers and connection details.

| Column | What it shows |
| - | - |
| **Number** | The phone number or extension, with its country code. |
| **Channels** | **Voice** on every number. **SMS** and **RCS** appear on numbers that have messaging turned on. |
| **Environment** | The environment that answers calls on the number. |
| **Assigned variant** | The [variant](https://docs.poly.ai/knowledge/variants/introduction.md) that handles calls on the number, or **Default**. |
| **Trunk** | The connection the number belongs to, such as a SIP trunk or Twilio. |

Sandbox has no phone numbers. Test there with an in-app call or [simulation tests](https://docs.poly.ai/testing/simulation-tests.md). See [Environments](https://docs.poly.ai/environments-and-versions/environments.md#channels).

## Add a number

Click **Add number** and choose how calls should reach your agent. See [Telephony](https://docs.poly.ai/integrations/voice/introduction.md) for every option.

To add a number to a SIP trunk you already have, open the trunk card's actions menu (**⋯**) and click **Add number**. See [Add numbers and extensions](https://docs.poly.ai/integrations/voice/sip/custom-sip.md#add-numbers-and-extensions).

> [!TIP]
>
> Use separate numbers for each environment so test calls never reach Live.

## Change the environment

Click the number's **Environment** value and pick a new one. The change saves immediately, and the next call to the number reaches that environment.

## Change the variant

1. Open the number's actions menu (**⋯**) and click **Change variant**.
2. In the **Change assigned variant** panel, pick a variant under **Assigned variant**, or leave it on **Default (no variant)** to follow the agent's default variant.
3. Click **Save change**. Calls to the number route to that variant as soon as the change saves.

A variant is listed once a version that contains it is running in the number's environment. If none are listed, publish to Live or move your Branch to Staging first.

## Turn on SMS

If your project has SMS set up, a number bought through PolyAI can also send and receive texts. Open the number's actions menu and click **Turn on SMS**. The number then shows **SMS** under **Channels**. Click **Turn off SMS** in the same menu to stop.

Some numbers that predate the Telephony tab can't have SMS changed here. The menu says so when that applies. See [SMS](https://docs.poly.ai/voice-channel/message-templates.md) and [Number availability](https://docs.poly.ai/voice-channel/number-availability.md).

## Delete a number

1. Open the number's actions menu and click **Delete number**.
2. Confirm.

Calls to the number stop reaching your agent. A number bought through PolyAI is also released, so you can't get it back. A number on your own SIP trunk, Twilio account or contact center stays with your provider.

> [!WARNING]
>
> Deleting a Live number takes effect immediately. You can't undo it.

## Automate with the Agents API

Use the [Agents API](https://docs.poly.ai/api-reference/agents/introduction.md) to provision numbers in bulk or to change routing as part of a deployment. A connector binds phone numbers to voice infrastructure, and each number is an E.164 string routed through a connector.

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Import a phone number onto an existing connector
curl -X POST https://api.us.poly.ai/v1/agents/AGENT_ID/telephony/phone-numbers/+442071234567 \
  -H "x-api-key: $POLYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "connectorId": "conn_abc123" }'

# Reassign a number to a different connector
curl -X PATCH https://api.us.poly.ai/v1/agents/AGENT_ID/telephony/phone-numbers/+442071234567 \
  -H "x-api-key: $POLYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "connectorId": "conn_new456" }'
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os, requests

BASE = "https://api.us.poly.ai"
HEADERS = {"x-api-key": os.environ["POLYAI_API_KEY"]}

# Look up which connector serves a given number
resp = requests.post(
    f"{BASE}/v1/agents/{AGENT_ID}/telephony/connectors/lookup",
    headers=HEADERS,
    json={"phoneNumber": "+442071234567"},
)
connector = resp.json()
```

See [Connectors](https://docs.poly.ai/api-reference/agents/endpoint/connectors/list-all-connectors-for-a-project.md) and [Phone numbers](https://docs.poly.ai/api-reference/agents/endpoint/phone-numbers/list-all-phone-numbers-for-a-project.md) for the full endpoint list. To manage SIP trunks and their extensions in code, use the [SIP Trunking API](https://docs.poly.ai/api-reference/sip-trunking/introduction.md).

## Troubleshooting

| Issue | Solution |
| - | - |
| The **Telephony** tab shows **Couldn't load numbers** | Check that you have telephony admin access on the account, then click **Try again**. |
| **Add number** doesn't appear | Your role can't configure telephony on this project. Ask an account admin for access. See [Access control](https://docs.poly.ai/user-management/access-control-scope.md). |
| No variants are listed in **Change assigned variant** | No version with variants is running in the number's environment yet. Publish to Live, or move your Branch to Staging. |
| Calls reach the wrong environment or variant | Check the number's **Environment** and **Assigned variant** in the table. |

## Related pages

> [card] [Telephony](https://docs.poly.ai/integrations/voice/introduction.md)
>
> Every way to connect a number to your agent

> [card] [Handoffs](https://docs.poly.ai/voice-channel/handoffs.md)
>
> Transfer callers to your team

> [card] [Variants](https://docs.poly.ai/knowledge/variants/introduction.md)
>
> Run one agent across several sites or brands

> [card] [Outbound calling](https://docs.poly.ai/voice-channel/numbers/outbound-calling.md)
>
> Have your agent place calls
