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

# Deploy a Chat agent with Voiceflow SMS

> Connect your Twilio number to Voiceflow’s managed SMS channel.

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

**Note:** 

**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](/docs/guides/channels/sms#installation-guides), which includes a developer-hosted relay. For one notification, use [Send a text follow-up](/docs/guides/integrations/phone-messaging/send-text-follow-up).

<a id="prepare-sms"></a>

## Before you begin

Prepare the Chat agent, Twilio account and a controlled test.

| Requirement | What to prepare |
| --- | --- |
| Agent owner | An existing [Chat agent](/docs/documentation/build/overview), approved Knowledge and a test Environment. Prepare its [text-support behavior](/docs/guides/integrations/phone-messaging/support-over-sms#prepare-the-text-support-behavior). Use an agentic Chat project; legacy chat projects do not expose this assignment. |
| Workspace administrator | Access to connect and assign numbers. Code uses a personal or service key; its retrieval and required inputs are in [Connect and assign SMS](#connect-sms). |
| Twilio administrator | An active two-way SMS number and the **Account SID** and **Auth Token** for the account or subaccount that owns it. Complete the [Twilio sender checks](/docs/guides/channels/sms/twilio#prepare-twilio). |
| Controlled test | A separate phone that expects the messages, one approved answer and a follow-up question. |

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](/docs/documentation/build/overview) before connecting it; number setup does not add Knowledge or support instructions.

<a id="connect-sms"></a>

## Connect and assign SMS

Route the owned number to a test Chat Environment.

#### Studio

### 1. Open SMS in the Chat project

Open the intended Chat project in [Agent studio](https://creator.voiceflow.com). Select **SMS → Create number → Twilio**. If the number is already connected in this workspace, use **Assign existing number** instead.

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

Native Twilio SMS number connection for a Chat agent — Connect an owned Twilio number before selecting its SMS Environment.

### 3. 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](/docs/guides/channels/sms/twilio#route-incoming-sms) 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.

### 1. Collect the credential and routing inputs

- **`VF_TOKEN`:** Create a [personal key](/docs/api-reference/authentication#personal-keys), or have an organization administrator create a [service key](/docs/api-reference/authentication#service-keys). Select the intended workspace and Chat project with **Read & write** access.
- **`WORKSPACE_ID`:** List workspaces below; select the intended workspace’s `workspaces[].id`.
- **`PROJECT_ID`:** List that workspace’s projects below; select the Chat project’s `projects[].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](/docs/documentation/deploy/environments/overview#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](/docs/guides/channels/sms/twilio#prepare-twilio). 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:

```sh
curl --fail-with-body --silent --show-error \
  'https://realtime-api.voiceflow.com/v1/stable/workspace' \
  -H "Authorization: Bearer $VF_TOKEN"

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

Match names and IDs to the intended workspace and Chat project before importing a number. The [Workspace](/docs/api-reference/resources/workspace) and [Project](/docs/api-reference/resources/project) references own the full lookup contracts.

### 2. Locate or import the number

List workspace numbers first. If the owned number exists, retain its `phoneNumbers[].id` and skip creation.

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

Otherwise set `SMS_FROM`, `TWILIO_ACCOUNT_SID` and `TWILIO_AUTH_TOKEN` to the owned number and its account credentials, then import it:

```sh
jq -n --arg workspace "$WORKSPACE_ID" --arg number "$SMS_FROM" \
  --arg sid "$TWILIO_ACCOUNT_SID" --arg token "$TWILIO_AUTH_TOKEN" \
  '{workspaceID:$workspace,provider:"twilio",name:"Northstar SMS",value:$number,twilioAccountSID:$sid,twilioAuthToken:$token}' |
curl --fail-with-body --silent --show-error \
  'https://realtime-api.voiceflow.com/v1/stable/phone-number' \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' --data-binary @-
```

Retain `phoneNumber.id` as `PHONE_NUMBER_ID`. Creation imports the number; it does not assign its voice route. See the [creation contract](/docs/api-reference/phone-number/create-phone-number) for permissions and credential validation.

### 3. Assign the SMS target and read it back

```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` 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](/docs/guides/channels/sms/twilio#route-incoming-sms). The [assignment contract](/docs/api-reference/phone-number/assign-phone-number) owns all fields and errors.

<a id="sms-sessions"></a>

## Understand SMS sessions

Follow sender identity, session continuity and reply delivery.

| Event | Managed SMS behavior |
| --- | --- |
| First incoming text | Twilio posts to Voiceflow's webhook; Voiceflow verifies its signature with the stored Auth Token and routes to the number's SMS target. |
| Returning customer | The sender's number identifies the user (`user_id`). The runtime resumes or creates a session according to the agent's session settings. Avoid treating a shared phone as authenticated identity. |
| Agent reply | Voiceflow sends text back from the business number to the customer through Twilio. A webhook `200` only acknowledges the incoming event. |
| Close or resume | Agent completion and session expiry determine whether the next message starts a new conversation. A new outbound launch starts a fresh session and can conflict with an active turn or hand-off. |
| Repeated or delayed event | Do not replay Twilio callbacks manually to recover a missing reply; this path does not promise exactly-once processing from `MessageSid`. Inspect Transcripts and the provider log first. |

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](/docs/documentation/build/behaviour#session-timeout-chat-projects). 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](/docs/documentation/deploy/sms/inbound) for the canonical session and file behavior, and [SMS human agent hand-off](/docs/documentation/handoff/sms) when a teammate must take over.

<a id="test-sms"></a>

## Test a two-way conversation

Prove the incoming text, agent turn and reply reach the intended destinations.

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

### 2. 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](/docs/documentation/measure/transcripts), then compare their times with Twilio's incoming and outgoing message IDs.

### 3. 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](https://www.twilio.com/docs/messaging/tutorials/advanced-opt-out).

### 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](/docs/guides/channels/sms/twilio#route-incoming-sms).

### 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](#sms-sessions), then confirm a new Transcript rather than continuing the old conversation. If the old session had no timeout, use another controlled sender.

<a id="start-sms"></a>

## Let the agent send first

Optionally launch an expected conversation from the connected number.

#### Studio

### 1. Open the outbound tester

In the Chat project's **SMS** list, select **View** under **Outbound SMS API** for the connected number.

### 2. 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](#connect-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.

```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: Bearer $VF_TOKEN" -H 'Content-Type: application/json' --data-binary @-
```

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](/docs/documentation/deploy/sms/outbound#api-reference) for the exact contract.

<a id="release-sms"></a>

## Release the SMS route

Verify Published behavior through the same number.

#### Studio

### 1. Publish and pin the reviewed Environment

Set the reviewed Chat Environment’s session timeout to the duration you want customers to have, then [publish](/docs/documentation/deploy/environments/publishing) it. In the SMS number's Environment selector, choose that Environment and **Published**, then **Save**.

### 2. 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](#sms-sessions). Then text the [known question and follow-up](#test-sms) 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](/docs/documentation/measure/transcripts#filtering-transcripts) for the filters.

#### Code

Have the agent owner restore the intended customer session timeout, then [publish the reviewed Environment](/docs/documentation/deploy/environments/publishing) using its canonical publication procedure. With the same management credential and IDs from connection, pin the SMS target to Published:

```sh
jq -n --arg project "$PROJECT_ID" --arg environment "$ENVIRONMENT" \
  '{target:"sms",projectID:$project,environmentAlias:$environment,version:"published"}' |
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 @-
```

Read back the number using the GET in [Connect and assign](#connect-sms). Confirm `phoneNumber.sms` names the intended alias and `published`. Leave the controlled phone idle longer than the timeout recorded [before testing](#sms-sessions), then repeat the [customer test](#test-sms). 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.

<a id="maintain-sms"></a>

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

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

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

### 3. Reconnect and restore the assignments

Repeat [Connect and assign SMS](#connect-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](/docs/documentation/deploy/phone/connect-a-phone-number).

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.

### 4. Verify the restored routes

Inspect the saved Twilio routes and repeat the [customer test](#test-sms), 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.

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

### 2. 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](#connect-sms) with the intended alias/version. Replacing saved Twilio credentials requires reconnecting: the stable update endpoint changes the name only.

### 1. Record both assignments

Use `VF_TOKEN`, `WORKSPACE_ID` and `PHONE_NUMBER_ID` from [Connect and assign SMS](#connect-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.

### 2. Delete only the imported Twilio connection

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

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](/docs/api-reference/phone-number/delete-phone-number) owns the exact permissions and response.

### 3. Import again and verify both routes

Repeat [Connect and assign SMS](#connect-sms) with the current Account SID/Auth Token. Retain the **new** `PHONE_NUMBER_ID`, restore SMS and any separate [voice assignment](/docs/documentation/deploy/phone/connect-a-phone-number), and update outbound URLs that used the old ID. Inspect Twilio’s routes and run the [customer test](#test-sms), 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](/docs/api-reference/phone-number/unassign-phone-number) with `target:"sms"` and the same credential/workspace/number inputs from [connection](#connect-sms), 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.
