--- "@context": https://schema.org "@type": TechArticle "@id": https://www.twilio.com/docs/voice/conversationrelay/onboarding#article headline: Onboarding description: Integrate Twilio Conversation Relay for AI agents and transcription use cases using Node.js or Python to add voice capabilities to applications. url: https://www.twilio.com/docs/voice/conversationrelay/onboarding inLanguage: en dateModified: 2026-09-25T18:57:30.000Z author: "@type": Organization name: Twilio Developer Education Team publisher: "@type": Organization name: Twilio --- # Onboarding Learn to integrate Twilio Conversation Relay by configuring a WebSocket server (`wss://`) and setting up a TwiML App in the Twilio Console to handle speech recognition and synthesis. You can use this guide to build AI agents and capture AI/ML transcriptions. See Related reference documentation to learn more about the `` elements used in this guide. [All Conversation Relay guides](/docs/voice/guides/by-feature-product#conversation-relay) ## Prerequisites Complete these prerequisite steps before starting the integration process: ### Set up your Twilio account Ensure you have a Twilio account set up and log into the [Twilio Console](https://www.twilio.com/console). ### Configure WebSocket server Set up a [WebSocket](/docs/glossary/what-are-websockets) server to handle communication with Conversation Relay. You can set up a WebSocket server using various frameworks and programming languages, such as [Node.js with Fastify](https://github.com/robinske/cr-demo/blob/main/server.js), [Python with FastAPI](https://github.com/rishabkumar7/cr-demo-python/blob/main/main.py), or others that support WebSocket protocols. **Note**: Ensure your WebSocket server is accessible via a `wss://` URL. #### WebSocket security with signature validation Conversation Relay includes an `X-Twilio-Signature` header in the initial WebSocket handshake request. This signature allows you to validate that requests are genuinely coming from Twilio, following the same verification mechanism used for standard Twilio webhooks. To validate this signature: 1. Extract the `X-Twilio-Signature` header from the incoming WebSocket connection request. 2. Use your Twilio auth token and the request URL to validate this signature. 3. Only accept connections with valid signatures to prevent spoofed requests. For detailed implementation guidance, refer to [Twilio's webhook security documentation](/docs/usage/webhooks/webhooks-security). ## Integrate Twilio with Conversation Relay Once you've completed the prerequisites, follow these steps to integrate your Twilio application with Conversation Relay. ### Configuration steps in the Twilio Console ## Twilio Console 1. In the Twilio Console, go to [**Communications** > **Voice** > **Settings** > **Privacy & Security**](https://1console.twilio.com/go?to=/account/__account__/us1/voice/settings/general-settings/privacy-security-settings). 2. Under **These features are subject to the predictive and generative AI/ML features addendum**, read and accept the terms to use Conversation Relay, and click **Save**.\ A confirmation message will appear indicating that the voice setting has been updated. 3. Go to [**Builder tools** > **TwiML host & config** > **TwiML apps**](https://1console.twilio.com/go?to=/account/__account__/us1/voice/twiml-apps). 4. Create a new TwiML App or select an existing one. 5. In the TwiML App settings, configure the Voice URL to point to your application's endpoint (for example, `https://your.example.com/voice`) where Twilio can retrieve the TwiML containing the `` instructions. 6. Save your changes. ## Legacy Console 1. Log in to your [Twilio Console](https://www.twilio.com/console). 2. Navigate to the **Voice** section, select **General** under **Settings**, and turn on the **Predictive and Generative AI/ML Features Addendum** in order to use Conversation Relay. 3. Navigate to the **Voice** section and select **TwiML Apps** under **Manage**. 4. Create a new TwiML App or select an existing one. 5. In the TwiML App settings, configure the Voice URL to point to your application's endpoint (for example, `https://your.example.com/voice`) where Twilio can retrieve the TwiML containing the `` instructions. 6. Save your changes. ### Configure Conversation Relay in your application > \[!WARNING] > > Ensure your WebSocket server is properly configured to handle incoming messages from Conversation Relay. If not, you may encounter connection errors. After configuring your TwiML App, update your application to handle Conversation Relay interactions: * Use the [`` TwiML noun](/docs/voice/twiml/connect/conversationrelay) to route calls to the [Conversation Relay service](/docs/voice/twiml/connect/conversationrelay). * Specify the WebSocket URL and any [additional attributes](/docs/voice/twiml/connect/conversationrelay#conversationrelay-attributes) needed for your use case. Example TwiML: ```xml ``` ## Develop your application with Conversation Relay Once you've integrated Conversation Relay, you can enhance your application with advanced voice capabilities. Consider the following features: ### Real-time speech recognition Use Conversation Relay's real-time speech recognition to process caller input and respond dynamically. ### Text-to-speech synthesis Use Conversation Relay to convert text responses into natural-sounding speech, providing a seamless conversational experience. For optimal speech quality, apply proper text normalization techniques (such as writing out numbers as words or spelling out abbreviations). See the [Conversation Relay documentation](/docs/voice/twiml/connect/conversationrelay#text-normalization-best-practices) for detailed text normalization best practices. ### Custom parameters Pass [custom parameters](/docs/voice/twiml/connect/conversationrelay#parameter-element) to Conversation Relay to tailor interactions based on specific use cases. ## Use cases for Conversation Relay with Twilio Voice This guide teaches the basics required for the following use cases: ### Build AI agents with Twilio Voice You can use this guide to connect real-time speech recognition and text-to-speech synthesis to conversational AI platforms. This enables you to build intelligent, human-like voice agents that understand caller intent and reply dynamically with natural-sounding speech. To learn more advanced features that you can use with AI agents, see [Voice AI agents](/docs/voice/guides/ai-agents). ### Create AI/ML transcriptions with Twilio Voice You can use this guide to stream live audio bi-directionally over WebSockets to your application server. This allows you to capture raw voice input for immediate speech-to-text processing, sentiment analysis, and downstream machine learning tasks. To learn more advanced features that you can use with AI or ML transcription, see [Voice AI/ML transcription](/docs/voice/guides/ai-ml-transcription). ## Result After following this guide, you have integrated your Twilio applications with the Conversation Relay service via a secure WebSocket connection. You can verify your setup by triggering an incoming call to your configured TwiML App number and checking your WebSocket server logs to confirm that the handshake with the valid `X-Twilio-Signature` header completes successfully and real-time audio messaging begins. ## Next steps Explore the following guides to build on what you've learned in this guide: * [Getting and sending WebSocket messages](/docs/voice/conversationrelay/websocket-messages): Understand the specific JSON message schemas exchanged during a live conversation. * [Picking a voice](/docs/voice/conversationrelay/voice-configuration): Customize the text-to-speech engine and language options for your conversational experiences. * [Integrate OpenAI with Twilio Voice Using Conversation Relay](https://twilio.com/en-us/blog/integrate-openai-twilio-voice-using-conversationrelay) * [Building Voice Bots with Twilio's Conversation Relay](https://twilio.com/en-us/blog/voice-ai-build-voice-bots-conversation-relay) * [Conversation Relay Application and Architecture for Voice AI Applications Built on AWS](https://twilio.com/en-us/blog/conversation-relay-aws-reference-architecture) ## Related reference documentation Find reference documentation for the topics on this page. * [`` TwiML noun](/docs/voice/conversationrelay/conversationrelay-noun) * [TwiML™ Voice: ``](/docs/voice/twiml/connect/conversationrelay) * [TwiML™ Voice: ``](/docs/voice/twiml/connect) * [TwiML™ for Programmable Voice](/docs/voice/twiml)