Use an owned provider number or provision a Voiceflow number, then select the release that answers it. Voice calls use a Voice project. SMS conversation assignment uses a Twilio number and a Chat project; the same number’s voice and SMS assignments are independent.
Before you begin
- Workspace phone-management access, an editable project and an administrator able to resolve its API key when assignment requires one.
- An owned number and credentials from the Twilio, Vonage or Telnyx manual, or allowance to provision a Voiceflow number.
- A separate test phone, available credits and call capacity. Record prior provider routing before changing a number serving customers.
For a PBX that keeps its numbers, use Voiceflow SIP or Bring your own SIP.
For an existing RingEX, Zoom Phone or Teams Phone user line, first connect and test a separate Voiceflow answering number using this guide. Then follow that phone product’s manual to forward its business number to the answering number. Keep the business number with its provider; do not import it as a Twilio, Vonage or Telnyx number with unrelated credentials. Test the direct answering number and the forwarded business route separately. A callback uses the configured Voiceflow caller, and a transfer back needs a separate unforwarded teammate number.
Studio
Open the target project in Agent studio. Use Phone numbers in a Voice project, or SMS in a Chat project.
Code
Set VF_TOKEN to a management bearer credential with workspace phone-management and project phone-number assignment access. Export it for CLI use. Set WORKSPACE_ID, PROJECT_ID and ENVIRONMENT to the workspace, target project and test alias. The project and number must belong to that same workspace. Keep its runtime API key separate for calls or SMS execution.
The Voiceflow MCP server also exposes number lookup, routing and maintenance tools to an authorized AI client. Use its canonical setup/authentication instructions; number creation is refused for MCP clients and uses Studio, REST or CLI instead.
Connect and choose the release
Create or select the workspace connection
Studio
Choose Create number, select the provider, complete its fields and Create. Provider manuals explain the credentials and routing effects. If the number already exists in this workspace, choose Assign existing number instead.
For a Voiceflow number, select an available US or Canadian entry in Area code, enter an optional Name, then create it. The entry determines the country. Availability and the workspace’s number allowance are checked during provisioning. The Voiceflow numbers manual covers acquisition and maintenance. This acquires a voice number through Voiceflow; it does not create an SMS channel. Outbound calls from these numbers use the calling API.
Code
First list workspace connections with vf phone-number list --workspace-id "$WORKSPACE_ID" --output-format json. If the owned number exists, retain its ID. Otherwise use the complete import procedure from the Twilio, Vonage or Telnyx manual. Import and assignment are separate operations.
To purchase a Voiceflow number, prepare the chosen US/CA country and area code. The Voiceflow numbers manual supplies the full API/CLI acquisition procedure. For example, this request purchases an available US 415 number; the carrier selects the digits and the returned number is final:
Creation requires workspace number allowance, spends money and returns an unassigned phoneNumber. Retain phoneNumber.id as PHONE_NUMBER_ID. REST and CLI support creation; MCP clients are refused. A Voiceflow-provisioned number supports voice, not an SMS Chat assignment. See Create phone number for the complete contract.
Select the voice release when using calls
Studio
For voice calls, confirm the intended Voice agent is assigned. Open the number’s Environment setting, select the test Environment and Draft, then Save. A fixed Environment/version uses that release. For Chat-only SMS setup, continue with the SMS assignment in the next step. All environments follows the project’s traffic split; it does not test only the Draft you are editing.
Code
For voice, use a Voice PROJECT_ID and the PHONE_NUMBER_ID retained above. Pin the test alias and Draft explicitly:
Confirm phoneNumber.voice names the intended project, alias and draft. Omitting the alias clears an existing pin and follows the project’s traffic split. This command leaves the SMS assignment unchanged. For Chat-only SMS, skip voice assignment and continue below.
Assign SMS independently when needed
Studio
Open the Chat project and its SMS page. Assign the Twilio number, then select its SMS Environment/version. The voice and SMS agents can differ; changing one does not move the other.
Code
Use a Twilio PHONE_NUMBER_ID. Set CHAT_PROJECT_ID and SMS_ENVIRONMENT for the intended Chat agent, then assign its independent SMS side:
Confirm the returned sms project, alias and Draft; inspect voice separately. A non-Twilio number or Voice project cannot receive an SMS assignment.
Support customers over SMS covers launch, reply and text-session checks. The Twilio Send SMS action uses separate credentials and does not perform this assignment.
Test the customer's channel
For voice, call the assigned number from your separate phone. Confirm the expected agent, two-way speech and a matching Transcript. For SMS, send a text and follow-up and check the Chat agent’s reply and Transcript separately. Browser Run does not verify provider routing.
For an imported provider number, use Outbound call API → View → Test call in Studio or follow the backend calling guide. Voiceflow numbers have no Studio outbound-test panel; use their outbound calling API path. HTTP acceptance alone does not prove the destination answered.
Verify the released route
Publish the reviewed Environment, select Published or the approved traffic split for the intended channel, and make a fresh customer-channel test. In Code, repeat the applicable vf phone-number assign command above with --version-param published, then read it back. Publishing alone does not change a Draft number assignment. Confirm that it uses the released instructions. Recheck the other channel rather than assuming it moved too.
Verify the result
The number reaches the intended agent and release, conversation works in both directions and the Transcript matches the test. Record the voice and SMS assignments separately for the team maintaining the connection.
For recording, use Voice configuration; number assignment and a Transcript do not by themselves establish that an audio recording exists.
Change or remove the connection
Unassign a channel to stop its agent assignment, or remove the workspace connection when no longer needed. The number operations and CLI support both lifecycle tasks; read its targets before a write. Unassigning both channels can partially succeed, so read them again after an error before retrying. Removing an imported number does not release it at the provider or restore its earlier application/webhook. Have its administrator restore the recorded provider route if that is the intended rollback. Removing a Voiceflow-provisioned number releases it from the workspace; do not assume you can reacquire the same number.
The number uses the wrong release
Check the channel, saved assignment and traffic-split choice.
Confirm whether the test was voice or SMS, then inspect that channel’s assignment. Select the exact Environment/version, save and start a fresh call or session. Check whether All environments intentionally uses traffic splitting. Existing conversations and browser Run do not test the newly selected customer route.