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

# Twilio integration

> Connect Voiceflow to Twilio for inbound and outbound calls, SMS conversations and support notifications.

## 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](#receiving-calls)** with a Voice agent on an existing Twilio number.
- **[Make an outbound call](#starting-calls)** from a reviewed agent and your backend's trigger.
- **[Transfer a caller](#transferring-callers)** to a phone number or SIP destination.
- **[Support customers over SMS](#sms-conversations)** with a Chat agent that receives and replies to texts.
- **[Send a text follow-up](#sending-sms)** 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.

#### Developer

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.

<a id="connecting-twilio"></a>

## 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](#sending-sms).

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](https://www.twilio.com/docs/phone-numbers/api/incomingphonenumber-resource).

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](https://help.twilio.com/articles/223136047-Configuring-Phone-Numbers-to-Receive-and-Respond-to-SMS-and-MMS-Messages).

### Import and assign the number

#### Studio

### 1. Open the phone connection

Open your Voice project in [Agent studio](https://creator.voiceflow.com). Select **Phone numbers → Create number → Twilio**.

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

Native Twilio number connection with phone number, account SID and auth token fields — Connect the owned Twilio number using its account credentials.

### 3. 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](/docs/documentation/deploy/phone/connect-a-phone-number) explains fixed-version and traffic-split routing.

#### Developer

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.

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

```sh
jq -n --arg workspace "$WORKSPACE_ID" --arg value "$PHONE_NUMBER_E164" \
  --arg sid "$TWILIO_ACCOUNT_SID" --arg token "$TWILIO_AUTH_TOKEN" \
  '{workspaceID:$workspace,name:"Northstar support line",provider:"twilio",value:$value,twilioAccountSID:$sid,twilioAuthToken:$token}' \
  > phone-create.json
```

#### API

```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"

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 @phone-create.json
```

#### CLI

```sh
vf phone-number list --workspace-id "$WORKSPACE_ID" --output-format json
vf phone-number create --output-format json < phone-create.json
```

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.

### 2. Assign and verify the Draft voice route

#### API

```sh
jq -n --arg project "$PROJECT_ID" --arg environment "$ENVIRONMENT" \
  '{target:"voice",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"
```

#### CLI

```sh
vf phone-number assign --phone-number-id "$PHONE_NUMBER_ID" --workspace-id "$WORKSPACE_ID" \
  --target voice --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --version-param draft --output-format json
vf phone-number get --phone-number-id "$PHONE_NUMBER_ID" --workspace-id "$WORKSPACE_ID" --output-format json
```

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

<a id="receiving-calls"></a>

## 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](/docs/documentation/build/querying-the-knowledge-base) for support answers; connecting Twilio does not import content.

#### Developer

Prepare and compile the assigned Draft using the [Voice configuration guide](/docs/guides/developers/voice/configure-voice). 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.

### 1. 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](/docs/guides/studio/voice/first-phone-call) supplies the worked agent-building journey.

### 2. Check the actual call

Find the call by its time and numbers in [Transcripts](/docs/documentation/measure/transcripts). Confirm the intended Environment and the two-way exchange. A saved number or successful browser Run is not evidence that telephone audio works.

### 3. 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](/docs/guides/studio/voice/go-live).

### 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](#reconnect-number-credentials); 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.

<a id="starting-calls"></a>

## Outbound calls

Place a callback through the assigned number and check whether it connected.

Use [Make an outbound call](/docs/documentation/deploy/phone/outbound-calling) 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.

Outbound call API dialog with a separate test destination and Call button — Test the connected number against a separate phone you can answer.

Use [pickup-reminder example](/docs/guides/outbound-calls) for a complete reminder-agent example.

#### Developer

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:

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

The minimal test disables answering-machine detection so you can first verify the live exchange. The [phone calling contract](/docs/api-reference/agent-runtime/voice/phone-calls) owns authentication, request fields and errors. [Start an outbound call](/docs/guides/developers/voice/outbound-calls) 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](https://www.twilio.com/docs/usage/tutorials/how-to-use-your-free-trial-account).

<a id="transferring-callers"></a>

## Transferring callers

Send an active call to a separate phone number or SIP destination.

The shared [Call forward step](/docs/documentation/build/steps/call-forward) 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

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

Native Call forward system tool with a separate support destination — Configure a destination distinct from the number that received the call.

### 2. 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](/docs/guides/studio/voice/transfer-calls) explains both entry paths.

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

#### Developer

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

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

Retain its `callForwardTool` configuration for restoration.

### 2. Enable the destination and compile

```sh
jq -n --arg address "$SUPPORT_DESTINATION" \
  '{callForwardTool:{enabled:true,addressType:"phone",address:$address,
    description:"Transfer when the caller asks for the support team.",messages:null,toolSound:null}}' |
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-binary @-

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"
```

For a SIP destination use `addressType: "sip"` and the verified URI, applying the provider requirements above. The [Agent API](/docs/api-reference/agent/get-agent) and [transfer guide](/docs/guides/developers/voice/transfer-calls) retain the complete configuration contract.

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

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

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

### 1. Assign the Twilio number to the Chat agent

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

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

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

#### Developer

Import or locate the owned Twilio number using the [connection procedure above](#connecting-twilio), 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:

```sh
jq -n --arg project "$CHAT_PROJECT_ID" --arg environment "$SMS_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`. Its `voice` target stays independent. Prepare and compile the Chat agent as shown in [Support customers over SMS](/docs/guides/integrations/phone-messaging/support-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`:

```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 @-
```

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](/docs/documentation/deploy/sms/inbound) and [Outbound SMS](/docs/documentation/deploy/sms/outbound) own the complete channel behavior.

Use [Support customers over SMS](/docs/guides/integrations/phone-messaging/support-over-sms) for the complete launch, reply and released-agent checks. [Inbound SMS](/docs/documentation/deploy/sms/inbound) owns session behavior and supported media; [SMS human agent hand-off](/docs/documentation/handoff/sms) 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](https://www.twilio.com/docs/messaging/services). A `202` from outbound SMS does not certify later model execution or delivery.

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

## Sending SMS notifications

Send confirmed text through the Twilio action without starting a Chat session.

<a id="what-it-connects" />
<a id="using-the-twilio-tool" />
<a id="actions" />

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](https://www.twilio.com/docs/messaging/api).

### Connect, test and attach Send SMS

#### Studio

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

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

Native Twilio Send SMS tool with body, to and from inputs — Configure the message and both phone-number roles before sending.

### 3. 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](/docs/guides/integrations/phone-messaging/send-text-follow-up) explains this sequence.

#### Developer

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.

#### API

```sh
jq -n --arg sid "$TWILIO_ACCOUNT_SID" --arg key "$TWILIO_API_KEY_SID" --arg secret "$TWILIO_API_KEY_SECRET" \
  '{integration:"twilio",credentials:{accountSid:$sid,apiKeySid:$key,apiKeySecret:$secret}}' |
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/integration/twilio?projectID=$PROJECT_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/integration/twilio/schema?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN"
```

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:

```sh
jq -n --arg from "$SMS_FROM" --arg to "$TEST_RECIPIENT" \
  '{toolName:"twilio_send_sms",inputs:{from:$from,to:$to,body:"Northstar support: your requested follow-up is ready."}}' |
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/integration/twilio/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' --data-binary @-
```

#### CLI

Use a current [Voiceflow CLI](/docs/cli/install). It reads `VF_TOKEN`; JSON output preserves the provider result.

```sh
jq -n --arg sid "$TWILIO_ACCOUNT_SID" --arg key "$TWILIO_API_KEY_SID" --arg secret "$TWILIO_API_KEY_SECRET" \
  '{integration:"twilio",credentials:{accountSid:$sid,apiKeySid:$key,apiKeySecret:$secret}}' |
vf integration connect --integration twilio --project-id "$PROJECT_ID" --output-format json

vf integration get-schema --integration twilio --project-id "$PROJECT_ID" \
  --environment-alias "$ENVIRONMENT" --output-format json

vf integration execute --integration twilio --project-id "$PROJECT_ID" \
  --environment-alias "$ENVIRONMENT" --tool-name twilio_send_sms \
  --inputs "$(jq -cn --arg from "$SMS_FROM" --arg to "$TEST_RECIPIENT" \
    '{from:$from,to:$to,body:"Northstar support: your requested follow-up is ready."}')" \
  --output-format json
```

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.

#### Developer

Add the catalog action, using the project, Environment and bearer credential prepared above:

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/integration/twilio/tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data '{"toolName":"twilio_send_sms"}'
```

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`:

```sh
for SMS_RESULT_VARIABLE in sms_message_id sms_status; do
  jq -n --arg name "$SMS_RESULT_VARIABLE" '{name:$name,color:"#515A63",defaultValue:""}' |
  curl --fail-with-body --silent --show-error \
    "https://realtime-api.voiceflow.com/v2/stable/variable?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
    -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' --data-binary @-
done
```

Prepare one attachment with fixed test inputs, using the sender and separate recipient already verified:

```sh
jq -n --arg id "$INTEGRATION_TOOL_ID" --arg from "$SMS_FROM" --arg to "$TEST_RECIPIENT" \
  --arg messageID "$SMS_MESSAGE_ID_VARIABLE_ID" --arg statusID "$SMS_STATUS_VARIABLE_ID" \
  '{type:"integration",integrationToolID:$id,target:{global:true},
    description:"Send the confirmed Northstar test follow-up once when requested.",
    inputVariables:{
      from:{integrationToolVariableName:"from",required:false,defaultValue:$from},
      to:{integrationToolVariableName:"to",required:false,defaultValue:$to},
      body:{integrationToolVariableName:"body",required:false,defaultValue:"Northstar support: your requested follow-up is ready."}
    },captureResponse:{
      messageID:{path:"processedMessages.sid",variableOrEntityID:$messageID},
      status:{path:"processedMessages.status",variableOrEntityID:$statusID}
    }}' > twilio-attachment.json

curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @twilio-attachment.json

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"
```

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](/docs/guides/integrations/phone-messaging/send-text-follow-up#confirm-and-send-the-follow-up); 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](/docs/documentation/deploy/environments/publishing) 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.

<a id="managing-twilio"></a>

## Managing the connection

Change routing or credentials without confusing the number and tool connections.

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

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

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

#### Developer

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**:

```sh
vf phone-number get --phone-number-id "$PHONE_NUMBER_ID" --workspace-id "$WORKSPACE_ID" --output-format json
vf phone-number update --phone-number-id "$PHONE_NUMBER_ID" --workspace-id "$WORKSPACE_ID" \
  --name "Northstar support line" --output-format json
vf phone-number unassign --phone-number-id "$PHONE_NUMBER_ID" --workspace-id "$WORKSPACE_ID" \
  --target voice --output-format json
```

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](/docs/api-reference/phone-number/get-phone-number) own the full request/response reference.

### Reconnect a number after credential rotation

Recreate its saved credential connection and update the dependent assignments and URLs.

<a id="reconnect-number-credentials" />

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

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

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

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