Build with

Overview

Voiceflow numbers are public phone numbers provisioned through Voiceflow and assigned to a Voice agent. You choose an available US or Canadian area code; Voiceflow selects the number and manages the carrier connection. You do not need your own Telnyx account or carrier credentials.

Each number belongs to a workspace. Its voice assignment identifies the agent and, optionally, a fixed Environment and Draft or Published version. Calls use workspace credits and available call capacity. A Voiceflow number does not provide a Chat agent’s SMS channel; use the Twilio SMS connection for that job.

Examples of when to use Voiceflow numbers

Use a Voiceflow number when your team needs a new callable line managed through Voiceflow. For example:

  • Give a support agent a dedicated line for shipping and returns questions.
  • Test a Voice agent on a real phone before selecting its Published release.
  • Start an agreed callback from your backend using the assigned number’s calling API.

Keep an existing business number with its current provider by connecting Twilio, Vonage, Telnyx or your phone system through Voiceflow SIP.

How to use Voiceflow numbers

1

Prepare the Voice agent

Create or open a Voice project. Prepare its instructions and voice input/output settings, then choose a test Environment. Keep a separate phone available to verify the result.

Prepare the agent that will answer the number before testing its phone route. Photo:
2

Get a number and pin its route

Follow Getting a number, then Routing calls to select the agent, Environment and Draft. Creation and assignment are separate checks, even when Studio performs both from the agent’s Phone numbers page.

Manage Voiceflow numbers and inspect the release assigned to each line. Photo:
3

Call, inspect and release

Call the number, confirm a two-way conversation and its Transcript, then publish and select the intended released route as described in Receiving calls.

Select Published after reviewing the release, then verify a fresh customer call. Photo:

Getting a number

Provision an available number within the workspace’s allowance.

Studio shows Voiceflow number only in workspaces where number provisioning is available. You need workspace phone-management access and an available Voiceflow-number allowance for acquisition. Assigning it also requires edit access to the Voice project and an administrator able to resolve the project API key when assignment needs it. The create form shows how many numbers remain on the workspace’s plan. Area-code availability can change; a selected area code does not reserve a particular sequence of digits. An existing connected number is selected through assignment rather than acquired again.

Studio

1

Open number creation

Open the Voice project’s Phone numbers, choose Create number, then Voiceflow number. If you are managing an unassigned workspace number, start from the workspace’s Phone numbers page instead.

2

Choose the area code and name

Open Area code, search for an available US or Canadian three-digit area code and select it. The selected entry determines the country. Enter an optional Name for your team; callers do not see this label.

Choose an available area code; Voiceflow selects the final number. Photo:
3

Create and inspect the number

Choose Create. Record the returned number and confirm it appears in the workspace. When creating from an agent, inspect its resulting assignment. A number created at workspace level still needs an agent before it can answer.

Code

Use a Voiceflow management bearer credential with workspace phone-number creation and project assignment access. Set VF_TOKEN, WORKSPACE_ID, PROJECT_ID and ENVIRONMENT to the authorized credential, workspace, Voice project and test Environment alias. These are separate from the project’s runtime API key used for outbound calls.

Prepare an illustrative request for a US 415 number. This operation acquires a number and consumes workspace allowance; only run it when you intend to provision one.

Retain the Voiceflow resource ID, which is different from the public phone number:

Creation returns an unassigned number. Complete Routing calls before testing it. The create-number contract owns the complete schema and errors. Number creation is refused for MCP clients; use Studio, REST or CLI.

The requested number cannot be created

Check the workspace allowance and available area code before trying again.

If Voiceflow number is absent from Create number, confirm provisioning availability with your workspace administrator or Voiceflow support. You can also connect an existing provider number or phone system. If Studio shows No free Voiceflow numbers left, inspect the included allowance and existing numbers. The form’s Add more action is available only to users allowed to upgrade. If an area code is unavailable or provisioning reports no available numbers, choose another supported area code. After a timeout, inspect the workspace list before submitting another acquisition request.

Routing calls

Choose the Voice agent and release that answer the number.

The number and agent must belong to the same workspace. A fixed Environment/version answers from that release. All environments follows the project’s traffic split on its Published versions; it does not select the Draft currently open in Studio.

Studio

Open the target Voice project’s Phone numbers. Use Assign existing number for a workspace number not yet attached to this agent, and confirm any reassignment from another agent. Open its Environment, select the test Environment and Draft, then Save.

Pin a Draft route before testing a newly assigned number. Photo:

Check the saved Environment/version in the table. Selecting a different agent changes who answers; selecting another Environment changes the configured release of that agent.

Code

Use the PHONE_NUMBER_ID from creation, or find it with vf phone-number list --workspace-id "$WORKSPACE_ID" --output-format json. Assign the Voice project and pin the test alias explicitly:

Confirm the returned phoneNumber.voice contains the intended project, alias and draft. Omitting the Environment alias clears a prior pin and follows traffic splitting. The assignment API provides the equivalent REST operation.

Routing best practices

