Phone Numbers

Buy phone numbers directly in the Studio — or bring numbers you already own — then route inbound calls to your AI agents. The numbers assigned to an agent are also the caller IDs its outbound campaigns call from. Phone numbers live in Studio → Manage → Phone Numbers.

​

Buying a Number

1. Click Buy Number. The Buy a Phone Number drawer opens.
2. Select a Country — United States, Canada, or Australia — and a Type: Local (the default), Toll-Free, or Mobile. 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 result shows its locality and a badge with its type — Local, Toll-Free, or Mobile.
4. Click Purchase. For billable numbers a Confirm purchase dialog shows the exact prorated charge for the current month and the recurring monthly amount before you commit.

​

How Number Search Matches

The Area Code box is a pattern, and the results only include numbers that genuinely match it — a search for 415 returns 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. Behaviour worth knowing: because matching is strict, a pattern that used to bring back a long list may now return fewer 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 fewer digits, a different area code, or another type. Not every Type exists in every country — there are no Mobile numbers to buy in the United States, for example — so an empty Toll-Free or Mobile search may simply mean that type 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 Type or Country runs the search again. Changing Country also sets Type back to Local, 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 Studio → Manage → Phone Numbers.

​

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: campaign calls can only go out from numbers bought in the Studio, so don’t assign a BYO number to an agent that runs campaigns — see 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.

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.

BYO numbers show a BYO badge in the numbers list in place of the Free/Billable badge.

​

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.

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. API callers receive an HTTP 409 for this, which is a definitive conflict and should not be retried blindly.

​

From the Agent Side

Numbers can also be attached from the agent, several at a time. This is open to account and partner users, not only SquawkVoice staff.

1. Go to Build → AI Agents and open the ⋯ menu on an agent’s card.
2. Choose Assign phone number (or Assign another number if the agent already holds some), or Unassign phone numbers (N).
3. In the drawer, tick as many numbers as you need — the list is searchable, 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. The N numbers chip on an agent’s card is clickable and visible to every user type. On the agent’s own screen, the header chip reads Assigned numbers and lists the first two with +N for the rest — hover it for the full list. An agent with no live assignment shows no chip at all.

​

How an Inbound Call Finds Its Agent

The webhook URL SquawkVoice configures on a purchased number does not name the agent. The answering agent is looked up from the number that was dialed, using its current assignment — so reassigning a number takes effect without the webhook changing. Two consequences worth knowing if you monitor your telephony configuration directly: the URL on an existing number is rewritten to this shorter form the next time the Studio syncs that number, for example on an assign or an unassign, so anything asserting on its previous shape should be updated; and a number with no active assignment now fails to route rather than reaching whichever agent a URL happened to name.

​

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).

​

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 billing overview plan card shows a live summary line, e.g. “3 phone numbers — 1 included, 2 × $1.50 =$3.00/mo”.
• 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, which used to be exempt. 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”. In the agent-side drawer at Build → AI Agents → ⋯ → Assign phone number the row’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. 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. The old per-number Payment Failed badge has been removed.
• 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. Purchased numbers are also released seven days after an account is deactivated or deleted. Reactivating the account inside that window cancels the release.

​

Where to go next