Overview
Voiceflow integrates with Twilio to answer support calls, call customers, run text conversations and send SMS notifications. A phone-number connection routes calls or messages to an agent. The Send SMS tool sends a specific message through a separate integration connection.
- Receive support calls with a Voice agent on an existing Twilio number.
- Make an outbound call from a reviewed agent and your backend’s trigger.
- Transfer a caller to a phone number or SIP destination.
- Support customers over SMS with a Chat agent that receives and replies to texts.
- Send a text follow-up with confirmed content and a confirmed recipient.
Studio
Use an editable Voice project for calls and a Chat project for an SMS conversation. An SMS notification tool can be attached to an agent or a Workflow without connecting an SMS conversation channel.
Code
Connect and assign the number through the management API or CLI, then call the runtime endpoint from your backend. The separate Send SMS action supports Voiceflow management and execution APIs or CLI. Keep provider credentials and Voiceflow API keys server-side.
Connecting Twilio numbers
Connect an owned number and assign each channel to its intended agent.
For a number connection, obtain an active Twilio number, its Account SID and Auth Token from the same Twilio account. The number must support the channel you will use. These credentials differ from the API key SID, API key secret and Account SID used by the Send SMS tool.
If the number currently uses a TwiML application or SIP trunk, have its administrator switch the relevant channel to number-webhook routing before the Voiceflow test. A TwiML application’s voiceApplicationSid overrides the number’s voice URLs; assigning Voiceflow’s voice URL does not clear that application SID. Record the old application/trunk first. See Twilio’s routing precedence.
Assignment changes the number’s Twilio voice or messaging webhook. Before connecting a number serving customers, have its administrator record the current routing and arrange the change. Use a separate test number first. See Twilio number routing.
Import and assign the number
Studio
Open the phone connection
Open your Voice project in Agent studio. Select Phone numbers → Create number → Twilio.
Enter the number credentials
Enter Twilio phone number, Twilio account SID and Twilio auth token. Give it an optional Name, then choose Create. The number must belong to the account whose credentials you entered.
Check its assignment
Complete assignment to the Voice agent. Open the number’s Environment setting, choose your test Environment and Draft, then Save. Use an administrator who can access or create the project’s API key when assignment requires it.
For a number already in this workspace, use Assign existing number rather than importing it again. Connect and route phone numbers explains fixed-version and traffic-split routing.
Code
Set VF_TOKEN to a Voiceflow management bearer credential with workspace phone create/read/list access and project phone-number assign permission. Set WORKSPACE_ID, PROJECT_ID to a Voice project in that workspace and ENVIRONMENT to its test alias. For SMS-only setup, import or locate the number here and skip the voice-assignment step; the SMS section assigns its Chat target. Assignment resolves the project’s long-lived runtime key; the management token is not the runtime calling key.
Set PHONE_NUMBER_E164 to the owned Twilio number. Supply TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN from that number’s account, using the prerequisites above. Export VF_TOKEN for the CLI. These operations import and route the real number; use a controlled test line.
Locate or import the owned number
List existing workspace connections first. If this number is already present, retain its phoneNumbers[].id and skip creation. Otherwise prepare its create body in your trusted shell:
Creation returns phoneNumber.id. Retain it as PHONE_NUMBER_ID; the new connection is unassigned until the next step. Protect and remove the local credential file when finished. The create operation is available through REST/CLI and Studio, and is refused for MCP clients.
Assign and verify the Draft voice route
Confirm phoneNumber.voice names the intended project, Environment alias and draft version. Inspect sms independently; this voice assignment leaves it unchanged. An omitted Environment alias clears a previous pin and follows the project’s traffic split, so supply the alias for this controlled test.
Use this Voiceflow ID and the assigned project’s runtime API key for the calling endpoint below. See the canonical number creation and assignment contracts for the complete schemas and permission errors.
The number cannot be imported
Check account ownership before changing the agent or routing.
- Invalid account credentials: use the number’s Account SID and Auth Token, not an SMS-tool API key pair.
- Number not found: confirm that the number is active in that exact account or subaccount and includes its country code.
- Number already exists: find the existing workspace connection and assign it instead of creating another copy.
- Created but not assigned: inspect the workspace list and finish assignment; repeating creation does not repair the missing agent connection.
Receiving calls
Route incoming callers to the assigned Voice agent and verify the conversation.
Twilio’s voice webhook points to Voiceflow after voice assignment. The selected Environment and version determine which agent answers; All environments uses the project’s traffic split. SMS has a separate assignment.
Studio
Prepare the opening and support instructions in Agent, then configure speech in Behaviour → Voice input and Voice output. Use approved Knowledge for support answers; connecting Twilio does not import content.
Code
Prepare and compile the assigned Draft using the Voice configuration guide. Provider number credentials route the call; they do not replace the Voiceflow project key used by your backend. Incoming callers do not call the outbound HTTP endpoint.
Call from a separate test phone
Call the connected Twilio number and confirm the expected agent answers. Speak a known support question and listen for a complete reply. Make your first phone call supplies the worked agent-building journey.
Check the actual call
Find the call by its time and numbers in Transcripts. Confirm the intended Environment and the two-way exchange. A saved number or successful browser Run is not evidence that telephone audio works.
Verify the released route
After reviewing and publishing the agent, select the intended Published assignment or reviewed traffic split. Make a fresh call and confirm it uses that release. See Go live with a Voice agent.
The phone rings but the expected agent does not answer
Compare Twilio’s voice routing with the saved Voiceflow assignment.
In the Twilio Console, inspect the number’s Voice configuration and call logs. Check whether a TwiML application or another service overrides its number webhook. Confirm the connection still has the correct Voice agent and release in Voiceflow. If the Auth Token changed, follow Reconnect a number after credential rotation; the existing number editor does not replace its stored provider credentials. Do not paste a different service’s webhook over the connection as a diagnostic shortcut.
Outbound calls
Place a callback through the assigned number and check whether it connected.
Use Make an outbound call for the shared preparation, calling and verification workflow. Apply the Twilio requirements below to that call.
Use a separate destination the recipient has agreed to receive calls on. Calling uses workspace credits and available production call capacity. The number must be assigned to the Voice agent; its assignment selects the release.
Place one test call
Studio
In Phone numbers, open View in the number’s Outbound call API column. Enter the separate destination in Test call, including its country code, then choose Call. This places a real call.
Use pickup-reminder example for a complete reminder-agent example.
Code
Use the PHONE_NUMBER_ID retained from the import/list procedure above. Set VF_API_KEY to the assigned project’s API key and TEST_RECIPIENT to a separate E.164 phone number you control. Keep them on your backend. Use jq to serialize the destination:
The minimal test disables answering-machine detection so you can first verify the live exchange. The phone calling contract owns authentication, request fields and errors. Start an outbound call explains backend triggers and correlation.
An accepted request returns no call ID or JSON payload. Answer the destination and inspect Twilio’s call log and the Voiceflow Transcript. Do not retry automatically after an uncertain response: the first request may already have dialed.
Twilio answering-machine detection is enabled by default when amd is omitted. The current Twilio consumer ends calls on machine_end_beep or fax; it does not deliver an arbitrary voicemail message. Keep Twilio-specific request overrides separate from other providers’ options.
The callback is refused or never reaches the recipient
Separate rejected requests from accepted calls that did not connect.
For a rejected request, check the destination, saved assignment, project key, credits and concurrency. For an accepted call, inspect Twilio’s call status and errors before making another attempt. Check the account’s destination permissions and trial restrictions in Twilio’s account guidance.
Transferring callers
Send an active call to a separate phone number or SIP destination.
The shared Call forward step owns the agent’s transfer behavior. Twilio supports a phone destination with optional extension digits, or a SIP address. Configure a reachable support destination distinct from the number receiving this call.
Studio
Configure the Call forward system tool
Open Agent, select Call forward in its system tools and enable it. Choose Phone number or SIP address and enter a separate reachable support destination. Apply this provider’s extension and caller-ID constraints above.
Describe when to transfer
Write a usage description such as transferring when the caller requests a person. Put the condition in the agent’s instructions too. For a fixed Workflow branch, use its Call forward step instead; Transfer a phone call explains both entry paths.
Verify the connected caller
Call the assigned number with a teammate waiting at the destination. Request a person, confirm the teammate receives the caller and inspect the Transcript. A configuration change or prototype run does not verify the provider transfer.
Code
Read and retain the current configuration
Set VF_TOKEN to a Voiceflow management bearer credential, PROJECT_ID to this Voice project, ENVIRONMENT to its test alias and SUPPORT_DESTINATION to a separate phone your team can answer. Read the current agent before replacing its system-tool settings:
Retain its callForwardTool configuration for restoration.
Enable the destination and compile
For a SIP destination use addressType: "sip" and the verified URI, applying the provider requirements above. The Agent API and transfer guide retain the complete configuration contract.
Verify the actual provider transfer
Call the assigned test number and request a person. Check the receiving phone, provider result and final Transcript. Read the agent back to confirm the settings and restore the retained configuration if the destination or invocation condition is wrong. The description explains when to transfer; it does not guarantee invocation or a human answer.
Test on the imported number with a teammate at the destination. Confirm that the teammate receives the caller and the AI leg ends. Transfer is disabled on Voiceflow’s prototype test-call path, so a prototype test cannot verify the production transfer. These instructions do not establish warm-transfer or return-to-AI behavior after a telephone transfer.
Supporting SMS conversations
Let a Chat agent receive texts or generate the first message.
SMS conversation assignment requires a Twilio number and a Chat project. Voice assignment and SMS assignment are independent: changing one does not change the other. Connecting the Send SMS tool does not create this channel.
Connect and test the SMS channel
Studio
Assign the Twilio number to the Chat agent
Open the Chat project in Agent studio, then open SMS → Create number → Twilio. Enter the number’s Account SID and Auth Token, or use Assign existing number for a Twilio number already connected in the workspace. Select the test Environment and Draft for its SMS assignment.
Test an incoming text and reply
Send a text from your separate phone to the Twilio number. Confirm the Chat agent replies, then send a follow-up and inspect its Transcript. Voiceflow installs the number’s SMS webhook during assignment.
Test the first message from the agent
Open View in Outbound SMS API. Enter a separate recipient in Test SMS and choose Send. Configure the agent’s launch instructions first: the agent writes the first text, rather than reading a message body supplied to this endpoint.
Code
Import or locate the owned Twilio number using the connection procedure above, with VF_TOKEN, WORKSPACE_ID and its PHONE_NUMBER_ID. Set CHAT_PROJECT_ID to the Chat project and SMS_ENVIRONMENT to its test alias. Assign the SMS side separately:
Confirm phoneNumber.sms names this Chat project, test alias and draft. Its voice target stays independent. Prepare and compile the Chat agent as shown in Support customers over SMS.
For the first agent-led text, set VF_API_KEY to the assigned Chat project’s runtime key and TEST_RECIPIENT to the separate E.164 test phone. Use the imported PHONE_NUMBER_ID:
The response is 202 with a sessionID, before asynchronous agent execution. The agent generates the first message from its launch behavior; this endpoint does not accept a notification body. Reply from the recipient and compare the exchange with its Transcript. Check inbound texting independently. Publish the reviewed Chat Environment, change this SMS assignment to published and verify a fresh released conversation. Inbound SMS and Outbound SMS own the complete channel behavior.
Use Support customers over SMS for the complete launch, reply and released-agent checks. Inbound SMS owns session behavior and supported media; SMS human agent hand-off owns the human-support path.
A connected number receives no agent replies
Check the SMS assignment and the provider’s effective messaging route.
Confirm that the number is SMS-capable and assigned to the intended Chat agent. Inspect Twilio’s Messaging logs. If the number belongs to a Messaging Service, check whether that service uses its own inbound URL or defers to the sender’s webhook; the number webhook installed by Voiceflow must be the effective route. See Twilio Messaging Services. A 202 from outbound SMS does not certify later model execution or delivery.
Sending SMS notifications
Send confirmed text through the Twilio action without starting a Chat session.
Prepare a Twilio Account SID, API key SID and API key secret, plus an SMS-capable sender authorized in that account. Grant the key access to the message operations you will use. A successful connection probe alone does not prove permission to send. See Twilio messaging authentication.
Connect, test and attach Send SMS
Studio
Connect the SMS action credentials
Open More → Integrations → Twilio → Connect. Enter API key SID, API key secret and Account SID. Connect the account intended for these messages; a number’s Auth Token connection is separate.
Add and configure Send SMS
In Agent → Global tools → +, select Twilio → Send SMS, or add an Integration step to the relevant Workflow. Write a Trigger that requires confirmed recipient and content. Set from to your authorized sender, to to a test phone you control and body to a short fixed support message.
Send once and inspect the result
Use Run to reach the tool. Inspect processedMessages.sid and processedMessages.status, then compare the message with Twilio’s log and the recipient’s phone. Use Capture response for values needed later; verify their actual returned paths.
For dynamic values, create the recipient/content variables first and populate them through the preceding confirmed conversation or trusted application. Keep the sender fixed. The text follow-up guide explains this sequence.
Code
Set VF_TOKEN to a Voiceflow management bearer credential, PROJECT_ID to a test project and ENVIRONMENT to a test Environment alias. For connection, set TWILIO_ACCOUNT_SID, TWILIO_API_KEY_SID and TWILIO_API_KEY_SECRET in your trusted shell. The stable connect operation writes the project’s Published connection, independently of the Environment query used for later tests. An existing Draft override can take precedence during standalone execution.
Set SMS_FROM to the authorized SMS sender and TEST_RECIPIENT to a separate international phone number you control before using either method. Export VF_TOKEN so the CLI can read it. Every send below creates a real message.
Inspect tools[] for twilio_send_sms and its input schema. Set SMS_FROM to the authorized sender and TEST_RECIPIENT to a separate phone you control, then send one fixed test message:
Use a current Voiceflow CLI. It reads VF_TOKEN; JSON output preserves the provider result.
Require success: true, error: null and truncated: false. Read output.data.processedMessages.sid and status; then check Twilio and the receiving phone. These calls send a real message. A tool call succeeding is not a carrier delivery receipt.
Standalone string inputs interpret brace tokens as Secret references. Keep this test body fixed; do not pass arbitrary customer text containing {name} to this execution path. JSON quoting does not disable that binding. Agent attachment input mappings have their own runtime scope.
Standalone execution needs no attachment or publication. Use the procedure below when the agent should send messages. The connection editor’s Draft/Published choice prepares a separate test credential; the stable connect operation above does not write a Draft override.
Attach Send SMS to an agent
Add the catalog action, bind test inputs and verify the agent’s use of it.
Studio
Add Twilio → Send SMS to Global tools or the intended Playbook. For a controlled test, set a fixed sender, separate recipient and message. For customer use, put the send in a confirmation-first Workflow and populate its recipient/content variables before the Integration step. Test both confirmation and cancellation, then publish the reviewed Environment and test a fresh released conversation.
Code
Add the catalog action, using the project, Environment and bearer credential prepared above:
Retain the returned integrationToolID as INTEGRATION_TOOL_ID. Create text project variables sms_message_id and sms_status with empty defaults, retaining each returned variable.id as SMS_MESSAGE_ID_VARIABLE_ID and SMS_STATUS_VARIABLE_ID:
Prepare one attachment with fixed test inputs, using the sender and separate recipient already verified:
Resolve unresolvedReferences and run a Draft conversation requesting that test follow-up. Confirm the attached action sends once, the captured sms_message_id/sms_status values match the result and the message ID matches Twilio. For repeated Workflow attempts, reset the result variables and check the current provider result; captures do not clear earlier values when a call fails. Persist the returned provider ID in your application when it must survive this conversation. For dynamic customer messages, replace the test defaults with trusted, populated recipient/content variables and enforce confirmation in your application or Workflow; the attachment description is not an authorization check. Prepare the intended Published connection, publish the reviewed Environment and test a fresh released conversation.
The SMS request succeeds but the message is missing
Use the provider’s message ID and delivery status before attempting another send.
Inspect the message SID in Twilio’s Messaging log. Check sender capability, destination permissions and the returned provider error. A queued or accepted status is not delivered. Verify applicable sender registration with your Twilio administrator. If the result is uncertain, inspect the existing message before retrying; another Send SMS call creates another message.
Managing the connection
Change routing or credentials without confusing the number and tool connections.
Choose the connection you are changing
Manage number names and voice/SMS assignments in Phone numbers, SMS or the workspace phone list. Manage the separate Send SMS credentials in More → Integrations → Twilio. Check Draft and Published credential slots when they differ.
Verify the affected channel after the change
Retest calls after a voice assignment change, texts after an SMS assignment change, and the Send SMS action after changing its API key. Use the reconnection procedure below when the stored number credentials must change. Changing the voice Environment does not change the SMS Environment. Keep the previous route recorded until your administrator has verified the replacement.
Remove only the intended connection
Stable API/CLI SMS unassignment clears the Twilio number’s SMS webhook; Studio’s current Unassign clears the saved assignment without performing that provider update. Neither restores an earlier messaging route. Check and restore the effective Twilio route with its administrator. Voice unassignment stops the Voiceflow assignment but does not restore prior Twilio routing. Removing an imported number from Voiceflow does not release it in Twilio. Have its administrator restore the recorded provider routing when required.
Disconnecting the SMS action credentials affects the tools using that integration. It does not disconnect the phone-number credential record. Coordinate key revocation with every consumer of the key.
Studio
Use the number’s menu in Phone numbers (or SMS for a Chat project) for its name and assignment. Inspect the provider’s effective routing after removal or channel changes.
Code
Use the imported PHONE_NUMBER_ID, WORKSPACE_ID and management VF_TOKEN. The credential also needs the workspace phone-number update, unassign or delete permission for each lifecycle operation you choose. Read the current targets before changing them. For example, rename the connection or clear voice only:
Only unassign a currently assigned side. The update operation edits its name, not stored credentials. Omitted unassign target clears both channels and can partially succeed; inspect the targets again after an error. To remove an imported connection deliberately, use vf phone-number delete --phone-number-id "$PHONE_NUMBER_ID" --workspace-id "$WORKSPACE_ID" --output-format json. This removes its Voiceflow ID and assignments; it does not release the provider-owned number or restore its previous routing. The lifecycle contracts own the full request/response reference.
Reconnect a number after credential rotation
Recreate its saved credential connection and update the dependent assignments and URLs.
The current number editor does not offer an in-place credential replacement. Arrange a maintenance window with the number administrator: removing and re-importing a connection interrupts its routing and gives it a new Voiceflow phone-number ID.
Record the dependencies before removing the connection
Record its voice agent, Environment/version, old Voiceflow number ID and every backend job using that ID. Record the SMS Chat agent and its Environment/version too. For planned rotation, perform stable API/CLI SMS unassignment while the old Auth Token still works, then inspect its cleared webhook. Studio Unassign clears the saved assignment but does not clear that provider webhook. Unassigning only voice leaves SMS connected. Keep its separate SMS notification tool credentials distinct.
Remove and re-import the owned number
Clear the intended assignments, then remove the imported connection from the workspace phone list or use the delete operation above. If the old Auth Token has already been revoked, stable SMS unassignment can fail before clearing its assignment. Have the administrator clear or restore Twilio’s effective messaging route using current provider access, then remove/re-import the saved connection; successful stable unassignment is not a prerequisite for deleting this imported connection. Read both targets after a partial failure. Removal does not release the provider’s number. Repeat the API/CLI import-and-assign procedure above or return to the target project’s Phone numbers → Create number → Twilio and enter the same owned number with the current Account SID and Auth Token. Complete assignment and restore the intended Environment/version. Use a controlled test assignment before returning customers to the route.
Restore every channel and update callers
Return to the Chat project’s SMS page and assign the newly imported number there as well when it also provides text support. Restore its SMS Environment/version independently. Replace old number-ID URLs in your backend with the new PHONE_NUMBER_ID, for both outbound calling and outbound SMS. Test inbound and outbound calls, and both directions of the SMS conversation, before ending the maintenance window. Confirm the intended Published route after testing. Do not retry a backend request still targeting the removed ID.