ConversationRelay

The <ConversationRelay> verb routes a call to a ConversationRelay service that provides voice interactions over a WebSocket connection. It provides speech-to-text transcription and allows requesting text-to-speech synthesis for the call over WebSocket.

Attributes

ATTRIBUTE	DESCRIPTION	OPTIONS	DEFAULT
`url`	The WebSocket URL of the conversation relay server.		-
`welcomeGreeting`	A greeting message to be spoken when the conversation relay session starts.		-
`voice`	The TTS voice to use (e.g., `Telnyx.Natural.abbie`, `Telnyx.NaturalHD.astra`).		-
`language`	The language for TTS and transcription (e.g., `en`, `fr`, `es`).		-
`transcriptionEngine`	Alias of `transcriptionProvider`: the speech-to-text provider. Any name that is not a built-in provider is the registered name of a community engine (add `apiKeyRef`).		-
`transcriptionProvider`	The speech-to-text provider (e.g., `deepgram`). Any name that is not a built-in provider is the registered name of a community engine (add `apiKeyRef`).		-
`speechModel`	The speech recognition model to use (e.g., `flux`).		-
`apiKeyRef`	Reference to the API key the speech-to-text engine is called with, an integration secret. Required with a community engine.		-
`interruptible`	Whether TTS playback can be interrupted by the caller. `true` is an alias for `any`, `false` is an alias for `none`.	`none`, `any`, `speech`, `dtmf`, `true`, `false`	`any`
`welcomeGreetingInterruptible`	Whether the welcome greeting can be interrupted by the caller. `true` is an alias for `any`, `false` is an alias for `none`.	`none`, `any`, `speech`, `dtmf`, `true`, `false`	`any`
`dtmfDetection`	Whether to enable DTMF detection during the conversation relay session.		`false`
`events`	A space-separated list of optional outbound WebSocket message streams to subscribe to. Recognized tokens are `speaker-events` (notifies your application about `agentSpeaking` and `clientSpeaking` events) and `tokens-played` (provides messages about the text just played over TTS). Tokens are case-insensitive and may be given in any order; unrecognized tokens are ignored. When omitted, none of these messages are sent. Example: `events="speaker-events tokens-played"`.		-
`partialPrompts`	When `true`, your application receives partial prompts while the caller is speaking: interim transcripts as `prompt` messages with `last: false`, an `eagerEndOfTurn` message when the caller has likely finished speaking, and a `turnResumed` message if the caller continues. Supported with Deepgram Flux (`speechModel="flux"`).		`false`
`backgroundAudioType`	The type of background audio to mix into the call during the conversation relay session. Must be set together with `backgroundAudioValue`; both must be present for background audio to apply.	`media_url`	-
`backgroundAudioValue`	The background audio source. For `media_url`, a URL pointing to an audio file (e.g., `https://example.com/hold-music.mp3`). Must be set together with `backgroundAudioType`; both must be present for background audio to apply.		-

Child verbs/nouns

NOUN/VERB	DESCRIPTION
`Language`	Configures a supported language with optional per-language voice and provider settings. Multiple `<Language>` elements can be specified to enable multilingual conversations.
`Parameter`	Custom key-value parameter passed to the WebSocket server as assistant dynamic variables.

Language Attributes

ATTRIBUTE	DESCRIPTION	OPTIONS	DEFAULT
`code`	The language code (e.g., `en`, `fr`, `es`).		-
`ttsProvider`	The text-to-speech provider to use for this language (e.g., `telnyx`, `google`).		-
`voice`	The voice to use for this language.		-
`transcriptionEngine`	Alias of `transcriptionProvider`: the speech-to-text provider to use for this language. Any name that is not a built-in provider is the registered name of a community engine (add `apiKeyRef`).		-
`transcriptionProvider`	The speech-to-text provider to use for this language (e.g., `google`, `telnyx`, `deepgram`). Any name that is not a built-in provider is the registered name of a community engine (add `apiKeyRef`).		-
`speechModel`	The speech recognition model to use for this language (e.g., `nova-2`).		-
`apiKeyRef`	Reference to the API key the speech-to-text engine of this language is called with, an integration secret. Required with a community engine, and not inherited from the verb.		-
`backgroundAudioType`	The type of background audio to mix into the call for this language. Must be set together with `backgroundAudioValue`; both must be present for background audio to apply.	`media_url`	-
`backgroundAudioValue`	The background audio source for this language. For `media_url`, a URL pointing to an audio file (e.g., `https://example.com/hold-music.mp3`). Must be set together with `backgroundAudioType`; both must be present for background audio to apply.		-

