Start Conversation Relay

Start a Conversation Relay session on an active call. Conversation Relay connects the call audio to your WebSocket so your application can exchange realtime messages with the caller while Telnyx handles speech recognition and text-to-speech. Only one AI Assistant or Conversation Relay session can be active on a call at a time.

Expected Webhooks:

call.conversation.ended - Sent when the Conversation Relay session ends. If the customer WebSocket disconnects, the webhook payload reason is customer_disconnect.

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);

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)
response = client.calls.actions.start_conversation_relay(
    call_control_id="call_control_id",
)
print(response.data)

package main

import (
	"context"
	"fmt"

	"github.com/team-telnyx/telnyx-go"
	"github.com/team-telnyx/telnyx-go/option"
)

func main() {
	client := telnyx.NewClient(
		option.WithAPIKey("My API Key"),
	)
	response, err := client.Calls.Actions.StartConversationRelay(
		context.TODO(),
		"call_control_id",
		telnyx.CallActionStartConversationRelayParams{},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", response.Data)
}

package com.telnyx.sdk.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.calls.actions.ActionStartConversationRelayParams;
import com.telnyx.sdk.models.calls.actions.ActionStartConversationRelayResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        ActionStartConversationRelayResponse response = client.calls().actions().startConversationRelay("call_control_id");
    }
}

<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;

$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');

try {
  $response = $client->calls->actions->startConversationRelay(
    'call_control_id',
    assistant: [
      'dynamicVariables' => ['customer_id' => '12345', 'tier' => 'premium']
    ],
    clientState: 'aGF2ZSBhIG5pY2UgZGF5ID1d',
    commandID: '891510ac-f3e4-11e8-af5b-de00688a4901',
    conversationRelayDtmfDetection: true,
    conversationRelaySettings: [
      'url' => 'wss://example.com/conversation-relay',
      'dtmfDetection' => true,
      'interruptible' => 'speech',
      'interruptibleGreeting' => 'dtmf',
      'languages' => [
        [
          'language' => 'en-US',
          'speechModel' => 'nova-3',
          'transcriptionEngine' => 'Deepgram',
          'transcriptionEngineConfig' => ['transcription_model' => 'bar'],
          'transcriptionProvider' => 'Deepgram',
          'ttsProvider' => 'telnyx',
          'voice' => 'Telnyx.KokoroTTS.af',
          'voiceSettings' => [
            'type' => 'elevenlabs', 'apiKeyRef' => 'my_elevenlabs_api_key'
          ],
        ],
      ],
    ],
    conversationRelayURL: 'wss://example.com/conversation-relay',
    customParameters: ['customer_id' => 'bar'],
    dtmfDetection: true,
    greeting: 'Hi! Ask me anything!',
    interruptible: 'speech',
    interruptibleGreeting: 'dtmf',
    interruptionSettings: [
      'enable' => true,
      'interruptible' => 'speech',
      'interruptibleGreeting' => 'speech',
      'welcomeGreetingInterruptible' => 'speech',
    ],
    language: 'en-US',
    languages: [
      [
        'language' => 'en-US',
        'speechModel' => 'nova-3',
        'transcriptionEngine' => 'Deepgram',
        'transcriptionEngineConfig' => ['transcription_model' => 'bar'],
        'transcriptionProvider' => 'Deepgram',
        'ttsProvider' => 'telnyx',
        'voice' => 'Telnyx.KokoroTTS.af',
        'voiceSettings' => [
          'type' => 'elevenlabs', 'apiKeyRef' => 'my_elevenlabs_api_key'
        ],
      ],
    ],
    provider: 'elevenlabs',
    structuredProvider: ['voice_id' => 'bar', 'model_id' => 'bar'],
    transcription: ['foo' => 'bar'],
    transcriptionEngine: 'Google',
    transcriptionEngineConfig: [
      'transcription_model' => 'bar',
      'interim_results' => 'bar',
      'keywords_boosting' => 'bar',
    ],
    ttsProvider: 'telnyx',
    url: 'wss://example.com/conversation-relay',
    voice: 'Telnyx.KokoroTTS.af',
    voiceSettings: ['type' => 'telnyx', 'voiceSpeed' => 1],
  );

  var_dump($response);
} catch (APIException $e) {
  echo $e->getMessage();
}

