Phone Numbers
Buy a US phone number directly through Helios and assign it to a voice agent, with E911 emergency address and a guided buy wizard.
Objective
Buy a US phone number provisioned directly through Helios and assign it to a voice agent, without connecting your own Twilio account. 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, 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, release) is re-checked server-side, so only owners and admins can provision 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 |
|---|---|
| Phone number | The number, formatted for display (for example +1 (302) 555-1234). |
| 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). |
| Release | Opens the release confirmation for that number. |
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 X of 3".
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. 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
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.
| Field | Mandatory | Format | Example | Note |
|---|---|---|---|---|
| Business or full name | Yes | text | Building Your Dreams Tech LLC | The name the 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 |
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.
Release a number
To give up a number, click Release on its card and confirm. Releasing:
- Stops the number working immediately and cannot be undone — "{number} will stop working immediately and cannot be recovered."
- Frees the plan slot and stops the number's monthly charge.
- Moves the number into the released history.
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.
- 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.
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.