Parameter Attributes

ATTRIBUTE	DESCRIPTION	OPTIONS	DEFAULT
`name`	The name of the custom parameter.		-
`value`	The value of the custom parameter.		-

Examples

Basic usage with greeting and voice

<Response>
  <Connect>
    <ConversationRelay
      url="wss://myapp.example.com/ws"
      voice="Telnyx.Natural.abbie"
      language="en"
      transcriptionProvider="deepgram"
      welcomeGreeting="Hello! How can I help you today?"
    />
  </Connect>
</Response>

Multilingual with DTMF language selection

<Response>
  <Connect>
    <ConversationRelay
      url="wss://myapp.example.com/ws"
      voice="Telnyx.Natural.abbie"
      language="en"
      transcriptionProvider="deepgram"
      welcomeGreeting="Hello! I am your multilingual assistant. Press 1 for English, 2 for French, 3 for Spanish."
      welcomeGreetingInterruptible="any"
      interruptible="any"
      dtmfDetection="true"
    >
      <Language code="fr" voice="Telnyx.NaturalHD.astra" transcriptionProvider="google" />
      <Language code="es" voice="Telnyx.NaturalHD.albion" transcriptionProvider="telnyx" />
    </ConversationRelay>
  </Connect>
</Response>

Custom parameters

Custom parameters are passed to the WebSocket server as assistant dynamic variables.

<Response>
  <Connect>
    <ConversationRelay
      url="wss://myapp.example.com/ws"
      voice="Telnyx.Natural.abbie"
      language="en"
      transcriptionProvider="deepgram"
      welcomeGreeting="Hi there!"
    >
      <Parameter name="customer_id" value="12345" />
      <Parameter name="agent_mode" value="support" />
    </ConversationRelay>
  </Connect>
</Response>

Non-interruptible greeting

Use welcomeGreetingInterruptible="none" to ensure the greeting plays fully before accepting input.

<Response>
  <Connect>
    <ConversationRelay
      url="wss://myapp.example.com/ws"
      voice="Telnyx.Natural.abbie"
      language="en"
      transcriptionProvider="deepgram"
      welcomeGreeting="Please listen to this important message."
      welcomeGreetingInterruptible="none"
      interruptible="speech"
    />
  </Connect>
</Response>

Background audio

Mix a background audio track into the call by setting backgroundAudioType and backgroundAudioValue together. Both attributes must be present; media_url plays audio from a URL.

<Response>
  <Connect>
    <ConversationRelay
      url="wss://myapp.example.com/ws"
      voice="Telnyx.Natural.abbie"
      language="en"
      transcriptionProvider="deepgram"
      welcomeGreeting="Hello! How can I help you today?"
      backgroundAudioType="media_url"
      backgroundAudioValue="https://example.com/hold-music.mp3"
    />
  </Connect>
</Response>

Per-language background audio is also supported on <Language> elements:

<Response>
  <Connect>
    <ConversationRelay
      url="wss://myapp.example.com/ws"
      voice="Telnyx.Natural.abbie"
      language="en"
      transcriptionProvider="deepgram"
      welcomeGreeting="Hello! I am your multilingual assistant."
    >
      <Language
        code="fr"
        voice="Telnyx.NaturalHD.astra"
        transcriptionProvider="google"
        backgroundAudioType="media_url"
        backgroundAudioValue="https://example.com/hold-music-fr.mp3"
      />
      <Language
        code="es"
        voice="Telnyx.NaturalHD.albion"
        transcriptionProvider="telnyx"
        backgroundAudioType="media_url"
        backgroundAudioValue="https://example.com/hold-music-es.mp3"
      />
    </ConversationRelay>
  </Connect>
</Response>

