Overview
Voiceflow SMS connects an SMS-capable number in your Twilio account to an existing Voiceflow Chat agent. Voiceflow hosts the incoming webhook, runs the assigned agent and sends its replies through Twilio. Your team supplies the number, its account credentials and the agent’s support behavior.
Choosing an approach: This manual teaches Voiceflow’s managed Twilio connection. Voiceflow-provisioned voice numbers do not establish SMS support. For another SMS provider, use its installation manual, which includes a developer-hosted relay. For one notification, use Send a text follow-up.
Before you begin
Prepare the Chat agent, Twilio account and a controlled test.
Use the owned number in E.164 format. Examples use 🇺🇸 US numbers: +12065550111 for the business and +12025550123 for the test customer. Replace both with numbers you control; these fictional numbers cannot receive a test.
If the SMS navigation is unavailable, have the workspace owner check the project type and workspace access before changing provider routing. Build the agent before connecting it; number setup does not add Knowledge or support instructions.
Connect and assign SMS
Route the owned number to a test Chat Environment.
Studio
Open SMS in the Chat project
Open the intended Chat project in Agent studio. Select SMS → Create number → Twilio. If the number is already connected in this workspace, use Assign existing number instead.
Connect the owned number
Enter Twilio phone number, Twilio Account SID, Twilio Auth Token and an optional Name. Choose Create. Use the account that actually owns the number.
Save the test assignment
Use a non-production test number. Select the test Environment and Draft, then Save. For an existing number, open its Environment selector to set this assignment. Confirm that the SMS list shows the intended Chat project and Environment.
Assignment writes Twilio’s number-level messaging webhook. The Twilio routing check ensures a Messaging Service does not send messages somewhere else. Voice assignment is independent.
Code
Use a terminal with curl and jq. Keep credentials in local environment variables or your backend’s secret store.
Collect the credential and routing inputs
VF_TOKEN: Create a personal key, or have an organization administrator create a service key. Select the intended workspace and Chat project with Read & write access.WORKSPACE_ID: List workspaces below; select the intended workspace’sworkspaces[].id.PROJECT_ID: List that workspace’s projects below; select the Chat project’sprojects[].id.ENVIRONMENT: Copy the test Environment’s Alias from Environments, or choose Copy alias in its row menu. Use the alias rather than the display name; see Environment aliases.SMS_FROM: The owned two-way business number in E.164.TWILIO_ACCOUNT_SID: The Account SID for the Twilio account that owns the number.TWILIO_AUTH_TOKEN: That account’s Auth Token.
Get the number and owning account credentials from Twilio preparation. If choosing Custom key scopes, allow the linked number operations, including delete for credential replacement. Outbound SMS also requires project:READ and project.versions:READ.
After storing the key as VF_TOKEN, find the IDs with these read-only requests. Set WORKSPACE_ID from the first response before running the second:
Match names and IDs to the intended workspace and Chat project before importing a number. The Workspace and Project references own the full lookup contracts.
Locate or import the number
List workspace numbers first. If the owned number exists, retain its phoneNumbers[].id and skip creation.
Otherwise set SMS_FROM, TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN to the owned number and its account credentials, then import it:
Retain phoneNumber.id as PHONE_NUMBER_ID. Creation imports the number; it does not assign its voice route. See the creation contract for permissions and credential validation.
Assign the SMS target and read it back
Confirm phoneNumber.sms contains the intended project, test alias and draft; inspect voice independently. Supply the Environment alias for this test: omitting it selects traffic-split routing instead of a fixed pin. Assignment resolves the project’s long-lived key and updates Twilio’s messaging webhook. Check its effective Messaging Service route. The assignment contract owns all fields and errors.
Understand SMS sessions
Follow sender identity, session continuity and reply delivery.
Before the first test, have the agent owner open the test Environment’s Behaviour → Session & timeout. Enable Session timeout and record its Inactivity timeout in minutes. For a dedicated test Environment, 1 minute makes repeat tests quicker. See Chat session timeout. An existing session keeps the timeout with which it started; changing the setting does not reset that session.
To reuse the same test phone, stop texting after the reply and wait longer than the recorded timeout. The next incoming text should create a new conversation. If the earlier session started with timeout disabled, use another controlled sender for this test instead of assuming the changed setting closes it.
Keep instructions brief and text-based. The managed runtime can rehost supported inbound media when file uploads are enabled; confirm your exact file type and agent settings before relying on MMS. Provider capability and destination restrictions still apply. Use Inbound SMS for the canonical session and file behavior, and SMS human agent hand-off when a teammate must take over.
Test a two-way conversation
Prove the incoming text, agent turn and reply reach the intended destinations.
Text a known question
From the separate phone, text “What are your collection hours?” to the connected number. For the practice agent, prepare an approved answer such as “Northstar collection hours are 10 am to 6 pm.” Confirm a reply arrives from the expected business number.
Continue and compare the session
Ask “Are you open at noon?” and an out-of-scope question. Confirm the follow-up uses the conversation context and the unknown answer follows your fallback. Find both turns in the intended project’s Transcripts, then compare their times with Twilio’s incoming and outgoing message IDs.
Check delivery separately
Open Twilio’s Monitor → Logs → Messaging for the outgoing reply. Inspect its terminal status and errors, and check the handset. An accepted/queued request, a saved number or a Transcript alone does not establish receipt. Test STOP/START behavior on the controlled recipient using your configured Twilio opt-out settings.
The text never reaches the agent
Check number ownership, SMS assignment and the effective Twilio webhook.
Confirm the number supports incoming SMS, the same account owns it, and the SMS target names the Chat agent. In Twilio, inspect the number’s messaging webhook and any Messaging Service’s inbound settings. A voice assignment does not route texts. Use the Twilio routing checks.
A Transcript exists but the phone has no reply
Separate agent output from Twilio and carrier delivery.
Check that the turn produces a text answer and that Twilio has an outgoing message for the correct recipient. Inspect registration, account balance, geographic permissions, opt-out state and provider errors. If no outgoing message exists, retain the incoming ID, Transcript and timestamp for investigation. Reposting the webhook can run the turn again.
The wrong answer or release appears
Check the SMS target and start a fresh controlled session after release changes.
Read the SMS Environment and Draft/Published selection, separate from voice. With traffic-split routing, confirm the selected Environment in the Transcript. Existing sessions can retain their selected release. Follow the same-phone timeout procedure, then confirm a new Transcript rather than continuing the old conversation. If the old session had no timeout, use another controlled sender.
Let the agent send first
Optionally launch an expected conversation from the connected number.
Studio
Open the outbound tester
In the Chat project’s SMS list, select View under Outbound SMS API for the connected number.
Launch and reply
In Test SMS, enter the separate controlled recipient in E.164 and select Send. Confirm the first text follows the agent’s launch instructions, then reply and verify continuity in the Transcript. You do not type the first message body in this request.
Code
Reuse VF_TOKEN, the personal or service key collected in Connect and assign SMS, with project:READ and project.versions:READ access to the assigned Chat project. Set TEST_RECIPIENT to the controlled phone’s E.164 number. This runtime endpoint accepts that credential directly; no additional project API key or session key is needed.
Retain the returned sessionID. A 202 accepts a fresh conversation before generation and sending finish; it is not a delivery receipt. Confirm the first text on the phone, reply, then compare the Transcript and Twilio log. The first text comes from the agent’s launch path; variables can supply starting context, but there is no request-supplied message body. See Outbound SMS for the exact contract.
Release the SMS route
Verify Published behavior through the same number.
Studio
Publish and pin the reviewed Environment
Set the reviewed Chat Environment’s session timeout to the duration you want customers to have, then publish it. In the SMS number’s Environment selector, choose that Environment and Published, then Save.
Start a new conversation from the same phone
After the previous test’s last reply, leave that phone idle longer than the Inactivity timeout recorded before testing. Then text the known question and follow-up again. If the previous session had timeout disabled, use another controlled sender.
Open Transcripts, filter to the released Environment and the time after publication, and open the new conversation. Confirm it is a separate conversation row with a new start time, rather than new turns appended to the old test. Compare its answer with the published behavior, then verify the business sender and Twilio delivery status. See finding conversations for the filters.
Code
Have the agent owner restore the intended customer session timeout, then publish the reviewed Environment using its canonical publication procedure. With the same management credential and IDs from connection, pin the SMS target to Published:
Read back the number using the GET in Connect and assign. Confirm phoneNumber.sms names the intended alias and published. Leave the controlled phone idle longer than the timeout recorded before testing, then repeat the customer test. If the earlier session had timeout disabled, use another controlled sender. In Transcripts, filter to that Environment and the time after publication; confirm a separate conversation row with a new start time, then open it and check the turns are separate from the earlier test. Compare the answer with the published behavior and check Twilio delivery. The managed path needs the Voiceflow release and the Twilio route to agree.
Maintain the connection
Recover the number route and credentials deliberately.
Studio
Update credentials or change routing
Coordinate provider credentials and both channel assignments before retesting.
For an Environment or Draft/Published change, use the SMS number’s Environment selector and Save; keep the existing connection. Replacing its saved Twilio Auth Token requires reconnecting the imported number.
Record both assignments before removing the connection
Have the workspace number administrator schedule a change window covering SMS and any voice assignment. Record both project/Environment/Draft-or-Published selections and Twilio’s current messaging and voice routes.
Remove the old imported Twilio connection
Return to the workspace dashboard and open Phone numbers. Find the owned Twilio number, open its More menu, choose Delete, then Confirm. Expect Number removed.
Deleting this imported connection removes both Voiceflow assignments. It does not release the number from your Twilio account. This procedure is only for the connected Twilio number; do not use it for a Voiceflow-provisioned number.
Reconnect and restore the assignments
Repeat Connect and assign SMS with the current Account SID/Auth Token and restore the recorded SMS assignment. If the number also handled voice, restore its separate voice assignment.
Reconnecting changes the Voiceflow number ID. If a backend starts outbound SMS, have its owner update the outbound URL using the new connection’s Outbound SMS API → View example.
Verify the restored routes
Inspect the saved Twilio routes and repeat the customer test, plus any voice test. If removal or creation reports an error, check the workspace Phone numbers list before repeating the action.
Rotating an unrelated Send SMS tool API key does not change this connection’s stored Auth Token.
Unassign or roll back SMS
Restore the intended provider route without disturbing voice calls.
Unassign from the Chat project
In the Chat project’s SMS list, open the number’s More menu, choose Unassign, then confirm Unassign. Expect Unassigned and the number to leave that project’s SMS list. This removes the SMS assignment; it keeps the workspace connection and separate voice assignment.
Restore and verify the provider route
Check Twilio’s messaging settings. If returning to another service, have its administrator restore the previously recorded incoming-message route. Unassignment clears the managed number-level SMS webhook; it does not recreate the old provider configuration. Verify voice separately and retain the Twilio number until its owner intentionally releases it.
Code
Update credentials or change routing
Coordinate provider credentials and both channel assignments before retesting.
For an Environment or Draft/Published change, repeat assignment with the intended alias/version. Replacing saved Twilio credentials requires reconnecting: the stable update endpoint changes the name only.
Record both assignments
Use VF_TOKEN, WORKSPACE_ID and PHONE_NUMBER_ID from Connect and assign SMS. The key needs the deletion operation’s permissions as well as import/assignment access. GET the old number and record its ID, SMS and voice project/Environment/version assignments, and Twilio’s current messaging and voice routes. Schedule a change window for both channels.
Delete only the imported Twilio connection
For this imported Twilio number, deletion removes both Voiceflow assignments without releasing the number in Twilio. Do not use this procedure for a Voiceflow-provisioned number. The deletion contract owns the exact permissions and response.
Import again and verify both routes
Repeat Connect and assign SMS with the current Account SID/Auth Token. Retain the new PHONE_NUMBER_ID, restore SMS and any separate voice assignment, and update outbound URLs that used the old ID. Inspect Twilio’s routes and run the customer test, plus any voice test. If a removal/import result is uncertain, list workspace numbers before retrying.
Rotating an unrelated Send SMS tool API key does not change this connection’s stored Auth Token.
Unassign or roll back SMS
Restore the intended provider route without disturbing voice calls.
Use the unassignment contract with target:"sms" and the same credential/workspace/number inputs from connection, then GET the number again. Confirm the SMS target is cleared and the separate voice target is retained.
Check Twilio’s messaging settings and restore the previous incoming-message route if returning to another service. Unassignment clears the managed number-level SMS webhook; it does not recreate the old provider configuration. Verify voice separately and retain the Twilio number until its owner intentionally releases it.