Twilio Voice
Overview
The Twilio Voice integration enables your AI agent to handle voice conversations through phone calls and web-based calling. By connecting your Twilio 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 Twilio phone numbers and web-based calling for browser-to-AI conversations. 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 Twilio Voice integration, you'll need to configure both your Twilio account and your Moveo setup.
Twilio account
You'll need an active Twilio account with voice capabilities enabled and sufficient balance to cover voice call costs.
Subaccount (optional)
If you want to keep your Moveo voice usage separate from other Twilio services, you can create a subaccount. This is useful to isolate Moveo voice costs, phone numbers, and call logs from your other Twilio services.
Each subaccount gets its own Account SID and Auth Token. For instructions on creating a subaccount, see Twilio's subaccount guide.
If you have a dedicated Twilio account with no other services using it, you can use the main account directly; a subaccount is not required.
Account SID and Auth Token (region-specific)
Your Twilio credentials must come from the Twilio region that matches your Moveo deployment:
| Moveo deployment | Twilio region |
|---|---|
| Europe (EU) | Ireland (IE1) |
| United States (US) | US1 |
| Brazil (BR) | US1 |
Make sure you select the correct Twilio region. Credentials from the wrong region cause connectivity issues with Moveo.
Trial account limitations
Twilio trial accounts are restricted to the US1 region (see Twilio's free trial limitations). This affects customers whose Moveo deployment is in Europe (EU), which uses the Ireland (IE1) Twilio region:
- A trial account cannot connect to a Moveo deployment in the EU, because the IE1 region only becomes available after upgrading to a paid Twilio account.
- Trial accounts are also limited to a single Twilio phone number.
- You cannot change the region of an existing trial account by re-routing or re-purchasing a number.
If your Moveo deployment is in the EU, upgrade your Twilio account to a paid plan before configuring the integration. There is no workaround on a trial account.
Phone number (optional)
You can use a Twilio-provided number or a number you've ported to Twilio. If you don't configure a phone number, the integration handles web-based calls only.
A phone number is not required if you only plan to handle web calls. It becomes required when supporting incoming phone calls or when using the integration to call customers through campaigns.
Moveo account
You connect your AI agent to Twilio 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 Twilio Voice integration creates a bridge between callers and your Moveo AI agent. When a user initiates a call through your web application, Twilio establishes the connection and begins streaming 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 phone calls, the flow is similar. When someone dials your Twilio phone number, Twilio routes the call to Moveo where the same speech processing and response cycle occurs. The conversation continues until the caller hangs up, or the AI agent resolves the conversation.
When the AI agent resolves the conversation, the platform hangs up the call within a couple of seconds.
Reaching your AI agent
After you configure the integration, users can reach your AI agent in two ways:
Inbound calls: Customers can call your Twilio 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
A call ends in one of two ways, both controlled from the AI agent's workflow:
- 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. - Gate the
Handoveraction on call type if callers can also reach your AI agent through browser-based (Web) voice calls. Browser calls do not support handover.
Setup guide
Step 1: Prepare your Twilio credentials
- Log in to your Twilio Console. If you are using a subaccount, make sure you have switched to it.
- Navigate to Account > Keys & Credentials > API keys & tokens.
- From the region dropdown, select the Twilio region that matches your Moveo deployment (see the region table).
- Copy the Account SID and Auth Token displayed for that region.
Keep these credentials handy for the next step.
Step 2: Configure the integration in Moveo
Navigate to Connections in your Moveo account, select your environment, find the Twilio Voice integration card, and select Connect.
Step 3: Enter your Twilio account details
In the configuration panel, you'll see an Account section where you'll enter your credentials and optionally select a phone number:
Account SID: Your Twilio Account SID from the previous step (make sure these are the region-specific credentials)
Auth Token: Your Twilio Auth Token
Phone: This field appears after Moveo verifies your Account SID and Auth Token. Select a phone number to enable phone calls, or leave it set to "None" for web calls only. A number that another service uses, or that Twilio routes to a different region, shows as unavailable.
When no phone number is selected, the integration works exclusively for web calls. When you select a phone number, the integration handles both web calls and incoming phone calls to that number.
Step 4: 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 5: Activate the integration
Review your configuration, turn on the toggle in the Twilio 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.
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, which is off by default and reduces background noise in the caller's audio to improve transcription accuracy at the cost of a little extra latency, 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.
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 field | Never, for a SIP call |
From | The SIP From field | When the From user part is a +E.164 number, for example sip:+5511912345678@pbx.example.com |
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 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.
Twilio passes only X- headers from a SIP call to Moveo, so any other header name has no effect.
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.
For more about text normalization, see the ElevenLabs normalization guide.
Testing your integration
Test phone calls
If you configured a phone number, dial your Twilio 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.
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
Integration fails to connect to Twilio: Verify your Account SID and Auth Token are correct, check that your Twilio account is active and funded, ensure you have voice capabilities enabled, and review Twilio account status for any restrictions.
Phone number not working: Confirm the phone number is active in your Twilio account, check that the number has voice capabilities enabled, verify the number is properly configured in Moveo, and test the number directly in Twilio Console.
Phone number cannot be re-routed to the EU region: If the "Re-route" button is grayed out in the Twilio console, or the integration rejects a number that otherwise looks correctly configured, your Twilio account is likely a trial account. Trial accounts are locked to the US1 region and do not work with an EU Moveo deployment. Upgrade to a paid Twilio account and retry. See Trial account limitations.
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. Check the microphone quality and audio input levels, consider environment noise, 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: Check your internet connection stability, review Twilio's service status for any issues, verify your server response times are optimal, consider geographic latency factors, and check for webhook processing delays.
Call handling issues
Calls not being answered: Verify the integration is set to Active, check Twilio webhook configuration, review call logs in Twilio Console, confirm your environment is properly configured, and check for any error messages in Moveo logs.
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.
Phone issues
If the call does not connect to Moveo at all, make sure that the phone number is set up correctly in the Twilio console.
Limitations
Platform limitations
Your Twilio plan and pricing set the call duration limits. Your Twilio account tier sets the concurrent call limits. Voice availability varies by region due to geographic restrictions. The codecs that Twilio supports set the audio format constraints. Trial Twilio accounts do not work with EU Moveo deployments; see Trial account limitations.
Integration constraints
Each integration configuration supports one phone number. Voice quality depends on the caller's connection and device. STT accuracy varies with accents and background noise. Complex multi-turn conversations may require optimization.
Best practices
Monitor call duration and implement time limits if needed for cost control. Set up call queuing for high-volume scenarios. Provide clear voice prompts for better recognition. Have fallback options for unclear or failed recognition. Regularly review and optimize based on call analytics.
Resources
Twilio documentation
Moveo resources
Support
- Twilio Support
- Moveo support: support@moveo.ai
Next steps
Once your Twilio 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.