# Conversation Relay widget

## Overview

The **Conversation Relay** widget connects a live voice call in a Studio flow to a WebSocket server (provided by you) using Twilio's [Conversation Relay](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 Conversation Relay 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 Conversation Relay widget works

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

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

While the Conversation Relay 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 Conversation Relay session ends, control returns to Studio and downstream widgets continue executing.

## Prerequisites

Before using the Conversation Relay widget, you must:

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

  * Docs: [Conversation Relay onboarding](/docs/voice/conversationrelay/onboarding)
  * Blog post: [Set Up a Native Integration with Conversation Intelligence (classic) and Conversation Relay 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 Conversation Relay](https://youtu.be/Kllgzniq7qE?si=YkIH1pmNR7Ybsf8f)
* Handle inbound Conversation Relay 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 Conversation Relay doesn't integrate directly with any LLM providers.

## Configure Conversation Relay options

### WebSocket settings

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

### Welcome greeting

**Welcome Greeting (optional)**\
Text that is spoken to the caller immediately when the Conversation Relay 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 Conversation Relay 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 Conversation Relay widget exposes the following transitions:

* **Success**: The Conversation Relay 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 Conversation Relay session is available in the Studio context after the widget finishes executing. For example, a Conversation Relay widget called "run\_crelay\_1" will have this data available within `{{widgets.run\_crelay\_1.HandoffData}}`.

## More details about Conversation Relay

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 [Conversation Relay docs](https://www.twilio.com/docs/voice/conversationrelay).