Call Commands

Start Conversation Relay

Changed on

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

Request

  • Base URL: https://api.telnyx.com/v2
  • URL: https://api.telnyx.com/v2/calls/{call_control_id}/actions/conversation_relay_start
  • Auth: HTTP bearer

Path parameters

call_control_idstring required

Unique identifier and token for controlling the call

Request body

urlstring

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

dtmf_detectionboolean

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

conversation_relay_urlstring

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

conversation_relay_dtmf_detectionboolean

Enable DTMF detection for the relay session.

voicestring

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.
greetingstring

Text played when the relay session starts.

languagestring

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

transcriptionobject

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

client_statestring

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

command_idstring

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

tts_providerstring

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

providerstring

Structured voice provider. Must be supplied together with structured_provider.

structured_providerConversationRelayStructuredProvider

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

transcription_engine'Google' | 'Telnyx' | 'Deepgram' | 'Azure' | 'xAI' | 'AssemblyAI' | 'Speechmatics' | 'Soniox' | 'A' | 'B'

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.

interruptible'none' | 'any' | 'speech' | 'dtmf'

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.

interruptible_greeting'none' | 'any' | 'speech' | 'dtmf'

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.

custom_parametersobject

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 request

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

Response

Successful response upon starting Conversation Relay.

Example response

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

Changes

  • da303e40b51eRevision changes
    • breaking

      added subschema #1 to the request body allOf list

    • breaking

      removed subschema #1 subschema #2 subschema #3 from the request body anyOf list

    • info

      added the new optional request property ////

    • info

      added the new optional request property ////

    • info

      added the new optional request property ////

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property /

    • info

      added the new optional request property /

    • info

      added the new optional request property /

  • d8b8159753eeRevision changes
    • info

      added soniox discriminator mapping keys to the /// request property

    • info

      added soniox discriminator mapping keys to the // request property

    • info

      added soniox discriminator mapping keys to the request property

    • info

      added to the /// request property oneOf list

    • info

      added to the // request property oneOf list

    • info

      added to the request property oneOf list