Build with

Overview

Voiceflow telephony connects a Voice agent to a number provisioned through Voiceflow or to your existing phone system over hosted SIP. Use it to answer support calls, make an agreed callback and transfer a caller to a separate support destination.

Studio

Start from a Voice project’s Phone numbers. Number provisioning uses the workspace allowance; SIP requires the phone-system administrator’s addresses/routing and enabled SIP availability. Prepare the agent’s speech, instructions and approved Knowledge before testing the live route.

Choose the number or SIP connection that routes calls to your agent. Photo:

Code

Use the management API/CLI to provision and assign a Voiceflow number. Create SIP connections in Studio before using their calling API. A management bearer credential authorizes number resources; a runtime API key authorizes the assigned project’s calls. SIP digest credentials authenticate a phone-system peer and do not replace either HTTP credential. Keep them server-side.

Getting a phone number

Provision and route a number through Voiceflow before testing its calls.

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.

Assign the answering release

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.

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

Connecting a SIP system

Create and authenticate a hosted route for your existing phone system.

Create SIP connections in Phone numbers in Agent studio, including when your backend will place calls. The stable phone-number API does not create SIP connections. You need workspace phone-management permission, SIP enabled for the workspace, an available SIP connection allowance and an administrator who controls the phone system.

Your phone system keeps its public numbers. Voiceflow creates a unique hosted SIP hostname and assigns one agent/release to that connection. Different dialled numbers on the same connection do not select different agents. Review the canonical network and media requirements with the administrator before routing traffic.

Choose and create the SIP connection

1

Choose Voiceflow SIP

Open Phone numbers → Create number → SIP → Voiceflow SIP and enter a recognizable Name.

2

Authenticate the sending phone system

Choose IPs, Credentials or Both. Enter the sender’s public IPv4 addresses/CIDR ranges for IP authentication, or the username and password the sender will supply for digest authentication. Both requires both identities to match. Use the provider’s public egress address, including NAT, rather than a private LAN address.

Authenticate the system sending calls to the hosted SIP address. Photo:
3

Enable outbound routing when needed

For callbacks or transfers through the phone system, enable Outbound calls and transfers. Enter one Address, Username, Password and E.164 Caller ID. When outbound is enabled, all four are required. Select Protocol and an optional Port. Use the outbound settings below to check the transport before calling.

Whether you enabled outbound or only need inbound calls, choose Create after completing the enabled settings.

Check transport, encryption and assignment

An outbound Address is a public IPv4 address or hostname without sip:, a path or an embedded port. Empty Port uses 5060 for UDP/TCP or 5061 for TLS. Outbound credentials authenticate Voiceflow to your peer; inbound credentials authenticate the peer to Voiceflow.

Encrypted audio (SRTP) requires matching peer support. Enabling it locks outbound routing to TLS; inbound calls must use TLS on 5061 with SRTP. TLS alone does not prove media encryption. TLS destinations need a publicly trusted certificate chain. Keep exact network/encryption settings with their Developer owner.

Set the peer route Voiceflow uses for outbound calls and transfers. Photo:

Creation from an agent’s Phone numbers page assigns that agent. At workspace level, assign the Voice agent after creation. In the connection’s Environment control, select your test Environment and Draft, then Save. Retain the complete SIP address for inbound routing and, for an outbound-enabled SIP connection, its connection ID from Outbound call API → View for API calling; these are different identifiers. All environments follows Published traffic-split routing.

For inbound calls, have the administrator route a controlled test number to sip:<dialled-number>@<connection-sip-address>, using peer SIP without REGISTER. A destination IP literal does not replace the hostname. Save the old route for rollback, then verify a real call using Inbound calls.

Inbound calls

Confirm that callers reach the intended agent with speech in both directions.

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 calls follow the assigned number or phone-system/SIP route; the HTTP key is for backend API calls.

1

Call from a separate phone

Dial the provisioned number or the controlled phone-system number routed to this SIP connection. 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. For a phone number, select Published in its Environment setting; in Code, repeat the number assignment with --version-param published (CLI) or version:"published" (API). For SIP, select Published in the connection’s Studio Environment controls, including for API-driven calls. Read the saved route back and make a new call to confirm the released instructions answer.

For SIP, the phone-system route must use the complete connection hostname and the configured inbound authentication. Test through the real carrier/PBX route, not only browser Run. Check its source identity, the agent/release and two-way audio. Use SIP troubleshooting to distinguish authentication, destination and media failures.

