Connect a Chat support agent to a Twilio number and verify a question and follow-up. You can also let the agent send the first message. This channel has its own assignment and session behavior; a one-off SMS action does not configure it.
Before you begin
- An existing Chat support agent with its intended Playbook or Workflow already registered, a test Environment and an administrator with workspace phone access and access to its project API key. This guide connects that agent to SMS; it retains its existing routing.
- An SMS-capable Twilio number, its Account SID and Auth Token, and a separate test phone. Follow the Twilio channel prerequisites, including the effective Messaging Service route when applicable.
- Two approved practice answers and one out-of-scope question. The example agent answers Northstar’s collection hours and refers account-specific questions to support without inventing details.
Use the customer’s expected messaging channel. For a single confirmed notification, choose Send a text follow-up.
Connect and verify the conversation
Prepare the Chat agent's text behavior
Studio
Open the Chat project in Agent studio. In Agent, give it concise text-support instructions and approved Knowledge. For this practice, use: “Northstar collection hours are 10 am to 6 pm. Ask one question at a time. Do not invent order details; offer the support contact when information is missing.” Add an opening appropriate for a recipient who expects a text from Northstar.
Code
Set VF_TOKEN to a Voiceflow management bearer credential, PROJECT_ID to the existing Chat project and ENVIRONMENT to its test alias. Read and retain the current agent configuration:
Update only the practice instructions, preserving its registered Playbooks/Workflows, then compile the Draft:
Test the opening in a Draft conversation before connecting the number. After the practice, restore the retained instructions with the same PATCH endpoint and recompile if you are returning this test agent to its previous behavior. Outbound SMS runs this launch path without a request-supplied message body. The Agent API owns the complete configuration contract; these text instructions do not change Voice speech controls.
Assign the number's SMS channel
Studio
Open Agent studio, select this Chat project, then open SMS → Create number → Twilio. Enter the owned number’s Account SID and Auth Token. If it already exists in the workspace, use Assign existing number. Set the SMS assignment to the test Environment and Draft, then save.
Code
Use the Twilio number import procedure to import or locate the owned number without assigning voice. Keep its PHONE_NUMBER_ID and WORKSPACE_ID; use the Chat PROJECT_ID, test ENVIRONMENT and management VF_TOKEN from the first step:
Confirm phoneNumber.sms names this Chat project, test alias and draft version. Assignment needs project phone-number permission in the same workspace; it resolves the project’s long-lived runtime key itself. See the assignment contract.
This updates the Twilio number’s messaging webhook. It leaves the voice assignment separate; verify both if the number also receives calls.
Send a question and a follow-up
From your separate phone, text “What are your collection hours?” to the Twilio number. Confirm the agent returns the approved hours, then ask a follow-up. Compare the conversation with Transcripts. Test an account-specific question the practice agent cannot answer; it should use the configured fallback.
For session selection, supported media and text delivery behavior, use Inbound SMS. A successful webhook acknowledgment does not establish that the later reply reached the phone.
Test the agent sending the first text
Studio
In the Chat project’s SMS page, open View in Outbound SMS API. Enter your separate recipient in Test SMS and choose Send. Check the first text and reply to it. The agent writes the first message from its launch instructions.
Code
Use the imported PHONE_NUMBER_ID. Set VF_API_KEY to the assigned Chat project’s runtime key and TEST_RECIPIENT to the separate E.164 recipient. Keep the key in your backend or trusted shell:
Retain the returned sessionID. A 202 accepts a fresh session before the agent generates and sends its first text. Verify the phone and Transcript afterward; do not retry an uncertain launch automatically. The outbound SMS contract owns its fields, rate limits and active-session conflicts.
Verify the released support path
Publish the reviewed Chat Environment, set the SMS assignment to its Published version, and repeat the question and reply in a fresh session. In Code, repeat the assignment request above with version:"published" and read back its sms target. In Studio, choose Published in the SMS assignment. Confirm the released instructions, intended sender, permitted answer and provider message status. Recheck the voice assignment independently.
Diagnose a missing reply
Inspect the intended Chat project’s assignment, its selected release and Twilio’s message log. A number connected for voice is not automatically assigned for SMS. Check whether a Messaging Service overrides the number webhook and whether sender eligibility permits the destination. Use Twilio’s connection diagnostics before changing the route.
For a teammate taking over the text conversation, follow SMS human agent hand-off and the relevant Help Desk manual. Telephone transfer and SMS hand-off are separate workflows.