Skip to main content
POST
/
calls
/
{call_control_id}
/
actions
/
conversation_relay_start
JavaScript
import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

const response = await client.calls.actions.startConversationRelay('call_control_id');

console.log(response.data);
{ "data": { "result": "ok", "conversation_relay_id": "d7e9c1d4-8b2a-4b8f-b3a7-9a671c9e9b0a" } }

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
call_control_id
string
required

Unique identifier and token for controlling the call

Body

application/json

Conversation Relay start request

Start a Conversation Relay session. You may provide the WebSocket URL as url, conversation_relay_url, or conversation_relay_settings.url; top-level values take precedence over nested settings. Use transcription_engine and transcription_engine_config for speech-to-text configuration; the transcription object is not supported.

​
url
string
required

Public alias for conversation_relay_url. Must start with ws:// or wss://. If both are present, this value wins.

Pattern: ^wss?://
Example:

"wss://example.com/conversation-relay"

​
conversation_relay_settings
Conversation Relay Settings · object

Conversation Relay connection settings. This object can provide url, dtmf_detection, interruptible, interruptible_greeting, and languages. Top-level aliases override nested values when both are present.

Example:
{
  "url": "wss://example.com/conversation-relay",
  "dtmf_detection": true,
  "interruptible": "speech",
  "interruptible_greeting": "dtmf",
  "languages": [
    {
      "language": "en-US",
      "tts_provider": "telnyx",
      "voice": "Telnyx.KokoroTTS.af",
      "transcription_engine": "Deepgram",
      "transcription_engine_config": { "transcription_model": "deepgram/nova-3" }
    }
  ]
}
​
dtmf_detection
boolean
default:false

Public alias for conversation_relay_dtmf_detection. If both are present, this value wins.

Example:

true

​
conversation_relay_url
string

WebSocket URL for your Conversation Relay server. Must start with ws:// or wss://.

Pattern: ^wss?://
Example:

"wss://example.com/conversation-relay"

​
conversation_relay_dtmf_detection
boolean
default:false

Enable DTMF detection for the relay session.

Example:

true

​
voice
string
default:Telnyx.KokoroTTS.af

The voice to be used by the voice assistant. Currently we support ElevenLabs, Telnyx and AWS voices.

Supported Providers:

  • AWS: Use AWS.Polly.<VoiceId> (e.g., AWS.Polly.Joanna). For neural voices, which provide more realistic, human-like speech, append -Neural to the VoiceId (e.g., AWS.Polly.Joanna-Neural). Check the available voices for compatibility.
  • Azure: Use `Azure.. (e.g. Azure.en-CA-ClaraNeural, Azure.en-CA-LiamNeural, Azure.en-US-BrianMultilingualNeural, Azure.en-US-Ava:DragonHDLatestNeural. For a complete list of voices, go to Azure Voice Gallery.)
  • ElevenLabs: Use ElevenLabs.<ModelId>.<VoiceId> (e.g., ElevenLabs.BaseModel.John). The ModelId part is optional. To use ElevenLabs, you must provide your ElevenLabs API key as an integration secret under "voice_settings": {"api_key_ref": "<secret_id>"}. See integration secrets documentation for details. Check available voices.
  • Telnyx: Use Telnyx.<model_id>.<voice_id>
  • Inworld: Use Inworld.<ModelId>.<VoiceId> (e.g., Inworld.Mini.Loretta, Inworld.Max.Oliver). Supported models: Mini, Max.
  • xAI: Use xAI.<VoiceId> (e.g., xAI.eve). Available voices: eve, ara, rex, sal, leo.
Example:

"Telnyx.KokoroTTS.af"

​
voice_settings
ElevenLabs Voice Settings · object

The settings associated with the voice selected

​
greeting
string

Text played when the relay session starts.

Example:

"Hi! Ask me anything!"

​
language
string
default:en

Default language for the relay session. This value is used for both text-to-speech and speech recognition.

Example:

"en-US"

​
languages
Conversation Relay Language · object[]

Per-language TTS and transcription settings.

​
interruption_settings
Conversation Relay Interruption Settings · object

Settings for handling caller interruptions during Conversation Relay speech.

​
transcription
object
deprecated

Not supported for Conversation Relay start requests. Use transcription_engine and transcription_engine_config instead.

​
assistant
Conversation Relay Custom Parameters · object

Custom parameters for the Conversation Relay session. Pass key-value data as assistant.dynamic_variables to make it available to the relay session.

​
client_state
string

Use this field to add state to subsequent webhooks. It must be a valid Base-64 encoded string.

Example:

"aGF2ZSBhIG5pY2UgZGF5ID1d"

​
command_id
string

Use this field to avoid duplicate commands. Telnyx will ignore any command with the same command_id for the same call_control_id.

Example:

"891510ac-f3e4-11e8-af5b-de00688a4901"

​
tts_provider
string

Text-to-speech provider. If omitted, Telnyx derives it from voice or provider.

Example:

"telnyx"

​
provider
string

Structured voice provider. Must be supplied together with structured_provider.

Example:

"elevenlabs"

​
structured_provider
Conversation Relay Structured Provider · object

Provider-specific structured voice settings. Must be supplied together with provider; Telnyx sends the value as the nested provider configuration for Conversation Relay.

Example:
{
  "voice_id": "voice-id",
  "model_id": "Default"
}
​
transcription_engine
enum<string>
default:Google

Engine to use for speech recognition. Legacy values A - Google, B - Telnyx are supported for backward compatibility. For Conversation Relay, use this field with transcription_engine_config; the transcription object is not supported.

Available options:
Google,
Telnyx,
Deepgram,
Azure,
xAI,
AssemblyAI,
Speechmatics,
Soniox,
A,
B
Example:

"Google"

​
transcription_engine_config
Conversation Relay Transcription Engine Config · object

Engine-specific transcription settings for Conversation Relay. This accepts the same provider-specific options used by the Call Transcription Start command, such as transcription_model, without requiring the engine discriminator to be repeated inside this object.

Example:
{
  "transcription_model": "deepgram/nova-3",
  "interim_results": true,
  "keywords_boosting": { "telnyx": 2 }
}
​
interruptible
enum<string>
default:any

Controls when caller input can interrupt assistant speech. any allows speech or DTMF interruptions; none disables interruptions; speech allows speech only; dtmf allows DTMF only.

Available options:
none,
any,
speech,
dtmf
Example:

"speech"

​
interruptible_greeting
enum<string>
default:any

Controls when caller input can interrupt assistant speech. any allows speech or DTMF interruptions; none disables interruptions; speech allows speech only; dtmf allows DTMF only.

Available options:
none,
any,
speech,
dtmf
Example:

"speech"

​
custom_parameters
object

Custom key-value parameters forwarded to the relay session as assistant.dynamic_variables. If assistant.dynamic_variables is also present, these values are merged in.

Example:
{ "customer_id": "12345" }

Response

Successful response upon starting Conversation Relay.

​
data
Call Control Command Result With Conversation Relay ID · object
Example:
{
  "result": "ok",
  "conversation_relay_id": "d7e9c1d4-8b2a-4b8f-b3a7-9a671c9e9b0a"
}