Subscribing to agent-speech and token events

Use the events attribute to subscribe to optional outbound WebSocket messages. It is a space-separated list of the streams you want; when omitted, none of these messages are sent.

Token	Subscribes you to
`speaker-events`	`agentSpeaking` (on/off) and `clientSpeaking` (on/off) messages
`tokens-played`	`tokensPlayed` messages carrying the text just played over TTS

<Response>
  <Connect>
    <ConversationRelay
      url="wss://myapp.example.com/ws"
      voice="Telnyx.Natural.abbie"
      language="en"
      transcriptionProvider="deepgram"
      welcomeGreeting="Hi."
      events="speaker-events tokens-played"
    />
  </Connect>
</Response>

Your WebSocket server then receives these messages (server → your application):

{"type": "info", "name": "agentSpeaking", "value": "on"}
{"type": "info", "name": "tokensPlayed", "value": "Hi."}
{"type": "info", "name": "agentSpeaking", "value": "off"}
{"type": "info", "name": "clientSpeaking", "value": "on"}
{"type": "info", "name": "clientSpeaking", "value": "off"}

agentSpeaking brackets each agent turn (on at the start, off at true end-of-playout); clientSpeaking brackets caller speech.
tokensPlayed carries the text that was played over TTS.
Subscribe to either stream, both, or neither. events="speaker-events" sends only the speaking events; events="tokens-played" sends only the played-text messages.
Tokens are case-insensitive and unrecognized tokens are ignored.

Note: events is space-separated. Do not use commas — events="speaker-events,tokens-played" is treated as a single unrecognized token and no messages are sent.

Partial prompts

Set partialPrompts="true" to receive the caller’s speech while they are still talking, together with an early signal that their turn is likely over. Your application can start preparing a reply before the final prompt arrives.

<Response>
  <Connect>
    <ConversationRelay
      url="wss://myapp.example.com/ws"
      voice="Telnyx.Natural.abbie"
      language="en"
      transcriptionProvider="deepgram"
      speechModel="flux"
      welcomeGreeting="Hi."
      partialPrompts="true"
    />
  </Connect>
</Response>

While the caller speaks, your WebSocket server then receives the frames below.

Partial prompt frame

The transcript of the turn so far, sent as a prompt frame with last: false:

{
  "type": "prompt",
  "voicePrompt": "I would like to book a table",
  "lang": "en",
  "last": false
}

Eager end of turn frame

Sent when the caller has likely finished speaking. voicePrompt is the transcript the final prompt is expected to match, so you can start generating a reply:

{
  "type": "eagerEndOfTurn",
  "voicePrompt": "I would like to book a table for two",
  "lang": "en"
}

Turn resumed frame

Sent if the caller keeps talking after an eagerEndOfTurn. Discard any reply prepared for it:

{
  "type": "turnResumed"
}

The turn ends with a prompt frame with last: true. If its text matches the last eagerEndOfTurn, you can use the reply you prepared. Partial prompts are supported with Deepgram Flux (speechModel="flux").

Guides

Markup Language

API Reference

For AI Agents

ConversationRelay

Attributes

Child verbs/nouns

Language Attributes

Parameter Attributes

Examples

Basic usage with greeting and voice

Multilingual with DTMF language selection

Custom parameters

Non-interruptible greeting

Background audio

Subscribing to agent-speech and token events

Partial prompts

Partial prompt frame

Eager end of turn frame

Turn resumed frame

​Attributes

​Child verbs/nouns

​Language Attributes

​Parameter Attributes

​Examples

​Basic usage with greeting and voice

​Multilingual with DTMF language selection

​Custom parameters

​Non-interruptible greeting

​Background audio

​Subscribing to agent-speech and token events

​Partial prompts

​Partial prompt frame

​Eager end of turn frame

​Turn resumed frame

Attributes

Child verbs/nouns

Language Attributes

Parameter Attributes

Examples

Basic usage with greeting and voice

Multilingual with DTMF language selection

Custom parameters

Non-interruptible greeting

Background audio

Subscribing to agent-speech and token events

Partial prompts

Partial prompt frame

Eager end of turn frame

Turn resumed frame