Skip to main content
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.

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.

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 agentsThe Phone numbers page with four numbers in the list and the Office PBX SIP number open: Number configuration, SIP configuration and Usage with agents
A number’s page has these cards:
A SIP number that goes through the Hamsa SIP gateway: Carrier setup with Send calls to and Allow calls from, and its SIP configurationA SIP number that goes through the Hamsa SIP gateway: Carrier setup with Send calls to and Allow calls from, and its SIP configuration
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.
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 tickedThe Select agent list in Usage with agents: None (disable inbound) and the project's agents, Billing Assistant ticked
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 ConfirmThe Reassign phone number confirmation: the number is assigned to Billing Assistant, with Cancel and Confirm
To stop the number from answering, pick None (disable inbound).
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, 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 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.
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.

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 buttonThe Test outbound call dialog from +97145550188, with a UAE number in To and the Call button
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. 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 DeleteThe Delete phone number confirmation for Office PBX, with Cancel and Delete
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.

Bring your own number

Add a Twilio number or connect a SIP trunk.

Make an outbound call

Call one person from the app or the API.

Batch calls

Call a list of people from one number.

Environments and releases

Point each number at dev, staging or prod.