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`).		-
`transcriptionProvider`	The speech-to-text provider (e.g., `deepgram`).		-
`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`
`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.		-
`transcriptionProvider`	The speech-to-text provider to use for this language (e.g., `google`, `telnyx`, `deepgram`).		-
`speechModel`	The speech recognition model to use for this language (e.g., `nova-2`).		-
`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>

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

​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

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