curl --request POST \
  --url https://api.telnyx.com/v2/calls/{call_control_id}/actions/conversation_relay_start \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "wss://example.com/conversation-relay",
  "dtmf_detection": true,
  "interruptible": "speech",
  "interruptible_greeting": "dtmf",
  "greeting": "Hi! Ask me anything!",
  "voice": "Telnyx.KokoroTTS.af",
  "tts_provider": "telnyx",
  "voice_settings": {
    "type": "telnyx"
  },
  "language": "en-US",
  "languages": [
    {
      "language": "en-US",
      "tts_provider": "telnyx",
      "voice": "Telnyx.KokoroTTS.af",
      "transcription_engine": "Deepgram",
      "transcription_engine_config": {
        "transcription_model": "deepgram/nova-3"
      }
    }
  ],
  "custom_parameters": {
    "customer_id": "12345"
  }
}
'

{
  "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. A WebSocket URL is required: provide it 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.

conversation_relay_settings

Conversation Relay Settings · object

conditionally required

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.

Show child attributes

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" }
    }
  ]
}

url

string

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"

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.<VoiceId> (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, Inworld.TTS2.Loretta). Supported models: Mini, Max, TTS2.
Fish Audio: Use FishAudio.<ModelId>.<VoiceId> (e.g., FishAudio.s2.1-pro.<reference_id>). Supported models: s2.1-pro, s2-pro, s1. VoiceId is a Fish Voice-Library reference ID.
Soniox: Use Soniox.<ModelId>.<VoiceId> (e.g., Soniox.tts-rt-v2.Emma). Supported model: tts-rt-v2. Browse the catalog via the Voices API. Every voice speaks all supported languages; set language to the two-letter ISO 639-1 code of the text, for example it. SSML is not supported. Use voice_settings to configure speed (0.7 to 1.3) and reduce_silence.
xAI: Use xAI.<VoiceId> (e.g., xAI.eve). Available voices: eve, ara, rex, sal, leo.
Humain: Use Humain.<VoiceId> (e.g., Humain.sara-ar). Available voices: sara-en, abdulaziz-en, sara-ar, abdulaziz-ar, nourah-ar, abdullah-ar. Native Arabic (Saudi dialect) and English voices only — no ModelId segment.

Example:

"Telnyx.KokoroTTS.af"

voice_settings

ElevenLabs Voice Settings · object

The settings associated with the voice selected

Show child attributes

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.

Show child attributes

interruption_settings

Conversation Relay Interruption Settings · object

Settings for handling caller interruptions during Conversation Relay speech.

Show child attributes

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.

Show child attributes

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. With Deepgram Flux (deepgram/flux), interim_results, eot_threshold and eager_eot_threshold control the interim prompts and the eagerEndOfTurn and turnResumed frames sent to your WebSocket server.

Show child attributes

Example:

{
  "transcription_model": "deepgram/flux",
  "interim_results": true,
  "eager_eot_threshold": 0.5
}

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

Show child attributes

Example:

{
  "result": "ok",
  "conversation_relay_id": "d7e9c1d4-8b2a-4b8f-b3a7-9a671c9e9b0a"
}

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);

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)
response = client.calls.actions.start_conversation_relay(
    call_control_id="call_control_id",
)
print(response.data)

package main

import (
	"context"
	"fmt"

	"github.com/team-telnyx/telnyx-go"
	"github.com/team-telnyx/telnyx-go/option"
)

func main() {
	client := telnyx.NewClient(
		option.WithAPIKey("My API Key"),
	)
	response, err := client.Calls.Actions.StartConversationRelay(
		context.TODO(),
		"call_control_id",
		telnyx.CallActionStartConversationRelayParams{},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", response.Data)
}

package com.telnyx.sdk.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.calls.actions.ActionStartConversationRelayParams;
import com.telnyx.sdk.models.calls.actions.ActionStartConversationRelayResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        ActionStartConversationRelayResponse response = client.calls().actions().startConversationRelay("call_control_id");
    }
}

<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;

$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');

