Phone Numbers

Buy phone numbers directly in the Studio — or bring numbers you already own — then route inbound calls to your AI agents. Numbers bought in the Studio, and BYO numbers on a Verified SIP trunk, are also the caller IDs the agent’s outbound campaigns call from. Phone numbers live in Manage → Phone Numbers. The page isn’t in the default sidebar: add it with Customize sidebar, or press Cmd/Ctrl+K and search for it. See Navigating Studio. The page lists every number in the workspace. Each row shows the number, with its country and type under it (such as “Canada · Toll-Free”; a BYO number shows its country only), a Free, Billable or BYO badge, and the agent it is assigned to (“Assigned to” and the agent’s name, or “No agent assigned”). A BYO row has a second line for its SIP trunk — see Adding a Number You Already Own. The actions for a number sit on the right of its row: Assign on an unassigned number; on an assigned one, a pencil icon (Reassign) and an unlink icon (Unassign); a cable icon (Change SIP trunk) on a BYO number; and a trash icon (Release number) on every row. Point at an icon to see its name. Use the Search by number, agent, country or type box to filter the list by number, by the name of the agent a number is assigned to, or by the country or type shown under the number, such as “canada” or “toll free”. The list shows 10 numbers per page. Use the page-size selector below it to switch between 10, 20 and 50.

​

Buying a Number

1. Click Buy Number. The Buy a Phone Number drawer opens.
2. Select a Country and a Type. The lists offer only the countries and types currently on sale, and the Type list shows only what is on sale in the country you chose. That includes Local and Toll-Free numbers in the United States and Canada, and Mobile numbers in the United Kingdom, which need approved business details first. Local is selected by default. For a Local number you can also enter an Area Code (e.g. 415); leave it empty when you search for Toll-Free or Mobile.
3. Click Search and pick from the available numbers. Each search shows up to 15 numbers; for Local numbers, use the Area Code box to narrow it down. Each result shows its locality and a badge with its type, such as Local or Toll-Free.
4. Click Purchase. If your number is free (see the free first number below), it is bought as soon as you click. Otherwise a Confirm purchase dialog shows the price before you commit: what you are charged now, for the rest of the current month, and the monthly price from your next billing cycle.

While the prices load, the Country and Type lists and Search are turned off. If the prices can’t be loaded, the drawer says “Couldn’t load phone number prices.” and offers a Retry button.

​

How Number Search Matches

Enter an area code in the Area Code box, such as 415. The results only include numbers that genuinely match it — numbers in that area code, not numbers that happen to contain those digits somewhere further along. For US and Canadian numbers the pattern is matched against the 10-digit national number. Digits after the third are ignored, so 415555 finds the same numbers as 415. A one- or two-digit entry matches numbers that start with those digits, so 41 matches numbers beginning 41. Because matching is strict, a search can return few numbers, or none at all. When nothing matches, you see “No numbers found. Try a different type, area code, or country.” rather than an unrelated list — try a shorter entry, a different area code, or another type. The Type list shows only the types on sale in the country you chose, so you can’t pick a type that isn’t offered there. Toll-Free and Mobile searches also ignore an area code of three or more digits instead of matching it, which is why the box should be left empty for them. Once you’ve searched, changing Area Code, Type or Country runs the search again. Changing Country also sets Type back to Local, or to the first type on sale there if Local isn’t offered, and the drawer reopens on United States and Local after you close it or complete a purchase. The call-routing step during onboarding uses the same search, but it looks for Local numbers only: the Type filter is only in the Buy a Phone Number drawer on Manage → Phone Numbers.

​

United Kingdom Mobile Numbers

United Kingdom Mobile numbers need approved business details before you can buy them, your free first number included. You submit the details once for the account, and they are reviewed before you can buy. You can submit them from either of two places:

• Manage → Compliance. Select Start on the United Kingdom regulatory bundle card. Compliance isn’t in the default sidebar: add it with Customize sidebar, or press Cmd/Ctrl+K and search for Compliance. See Navigating Studio.
• The Buy a Phone Number drawer. Choose United Kingdom (GB) and Mobile. Instead of search results, the drawer says “Add United Kingdom business details first” and shows Add details, and Search is turned off until the details are approved. The buy drawer steps aside while you fill in the details and keeps your choices.

Both open the Business details drawer. It has a Business and representative section with the details the United Kingdom asks for and an Address section for the business. Submit turns on once the required fields are filled in correctly. After you submit, a message reads “Submitted for review. You can buy mobile numbers in the United Kingdom once they are approved.” The card and the prompt in the buy drawer follow the status of your details:

