Phone Numbers
Buy and manage the phone numbers your voice agents answer. Covers where the page lives, the number types, country paperwork, what you pay, assigning a number to an agent, and how releasing works — including who is allowed to do it.
Where the Page Lives
Settings → Connections → Phone numbers. Numbers sit in your workspace's settings rather than inside a brand for two reasons: a number is bought by the organization and billed on the organization's invoice, and one number can only ever ring one agent, so it cannot be shared between brands. The permission required is Voice & calls.
The page is one table of your numbers, with a button under it. A line above the table reminds you that numbers are billed monthly and that some countries ask for proof of address or identity before a number goes live.
- New phone number — opens the purchase dialog, where you browse and buy numbers from Telnyx, our telephony partner. While you own no numbers yet, the page shows a Get a phone number button instead, which opens the same dialog.
- The table of your numbers — everything your organization currently owns. The columns are Name (a nickname you choose), Country, Type, Phone number (with a button that copies it), Answered by (the assigned voice agent, or "No agent assigned"), Monthly (hidden on narrower screens) and Status (Active or Pending). Each row has a pencil button (Edit) and a ⋯ menu with Edit and Release.
- Orders still in progress — numbers waiting on identity or address documents before they can be activated show in the same table with New order in the first column. The status reads Verification required, Continue opens the verification wizard, and the ⋯ menu has Refresh and Cancel order.
Number Types
Local
A geographic number tied to a specific city or region. Best for businesses with a regional presence.
Mobile
A number that looks like a mobile line. Useful in markets where customers won't call landlines.
National
A non-geographic number reachable from anywhere in the country.
Toll-free
Free for the caller — your organization pays for incoming calls. Good for support hotlines.
Shared cost
The cost is split between the caller and your organization. Available in a small set of countries.
Buying a Number
Open the dialog
Click New phone number (or Get a phone number if you have none yet). The New phone number dialog opens: you choose on the left and see exactly what you are buying on the right. The dialog asks which voice agent answers the number, so create one first if you have none.
Pick a country and a type
Choose the country in the Country field (the list is searchable and shows every country Telnyx currently sells numbers in) and the type under Number type: Any type, Local, Mobile, National, Toll-free or Shared cost. The numbers on offer refresh as soon as you change either one.
Narrow the search
Under Phone number, type the digits the number should start with (the country's dial code is shown for you) and press Enter or the search button. Advanced filters adds Area code, City, State / Region, Number contains and Ends with, plus Include approximate matches and, for US and Canadian toll-free numbers, Instant activation only.
Choose the number
The numbers on offer appear as tiles, each with its monthly price and region. See more numbers loads a fresh set. Click a tile, and the summary on the right shows the Selected phone number, its type and features, and what it costs: the Setup fee, the rental Prorated for the remaining days (when there is one), Total due now, and Billed monthly with the date it starts.
Assign an agent and pay
Under Assign voice agent, pick the agent that answers this number (required; you can change it later). Then click the activate button at the bottom, which shows the amount due now. When the number is live, the dialog says Say hello to your new number!.
Country Paperwork
Some countries require identity or address verification before a number can be activated. When you order such a number, the dialog ends with Your number is reserved instead, and its Continue verification button opens a step-by-step wizard that collects each requirement. Yaplet also opens an order with the carrier and tracks it as a New order row in the numbers table, where Continue opens the same wizard later. Accepted documents are PDF, PNG, JPEG or WebP, up to 15 MB.
An order moves through these states:
- Pending — the order is being processed.
- Verification required — complete and submit the verification requirements.
- Under review — Telnyx is reviewing what you submitted. Activation usually completes within 1–3 business days.
- Approved — accepted; the number will move to your owned list as soon as activation completes.
- Active — the number is live and ready to use.
- Failed — the carrier declined the order. Choose Cancel order in the row's ⋯ menu to get the charge credited back, then start a new order or contact support.
Assigning a Number to an Agent
There are two routes, and both write the same thing:
- From this page — click a number's Edit button to open the Edit number dialog, where you pick the Voice agent (or No agent) and give the number a Nickname, then Save.
- From the agent — Brand → (your brand) → AI agent → Phone → (agent) → Phone numbers.
A number can only be attached to one agent at a time; assigning it elsewhere detaches it from the previous one. A member who is limited to some brands can attach numbers only to the voice agents of those brands.
Releasing a Number
Releasing is immediate, not end-of-period. In the ⋯ menu choose Release, and when the owner confirms the Release phone number? dialog:
- The number is handed back to the provider straight away and stops answering calls. You cannot reclaim it through Yaplet once it is gone.
- The unused portion of the current month is credited to your Yaplet account balance, which is applied against your next invoice. It is a credit, not a card refund.
- The setup fee is not refunded — it covered the upfront cost of provisioning the number, which the carrier does not return.
When an Agent or a Brand Is Deleted
- You can delete a voice agent while numbers are attached. It unassigns them, and the confirmation — from the brand's Phone list or from the agent's own page — tells you how many numbers are affected.
- Deleting a brand deletes its voice agents — but never its phone numbers.
What You Pay
- Monthly rental — varies by country and number type. Visible before you buy and in the Monthly column of the numbers table. Charged monthly from your next billing date.
- One-time setup fee — paid once per number on purchase, not refunded on release.
- Prorated first-month rental — paid on purchase, covers the days between purchase and your next billing date.
- Per-minute conversation usage — metered separately at about $0.15 per call minute, billed by actual use. It comes out of the credit you bought first, and whatever that doesn't cover is billed with your plan's usage. See Pricing & limits.