TwiML™ Voice: <ConversationRelay>

The <ConversationRelay> noun supports the following attributes:

For more granular configuration, you can nest elements in <ConversationRelay>.

The <Language> element maps a language code to a set of text-to-speech and speech-to-text settings. Add one <Language> element for each language that the session may use.

Attributes

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>

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

You can set the text-to-speech language in four ways:

1. The value of the language attribute on the <ConversationRelay> noun
2. The value of the ttsLanguage attribute on the <ConversationRelay> noun
3. The ttsLanguage value in the last switch language message that your app sent to Twilio
4. The lang value in the text token message your app sent to Twilio

Later items on this list override earlier items on the list. For example, if you set the text-to-speech language to sv-SE in the text token message and en-US in the ttsLanguage attribute of the <ConversationRelay> noun, the TTS language is sv-SE for that token.

You can set the speech-to-text language in three ways. Later items on this list override earlier items on the list.

1. The value of the language attribute on the <ConversationRelay> noun
2. The value of the transcriptionLanguage attribute on the <ConversationRelay> noun
3. The transcriptionLanguage value in the last switch language message that your app sent to Twilio

If your session could have more than one language, use the <Language> noun to configure the speech model, transcription provider, text-to-speech provider, and voice for each language. Add one <Language> noun for each language that you support.

The attributes of the <Language> noun override attributes of the parent <ConversationRelay> noun.

ConversationRelay generally uses default values when you don't specify a speech model, voice, or provider. For example, if you set the ttsProvider attribute without the voice attribute, the system uses a default voice for that text-to-speech provider.

ConversationRelay sends an error message to your app and disconnects the call when you've specified an invalid combination of transcriptionProvider and speechModel or of ttsProvider and voice.

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

Use the hints attribute of <ConversationRelay> to help accurately transcribe phrases that may appear in the speech. Hints could include brand names, industry-specific terms, or other expressions that you think the call is likely to contain. Adding a phrase to hints could increase the likelihood that it will be recognized by your speech-to-text provider. Separate each hint with a comma and capitalize proper nouns (like brand names) in the way that they're normally written.

If Nova-3 is your speech-to-text model, hints uses the keyterms feature of Deepgram. You can provide up to 100 hints and the hints attribute can contain up to 500 tokens. See the Deepgram documentation to learn more about hints with Nova-3.

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.