• Incomplete means a submission couldn’t be completed. Continue reopens the form, and the drawer gives the reason when there is one.
• In review and Approved open the Business details drawer to read only. You can buy once the details are approved.
• Rejected lists the reasons on the card under Reviewer’s note and What failed the check, or “No reason was given.” when there are none. Edit & resubmit opens the drawer with the same reasons and your earlier details filled in where the Studio can show them. Correct them and select Resubmit.

​

Emergency Address

United Kingdom numbers need an emergency address, which is required for numbers that make calls. Emergency services use it for 999 and 112 calls from your United Kingdom numbers. Use the address where the numbers are used; a PO box isn’t accepted.

• When you buy a United Kingdom number, the Studio uses your approved business address if it is in the United Kingdom.
• If it isn’t, or you want a different address, open the Emergency address drawer from the United Kingdom regulatory bundle card once your details are approved. The card shows Add emergency address when you need to add one, Review when an address is set but a number still lacks it, and Change otherwise. Saving adds the address to every United Kingdom number you hold, and Add to numbers in the drawer retries any number that still lacks it.
• A United Kingdom number without one shows No emergency address in the list on this page, and Emergency address pending while it is being registered. Point at the badge for details.

​

Adding a Number You Already Own

If you already hold numbers with your own carrier, you can add them to the workspace instead of buying new ones. Once added they behave like any other number in the list — assign them to an agent, release them. Outbound calling is different: a BYO number takes inbound calls only until it is attached to a SIP trunk, and campaign calls go out from it only when that trunk is Verified — see the SIP trunk notes at the end of this section and Numbers as Campaign Caller IDs.

1. Click BYO Number. The drawer opens on Single number.
2. Enter the number in international format, for example +14155550100, and click Add BYO Number.

If that number is already in use, a Number Already Exists dialog says so and nothing is added. To add several at once, switch to Range of numbers:

1. Enter the Start number.
2. Choose a Count — 5, 10, 25, 50, or 100, or click Custom to enter any value from 2 to 100.
3. Click Add BYO Numbers. The platform walks upward from the start number; any number already in use is skipped and reported back under Skipped (already in use), so a partly-used range still succeeds.

The platform only looks about ten times the Count ahead, so a heavily used range can fail. If it can’t find enough free numbers in that stretch, the drawer shows “Could not find enough available numbers. Try a different starting number.” and nothing from the request is added. BYO numbers show a BYO badge in the numbers list in place of the Free/Billable badge. Under the assigned agent, a BYO row has a second line that says how the number places outbound calls: Inbound only, or SIP trunk with the trunk’s name and a Pending, Verified or Disabled badge. Outbound calls through a SIP trunk. A SIP trunk is the link from SquawkVoice to your own carrier’s session border controller (SBC) that carries a BYO number’s outbound calls. Your provider sets up and verifies the trunks for your account, and you choose from the ones it has made. Attaching one needs BYO Number to be turned on for your account, as adding a BYO number does. The trunk’s status sets what the number can do:

• Verified: the number can place campaign calls, including on-demand calls.
• Pending: only a campaign’s Test Call can use the number.
• Disabled: the trunk carries no calls, and it can’t be newly chosen for a number.
• Inbound only (no trunk): the number only receives calls.

To attach, change or remove a trunk on a number you’ve added:

1. Select the cable icon (Change SIP trunk) on the number’s row.
2. In the SIP trunk list, choose a trunk, or No trunk (inbound only) to detach it. A trunk that isn’t verified shows its status after its name, such as “(pending)”.
3. Select Save, which stays off until you change the choice.

The BYO Number drawer has the same SIP trunk (outbound) list, set to No trunk (inbound only) until you choose one. The trunk you choose applies to every number you add in that request, including a whole range. If your account has no trunks, No trunk (inbound only) is the only choice. BYO numbers you already had, including a number set up with Forward an existing number during onboarding, start as Inbound only. Their inbound calls are unchanged, and a transfer never shows a BYO number as the caller ID, with or without a trunk.

​

Assigning a Number to an AI Agent

Assigning a number routes its inbound calls to an agent:

1. Click Assign on an unassigned number (or Reassign on an assigned one).
2. Search and select the AI agent in the Assign Phone Number drawer. The drawer shows up to 50 agents at a time, so type in Search agents… to narrow the list; the agent that already holds the number is marked Assigned.

A number can be active on only one agent at a time; an agent can hold many numbers. Inbound call routing is updated automatically the moment the assignment saves. Unassign stops routing new calls to the agent — active calls are not interrupted, but new calls go unrouted until the number is assigned again. It also stops the agent’s campaigns calling from the number — see Numbers as Campaign Caller IDs. If someone else claims a number a moment before you do, the conflict is reported for what it is — “That phone number was just assigned to another assistant. Reload and try again.” — rather than as a generic failure.

