Phone Numbers
Buy a US phone number through Helios, name it, and use it for a voice agent or WhatsApp, with E911 address and a guided buy wizard.
Objective
Buy a US phone number provisioned directly through Helios, give it a name, and put it to work: assign it to a voice agent, or use it to connect WhatsApp. The buy wizard walks you through choosing a number, registering the legally required emergency (911) address, and confirming the purchase. Numbers are ready to receive calls the moment the purchase completes.
This is the managed alternative to the Bring-Your-Own-Twilio path used in Voice Agents: with a Helios number you do not manage a separate carrier account.
Access
Sidebar -> Telephony -> Phone Numbers Route: /app/{tenant}/phone-numbers
Roles
- owner, admin — full access (view the list, search, buy, rename, release).
- agent — no access. The page is owner/admin only; agents do not see it in the sidebar, and a direct visit shows "Only owners and admins can manage phone numbers."
Every action (search, purchase, rename, release) is re-checked server-side, so only owners and admins can provision, rename or release a number regardless of how the page is reached.
Availability and prerequisites
- Managed numbers must be enabled in your workspace. If the module is not turned on for your environment you will see a quiet "Phone numbers are not available yet." card instead of the manager.
- Owner or admin role (see Roles above).
- A verified email. Searching is open, but purchasing is blocked until your workspace email is verified ("Please verify your email address before purchasing a phone number.").
- A plan that includes a phone number slot to complete a purchase. Searching is always free on every plan, including free — only the final purchase step is plan-gated. See Plan limits and billing below.
Your numbers
The manager lists the numbers your workspace owns.
- A usage line shows how many numbers are in use, for example "N of M numbers used" (or an unlimited count when your plan has no cap).
- Each active number is shown as a card with:
| Element | Meaning |
|---|---|
| Name | The reference name you gave the number, shown first. A number with no name shows the number itself instead. |
| Phone number | The number, formatted for display (for example +1 (302) 555-1234). Shown under the name when a name is set. |
| Active badge | The number is live and can receive calls. |
| Purchased date | When the number was bought. |
| Emergency address registered | Confirms the E911 address is on file (every active Helios number has one). |
| Number options (three-dot menu) | Edit name opens the rename dialog; Release opens the release confirmation. |
Released numbers move to a collapsible released numbers history at the bottom of the page, each showing a Released badge and the release date.
Buy a number
Click Buy a number to open the buy wizard. It has three steps plus a success screen; the header shows "Step 1 of 3", "Step 2 of 3", and so on.
Step 1: Choose a number
Search Helios's live inventory of US local, voice-enabled numbers.
| Field | Mandatory | Format | Example | Note |
|---|---|---|---|---|
| Area code | No | 3 digits | 302 | Leave blank to see numbers from any US area code. |
| Contains | No | 2-10 letters, digits or * | 2020, CAFE | Filters for memorable numbers; letters map to the phone keypad. |
- Leave both fields blank to browse numbers from any US area code.
- Only US numbers are available. A non-US area code (like +1 809) returns no results.
- Results appear as a selectable list with a live count ("N numbers available"). Pick one, or use Show more to re-roll a fresh set of available numbers.
- If nothing matches, you get a "No available numbers matched your search." message — try a different area code.
Step 2: Emergency address
This step also names the number and registers its emergency address.
| Field | Mandatory | Format | Example | Note |
|---|---|---|---|---|
| Name for this number | No | text, up to 60 characters | Sales line | A reference so you can tell your numbers apart. Left blank, the number is named "Helios number". You can change it later. |
| Business or full name | Yes | text | Building Your Dreams Tech LLC | The name the emergency address is registered under. |
| Street address | Yes | street + unit only | 123 Main St, STE 100 | Do not include city, state or ZIP here. |
| City | Yes | text | Wilmington | |
| State | Yes | selection | DE | Chosen from a list of the 50 states plus DC and Puerto Rico. |
| ZIP code | Yes | 5 digits or ZIP+4 | 19801 |
US law requires every phone number to have an address on file for emergency (911) calls. This address is used only for emergency dispatch and is never shared with callers.
The form validates as you go: it flags a street field that looks like a full address, an unselected state, and an invalid ZIP, so mistakes are caught here rather than failing later.
Step 3: Confirm purchase
The confirm step shows the selected number and the emergency address you entered.
- If your plan includes a number slot: a price line shows how much the number adds to your monthly billing (when a price is configured), and you must check the box agreeing to the Phone Number Terms and Acceptable Use Policy before the Purchase button becomes active. In short: numbers are for inbound voice AI only, no spam or robocalls, you are responsible for lawful use, and a number may be suspended for abuse. The full terms open in a new tab.
- If your plan does not include a number slot: instead of a purchase button you see "Upgrade your plan to buy this number" with a View plans link to billing. Searching stays free; only the purchase is gated.
Use Back to revise a previous step or Cancel to close the wizard.
Success
After a successful purchase you see "Your new number is ready" with the new number and an Assign it to a voice agent button that takes you to Voice Agents. The number is already configured to receive calls; assign it to a voice agent to start answering.
Name a number
Every Helios number carries a reference name that identifies it across the app — in the phone numbers list, in the voice-agent picker, and when connecting WhatsApp.
- At purchase: set the name in the buy wizard's Step 2 ("Name for this number"). Left blank, the number is named "Helios number".
- After purchase: open the number's three-dot menu and choose Edit name. The "Name this number" dialog shows a Name field (up to 60 characters, for example "Sales line"). Save applies it immediately ("Name updated.").
- Clearing the name is allowed: save an empty name and the card shows the bare phone number instead.
Use a number for WhatsApp
An active Helios number can also power WhatsApp. In the WhatsApp section, choose Use a Helios number when connecting: Meta sends its phone-verification code by SMS to the number, and Helios receives and enters the code automatically — you never read or type it. This works for every active Helios number, including numbers bought before this option existed.
- If you have no numbers yet, the WhatsApp flow tells you: "You do not have a Helios number yet. Buy one first, then connect it to WhatsApp."
- A number connected to WhatsApp cannot be released until you disconnect it there first (see Release a number below).
See WhatsApp for the full connection flow.
Release a number
To give up a number, open its three-dot menu, choose Release, and confirm ("Release this number?"). Releasing:
- Stops the number working immediately and cannot be undone — "{number} will stop working immediately and cannot be recovered. You will need to buy a new number to replace it."
- Frees the plan slot and stops the number's monthly charge.
- Moves the number into the released history.
A number connected to WhatsApp cannot be released. You get "This number is connected to WhatsApp. Disconnect it in the WhatsApp section first, then release it here." Disconnect WhatsApp, then release.
You would need to buy a new number to replace a released one; the same number is not guaranteed to be available again.
Plan limits and billing
- Searching is free on every plan, including free — it never counts against a limit.
- Purchasing is plan-gated. Your available slots are your plan's phone-number allowance plus any phone-number add-on you have purchased. Some plans grant none; some are unlimited.
- Each active number adds a recurring monthly charge to your subscription, shown on the confirm step when a price is configured. Releasing a number removes that charge.
- At your limit: the Buy a number button is disabled with a tooltip explaining you have reached your plan's maximum. Release a number or upgrade to buy more.
- After a downgrade: if you now own more numbers than your new plan allows, you keep all of them — Helios never releases your numbers automatically — but you cannot buy more until you release some or upgrade. A notice at the top of the page explains this state.
Good practices
- Verify your workspace email before you try to buy, so the purchase is not blocked.
- Name each number for its job ("Sales line", "Support desk") so it is easy to pick in the voice-agent and WhatsApp flows; you can rename at any time.
- Enter the street and unit only in the Street address field; put city, state and ZIP in their own fields to pass emergency-address validation.
- Use the Contains filter to find a memorable number (digits or keypad letters).
- Assign a new number to a voice agent right away so it starts answering calls.
- Release numbers you no longer use to stop their monthly charge — after disconnecting WhatsApp if the number is connected there.
Common notes
- "Phone numbers are not available yet." — managed numbers are not enabled in your workspace yet.
- No results when searching — the area code may be exhausted, or you searched a non-US area code (only US numbers are offered).
- Purchase blocked with an upgrade prompt — your current plan grants no number slots; upgrade from the View plans link.
- "Please verify your email address before purchasing a phone number." — verify your workspace email, then retry.
- Buy button disabled — you are at your plan's number limit; release a number or upgrade.
- "This number is connected to WhatsApp. Disconnect it in the WhatsApp section first, then release it here." — release is blocked while the number backs a live WhatsApp connection; disconnect WhatsApp first.
- "Number not found." when renaming — the number no longer exists in your workspace or was already released.