try {
  $response = $client->calls->actions->startConversationRelay(
    'call_control_id',
    assistant: [
      'dynamicVariables' => ['customer_id' => '12345', 'tier' => 'premium']
    ],
    clientState: 'aGF2ZSBhIG5pY2UgZGF5ID1d',
    commandID: '891510ac-f3e4-11e8-af5b-de00688a4901',
    conversationRelayDtmfDetection: true,
    conversationRelaySettings: [
      'url' => 'wss://example.com/conversation-relay',
      'dtmfDetection' => true,
      'interruptible' => 'speech',
      'interruptibleGreeting' => 'dtmf',
      'languages' => [
        [
          'language' => 'en-US',
          'speechModel' => 'nova-3',
          'transcriptionEngine' => 'Deepgram',
          'transcriptionEngineConfig' => ['transcription_model' => 'bar'],
          'transcriptionProvider' => 'Deepgram',
          'ttsProvider' => 'telnyx',
          'voice' => 'Telnyx.KokoroTTS.af',
          'voiceSettings' => [
            'type' => 'elevenlabs', 'apiKeyRef' => 'my_elevenlabs_api_key'
          ],
        ],
      ],
    ],
    conversationRelayURL: 'wss://example.com/conversation-relay',
    customParameters: ['customer_id' => 'bar'],
    dtmfDetection: true,
    greeting: 'Hi! Ask me anything!',
    interruptible: 'speech',
    interruptibleGreeting: 'dtmf',
    interruptionSettings: [
      'enable' => true,
      'interruptible' => 'speech',
      'interruptibleGreeting' => 'speech',
      'welcomeGreetingInterruptible' => 'speech',
    ],
    language: 'en-US',
    languages: [
      [
        'language' => 'en-US',
        'speechModel' => 'nova-3',
        'transcriptionEngine' => 'Deepgram',
        'transcriptionEngineConfig' => ['transcription_model' => 'bar'],
        'transcriptionProvider' => 'Deepgram',
        'ttsProvider' => 'telnyx',
        'voice' => 'Telnyx.KokoroTTS.af',
        'voiceSettings' => [
          'type' => 'elevenlabs', 'apiKeyRef' => 'my_elevenlabs_api_key'
        ],
      ],
    ],
    provider: 'elevenlabs',
    structuredProvider: ['voice_id' => 'bar', 'model_id' => 'bar'],
    transcription: ['foo' => 'bar'],
    transcriptionEngine: 'Google',
    transcriptionEngineConfig: [
      'transcription_model' => 'bar',
      'interim_results' => 'bar',
      'keywords_boosting' => 'bar',
    ],
    ttsProvider: 'telnyx',
    url: 'wss://example.com/conversation-relay',
    voice: 'Telnyx.KokoroTTS.af',
    voiceSettings: ['type' => 'telnyx', 'voiceSpeed' => 1],
  );

  var_dump($response);
} catch (APIException $e) {
  echo $e->getMessage();
}

curl --request POST \
  --url https://api.telnyx.com/v2/calls/{call_control_id}/actions/conversation_relay_start \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "wss://example.com/conversation-relay",
  "dtmf_detection": true,
  "interruptible": "speech",
  "interruptible_greeting": "dtmf",
  "greeting": "Hi! Ask me anything!",
  "voice": "Telnyx.KokoroTTS.af",
  "tts_provider": "telnyx",
  "voice_settings": {
    "type": "telnyx"
  },
  "language": "en-US",
  "languages": [
    {
      "language": "en-US",
      "tts_provider": "telnyx",
      "voice": "Telnyx.KokoroTTS.af",
      "transcription_engine": "Deepgram",
      "transcription_engine_config": {
        "transcription_model": "deepgram/nova-3"
      }
    }
  ],
  "custom_parameters": {
    "customer_id": "12345"
  }
}
'

{
  "data": {
    "result": "ok",
    "conversation_relay_id": "d7e9c1d4-8b2a-4b8f-b3a7-9a671c9e9b0a"
  }
}

Voice API Fundamentals

Voice Features

AI Capabilities

Tutorials

Regional & Restrictions

API Reference

For AI Agents

Start Conversation Relay

Authorizations

Path Parameters

Body

Response