A call reaches the wrong agent or release

Reconcile the connection, phone-system route and saved release with a fresh call.

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

Place a callback through the assigned connection and verify the answered result.

Start an agreed callback, reminder or other customer call through the assigned Voice agent. Prepare the agent’s opening and approved context, choose a separate test phone you can answer, and verify the saved Environment/version before dialing. Calling requires workspace credits and production call capacity.

Place and verify one call

Studio

For a SIP connection, open Phone numbers → Outbound call API → View. In Test call, enter a separate E.164 phone you control, including its country code, then choose Call. Studio resolves the assigned project’s key and compiles before sending the request; an administrator may be needed for that key access. The native Outbound call sent message confirms request acceptance.

Test the configured SIP route against a separate phone you can answer. Photo:

Voiceflow numbers do not expose this panel. Give your backend implementer the intended number, agent, Environment and a controlled recipient, then use the API path in Code or Make an outbound call. This is a required execution step, not an additional Studio button.

Code

Set VF_API_KEY to a runtime API key with read/version-read authorization for the assigned project. Set TEST_RECIPIENT to the separate E.164 test phone. Use the connection’s saved assignment; neither request selects a different project or Environment.

For a Voiceflow number, retain its phoneNumber.id as PHONE_NUMBER_ID from creation or workspace number lookup. Send a number request:

variables values are strings. Prepare matching agent instructions/variables for the context you send. This minimal test sets amd:false to disable answering-machine detection; it does not assert that every provider implements detection in the same way.

For SIP, retain SIP_CONNECTION_ID from the connection-specific URL in Studio’s View dialog. Send only to:

Voiceflow SIP requires E.164. Bring your own SIP also accepts a one-to-fifteen-digit PBX extension through this API when the peer routes it. Studio’s SIP Test call input still requires an E.164 phone. The SIP endpoint accepts no variables, amd, arbitrary SIP URI or Environment override. Use the phone calling and SIP outbound contracts for exact fields, detection behavior and errors.

Answer the phone, confirm the agent’s identity and intended conversation, and inspect the matching Transcript and call events. The number endpoint returns empty 201; SIP returns empty 200. Neither returns a call ID or proves that someone answered.

For an application or CRM trigger, use the backend calling workflow. Keep scheduling, recipient selection and calling preferences in that owning system; the calling endpoint does not create a campaign scheduler.

A call is rejected or its result is uncertain

Check the saved route and call outcome before sending another request.

On 402, resolve credits. On 429, wait for available production capacity. Inspect provider errors for an invalid destination or unavailable outbound route. If a timeout leaves the result unknown, inspect the provider/call events before retrying; the first request may already have dialled. Do not assume an idempotency key or call ID was returned.

Transferring calls

Connect an active caller to a separate support phone or SIP 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.

Place a real inbound or outbound test call through the assigned number or phone-system route 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.

For SIP connections, enable and configure the outbound direction before the transfer. The peer must accept SIP REFER for a SIP target and route the destination. Verify the receiving team gets the caller; acceptance alone does not prove a teammate answered. The SIP transfer contract owns URI handling and supported context headers.

Managing connections

Maintain the workspace resources and coordinate changes to live call routes.

Phone numbers

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.

SIP connections

Maintain SIP connections in Studio, including those your backend calls through the API. The stable number-management endpoints operate on phone numbers, not these SIP records.

1

Update names, credentials or outbound routing

Open the connection in Phone numbers, then open the relevant setting. Changes save automatically. A blank existing-password field keeps the stored password; enter a replacement to rotate it and coordinate the matching peer change with the phone-system administrator. Turning outbound off clears its saved destination and credentials, so retain the configuration before changing the direction.

2

Change or remove its agent assignment

Use the connection’s assignment and Environment controls to select the intended agent/release. Use Unassign in the agent’s connection menu to remove its answering route while retaining the workspace connection. Retest any route that should continue serving customers.

3

Retire the workspace connection

Have the phone-system administrator remove or replace routes pointing to its SIP hostname. In the workspace’s Phone numbers, select the connection’s Delete action and confirm only after reviewing its name, address and assignment. This removes the connection, not the phone numbers held by your carrier. Confirm it is absent and that customer calls follow the replacement route.

Use the canonical connection maintenance reference for removal behavior and SIP troubleshooting when a saved change fails its call test. Provider-specific contact-centre queues, authentication and mappings remain in the relevant Contact Center manual.

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