Documentation

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 → Organization settings → Phone numbers. Numbers sit in organisation settings rather than inside a brand for two reasons: a number is bought by the organisation and billed on the organisation's invoice, and one number can only ever ring one agent, so it cannot be shared between brands. The permission required is Voice.

The page has three tabs:

  • Search & Buy — browse and purchase numbers from Telnyx, our telephony partner.
  • Owned Numbers — everything your organisation currently owns, with its country, status, assigned agent and monthly cost.
  • Verification — orders that are still waiting on identity or address documents before the number can be activated.
The Owned Numbers list shows the assigned agent, not a brand. Voice agents belong to brands, but numbers belong to the organisation — so on this page there is no brand column at all.

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 organisation pays for incoming calls. Good for support hotlines.

Shared cost

The cost is split between the caller and your organisation. Available in a small set of countries.

Buying a Number

Pick a country

Yaplet lists every country Telnyx currently sells numbers in. Each result shows the monthly rental and the setup fee before you commit.

Pick a type and filter

Choose the number type, and narrow the search by area code, city, state or region, or by digits the number should contain, start with or end with.

Choose the number

Click a candidate to open the purchase dialog. It shows the exact number and what it will cost.

Confirm and pay

Review the breakdown — Due now (the setup fee plus the prorated rental for the remaining days) and Billed monthly (the recurring rental, starting on your next billing date) — then confirm. You can also assign a voice agent right here; that can be changed later.

Your card on file is charged immediately, and you pay two things up front: the one-time setup fee for the number, and the prorated rental from today until your next billing date. From the next billing date onwards you just pay the monthly rental.
If the purchase is refused, the dialog stays open and shows a red "The purchase did not go through" panel with the provider's reason. Only a successful purchase closes it — so a closed dialog means the number really is yours.

Country Paperwork

Some countries require identity or address verification before a number can be activated. When you order such a number, Yaplet opens an order with the carrier and tracks it on the Verification tab, where a step-by-step wizard collects each requirement. Accepted documents are PDF, PNG, JPEG or WebP, up to 15 MB.

An order moves through these states:

  • Pending — the order is being processed.
  • Awaiting your action — 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. Cancel it to get the charge credited back, then start a new order or contact support.
Have your documents ready before you start. Most delays come from blurry scans, an address that doesn't match what you registered, or an expired ID — not from the carrier being slow.
Pending orders catch up on their own. Opening the Phone numbers page re-checks every unsettled order against the provider and refreshes the list, and a background job does the same every hour. Before this, an order could sit "pending" indefinitely while the number was already live and billing.

Assigning a Number to an Agent

There are two routes, and both write the same thing:

  • From this page — open a number's Edit dialog and pick the assigned agent (you can also give it a nickname).
  • From the agent — Brand → (your brand) → Voice → (agent) → Connections → Assigned phone numbers.

A number can only be attached to one agent at a time; assigning it elsewhere detaches it from the previous one.

You can run different agents in different languages on different numbers from the same organisation — for example a Hungarian agent on a Budapest local number and an English agent on a US toll-free, each answering from its own brand's knowledge.

Releasing a Number

Only the organisation owner can release a number. An administrator is refused, even one who can otherwise see and edit the Phone numbers page.

Releasing is immediate, not end-of-period. When the owner confirms:

  • 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.
Releasing can fail visibly. If the provider refuses the hand-back you get "The number could not be released with our phone provider, so nothing has been removed. Please try again, or contact support if it keeps happening", and the number stays in your list. Be aware that the billing steps run before the hand-back, so in that case the recurring charge has already been stopped and any credit already applied while the number is still shown. Retrying the release is safe and is exactly the right thing to do.

When an Agent or a Brand Is Deleted

  • Deleting a voice agent no longer refuses while numbers are attached. It unassigns them and resets their routing, and when you delete the agent from the brand's Voice list the confirmation tells you how many numbers are affected.
  • Deleting a brand deletes its voice agents — but never its phone numbers.
In both cases the numbers stay on your organisation, unassigned, and keep costing their monthly rental until the owner releases them here. Unassigning is not the same as releasing.

What You Pay

  • Monthly rental — varies by country and number type. Visible before you buy and on the Owned Numbers tab. 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 $0.12/min in Yaplet credits, the usage currency used across every usage-based feature, and added to your next invoice. See Pricing & limits.

Billing

Where to see every voice charge — number rental, setup fees and per-minute usage — alongside the rest of your Yaplet bill.