> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Support customers over SMS

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

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](/docs/guides/integrations/twilio/overview#sms-conversations), 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](/docs/guides/integrations/phone-messaging/send-text-follow-up).

## Connect and verify the conversation

### 1. Prepare the Chat agent's text behavior

#### Studio

Open the Chat project in [Agent studio](https://creator.voiceflow.com). 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.

#### Developer

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:

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/agent?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT&includeInstructions=true" \
  -H "Authorization: Bearer $VF_TOKEN"
```

Update only the practice instructions, preserving its registered Playbooks/Workflows, then compile the Draft:

```sh
curl --fail-with-body --silent --show-error -X PATCH \
  "https://realtime-api.voiceflow.com/v2/stable/agent?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data '{"instructions":"You are Northstar text support. Begin by identifying Northstar and offering help with collection. 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."}'

curl --fail-with-body --silent --show-error -X PUT \
  "https://realtime-api.voiceflow.com/v1/stable/environment/$ENVIRONMENT/compile?projectID=$PROJECT_ID" \
  -H "Authorization: Bearer $VF_TOKEN"
```

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](/docs/api-reference/agent/get-agent) owns the complete configuration contract; these text instructions do not change Voice speech controls.

### 2. Assign the number's SMS channel

#### Studio

Open [Agent studio](https://creator.voiceflow.com), 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.

Native SMS number setup for a Chat agent with Twilio selected — Assign the text channel to the Chat agent separately from voice calls.

#### Developer

Use the [Twilio number import procedure](/docs/guides/integrations/twilio/overview#connecting-twilio) 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:

```sh
jq -n --arg project "$PROJECT_ID" --arg environment "$ENVIRONMENT" \
  '{target:"sms",projectID:$project,environmentAlias:$environment,version:"draft"}' |
curl --fail-with-body --silent --show-error -X PUT \
  "https://realtime-api.voiceflow.com/v1/stable/phone-number/$PHONE_NUMBER_ID/assign?workspaceID=$WORKSPACE_ID" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' --data-binary @-

curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/phone-number/$PHONE_NUMBER_ID?workspaceID=$WORKSPACE_ID" \
  -H "Authorization: Bearer $VF_TOKEN"
```

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](/docs/api-reference/phone-number/assign-phone-number).

This updates the Twilio number's messaging webhook. It leaves the voice assignment separate; verify both if the number also receives calls.

### 3. 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](/docs/documentation/measure/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](/docs/documentation/deploy/sms/inbound). A successful webhook acknowledgment does not establish that the later reply reached the phone.

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

#### Developer

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:

```sh
jq -n --arg to "$TEST_RECIPIENT" '{to:$to}' |
curl --fail-with-body --silent --show-error \
  "https://runtime-api.voiceflow.com/v1/phone-number/$PHONE_NUMBER_ID/sms/outbound" \
  -H "Authorization: $VF_API_KEY" -H 'Content-Type: application/json' --data-binary @-
```

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](/docs/documentation/deploy/sms/outbound#api-reference) owns its fields, rate limits and active-session conflicts.

### 5. Verify the released support path

[Publish the reviewed Chat Environment](/docs/documentation/deploy/environments/publishing), 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](/docs/guides/integrations/twilio/overview#sms-conversations) before changing the route.

For a teammate taking over the text conversation, follow [SMS human agent hand-off](/docs/documentation/handoff/sms) and the relevant [Help Desk manual](/docs/guides/integrations/help-desks). Telephone transfer and SMS hand-off are separate workflows.
