> ## Documentation Index > Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt > Use this file to discover all available pages before exploring further. # ConversationRelay WebSocket channel > Single bidirectional channel carrying all ConversationRelay messages. Telnyx-to-customer frames: setup, prompt, dtmf, interrupt, error. Customer-to-Telnyx frames: text, play, sendDigits, language, end. ## AsyncAPI ````yaml https://telnyx-openapi-ng.s3.us-east-1.amazonaws.com/conversation-relay/conversation-relay.yml conversation-relay-websocket id: conversation-relay-websocket title: ConversationRelay WebSocket channel description: | Single bidirectional channel carrying all ConversationRelay messages. Telnyx-to-customer frames: setup, prompt, dtmf, interrupt, error. Customer-to-Telnyx frames: text, play, sendDigits, language, end. servers: - id: customer-conversation-relay-websocket protocol: wss host: yourdomain.com bindings: - protocol: ws version: 0.1.0 value: {} schemaProperties: [] variables: [] address: / parameters: [] bindings: [] operations: - &ref_7 id: receiveTelnyxEvents title: Receive ConversationRelay events from Telnyx description: >- Telnyx sends setup, transcription prompt, DTMF, interrupt, and error frames to the customer's WebSocket server. type: receive messages: - &ref_9 id: telnyxSetup contentType: application/json payload: - name: Setup Frame description: > First frame Telnyx sends after the WebSocket connects. Identifies the relay session, call, and any custom parameters configured on the assistant. type: object properties: - name: type type: string description: setup required: true - name: sessionId type: string description: Unique identifier for this ConversationRelay session. required: true - name: accountSid type: string description: Telnyx user/account identifier for the call. required: true - name: callSid type: string description: Telnyx call identifier (typically equal to `callControlId`). required: true - name: callControlId type: string description: Telnyx Call Control ID for the underlying call. required: true - name: callSessionId type: string description: Telnyx call session ID. required: true - name: callLegId type: string description: Telnyx call leg ID. required: true - name: from type: string description: Caller number or SIP URI. required: true - name: to type: string description: Callee number or SIP URI. required: true - name: direction type: string description: Call direction. enumValues: - inbound - outbound required: true - name: callerName type: string description: Caller display name, or an empty string when unknown. required: true - name: callStatus type: string description: >- Call status at the moment ConversationRelay starts. Typically `active`. required: true - name: customParameters type: object description: >- Custom parameters configured for the call, keyed by parameter name. required: true headers: [] jsonPayloadSchema: type: object additionalProperties: false required: - type - sessionId - accountSid - callSid - callControlId - callSessionId - callLegId - from - to - direction - callerName - callStatus - customParameters properties: type: type: string const: setup x-parser-schema-id: sessionId: type: string description: Unique identifier for this ConversationRelay session. x-parser-schema-id: accountSid: type: string description: Telnyx user/account identifier for the call. x-parser-schema-id: callSid: type: string description: Telnyx call identifier (typically equal to `callControlId`). x-parser-schema-id: callControlId: type: string description: Telnyx Call Control ID for the underlying call. x-parser-schema-id: callSessionId: type: string format: uuid description: Telnyx call session ID. x-parser-schema-id: callLegId: type: string format: uuid description: Telnyx call leg ID. x-parser-schema-id: from: type: string description: Caller number or SIP URI. x-parser-schema-id: to: type: string description: Callee number or SIP URI. x-parser-schema-id: direction: type: string description: Call direction. enum: - inbound - outbound x-parser-schema-id: callerName: type: string description: Caller display name, or an empty string when unknown. x-parser-schema-id: callStatus: type: string description: >- Call status at the moment ConversationRelay starts. Typically `active`. x-parser-schema-id: customParameters: type: object description: >- Custom parameters configured for the call, keyed by parameter name. additionalProperties: type: string x-parser-schema-id: x-parser-schema-id: x-parser-schema-id: SetupFrame title: Setup Frame description: > First frame Telnyx sends after the WebSocket connects. Identifies the relay session, call, and any custom parameters configured on the assistant. example: |- { "type": "setup", "sessionId": "7a7e6a4f-1d44-4f0c-b5d4-9f9bf3a5c1f2", "accountSid": "1f1a8b6f-1234-4abc-9def-1234567890ab", "callSid": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ", "callControlId": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ", "callSessionId": "ff55a038-6f5d-11ef-9692-02420aeffb1f", "callLegId": "428c31b6-7af4-4b6f-92e7-7a7e6a4f1d44", "from": "+13122010094", "to": "+13122123456", "direction": "inbound", "callerName": "", "callStatus": "active", "customParameters": { "customer_id": "customer_123" } } bindings: [] extensions: - id: x-parser-unique-object-id value: telnyxSetup - &ref_10 id: telnyxPrompt contentType: application/json payload: - name: Prompt Frame description: > Transcription of caller speech. Sent repeatedly during an utterance — `last: false` marks a partial, `last: true` marks the final transcript for that utterance. type: object properties: - name: type type: string description: prompt required: true - name: voicePrompt type: string description: Caller speech transcribed to text. required: true - name: lang type: string description: BCP-47 language tag (e.g. `en`, `en-US`). required: true - name: last type: boolean description: >- `true` if this is the final transcript for the utterance, `false` for a partial. required: true headers: [] jsonPayloadSchema: type: object additionalProperties: false required: - type - voicePrompt - lang - last properties: type: type: string const: prompt x-parser-schema-id: voicePrompt: type: string description: Caller speech transcribed to text. x-parser-schema-id: lang: &ref_2 type: string minLength: 1 description: BCP-47 language tag (e.g. `en`, `en-US`). x-parser-schema-id: LanguageCode last: type: boolean description: >- `true` if this is the final transcript for the utterance, `false` for a partial. x-parser-schema-id: x-parser-schema-id: PromptFrame title: Prompt Frame description: > Transcription of caller speech. Sent repeatedly during an utterance — `last: false` marks a partial, `last: true` marks the final transcript for that utterance. example: |- { "type": "prompt", "voicePrompt": "hello there", "lang": "en", "last": false } bindings: [] extensions: - id: x-parser-unique-object-id value: telnyxPrompt - &ref_11 id: telnyxDtmf contentType: application/json payload: - name: DTMF Frame description: Sent when a caller pressed a DTMF digit. type: object properties: - name: type type: string description: dtmf required: true - name: digit type: string description: DTMF digit detected on the call. enumValues: - '0' - '1' - '2' - '3' - '4' - '5' - '6' - '7' - '8' - '9' - '*' - '#' - A - B - C - D required: true headers: [] jsonPayloadSchema: type: object additionalProperties: false required: - type - digit properties: type: type: string const: dtmf x-parser-schema-id: digit: type: string description: DTMF digit detected on the call. enum: - '0' - '1' - '2' - '3' - '4' - '5' - '6' - '7' - '8' - '9' - '*' - '#' - A - B - C - D x-parser-schema-id: x-parser-schema-id: DtmfFrame title: DTMF Frame description: Sent when a caller pressed a DTMF digit. example: |- { "type": "dtmf", "digit": "1" } bindings: [] extensions: - id: x-parser-unique-object-id value: telnyxDtmf - &ref_12 id: telnyxInterrupt contentType: application/json payload: - name: Interrupt Frame description: >- Sent when the caller interrupts (barges in over) ongoing TTS playback. type: object properties: - name: type type: string description: interrupt required: true - name: utteranceUntilInterrupt type: string description: >- The portion of the spoken utterance that was already played to the caller before the interrupt occurred. required: true - name: durationUntilInterruptMs type: integer description: Milliseconds of speech played before the interrupt. required: true headers: [] jsonPayloadSchema: type: object additionalProperties: false required: - type - utteranceUntilInterrupt - durationUntilInterruptMs properties: type: type: string const: interrupt x-parser-schema-id: utteranceUntilInterrupt: type: string description: >- The portion of the spoken utterance that was already played to the caller before the interrupt occurred. x-parser-schema-id: durationUntilInterruptMs: type: integer minimum: 0 description: Milliseconds of speech played before the interrupt. x-parser-schema-id: x-parser-schema-id: InterruptFrame title: Interrupt Frame description: Sent when the caller interrupts (barges in over) ongoing TTS playback. example: |- { "type": "interrupt", "utteranceUntilInterrupt": "Welcome to Telnyx, how can I help", "durationUntilInterruptMs": 1820 } bindings: [] extensions: - id: x-parser-unique-object-id value: telnyxInterrupt - &ref_13 id: telnyxError contentType: application/json payload: - name: Error Frame description: > Sent by Telnyx when a customer-sent frame is invalid or another error occurs. The connection may be closed after this frame (after 10 consecutive invalid frames, it will be). type: object properties: - name: type type: string description: error required: true - name: description type: string description: Human-readable error description. required: true headers: [] jsonPayloadSchema: type: object additionalProperties: false required: - type - description properties: type: type: string const: error x-parser-schema-id: description: type: string description: Human-readable error description. x-parser-schema-id: x-parser-schema-id: ErrorFrame title: Error Frame description: > Sent by Telnyx when a customer-sent frame is invalid or another error occurs. The connection may be closed after this frame (after 10 consecutive invalid frames, it will be). example: |- { "type": "error", "description": "Invalid message: unknown type: foo" } bindings: [] extensions: - id: x-parser-unique-object-id value: telnyxError bindings: [] extensions: &ref_6 - id: x-parser-unique-object-id value: conversation-relay-websocket - &ref_8 id: sendClientCommands title: Send commands back to Telnyx description: >- The customer's WebSocket server sends text, play, sendDigits, language, and end frames to drive the call. type: send messages: - &ref_14 id: clientText contentType: application/json payload: - name: Text Frame description: > Customer-to-Telnyx frame containing text to be spoken back to the caller via TTS. For streaming LLM token chunks: send each chunk as a `text` frame with `last: false` (or omit `last` — it defaults to `false`). Send `last: true` to finalize the turn. **Important:** Omitting `last` defaults to `false`. A customer finalizing a turn must send `last: true` explicitly, otherwise Telnyx will keep waiting for more tokens. type: object properties: - name: type type: string description: text required: true - name: token type: string description: Text fragment to be spoken back to the caller. required: true - name: last type: boolean description: >- `true` finalizes the turn; `false` (the default when omitted) means more tokens will follow. required: false - name: interruptible type: &ref_0 - boolean - 'null' description: >- Overrides the call's `interruptible` setting for this fragment. Omit (or send `null`) to inherit. required: false - name: preemptible type: &ref_1 - boolean - 'null' description: >- Overrides the call's `preemptible` setting for this fragment. Omit (or send `null`) to inherit. required: false - name: lang type: string description: Overrides the TTS language for this fragment. required: false headers: [] jsonPayloadSchema: type: object additionalProperties: false required: - type - token properties: type: type: string const: text x-parser-schema-id: token: type: string description: Text fragment to be spoken back to the caller. x-parser-schema-id: last: type: boolean default: false description: >- `true` finalizes the turn; `false` (the default when omitted) means more tokens will follow. x-parser-schema-id: interruptible: type: *ref_0 description: >- Overrides the call's `interruptible` setting for this fragment. Omit (or send `null`) to inherit. x-parser-schema-id: preemptible: type: *ref_1 description: >- Overrides the call's `preemptible` setting for this fragment. Omit (or send `null`) to inherit. x-parser-schema-id: lang: allOf: - *ref_2 description: Overrides the TTS language for this fragment. x-parser-schema-id: x-parser-schema-id: TextFrame title: Text Frame description: > Customer-to-Telnyx frame containing text to be spoken back to the caller via TTS. For streaming LLM token chunks: send each chunk as a `text` frame with `last: false` (or omit `last` — it defaults to `false`). Send `last: true` to finalize the turn. **Important:** Omitting `last` defaults to `false`. A customer finalizing a turn must send `last: true` explicitly, otherwise Telnyx will keep waiting for more tokens. example: |- { "type": "text", "token": "Hello", "last": false } bindings: [] extensions: - id: x-parser-unique-object-id value: clientText - &ref_15 id: clientPlay contentType: application/json payload: - name: Play Frame description: >- Customer-to-Telnyx frame requesting Telnyx to play an audio file URL into the call. type: object properties: - name: type type: string description: play required: true - name: source type: string description: URL of the audio file to play. Must be non-empty. required: true - name: loop type: integer description: >- Number of times to play the file. `0` means loop forever (until interrupted or session ends). required: false - name: interruptible type: &ref_3 - boolean - 'null' description: >- Overrides the call's `interruptible` setting for this playback. Omit (or send `null`) to inherit. required: false - name: preemptible type: &ref_4 - boolean - 'null' description: >- Overrides the call's `preemptible` setting for this playback. Omit (or send `null`) to inherit. required: false headers: [] jsonPayloadSchema: type: object additionalProperties: false required: - type - source properties: type: type: string const: play x-parser-schema-id: source: type: string minLength: 1 description: URL of the audio file to play. Must be non-empty. x-parser-schema-id: loop: type: integer minimum: 0 maximum: 100 default: 1 description: >- Number of times to play the file. `0` means loop forever (until interrupted or session ends). x-parser-schema-id: interruptible: type: *ref_3 description: >- Overrides the call's `interruptible` setting for this playback. Omit (or send `null`) to inherit. x-parser-schema-id: preemptible: type: *ref_4 description: >- Overrides the call's `preemptible` setting for this playback. Omit (or send `null`) to inherit. x-parser-schema-id: x-parser-schema-id: PlayFrame title: Play Frame description: >- Customer-to-Telnyx frame requesting Telnyx to play an audio file URL into the call. example: |- { "type": "play", "source": "https://example.com/audio/welcome.mp3" } bindings: [] extensions: - id: x-parser-unique-object-id value: clientPlay - &ref_16 id: clientSendDigits contentType: application/json payload: - name: Send Digits Frame description: > Customer-to-Telnyx frame requesting Telnyx to send DTMF digits on the call. Valid characters: `0`-`9`, `A`-`D`, `w` or `W` (pause), `#`, `*`. type: object properties: - name: type type: string description: sendDigits required: true - name: digits type: string description: >- DTMF digit string. Allowed characters: `0`-`9`, `A`-`D`, `w` or `W` (half-second pause), `#`, `*`. required: true headers: [] jsonPayloadSchema: type: object additionalProperties: false required: - type - digits properties: type: type: string const: sendDigits x-parser-schema-id: digits: type: string minLength: 1 pattern: ^[0-9A-DwW#*]+$ description: >- DTMF digit string. Allowed characters: `0`-`9`, `A`-`D`, `w` or `W` (half-second pause), `#`, `*`. x-parser-schema-id: x-parser-schema-id: SendDigitsFrame title: Send Digits Frame description: > Customer-to-Telnyx frame requesting Telnyx to send DTMF digits on the call. Valid characters: `0`-`9`, `A`-`D`, `w` or `W` (pause), `#`, `*`. example: |- { "type": "sendDigits", "digits": "1234#" } bindings: [] extensions: - id: x-parser-unique-object-id value: clientSendDigits - &ref_17 id: clientLanguage contentType: application/json payload: - name: Language Frame description: > Customer-to-Telnyx frame requesting a language change mid-session. At least one of `ttsLanguage` (output TTS language) and `transcriptionLanguage` (input STT language) must be provided. type: object properties: - name: type type: string description: language required: true - name: ttsLanguage type: string description: New TTS (output) language for the session. required: false - name: transcriptionLanguage type: string description: New transcription (input) language for the session. required: false headers: [] jsonPayloadSchema: type: object additionalProperties: false required: - type anyOf: - required: - ttsLanguage x-parser-schema-id: - required: - transcriptionLanguage x-parser-schema-id: properties: type: type: string const: language x-parser-schema-id: ttsLanguage: allOf: - *ref_2 description: New TTS (output) language for the session. x-parser-schema-id: transcriptionLanguage: allOf: - *ref_2 description: New transcription (input) language for the session. x-parser-schema-id: x-parser-schema-id: LanguageFrame title: Language Frame description: > Customer-to-Telnyx frame requesting a language change mid-session. At least one of `ttsLanguage` (output TTS language) and `transcriptionLanguage` (input STT language) must be provided. example: |- { "type": "language", "ttsLanguage": "es-ES", "transcriptionLanguage": "es-ES" } bindings: [] extensions: - id: x-parser-unique-object-id value: clientLanguage - &ref_18 id: clientEnd contentType: application/json payload: - name: End Frame description: > Customer-to-Telnyx frame ending the ConversationRelay session gracefully. Optionally carries `handoffData` — an opaque string forwarded to whatever the assistant hands the call off to next. type: object properties: - name: type type: string description: end required: true - name: handoffData type: &ref_5 - string - 'null' description: Opaque handoff payload forwarded to the next step of the call. required: false headers: [] jsonPayloadSchema: type: object additionalProperties: false required: - type properties: type: type: string const: end x-parser-schema-id: handoffData: type: *ref_5 description: Opaque handoff payload forwarded to the next step of the call. x-parser-schema-id: x-parser-schema-id: EndFrame title: End Frame description: > Customer-to-Telnyx frame ending the ConversationRelay session gracefully. Optionally carries `handoffData` — an opaque string forwarded to whatever the assistant hands the call off to next. example: |- { "type": "end" } bindings: [] extensions: - id: x-parser-unique-object-id value: clientEnd bindings: [] extensions: *ref_6 sendOperations: - *ref_7 receiveOperations: - *ref_8 sendMessages: - *ref_9 - *ref_10 - *ref_11 - *ref_12 - *ref_13 receiveMessages: - *ref_14 - *ref_15 - *ref_16 - *ref_17 - *ref_18 extensions: - id: x-parser-unique-object-id value: conversation-relay-websocket securitySchemes: [] ````