​

From the Agent Side

Numbers can also be attached from the agent, several at a time, in one Manage Phone Numbers drawer.

1. Go to Build → AI Agents. Each agent’s row has a numbers chip that names up to two of its numbers, newest assignment first, with +N more for the rest, or reads No numbers.
2. Open the drawer from the row. The No numbers chip opens it on the Available tab, and so do Assign phone number (or Assign another number if the agent already holds some) in the row’s More actions menu. A chip that names numbers opens it on the Unassign tab, and so does Unassign phone number in the same menu (it reads Unassign phone numbers (N) when the agent holds several).
3. The drawer is titled Manage Phone Numbers, with the agent’s name under the title and two tabs, Available and Unassign, each with the number of numbers it lists. Available lists the numbers no agent holds, to assign; Unassign lists this agent’s own numbers. Switch tabs at any time; the search, selection and page start clean on the other tab. Tick as many numbers as you need — the list is searchable by number, shows ten to a page, and offers select-all-on-page — then assign or unassign the whole selection in one action.

Unassigning asks you to confirm and spells out how many numbers the agent will be left answering on, warning explicitly when your selection would remove its inbound routing altogether. Assigning doesn’t ask. On the agent’s own screen, the header chip reads Assigned number for one number or Assigned numbers for several, and lists the first two with +N for the rest — hover it for the full list. An agent with no live assignment shows no numbers chip in that header. An agent that still holds numbers can’t be deleted: unassign them first. The delete dialog lists the numbers that are still assigned. See Delete an Agent.

​

How an Inbound Call Finds Its Agent

When a call arrives, SquawkVoice looks up the number that was dialed and sends the call to the agent that number is assigned to at that moment. So reassigning a number takes effect straight away, with nothing to change on your side, and a number with no active assignment has no agent to answer. If a SIP trunk sends an X-SIP-AssistantId header, the header decides the agent instead of the assignment. See Mapping the Call to an AI Agent.

​

Numbers as Campaign Caller IDs

An agent’s numbers do two jobs: inbound calls arrive on them, and the agent’s campaigns call out from them. A campaign has no number setup of its own — it dials from the numbers of the agent chosen on its Setup tab, so assigning and unassigning numbers is how you change a campaign’s caller IDs. Only numbers that can place the call are used: numbers bought in the Studio, and BYO numbers attached to a Verified SIP trunk. See Campaign Setup.

• Rotation. When an agent holds several numbers, the dialer picks the one that was used least recently, so calls spread across your numbers over time.
• Changes apply on the next call. Assign adds a number to the rotation and Unassign takes it out, even while a campaign is running. A campaign’s Test Call uses the same numbers but doesn’t advance the rotation, so testing doesn’t change which number your contacts see. Unlike a real run, a Test Call can also use a BYO number on a Pending trunk.
• Numbers with a failed payment are skipped. A number flagged for a failed subscription payment is never used as a caller ID. If every number the agent holds is flagged, the campaign can’t launch.
• BYO numbers need a Verified trunk. A number with the BYO badge (one you added as a BYO number, or set up with Forward an existing number during onboarding) is skipped by the rotation unless it is attached to a Verified SIP trunk. A BYO number with no trunk, or on a Pending or Disabled one, is left off the campaign’s Caller ID list and doesn’t count for the launch checklist, although it still takes inbound calls. To campaign from it, ask your provider to set up and verify a SIP trunk for the number, or give the agent a number bought in the Studio.
• The agent needs a number that can place campaign calls. The launch checklist item Number assigned to agent stays unmet while the agent has no such number. When the agent’s only numbers are BYO numbers that aren’t on a Verified trunk, the item reads Agent’s BYO numbers on a verified SIP trunk instead, and Launch stays disabled. If a running campaign’s agent is left with no number that can place campaign calls, the campaign keeps its status but places no calls until the agent has one again.
• A run keeps the agent it started with. Each run calls from the numbers of the agent the campaign had when that run was created. Changing the campaign’s agent later doesn’t move a run that already exists onto the new agent’s numbers, and that includes the long-running run behind on-demand calls.

​

Releasing a Number

Click the Release number action and confirm. Releasing permanently removes the number — it cannot be undone, and no refund is issued for the remainder of the billing cycle. A number cannot be released while it is assigned to an agent — unassign it first (the dialog offers a shortcut). If the number you release is your free one, the Studio-bought number you have left with the lowest monthly price becomes the free one (a number flagged for a failed payment only if none of the others is paying), and the Free badge moves to it. Releasing your only Studio-bought number makes your next purchase free again.

