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 with a Voice agent on an owned Telnyx number.
- Make an outbound call from your backend or Studio’s test-call dialog.
- Transfer callers to the phone or SIP destination your team operates.
- Send a text follow-up 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.
Code
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.
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. Create the API credential separately using Telnyx API 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
Open the provider connection
Open the Voice project in Agent studio, then select Phone numbers → Create number → Telnyx. Use a separate test number before changing a number serving customers.
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.
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 explains assignment and traffic splitting.
Code
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.
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:
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.
Assign and verify the Draft voice route
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 and assignment 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.
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 for support answers; the number connection does not import content.
Code
Prepare and compile the assigned Draft using the Voice configuration guide. Voiceflow resolves the call through this number’s assigned agent, Environment and version. All environments follows the traffic split.
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 supplies a complete agent-building journey.
Inspect the conversation and release
Locate the call by time and numbers in 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 to distinguish media failures from agent behavior. Recreating the number does not fix a provider route that another service overrides.
Outbound calls
Dial through the assigned number and verify the actual answered call.
Use Make an outbound call 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 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.
pickup-reminder example explains building and releasing a reminder agent.
Code
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:
The phone calling contract owns exact fields and errors. For an event-triggered callback, follow Start an outbound call 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.
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
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.
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 explains both entry paths.
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.
Code
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:
Retain its callForwardTool configuration for restoration.
Enable the destination and compile
For a SIP destination use addressType: "sip" and the verified URI, applying the provider requirements above. The Agent API and transfer guide retain the complete configuration contract.
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.
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 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 and the API-tool definition. 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
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.
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.
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}.
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.
Code
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.
Prepare the project Secret
Set SMS_API_KEY in your trusted shell to the credential described above. Create the Secret in the test project:
This writes the project default and Main’s Published value. Retain secret.id; use the Secret value contract to set environmentAlias and versionVariant: "draft" when the test alias needs an override.
Save the API request and discover its inputs
Retain apiTool.id as API_TOOL_ID. Inspect its schema and the returned input IDs:
The schema declares api_key and payload. Match each variables[].name to its id for attachment later.
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:
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:
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, 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:
Create the attachment, then compile the Draft:
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; 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, 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 for the confirmation-first cross-provider journey. This SMS API tool does not provide incoming SMS sessions; Twilio 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.
Managing the connection
Maintain voice routing and SMS credentials as separate connections.
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.
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.
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.
Code
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:
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 own the full request/response reference.
Reconnect a number after credential rotation
Recreate its saved credential connection and update the dependent assignments and URLs.
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.
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.
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.
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.