# ConversationRelay widget

## Overview

The **ConversationRelay** widget connects a live voice call in a Studio flow to a WebSocket server (provided by you) using Twilio's [ConversationRelay](https://www.twilio.com/docs/voice/conversationrelay) capability. This enables real-time, bidirectional voice interactions without requiring you to manage speech-to-text (STT) or text-to-speech (TTS) directly.

Use this widget to orchestrate ConversationRelay sessions natively in Studio, eliminating the need to return custom TwiML. You retain full control over the conversational logic and infrastructure, including any large language model (LLM) integrations, which run outside of Twilio.

## How the ConversationRelay widget works

The **ConversationRelay** widget executes during an active voice call in a Studio Flow. When the widget runs:

* Studio initiates a ConversationRelay session.
* The live call is connected to the WebSocket server that you configure.
* ConversationRelay takes control of audio input and output for the duration of the session.
* Studio regains control of the call when the ConversationRelay session ends.

While the ConversationRelay session is active, the flow is paused.

During the call, caller speech, keypad (DTMF) input, interruptions, and system events can be delivered to the WebSocket server as structured messages. Likewise, the WebSocket server can stream text-to-speech incrementally to the caller. You can mark messages sent to the caller as interruptible or preemptible.

When the ConversationRelay session ends, control returns to Studio and downstream widgets continue executing.

## Prerequisites

Before using the ConversationRelay widget, you must:

* Host and operate a WebSocket server (WSS) that implements the ConversationRelay protocol. For more information, check out these resources:

  * Docs: [ConversationRelay onboarding](/docs/voice/conversationrelay/onboarding)
  * Blog post: [Set Up a Native Integration with Conversational Intelligence and ConversationRelay using Node.js](https://www.twilio.com/en-us/blog/native-integration-conversational-intelligence-conversationrelay-node)
  * Video: [Integrating ElevenLabs Voices into Twilio](https://youtu.be/5ci8h9hpNmA?si=XVAhuWpdFP1nZt8K)
  * Video: [Tips for building with Twilio ConversationRelay](https://youtu.be/Kllgzniq7qE?si=YkIH1pmNR7Ybsf8f)
* Handle inbound ConversationRelay events and send outbound WebSocket messages over the WebSocket connection.
* If you need dynamic, AI-driven responses: Integrate the WebSocket server with an LLM or other logic.

Studio doesn't provide a WebSocket server, and ConversationRelay doesn't integrate directly with any LLM providers.

## Configure ConversationRelay options

### WebSocket settings

**WebSocket URL**\
The secure WebSocket (`wss://`) endpoint that Studio connects to when starting the ConversationRelay session. This endpoint must point to a server capable of handling ConversationRelay messages. Studio does not provide this endpoint for you.

### Welcome greeting

**Welcome Greeting (optional)**\
Text that is spoken to the caller immediately when the ConversationRelay session begins, before any caller input is received.

### Custom parameters

**Custom Parameters**\
A set of key-value pairs sent to the WebSocket server when the session starts. These parameters allow Studio builders to pass contextual information, such as flow variables or customer metadata, to the external system managing the conversation.

### Voice and language controls

These settings control speech recognition and synthesis behavior for the ConversationRelay session:

* **Language Code**
* **TTS Provider**
* **Voice**
* **Speech Model**
* **Transcription Provider**

These options function similarly to voice and language settings in Studio's **Say/Play** widgets. However, they apply at the session level, rather than to individual prompts.

> \[!NOTE]
>
> If your workflow is subject to PCI, not all TTS and transcription providers are guaranteed to be PCI compliant. Refer to [Twilio's Responsibility Matrix](https://www.twilio.com/en-us/pci-compliance) for further information.

### AI hints

**AI Hints**\
A list of words or phrases used to improve speech recognition accuracy during the session. AI hints are useful for domain-specific terminology that may otherwise be misinterpreted by speech recognition systems.

## Outputs and transitions

The ConversationRelay widget exposes the following transitions:

* **Success**: The ConversationRelay session ended normally. This indicates that the external system explicitly ended the session.
* **Failed**: The session failed due to errors such as WebSocket connection issues, protocol errors, or an unexpected termination (for example, an outage or configuration problem).

These transitions allow you to define fallback behavior or escalation paths.

Any handoff data included in the **End session** message sent to the ConversationRelay session is available in the Studio context after the widget finishes executing. For example, a ConversationRelay widget called "run\_crelay\_1" will have this data available within `{{widgets.run\_crelay\_1.HandoffData}}`.

## More details about ConversationRelay

This widget provides a way to use the Twilio Voice `<ConversationRelay>` TwiML noun within Studio.

For protocol details, message formats, and supported events, see our [ConversationRelay docs](https://www.twilio.com/docs/voice/conversationrelay).