​

Number Billing

Billing applies only to numbers purchased in the Studio. Numbers you bring yourself are never charged, do not use up your free included number, and are not counted on the plan card.

• The included number is your first number bought in the Studio, whatever its type, in any country and type the Buy a Phone Number drawer offers. It stays free for as long as you keep it, even if you later buy a cheaper one, and if you release it your cheapest remaining number becomes the included one. Every other number is billed monthly at the price for its country and type. Numbers bought before country and type pricing keep the price they were bought at.
• A paid number is charged when you buy it. The charge, prorated for the rest of the current month, goes to your payment method as soon as you confirm the purchase. From your next billing cycle the number is part of your subscription invoice.
• The plan card on the billing overview (the Current Plan card at Manage → Billing → Overview) shows a live summary line, e.g. “3 phone numbers — 1 included, 2 × $1.50 = $3.00/mo”. When your billable numbers are at different prices, the line gives how many are billable and the monthly total instead of a single price. See Your Plan.
• The phone-number line is a toggle whenever you have billable numbers. Select it to see one row for each country, type and price, with the count, the price of each and the monthly total, so numbers bought at different prices show separately. Your included number isn’t listed.
• Invoices list your numbers the same way. Every phone-number charge on an invoice is named Phone Number Add-on, with one line for each price, and the invoice’s notes break the numbers down by country and type: “Phone numbers this period:” on a renewal invoice, and “Phone numbers added:” on the invoice for a number you buy. Numbers bought before country and type pricing are listed as “Phone number”, with their price and no country or type. Open the invoice itself (View, or the PDF) to read the notes; the Description column in Billing history doesn’t show them.
• If a subscription invoice payment fails, every purchased number on the account stops taking calls and is released after seven days — see When a Payment Fails.
• Cancelling your subscription permanently removes all purchased phone numbers on the account at the end of the billing cycle — the cancel dialog warns you with the exact count before you confirm. BYO numbers are yours and are left in place.

​

When a Payment Fails

When a subscription invoice fails to collect, every active purchased number on the account is flagged — including the free included number. A flagged number:

• Stops receiving inbound calls. A caller hears a generic carrier error message and the call ends. There is no greeting, no agent, and nothing that tells them to call back later.
• Cannot be assigned or reassigned to an agent. On this page the Assign button and the reassign (pencil) control are disabled, with the tooltips “Payment failed — resolve payment to assign this number” and “Payment failed — resolve payment to reassign”. On the Available tab of the Manage Phone Numbers drawer (Build → AI Agents, then More actions → Assign phone number on an agent’s row) the number’s checkbox is disabled, carries a red Payment failed label, and is excluded from select-all.

Numbers you brought yourself (BYO) are never flagged, because we do not bill for them.

​

How you are told

A red banner appears across the top of this page whenever any purchased number in the workspace is flagged. It reads “Subscription payment failed for your phone numbers”, explains that the numbers cannot make or receive calls until the payment is resolved, names the exact date they will be permanently released, and offers an Update payment method button that takes you to Manage → Billing, where the Payment methods tab holds your saved methods and your default. See Payment Methods. The banner is computed across your whole number list, so it cannot be filtered or paged away. Two limits worth knowing:

• It does not mark which individual rows are affected. The per-row signal is the disabled Assign/reassign control and its tooltip.
• It is scoped to the workspace you are viewing. A flagged number in another workspace of the same account will not raise a banner here, but will still block purchases — see below.

​

Buying is blocked account-wide

While any purchased number on the account has an unresolved payment failure, you cannot buy another number anywhere. Buy Number is disabled on this page, and its tooltip reads “Resolve the outstanding payment in Billing, or release the affected numbers, before buying more.” Because the check is account-wide but the banner is workspace-scoped, you may see Buy Number disabled with a payment tooltip and no banner explaining it — the flagged number is in another workspace. Adding a BYO number is unaffected.

​

The Seven-Day Release Window

A flagged number has exactly seven days of grace, counted from its earliest unrecovered failed payment — not from the most recent retry. A sweep runs daily at 04:00 UTC and permanently releases every number still flagged past that window: the number goes back to the carrier, its assignments are closed, and it disappears from this page. Paying the outstanding invoice at any point inside the seven days clears the flag, cancels the scheduled release, and restores the number to full service on its existing agent. The sweep re-checks payment status immediately before each release, so a payment that lands the same morning still saves the number. If the carrier release itself fails, the number is kept and retried the next day rather than being removed from Studio while it is still live.

​

Where to go next