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

# Telnyx integration

> Voiceflow integrates with Telnyx to answer calls on your numbers, call customers and transfer callers.

## Overview

Voiceflow integrates with Telnyx to answer calls on your numbers, call customers and transfer callers. Use the SMS notification recipe below to send confirmed text through an API tool, independently of the voice-number connection.

- **[Receive support calls](#receiving-calls)** with a Voice agent on an owned Telnyx number.
- **[Make an outbound call](#starting-calls)** from your backend or Studio's test-call dialog.
- **[Transfer callers](#transferring-callers)** to the phone or SIP destination your team operates.
- **[Send a text follow-up](#sending-sms)** using a Secret-backed API tool and a correctly encoded message.

#### Studio

Use an editable Voice project and access to manage workspace numbers. The SMS recipe uses an API tool and a small formatting Function; the provider administrator supplies its sender and credentials.

#### Developer

Connect and assign the number through the management API or CLI, then use Voiceflow's runtime API for calls. The SMS recipe uses management APIs to save and attach an API tool; its payload formatter also runs on your backend. These workflows use existing Voiceflow capabilities.

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

## Connecting Telnyx numbers

Connect the owned number and prepare its provider-side call routing.

Obtain an owned voice-capable Telnyx number, an API key with access to it and the account’s public key for signed-webhook verification. The public key verifies Telnyx events; it is not an API key or SIP password. Find the verification key under **Account settings → Keys & Credentials → Public Key**, as described in [Telnyx webhook signing](https://support.telnyx.com/en/articles/4334722-how-to-leverage-webhooks). Create the API credential separately using [Telnyx API authentication](https://developers.telnyx.com/docs/development/api-fundamentals/authentication).

When you assign the number, Voiceflow creates or updates a Telnyx Call Control application and assigns it to the number. Have the administrator record its existing connection/application and routing before assignment, because this can replace them. Supplying the public key selects the signed-webhook path.

### Import and assign the number

#### Studio

### 1. Open the provider connection

Open the Voice project in [Agent studio](https://creator.voiceflow.com), then select **Phone numbers → Create number → Telnyx**. Use a separate test number before changing a number serving customers.

### 2. Enter the account and number details

Fill in **Telnyx phone number**, **Telnyx API key** and **Telnyx public key**. Add an optional **Name**, then choose **Create** and complete assignment to this Voice agent.

Native Telnyx number connection and its provider credential fields — Use the credentials and verification key for the account that owns this number.

### 3. Select the test release

In the number's **Environment** setting, choose the test Environment and **Draft**, then **Save**. Assignment requires permission to manage workspace phone connections and edit the project; an administrator may need to resolve its project API key.

Use **Assign existing number** for a number already connected in this workspace. [Connect and route phone numbers](/docs/documentation/deploy/phone/connect-a-phone-number) explains assignment and traffic splitting.

#### 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. 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 Telnyx number. Supply `TELNYX_API_KEY`, `TELNYX_PUBLIC_KEY` 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 key "$TELNYX_API_KEY" --arg publicKey "$TELNYX_PUBLIC_KEY" \
  '{workspaceID:$workspace,name:"Northstar support line",provider:"telnyx",value:$value,telnyxAPIKey:$key,telnyxPublicKey:$publicKey}' \
  > 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 connected

Check the owning account and any partially completed assignment.

Confirm the number is active in the exact provider account whose credentials you entered. If it already exists in Voiceflow, assign that workspace connection. If creation completed but assignment failed, locate the number and complete assignment rather than creating it again. Compare the saved credentials with the provider's current values and check the specific error before retrying.

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

## Receiving calls

Verify that callers reach the intended agent with audio in both directions.

Check the number’s assigned Call Control application and its Voiceflow webhook. The account public key must match signed events. Voiceflow handles the provider event and bidirectional media connection; you do not need to build a separate media-stream server for this integration.

#### Studio

Prepare **Agent** instructions and **Behaviour → Voice input / Voice output**. Use approved [Knowledge](/docs/documentation/build/querying-the-knowledge-base) for support answers; the number connection does not import content.

#### Developer

Prepare and compile the assigned Draft using the [Voice configuration guide](/docs/guides/developers/voice/configure-voice). Voiceflow resolves the call through this number's assigned agent, Environment and version. **All environments** follows the traffic split.

### 1. Call the connected number

Use a separate phone to call the Telnyx number. Ask a known support question and confirm the assigned agent answers and hears you. [Make your first phone call](/docs/guides/studio/voice/first-phone-call) supplies a complete agent-building journey.

### 2. Inspect the conversation and release

Locate the call by time and numbers in [Transcripts](/docs/documentation/measure/transcripts). Verify two-way audio and the intended Environment. After publishing the reviewed agent, select **Published** or the reviewed traffic split and make a fresh call. A stored connection alone does not verify the call path.

### The connection exists but calls do not reach the agent

Compare provider application routing with the saved Voiceflow assignment.

Check the number's effective application, answer webhook and provider call log. Confirm its Voiceflow assignment and credentials. If audio is one-way, use the [Voice troubleshooting owner](/docs/api-reference/agent-runtime/voice/troubleshooting) to distinguish media failures from agent behavior. Recreating the number does not fix a provider route that another service overrides.

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

## Outbound calls

Dial through the assigned number and verify the actual answered call.

Use [Make an outbound call](/docs/documentation/deploy/phone/outbound-calling) for the shared preparation, calling and verification workflow. Apply the Telnyx requirements below to that call.

In Telnyx, open the Call Control application attached to this number and assign an **Outbound Voice Profile** that permits your test destination. Voiceflow provisions the application but does not supply that account-owned profile. The [application contract](https://developers.telnyx.com/api-reference/call-control-applications/create-a-call-control-application) names it `outbound.outbound_voice_profile_id`. With answering-machine detection enabled, Voiceflow requests `detect_beep`; this does not configure an arbitrary voicemail message.

### Place one test call

#### Studio

Open **Phone numbers → Outbound call API → View** for this number. Enter a separate phone you control in **Test call**, then choose **Call**. This places a real call and uses workspace credits/call capacity.

Outbound test-call dialog with a separate destination — Use a separate test destination and check the answered conversation.

[pickup-reminder example](/docs/guides/outbound-calls) explains building and releasing a reminder agent.

#### Developer

Use the `PHONE_NUMBER_ID` retained from the import/list procedure above. Set `VF_API_KEY` to the assigned project's key and `TEST_RECIPIENT` to a separate E.164 destination you control. Run the request only from your backend or trusted shell:

```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 [phone calling contract](/docs/api-reference/agent-runtime/voice/phone-calls) owns exact fields and errors. For an event-triggered callback, follow [Start an outbound call](/docs/guides/developers/voice/outbound-calls) rather than exposing the key in a browser.

A successful dial request returns an empty body, not a call ID. Answer the destination, check the provider call log and compare its Transcript. Inspect an uncertain attempt before retrying; it may already have dialed. Check credits, production concurrency, destination permissions and provider account restrictions when rejected.

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

## Transferring callers

Route a connected caller to a separate support destination.

Telnyx transfers a phone call to the configured number or sends SIP Refer for a SIP destination. Inbound caller-ID passthrough can use the original caller number. The current Telnyx phone-transfer consumer does not send a separate extension field: use a directly reachable destination or a verified SIP destination instead of assuming extension digits are applied.

#### 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 with a teammate at the destination. Confirm the caller reaches them and the AI leg ends; do not infer warm-transfer or return-to-AI behavior from provider API availability. Test transfers on the assigned number, independently of a prototype test-call path.

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

## Sending SMS notifications

Send one confirmed support message through an existing API tool.

Have your Telnyx administrator enable messaging on the sender and assign it to an appropriate Messaging Profile, including its required sender registration. The recipe uses that configured numeric sender. Connecting a voice application does not configure a messaging profile or an SMS conversation channel.

This setup is separate from the number's voice credentials. The [provider SMS contract](https://developers.telnyx.com/api-reference/messages/send-a-message) owns sender eligibility and delivery details. Keep sender registration with the provider administrator.

### Prepare the credential and payload

Obtain the Telnyx API key for the messaging account and store only the key as the Secret value. The request header adds `Bearer `; do not put the public verification key here.

Create the restricted project Secret **telnyx_sms_token** in **More → Secrets**, in a test project. Creating a Secret default also sets Main's Published value; set the intended Environment's Draft override if it differs. Before release, prepare that Environment's Published value too.

Download [the Telnyx payload formatter](/docs/examples/telephony/prepare-telnyx-sms.js) and [the API-tool definition](/docs/examples/telephony/telnyx-sms-tool.json). The formatter accepts `from`, `to` and `text`, all strings; it returns `outputVars.sms_payload`. Both numbers must start with `+` and include a country code. Use an approved sender and a separate confirmed test recipient.

The formatter serializes the entire object and encodes braces inside JSON string values as Unicode escapes. JSON decoding restores the original message, while standalone input binding cannot mistake customer text for a project Secret. Do not interpolate unescaped customer text into a quoted JSON body.

#### Studio

### 1. Prepare the confirmed content

Create an escalation/follow-up Workflow. Collect the recipient and message, read them back and require confirmation before its send branch. Keep the approved sender fixed. Create the project text variable `sms_payload` in **More → Variables**, with an empty default.

### 2. Add the formatting Function

Open **Tools** under **Agent** in the left navigation and choose **New tool → Function**. Name it **Prepare Telnyx SMS** and paste the downloaded formatter. In your Workflow, add a **Function** step and select this saved Function. Declare text inputs `from`, `to`, `text` and text output `sms_payload`. Map its inputs from the fixed sender and confirmed conversation values. Map the output into the project's `sms_payload` variable. Leave custom Function paths empty for this output-only formatter. Turn **Async execution** off. Enable **Failure path** on the step: connect **Success** to the API step and **Failure** to a review/correction message and End, with no connection back to the API. A thrown validation error must not fall through to the send using a previous payload.

### 3. Configure the API request

In **Agent → Tools**, choose **New tool → API**. Name it **Send Telnyx support SMS**, using **POST** `https://api.telnyx.com/v2/messages`. Add `Authorization: Bearer {api_key}` and `Content-Type: application/json`. Choose **Raw → JSON** for the body and insert the single tool input `{payload}`.

Native Send Telnyx support SMS request editor with method, URL and headers — Keep the provider URL fixed and send the complete encoded payload.

### 4. Bind inputs and send after confirmation

Bind **api_key** to the Secret **telnyx_sms_token**, and **payload** to the populated `sms_payload` variable. Add an **API** step after the formatting Function and select this tool. Confirm its mappings before running the Workflow and keep the API step's **Async execution** off while retaining its result. Do not let the model generate credentials or an arbitrary sender.

Run the confirmed test once, then test a malformed destination after that successful turn: the Function must take Failure and the API must not run. Inspect the result below, then use **Capture response** to save the actual provider message ID when needed. The formatter itself sends nothing.

#### Developer

Set `VF_TOKEN` to a Voiceflow management bearer credential, `PROJECT_ID` to a test project and `ENVIRONMENT` to its test alias. Save the downloaded definition as `telnyx-sms-tool.json` and the formatter as `prepare-telnyx-sms.mjs`. The same pure formatter can run in Node; no provider credentials enter its payload.

### 1. Prepare the project Secret

Set `SMS_API_KEY` in your trusted shell to the credential described above. Create the Secret in the test project:

```sh
jq -n --arg value "$SMS_API_KEY" \
  '{name:"telnyx_sms_token",visibility:"restricted",defaultValue:$value}' |
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/secret?projectID=$PROJECT_ID" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' --data-binary @-
```

This writes the project default and Main's Published value. Retain `secret.id`; use the [Secret value contract](/docs/cli/commands/secret/set-value) to set `environmentAlias` and `versionVariant: "draft"` when the test alias needs an override.

### 2. Save the API request and discover its inputs

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

Retain `apiTool.id` as `API_TOOL_ID`. Inspect its schema and the returned input IDs:

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

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

The schema declares `api_key` and `payload`. Match each `variables[].name` to its `id` for attachment later.

### 3. Build and execute one confirmed message

Set `SMS_FROM`, `TEST_RECIPIENT` and `SMS_TEXT` to the approved sender, separate recipient and confirmed message in your shell. Save the following as `prepare-send.mjs` beside the formatter, export these three variables, then use the gated command below:

```js
import prepare from './prepare-telnyx-sms.mjs';
const result = await prepare({inputVars:{
  from:process.env.SMS_FROM,
  to:process.env.TEST_RECIPIENT,
  text:process.env.SMS_TEXT
}});
process.stdout.write(JSON.stringify({inputs:{
  api_key:"{telnyx_sms_token}",
  payload:result.outputVars.sms_payload
}}));
```

```sh
node prepare-send.mjs > sms-execute.json && \
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/api-tool/$API_TOOL_ID/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @sms-execute.json
```

Stop if the formatter fails; do not execute an empty or previously saved request. This sends a real message through the saved request. First require `success: true`, `error: null` and `truncated: false`, then check the provider result below. Standalone execution uses the selected Environment's Draft and does not attach the request to an agent.

**Attach the request to the agent**

For an agent attachment, first create the project text variable `sms_payload` with an empty default:

```sh
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 '{"name":"sms_payload","color":"#515A63","defaultValue":""}'
```

Create two more text variables, `sms_message_id` and `sms_status`, with empty defaults using the same variable endpoint. Keep their returned `variable.id` values for `MESSAGE_ID_VARIABLE_ID` and `STATUS_VARIABLE_ID` in the attachment below.

Have your backend populate it with the formatter's complete output **after** verifying the recipient/content and before the tool runs. Use [runtime action variables](/docs/api-reference/v4interact/interact-non-stream#streaming-action), for example `variables: {"sms_payload":"THE_FORMATTER_OUTPUT"}` on the action that starts this verified follow-up. Defining the variable or creating a session does not populate it.

Save this as `sms-attachment.json`, replacing `YOUR_API_TOOL_ID`, `CREDENTIAL_INPUT_ID` and `PAYLOAD_INPUT_ID` with the saved tool and discovered input IDs:

```json
{
  "type":"api",
  "apiToolID":"YOUR_API_TOOL_ID",
  "target":{"global":true},
  "description":"Send the support follow-up only after the application supplies its confirmed payload.",
  "inputVariables":{
    "api_key":{"apiToolInputVariableID":"CREDENTIAL_INPUT_ID","required":false,"defaultValue":"{telnyx_sms_token}"},
    "payload":{"apiToolInputVariableID":"PAYLOAD_INPUT_ID","required":false,"defaultValue":"{sms_payload}"}
  },
  "captureResponse":{
    "messageID":{"path":"data.id","variableOrEntityID":"MESSAGE_ID_VARIABLE_ID"},
    "status":{"path":"data.to[0].status","variableOrEntityID":"STATUS_VARIABLE_ID"}
  }
}
```

Create the attachment, then compile the Draft:

```sh
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 @sms-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 any `unresolvedReferences`. Test a Draft conversation in which the trusted application supplies the confirmed payload; check that the agent uses the attached request once and its `sms_message_id`/`sms_status` variables match the actual result. 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 provider ID in your application if it must survive this conversation. The description explains intent; your application or Workflow owns confirmation and authorization. Prepare the intended Published Secret and [publish the reviewed Environment](/docs/documentation/deploy/environments/publishing), then repeat in a fresh released-agent conversation. Standalone execution alone does not verify that path.

### Check acceptance and delivery

Require a successful `output.status`, `output.body.data.id` and the expected recipient in `output.body.data.to`. Retain the message ID and inspect the recipient’s status and any errors. A queued message is not delivered; verify the same message in the provider log and on the recipient’s phone.

Use [Send a text follow-up](/docs/guides/integrations/phone-messaging/send-text-follow-up) for the confirmation-first cross-provider journey. This SMS API tool does not provide incoming SMS sessions; [Twilio SMS conversations](/docs/guides/integrations/twilio/overview#sms-conversations) use a separate channel.

### The send fails or its result is uncertain

Inspect the saved request and provider message record before another write.

Check the actual HTTP status, response body, sender eligibility and selected Environment's Secret value. A successful Voiceflow request can still contain a provider failure. Compare the returned message ID with the provider log. If a timeout leaves the result uncertain, inspect that log before retrying; another POST can send a duplicate. The formatter must run before the API step, and the payload input must hold its complete output rather than a quoted placeholder or unescaped customer text.

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

## Managing the connection

Maintain voice routing and SMS credentials as separate connections.

### 1. Change the intended connection

Manage the number's name, agent, Environment and version in **Phone numbers** or the workspace phone list. Manage SMS API-tool credentials in **More → Secrets**. The number editor changes its name and routing, not its stored provider credentials. Use the reconnection procedure below when those credentials must change; the separate SMS Secret has its own rotation path.

### 2. Retest the affected path

After changing voice routing, make a fresh incoming call and one controlled outbound call. After rotating an SMS credential, test the selected Draft, update the intended Published Secret and verify a fresh released-agent conversation. Keep the old credential until its owner confirms every required consumer has switched.

### 3. Unassign or remove deliberately

Unassigning stops the Voiceflow agent assignment. Removing the imported connection does not release the phone number or restore its earlier Telnyx application. Have the administrator restore the recorded connection if required. Retain the intended outbound profile when reviewing later application changes.

Deleting an SMS tool or its Secret affects its request/attachments, independently of the voice-number connection. Review both paths before revoking a provider account credential.

#### 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. Retain the provider application/connection details so the number administrator can inspect or restore the intended route. Keep its separate SMS notification tool credentials distinct.

### 2. Remove and re-import the owned number

Unassign the intended channel(s), then remove the imported connection from the workspace phone list. This 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 → Telnyx** and enter the same owned number with the current API key and public verification key. 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

Replace old number-ID URLs in your backend with the new `PHONE_NUMBER_ID`, also shown under **Outbound call API → View** in Studio. Test inbound and outbound calls, and the linked provider application, before ending the maintenance window. Confirm the intended Published route after testing. Do not retry a backend request still targeting the removed ID.
