<ConversationRelay> TwiML noun

The <ConversationRelay> noun supports the following attributes:

Include nested elements within <ConversationRelay> for more granular configuration. For more information on configuring ConversationRelay, refer to the ConversationRelay Onboarding Guide.

The <Language> element maps a language code to specific TTS and STT settings. Use this element to configure multiple languages for your session.

Example

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3
const response = new VoiceResponse();
4
const connect = response.connect();
5
const conversationrelay = connect.conversationRelay({
6
    url: 'wss://mywebsocketserver.com/websocket'
7
});
8
conversationrelay.language({
9
    code: 'sv-SE',
10
    ttsProvider: 'amazon',
11
    voice: 'Elin-Neural',
12
    transcriptionProvider: 'google',
13
    speechModel: 'long'
14
});
15
conversationrelay.language({
16
    code: 'en-US',
17
    ttsProvider: 'google',
18
    voice: 'en-US-Journey-O'
19
});
20

21
console.log(response.toString());

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
  <Connect>
4
    <ConversationRelay url="wss://mywebsocketserver.com/websocket">
5
      <Language code="sv-SE" ttsProvider="amazon" voice="Elin-Neural" transcriptionProvider="google" speechModel="long"/>
6
      <Language code="en-US" ttsProvider="google" voice="en-US-Journey-O" />
7
    </ConversationRelay>
8
  </Connect>
9
</Response>

Attributes

Notes

• If you specify the same language code in both <ConversationRelay> and <Language>, the settings in <Language> take precedence.
• ConversationRelay provides default settings for commonly used languages.

The <Parameter> element allows you to send custom parameters from the TwiML directly into the initial "setup" message sent over the WebSocket. These parameters appear under the customParameters field in the JSON message.

Example

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3
const response = new VoiceResponse();
4
const connect = response.connect();
5
const conversationrelay = connect.conversationRelay({
6
    url: 'wss://mywebsocketserver.com/websocket'
7
});
8
conversationrelay.parameter({
9
    name: 'foo',
10
    value: 'bar'
11
});
12
conversationrelay.parameter({
13
    name: 'hint',
14
    value: 'Annoyed customer'
15
});
16

17
console.log(response.toString());

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
  <Connect>
4
    <ConversationRelay url="wss://mywebsocketserver.com/websocket">
5
      <Parameter name="foo" value="bar"/>
6
      <Parameter name="hint" value="Annoyed customer"/>
7
    </ConversationRelay>
8
  </Connect>
9
</Response>

Resulting Setup Message

1
{
2
  "type": "setup",
3
  "sessionId": "VX00000000000000000000000000000000",
4
  "callSid": "CA00000000000000000000000000000000",
5
  "...": "...",
6
  "customParameters": {
7
    "foo": "bar",
8
    "hint": "Annoyed customer"
9
  }
10
}

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3
const response = new VoiceResponse();
4
const connect = response.connect({
5
    action: 'https://myhttpserver.com/connect_action'
6
});
7
connect.conversationRelay({
8
    url: 'wss://mywebsocketserver.com/websocket',
9
    welcomeGreeting: 'Hi! Ask me anything!'
10
});
11

12
console.log(response.toString());

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
  <Connect action="https://myhttpserver.com/connect_action">
4
    <ConversationRelay url="wss://mywebsocketserver.com/websocket" welcomeGreeting="Hi! Ask me anything!" />
5
  </Connect>
6
</Response>

• action (optional): The URL that Twilio will request when the <Connect> verb ends.
• url (required): The URL of your WebSocket server (must use the wss:// protocol).
• welcomeGreeting (optional): The message automatically played to the caller after we answer the call and establish the WebSocket connection.

When the TwiML execution is complete, Twilio will make a callback to the action URL with call information and the return parameters from ConversationRelay.

Language settings refer to configurations for both Text-to-Speech and Speech-to-Text:

• Text-to-Speech (TTS) settings:
  • ttsLanguage
  • ttsProvider
  • voice
• Speech-to-Text (STT) settings:
  • transcriptionLanguage
  • transcriptionProvider
  • speechModel

Configure language settings in two places:

1. Attributes of <ConversationRelay>: These serve as the default settings used when the session starts.
2. Within <Language> Elements: Each <Language> element configures settings for a specific language code. You can include multiple <Language> elements to support multiple languages.

• In <ConversationRelay>, the ttsLanguage attribute overrides the language attribute for the default TTS language.
• In <ConversationRelay>, the transcriptionLanguage attribute overrides the language attribute for the STT language.
• If a <Language> element specifies the same code attribute as in <ConversationRelay>, the <Language> element's settings take precedence.
• The system uses default values when you don't provide specific settings.

Default Values

• language: Defaults to en-US if not specified.
• ttsProvider: Defaults to ElevenLabs if not specified.
• transcriptionProvider: Defaults to Google if not specified.
• If you set the ttsProvider attribute without the voice attribute, the system uses a default voice for that provider.
• If you set the transcriptionProvider attribute without the speechModel attribute, the system uses a default model for that provider.
• If you set the voice attribute without the ttsProvider attribute, the system infers the provider from the default or specified ttsProvider.
• If you set the speechModel attribute without the transcriptionProvider attribute, the system infers the provider from the default or specified transcriptionProvider.

For Speech-to-Text (STT) settings:

• At session start, the service uses the transcriptionLanguage attribute to initiate the STT session.
• If the combination of the transcriptionProvider and speechModel attributes is invalid, the call disconnects, and the system reports an error in the action callback and error notifications.
• You can change the transcriptionLanguage attribute during the session via the language message you send through the Service Provider Interface (SPI).

For Text-to-Speech (TTS) settings:

• When the lang property is present in the text token message from the SPI, the service uses it to select the TTS voice.
• If the combination of the ttsProvider and voice attributes is invalid, the system sends an error message over the SPI.
• If you don't specify the lang property in the text token, the service uses the current TTS language settings.

When an action URL is specified in the <Connect> verb, ConversationRelay will make a request to that URL when the <Connect> verb ends. The request includes call information and session details.

Example Payloads

ConversationRelay, including the <ConversationRelay> TwiML nouns and APIs, use artificial intelligence or machine learning technologies.

Our AI Nutrition Facts for ConversationRelay provide an overview of the AI feature you're using, so you can better understand how the AI is working with your data. The below AI Nutrition Label details the ConversationRelay AI qualities. For more information and the glossary regarding the AI Nutrition Facts Label, refer to our AI Nutrition Facts page.