Make test and customer release changes independently observable.
  • Keep a dedicated test number pinned to Draft so customer traffic does not move when you edit the agent.
  • Read the saved assignment after a change. Publishing an Environment does not move a number already pinned to Draft.
  • Name numbers for their purpose and team so an administrator can distinguish test and customer routes before reassigning them.

Receiving calls

Verify the conversation on the actual number before directing customers to it.

Configure the agent’s opening, speech and approved Knowledge before testing. Provisioning a number does not create support content or prove that the agent can answer the customer’s question.

Studio

Prepare the Voice agent in Agent, use Run to check its conversation, then make the phone test below. Use Build a phone support agent for the complete support-content workflow.

Code

Prepare and compile the assigned Draft using Voice configuration. Keep its runtime API key on your backend; incoming callers use the public phone number.

1

Call from a separate phone

Dial the provisioned number. Confirm the intended greeting, a relevant answer and speech in both directions. Browser Run checks the agent conversation separately from telephone routing.

2

Inspect the matching conversation

Find the call in Transcripts. Check the time, caller and agent response against the test. A Transcript does not by itself establish that an audio recording exists; configure call recording separately when needed.

3

Select and retest the released route

Publish the reviewed Environment, then select Published in the number’s Environment setting. In Code, repeat the assignment command with --version-param published. Read the route back and make a new call to confirm the released instructions answer.

The number answers with the wrong agent or instructions

Reconcile the number, saved Environment and version with a fresh phone test.

Inspect the actual dialled number and its saved voice assignment. Check whether the number moved to another agent, remains pinned to Draft or intentionally follows a traffic split. Correct the assignment and start a new call. Editing or publishing the agent alone does not repair an incorrect route.

Outbound calls

Have your backend call a customer through the assigned Voiceflow number.

The current runtime supports outbound calls from Voiceflow numbers through the phone calling API. Studio does not show Outbound call API → View for these numbers. Outbound calls need the assigned Voice project, a valid destination, available credits and production call capacity.

Studio

Prepare the agent and verify its saved assignment as above. Give the backend implementer the workspace, agent, intended Environment and public number to identify the matching phoneNumber.id. A project administrator provides its runtime API key. The implementer uses the calling API workflow; this number type has no Studio Test call panel. Arrange a destination you can answer and verify the resulting call and Transcript together.

Code

Set VF_API_KEY to the assigned project’s runtime API key and TEST_RECIPIENT to a separate E.164 number you control. Use the retained Voiceflow PHONE_NUMBER_ID, not the public number, in the URL:

The phone calling contract owns the request and errors. Use Start an outbound call for a backend trigger and correlation. This endpoint does not create a campaign schedule.

An accepted request returns no call ID or JSON result. Answer the destination and inspect the matching Transcript; HTTP acceptance is not proof of an answered call. Inspect call results before retrying an ambiguous timeout so the retry does not place a duplicate call.

Transferring callers

Send a connected caller to a separate support destination.

Use the agent’s Call forward system tool or a Workflow’s Call forward step. Configure a support phone or SIP destination distinct from the number receiving the call, and define when the agent should transfer.

Studio

Open Agent → Call forward, enable it, choose Phone number or SIP address, and enter the support destination. Add a usage description and the transfer condition to the agent’s instructions. For a fixed branch, configure the Workflow step instead.

Give the transfer a separate reachable destination and a clear trigger. Photo:

Code

Configure the assigned agent’s callForwardTool with the Agent API, then compile the selected Environment. The developer transfer guide supplies the complete read, update, compile and verification procedure. Use addressType: "phone" with the separate E.164 destination, or "sip" with the intended SIP URI; keep the current configuration before replacing it.

Call the actual assigned number with a teammate ready at the destination. Request a person, confirm the teammate receives the caller and inspect the Transcript. Prototype call forwarding is disabled, so a prototype test cannot verify the production transfer. Use Transfer a phone call for the complete Studio workflow.

Managing numbers

Find, rename, unassign or retire a workspace number.

Unassigning a number removes its agent route and retains the number in the workspace. Deleting a Voiceflow number removes it from the workspace and returns it to Voiceflow’s number pool; you cannot rely on recovering the same digits. Arrange replacement customer routing before retirement.

Studio

1

Rename or unassign the agent route

In the Voice project’s Phone numbers, open the number’s … menu. Choose Rename to update its internal name, or Unassign and confirm to remove it from the agent. Verify that the old agent no longer lists the number. Use Assign existing number when routing it to another Voice project.

2

Delete a number from the workspace

Open the workspace’s Phone numbers page, find the exact public number and review its agent assignment. Open … → Delete, then confirm the deletion. Check that the number is absent from the workspace. Deleting differs from the project’s Unassign action.

Code

Inspect the resource before changing it:

Use only the operation matching your intended change:

To change the internal name:

To remove the voice assignment while retaining the workspace number:

To retire the number from the workspace when it is no longer needed:

After renaming or unassigning, read the resource again; after deletion, confirm its absence from the workspace list. The number-management APIs provide the equivalent REST operations. Only the name is editable through the update operation; the provider and number are fixed.

Use the up and down arrow keys to select a result, Enter to open it, and Escape to close the search.