Telnyx Voice
Overview
The Telnyx Voice integration enables your AI agent to handle voice conversations over phone calls. By connecting your Telnyx account to Moveo, you can provide automated voice support that combines the power of AI with natural speech interaction.
This integration supports automated phone support through your Telnyx phone numbers and outbound calling through campaigns. It also provides natural voice interactions with text-to-speech and speech-to-text, and flexible configuration to optimize voice quality and recognition accuracy.
Prerequisites
Before setting up the Telnyx Voice integration, you'll need to configure both your Telnyx account and your Moveo setup.
Telnyx account
You'll need an active Telnyx account with voice capabilities enabled and sufficient balance to cover voice call costs. You collect all Telnyx-side values from the Mission Control Portal.
API key
Moveo uses a Telnyx API v2 key to place calls, control them, and provision the voice resources described in What Moveo configures in your Telnyx account. Create the key in the Telnyx portal under API Keys.
Copy the API key when it's created. Telnyx shows the value only once. You also cannot change the key after you save the integration. To use a different key, delete the integration and create a new one.
Public key
Telnyx signs every webhook it sends to Moveo, and Moveo verifies that signature before acting on the call. Copy the public key from the Public Key page, in the same API Keys section of the Telnyx portal. Telnyx exposes a single public key for your organization.
Moveo checks your API key when you enter it, but it cannot check the public key. If the public key is wrong, the integration still saves, and Moveo then rejects every webhook Telnyx sends, so calls are never answered. Copy it exactly.
Account level
Telnyx applies limits per account level, and the lower levels are not usable for production voice. An account belongs to either the Pretrial to Verified ladder or the Level 1 and Level 2 framework, never both:
- Pretrial accounts have no access to Call Control Applications, which this integration requires. Upgrade before configuring the integration.
- Trial accounts are limited to a single outbound voice profile, restrict calls to a verified phone number, cap call duration at 10 minutes, and allow 2 concurrent outbound calls. See trial limitations.
- Paid accounts allow 5 concurrent outbound calls. Reaching 10 requires completing verification, and higher limits are available from Telnyx on request. See concurrent call limits.
- Level 1 accounts cap outbound calling at 100 calls per day and 10 calls per hour, which is not enough for a campaign. See L1 restrictions.
Below the Verified level, Telnyx prepends an automated-call announcement to machine-generated speech, so your callers hear a Telnyx fraud notice before the AI agent. This applies to paid accounts too, not only trials. Completing verification also lifts the concurrency and destination limits.
Phone number
Connect a Telnyx number, or a number you've ported to Telnyx, to receive incoming calls and to place campaign calls. Telnyx assigns a number to one connection at a time, so you cannot select a number in Moveo that is already in use elsewhere in your Telnyx account.
Without a phone number the integration cannot answer incoming calls or place campaign calls. Leave Phone set to None only if you plan to add the number later.
Moveo account
You connect your AI agent to Telnyx in Moveo. For a complete walkthrough of the Moveo-side setup including AI agent selection, environment configuration, and rule creation, see Deploy the AI agent to a channel.
How it works
The Telnyx Voice integration creates a bridge between callers and your Moveo AI agent. When someone dials your Telnyx phone number, Telnyx notifies Moveo, Moveo answers the call, and Telnyx starts streaming the call audio. The speech-to-text engine converts spoken words into text, which your AI agent processes to generate an appropriate response. Text-to-speech then converts that response back to natural voice and streams it to the caller in real time. The AI agent sets both speech engines in its voice settings.
For outbound calls the flow is similar. A campaign asks Telnyx to dial the customer, and when the customer answers, the same speech processing and response cycle occurs. The conversation continues until the caller hangs up, or the AI agent resolves the conversation.
What Moveo configures in your Telnyx account
Once you save the integration with valid credentials, Moveo creates the Telnyx resources the AI agent needs and keeps them in sync:
- An outbound voice profile that authorizes outbound calling.
- A voice API application whose webhook points at Moveo, so Telnyx notifies Moveo about incoming calls and call events.
- The connection resources used for call control.
- The phone number assignment that binds the number you selected to that application.
Moveo re-checks these resources periodically and removes them when you delete the integration.
Don't rename, delete, or repoint the Telnyx resources that Moveo creates. The integration stops working until the expected configuration returns. If one of them changes, delete and save the integration again so that Moveo recreates it.
The outbound voice profile that Moveo creates covers the common destination countries. If your campaign targets a country that isn't enabled, contact Moveo support. Telnyx also gates many destinations behind account verification, so verify your Telnyx account before dialing outside the United States and Canada.
Reaching your AI agent
After you configure the integration, users can reach your AI agent in two ways:
Inbound calls: Customers can call your Telnyx phone number directly to start a conversation with your AI agent. This is particularly useful for customer support hotlines or IVR systems where users initiate contact.
Outbound calls: Your AI agent can also call customers as part of a campaign. This enables proactive outreach for appointment reminders, notifications, surveys, or follow-ups, with the AI agent handling the conversation when the customer answers.
Call termination and handover
Apart from the caller hanging up, a call ends in one of two ways, both controlled from the AI agent's workflow. When the AI agent resolves the conversation, the platform hangs up the call within a couple of seconds.
- Resolve: the
Resolveaction marks the conversation as completed. The call leg closes within a couple of seconds, whatever the environment's Keep alive value. - Handover: the
Handoveraction transfers the active call to a phone number or SIP URI, via a Standard transfer (Moveo stays on the call) or SIP REFER (Moveo hands off to your SIP system and drops off). You can attach optional custom SIP headers for SIP destinations. See Voice call transfer.
To make voice calls behave predictably at the end of a conversation, apply the following checklist to every voice-enabled environment:
- Leave Keep alive as it is. It does not affect voice call termination. See Keep alive for voice integrations.
- Add a
Pauseaction of 1–2 seconds immediately before anyResolveorHandoveraction so the AI agent's final sentence is not clipped.
Setup guide
Step 1: Prepare your Telnyx credentials
- Log in to the Mission Control Portal and open API Keys.
- On the API Keys page, select Create API Key and copy the key immediately.
- Open Public Key in the same section and copy the public key.
Keep both values handy for the next step.
Step 2: Configure the integration in Moveo
Navigate to Connections in your Moveo account, select your environment, find the Telnyx Voice integration card, and select Connect.
Step 3: Enter your Telnyx account details
Enter your credentials in the Account section of the configuration panel:
API Key: the Telnyx API v2 key from the previous step. Moveo checks the key as you type and reports whether Telnyx accepts it.
Public Key: the public key of the same Telnyx account, used to verify webhook signatures. Moveo cannot validate this one, so copy it exactly.
Once the API key is verified, a Phone field appears so you can connect a number to the AI agent. Moveo groups the numbers to show what you can pick:
| Group | Meaning |
|---|---|
| Available | Telnyx numbers in your account that aren't attached to another connection |
| Verified caller ID | Numbers you own elsewhere and have verified in Telnyx, usable for outbound calls only |
| In use | Already taken, so they can't be selected: a Telnyx number attached to another connection, or a verified caller ID used by another Moveo integration |
The list shows only numbers that are active in Telnyx, up to the first 250. Select a number to let the integration answer incoming calls to it and place campaign calls from it. A verified caller ID is the exception, since it works for outbound calls only, so read Choose the caller ID for outbound calls before picking one.
Step 4: Choose the caller ID for outbound calls
Which number your customers see on outbound campaign calls depends on the kind of number you selected:
A Telnyx number is the recommended option, because it handles incoming and outgoing calls. For calls to the United States and Canada, Telnyx also signs numbers you own at the highest STIR/SHAKEN attestation level, A, which lowers the chance that carriers block or label the call.
A verified caller ID is a number you own with another provider and have registered under Numbers → Verified numbers in the Telnyx portal. Keep two constraints in mind:
- It works for outbound campaigns only. Incoming calls to that number keep routing through your original provider.
- Some destination carriers screen calls that present a local number arriving from another carrier's network, and in-country calls to mobile numbers are the common failure case. Telnyx also signs these calls at attestation B rather than A. Prefer a Telnyx number for the market you dial most.
Your own SIP gateway is an optional advanced setup. Selecting a verified caller ID reveals a SIP gateway field in the Account section: enter a host there and Moveo sends outbound calls to that gateway, so your own carrier places the call to the recipient. Enter the host without a sip: prefix, for example sbc.example.com:5060. If the gateway authenticates, enter its credentials in SIP auth username and SIP auth password.
This setup requires your own SIP infrastructure and a carrier contract that allows presenting those numbers. Contact Moveo support to plan it.
Step 5: Set up the voice of the AI agent
The integration handles only the telephony. The AI agent holds the voice and the language model, so every integration that connects to the AI agent uses the same settings:
- The voice settings of the AI agent set the speech-to-text and text-to-speech provider, the model, the voice, and turn detection for each language.
- The Voice channel of the model strategy sets the language model for calls.
Set them up before the first test call. The primary language of the AI agent needs speech settings, or a Moveo default for your region. See Default settings.
Step 6: Activate the integration
Review your configuration, turn on the toggle in the Telnyx Voice card at the top of the panel, and select Save to apply your changes. The Account section reports Active once the integration is live.
Step 7: Route calls to an AI agent
The integration is now connected to Telnyx, but calls still need an AI agent to answer them. Create a rule for this integration as described in Deploy the AI agent to a channel, then place a test call.
Configuration options
Call settings
The configuration panel holds the call behavior of the integration:
Preferences controls whether Moveo stores voice conversations as call recordings on your account, and whether the AI agent starts the conversation with the initial welcome message instead of waiting for the caller to speak first. It also holds Noise suppression and Answering machine detection.
- Call recordings: see Call recording.
- Answering machine detection: see Answering machine detection.
- Campaign calls and the opening message: see Outbound calls.
The integration does not hold speech-to-text, text-to-speech, turn detection, or language model settings. Set the voice in the voice settings of the AI agent, and the language model in the Voice channel of its model strategy.
Noise suppression
Noise suppression reduces background noise in the caller's audio, which improves transcription accuracy at the cost of a little extra latency. It's off by default. In the Preferences card, select the Noise suppression checkbox, then choose the Provider:
- Moveo applies noise suppression on every voice integration. This is the default when you enable the feature.
- Telnyx Noise Suppression applies it on the Telnyx leg, before the audio reaches Moveo, and is available on Telnyx Voice only. Telnyx bills this separately, per direction of audio.
Select an Engine after you select a provider. For Moveo, choose GTCRN (the default) or Quail Voice Focus. For Telnyx Noise Suppression, choose the engine that fits your call. Denoiser suits most calls. The list describes what each engine does. See Telnyx's noise suppression guide.
Calls from your own dialer
Some teams place calls from their own dialer or PBX and bridge the answered call to Moveo over SIP. The dialer can put its own number in the SIP From field and send the customer's number in a custom header instead. Use SIP caller to tell Moveo where the dialer puts the customer.
To set it, open the integration, select Show advanced, and fill in Caller field in the SIP caller card:
| Value | Who the caller is | When the user's phone is saved |
|---|---|---|
| Empty (default) | The SIP from value that Telnyx sends | As for a call from a phone number. When Telnyx sends from as a plain number, Moveo saves it, even if it is the dialer's number. |
From | The SIP from value that Telnyx sends | As with an empty value. A SIP URI from with a +E.164 user part also gives a phone. |
An X- header name, for example X-Caller-ID | The value of that header | When the header value is a +E.164 number, for example +5511912345678 |
When Moveo saves the phone number, it also sets the user's country and time zone from it. The AI agent can then look up the customer by phone. Moveo does not save a header value or a SIP URI user part without the leading + as a phone. A national number can read as a number in another country.
When the dialer sends its own number in From, choose an X- header. Some calls have no such header, or a header longer than 256 characters. For these calls, Moveo identifies the caller by From and saves no phone number. This rule stops the dialer's own number from becoming the customer's phone. The header name match ignores case.
Telnyx passes the custom headers of an incoming SIP call to Moveo, and Moveo reads only X- headers from them.
A call from a phone number has no such header either, so with an X- header name it also gets no phone number. If the same number also receives phone calls, use a separate integration for the dialer. Campaign calls do not use this setting. To stop using it, clear Caller field and save.
Voice quality optimization
To ensure the best voice experience, structure your AI agent's responses using clear, concise language without complex formatting. Avoid special characters and symbols that don't translate well to speech, and use natural spoken language patterns. Consider adding pauses with punctuation for better pacing.
AI agent guidelines for voice
Voice conversations have unique characteristics compared to text-based chat. To improve your AI agent's performance in voice interactions, you can add specific guidelines that optimize for the auditory experience. For example, use shorter, more conversational responses, and avoid lists or complex structures that are hard to follow by ear. Confirm what the user said before you proceed, use verbal cues for transitions between topics, and give clear call-to-action statements.
Testing your integration
Test phone calls
Dial your Telnyx phone number and wait for the AI agent greeting. Test various conversation scenarios, verify proper call handling and termination, and check call quality and response timing.
Test outbound calls
If you plan to run campaigns, and especially if you configured a verified caller ID, run a campaign with a single contact to a phone you control. Confirm that the call connects and that the caller ID the recipient sees is the number you expect.
Key test scenarios
Make sure to validate call initiation and greeting, clear speech recognition, natural-sounding responses, handling of unclear input or silence, proper call termination, and transcription mismatches.
Troubleshooting
Connection issues
The integration doesn't verify: Confirm the API key is still active in the Telnyx portal, that the public key belongs to the same account, and that the account is funded and has voice enabled. Pretrial accounts cannot create the Call Control Application the integration needs, so you cannot configure the integration on one. See Account level.
You need to change the API key: You cannot change it after you save the integration. Delete the integration and create a new one with the new key.
Your number isn't in the list: The number must be in the Telnyx account that owns the API key and must be active in Telnyx, and only the first 250 active numbers are listed. Numbers shown under In use are already taken: detach a Telnyx number from its other connection in the Telnyx portal, or remove a verified caller ID from the other Moveo integration that holds it.
The Verified caller ID group is missing: Moveo lists Telnyx-owned numbers only when it cannot read your verified numbers from Telnyx. Confirm the numbers are verified in the Telnyx portal, then reopen the configuration panel.
Call handling issues
Calls aren't being answered: Verify the integration is active, and review the call in the Telnyx portal to confirm that it reached Telnyx. Check that the public key in Moveo matches the one in your Telnyx account, since a mismatch makes Moveo reject every webhook. If the voice API application Moveo created was renamed or repointed, delete and save the integration again so Moveo recreates it.
Outbound campaign calls fail to connect: This is the common symptom of dialing in-country mobile numbers from a verified caller ID, where the destination carrier screens the call. Use a Telnyx number in that market, or route the calls through your own SIP gateway. See Choose the caller ID for outbound calls.
Outbound calls are rejected because of the caller ID: The number must be in E.164 format (the international format, for example +12025551234), and you must register a number that you own elsewhere as a verified number in Telnyx before Moveo can present it.
AI agent not responding correctly: Test the AI agent in text mode first to verify the logic, and review the voice-specific guidelines. Check the logs for speech recognition errors, and verify that intent recognition works. Consider adding confirmation steps for critical information.
Audio quality issues
Speech recognition is inaccurate: Speech-to-text is fixed for the call and uses the settings of the primary language. In the AI agent voice settings, select a speech-to-text model for the primary language that hears every language of your callers. Turn on noise suppression for better accuracy, and review the recognition sensitivity settings.
Voice responses sound unnatural: Review your AI agent's response formatting, and remove special characters and formatting that don't translate to speech. Change the voice, the model, or the speed in the AI agent voice settings. Simplify complex responses for better verbal delivery, and add punctuation for natural pauses and pacing.
Audio delays or lag: Review Telnyx's service status for any issues, and check whether the callers reporting the delay are in a region far from your Moveo deployment.
Limitations
Platform limitations
Your Telnyx account level and plan set the call duration and concurrency limits, and that level also sets the destination countries that you can dial. The codecs that Telnyx supports set the audio format constraints. Accounts below the Verified level are capped and prepend an automated-call announcement, so they can't be used for production traffic.
Integration constraints
Each integration configuration supports one phone number, and that number is assigned to the connection Moveo creates while the integration exists. Verified caller IDs work for outbound calls only. Voice quality depends on the caller's connection and device, STT accuracy varies with accents and background noise, and complex multi-turn conversations may require optimization.
Best practices
Monitor call duration and implement time limits if needed for cost control. Provide clear voice prompts for better recognition. Have fallback options for unclear or failed recognition. Regularly review and optimize based on call analytics.
Resources
Telnyx documentation
- Voice API overview
- Mission Control Portal
- API reference
- Voice API pricing
- Account levels and upgrades
- Telnyx status
Moveo resources
Support
- Telnyx support
- Moveo support: support@moveo.ai
Next steps
Once your Telnyx Voice integration is active, optimize your AI agent with voice-specific guidelines, and test it with various scenarios and voice configurations. Monitor call analytics to find areas to improve, and adjust the AI agent voice settings based on user feedback. Configure fallback options for complex queries, and train your team to monitor and handle escalations.