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

# Phone numbers: connect an agent to a number

> How phone numbers work in Hamsa: assign a number to an agent, point it at an environment, test a call, and what happens when someone dials it.

A phone number lets callers reach your agent and lets your agent call out. You add numbers you already own (from Twilio or any SIP provider), then assign each one to an agent. This page covers assigning numbers, environments, testing and removing numbers. To add a number, see [Bring your own number](https://docs.tryhamsa.com/agents/connect/bring-your-own-number.md).

## Before you start

* You need at least one number in the project. Add it under **Telephony** > **Bring your own number**.
* Owners and Admins can add numbers and assign them. Members can see them. Only the Owner can delete a number. See [Roles and permissions](https://docs.tryhamsa.com/overview/projects/roles-and-permissions.md).

## How numbers and agents fit together

* A number answers for one agent at a time.
* An agent has at most one number per environment. Without deployments that means one number. With deployments on, it can have one number each for dev, staging and prod.
* The number decides which agent answers an inbound call. For outbound calls, you choose the number to call from.
* A number can be added to Hamsa only once. If it's already in use anywhere in Hamsa, adding it again fails with "The phone number is already used in the system."

## The phone numbers page

In the sidebar, open **Telephony** > **Bring your own number**. The page is titled **Phone numbers**. The list on the left shows each number with its label and provider. Click a number to open it.

![The Phone numbers page with four numbers in the list and the Office PBX SIP number open: Number configuration, SIP configuration and Usage with agents](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/connect/phone-numbers-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=581a6648389deb2c5a7793751c9543d6)

A number's page has these cards:

| Card | What it shows |
| - | - |
| **Number configuration** | The phone number, the provider and the label. |
| **Carrier setup** | Only for SIP numbers that go through the Hamsa SIP gateway: **Send calls to** and **Allow calls from** (the gateway's IP, `34.243.238.8`), the two values your provider needs. |
| **SIP configuration** | Only for SIP numbers: the origination URI, SIP address, transport type and headers you set when you added it. |
| **Usage with agents** | The agent this number answers for. This is the only part you can change. |

![A SIP number that goes through the Hamsa SIP gateway: Carrier setup with Send calls to and Allow calls from, and its SIP configuration](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/connect/phone-number-carrier-setup-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=9637c13a2f33b09cae517b67b001c71a)

You can't edit a number after you add it. To change its label, address or credentials, delete it and add it again.

## Assign a number to an agent

There are three places to do this. Use whichever you're in.

> [tab] From the number
>
> **1. Open the number**
>
> Go to **Telephony** > **Bring your own number** and click the number.
>
> **2. Pick the agent**
>
> In **Usage with agents**, open **Select agent** and pick an agent. It saves at once and shows "Agent assigned".
>
> ![The Select agent list in Usage with agents: None (disable inbound) and the project's agents, Billing Assistant ticked](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/connect/number-select-agent-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=0a80c396008760b1f7d66e784ec9c24f)
>
> **3. Confirm a move**
>
> If the number already answers for another agent, Hamsa asks **Reassign phone number** first. Click **Confirm** to move it. The other agent stops answering on it.
>
> ![The Reassign phone number confirmation: the number is assigned to Billing Assistant, with Cancel and Confirm](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/connect/reassign-number-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=4399ee480a9803d55a9c1042e1b06577)
>
> To stop the number from answering, pick **None (disable inbound)**.

> [tab] From the agent
>
> **1. Open the agent's phone settings**
>
> In the agent, open **Phone number** ("Assign a phone number for calls."). On a single prompt agent it's in **Configuration**. On a flow agent, open **Global settings** from the canvas toolbar.
>
> **2. Select a number**
>
> In **Select phone numbers**, search or filter by status and provider, pick a number and click **Done**.
>
> ![Select phone numbers in the agent's configuration: a search box, status and provider filters, the project's numbers with the agents they are assigned to, and Done](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/connect/agent-select-phone-numbers-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=0f530972a67ddb98434e57d0c5954a1d)
>
> **3. Confirm a move**
>
> If the number answers for another agent, Hamsa asks **Move this number?** Moving it here means the other agent stops taking calls on it.
>
> Changing the number from the agent needs the permission to manage channels (Owner and Admin by default). Without it, the number shows read only.

> [tab] With deployments on
>
> When the agent uses environments, the agent's **Phone number** section only lists its numbers, each with "Calls on this number reach prod" (or dev, staging), and a **Manage in Releases** link.
>
> ![The agent's Phone number section with deployments on: one number on prod, one on staging, and Manage in Releases](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/connect/agent-phone-number-deployments-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=56c9f3db6d1f8b17c53a1dff7972042a)
>
> Open **Releases** > **Channels** > **Phone** to add a number and choose the environment its calls land in. Each environment answers on one number. See [Environments and releases](https://docs.tryhamsa.com/agents/release/environments.md).

> [!NOTE]
>
> Assigning a number doesn't need a publish. Phone numbers aren't part of an agent version.

## How an inbound call is answered

1. Someone dials your number. Hamsa finds the agent the number is assigned to.
2. With deployments on, the call lands in the environment the number points at and is answered by the version published there. Otherwise, or if that environment has nothing published yet, the prod version answers.
3. If prod runs an [A/B test](https://docs.tryhamsa.com/agents/release/ab-tests.md), the caller's number decides which version they hear, and the same caller keeps hearing the same version.
4. The agent greets the caller and the call starts. The [Conversation log](https://docs.tryhamsa.com/agents/monitor/conversation-log.md) shows it.

A call doesn't start when:

* the number has no agent. The call fails with "No voice agents assigned to this phone number."
* the owner's account already has as many calls running as the plan allows, across all of the owner's projects. The call is refused with "Voice agent concurrency limit reached. Please wait for an active call to finish." See [Limits](https://docs.tryhamsa.com/agents/reference/limits.md).

SIP numbers can pass headers from your provider to the agent. The agent reads them as `{{sip.headers['x-header-name']}}`, with the header name in lowercase. See [System variables](https://docs.tryhamsa.com/agents/variables/system-variables.md).

## Test a call from a number

Use this to check that a number can call out with its agent.

**1. Open the number**

The number must be saved and assigned to an agent.

**2. Click Test outbound call**

In the dialog, enter the number to call in **To** and click **Call**. The toast says "Call started", and your phone rings.

![The Test outbound call dialog from +97145550188, with a UAE number in To and the Call button](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/connect/test-outbound-call-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=126e9c8374860e1fff1826a1a6dd1899)

The test call uses the number's assigned agent and passes no variables. To test with variables or with your draft, use **Test** > **Phone call** in the agent editor. See [Test your agent](https://docs.tryhamsa.com/agents/release/test-your-agent.md).

If the button is greyed out, hover it to see why: "Assign this number to an agent to make calls." or "The assigned agent no longer exists. Select a valid agent."

## Delete a number

**1. Open the number and click Delete**

The dialog asks "Delete \{label}? This can't be undone.", naming the number by its label (or the number, if it has none).

**2. Click Delete**

The number is removed at once. There's no undo.

![The Delete phone number confirmation for Office PBX, with Cancel and Delete](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/connect/delete-number-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=8da41014379da247cae66659bf844ab0)

Deleting a number removes the trunks Hamsa set up for it, and frees the number so you can add it again later. Agents stop answering on it. Batch calls that use it as the from number fail on every call they try after that.

## Good to know

* Admins can add and assign numbers but can't delete them by default.
* A number with no agent can't make a test call, and inbound calls to it fail.
* If the agent already has a number in that environment, the number you assign replaces it. The old number stops answering for the agent.
* Credits: every call needs a credit balance above zero. See [Billing](https://docs.tryhamsa.com/overview/billing.md).

## Related

> [card] [Bring your own number](https://docs.tryhamsa.com/agents/connect/bring-your-own-number.md)
>
> Add a Twilio number or connect a SIP trunk.

> [card] [Make an outbound call](https://docs.tryhamsa.com/agents/connect/outbound-calls.md)
>
> Call one person from the app or the API.

> [card] [Batch calls](https://docs.tryhamsa.com/agents/connect/batch-calls.md)
>
> Call a list of people from one number.

> [card] [Environments and releases](https://docs.tryhamsa.com/agents/release/environments.md)
>
> Point each number at dev, staging or prod.


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