VoiceCallMethods

promptTTS

View as Markdown

promptTTS

Play text-to-speech while collecting user input from the call, such as digits or speech.

Parameters

params
objectRequired

Object containing the parameters for prompting the user for input while playing text-to-speech.

text
stringRequired

Text to play. SSML may be entered as a string wrapped in <speak> tags. See our supported voices and languages documentation for usage and supported tags.

digits
CollectDigitsConfig

Configuration for collecting digits. You must either set this, or speech. See CollectDigitsConfig.

speech
CollectSpeechConfig

Configuration for collecting speech. You must either set this, or digits. Pass an empty object to use the default configuration. See CollectSpeechConfig.

language
stringDefaults to en-US

Language of the text in ISO 639-1 (language name) + ISO 3166 (country code). Supported languages can be found here.

gender
"male" | "female"Defaults to female

Gender of the voice.

voice
string

Voice to use (takes precedence over gender). Supported voices can be found here.

initialTimeout
numberDefaults to 4

Initial timeout in seconds.

volume
numberDefaults to 0

Volume value between -40dB and +40dB where 0 is unchanged.

listen
object

Callback to listen for events. List of prompt events can be found here. Example event: onStarted.

Returns

Promise<CallPrompt>

A promise that resolves to a CallPrompt object that you can use to view the current state and results of the prompt session.

Examples

Digits Example

In this example, we dial a phone number and prompt for digits while playing TTS in the background. After the digits are entered or a timeout occurs, the prompt session will end and return the digits results, and the call will hangup.

1import { SignalWire } from "@signalwire/realtime-api";
2
3const client = await SignalWire({ project: "ProjectID Here", token: "Token Here" })
4
5const voiceClient = client.voice;
6
7// Listen for incoming calls
8await voiceClient.listen({
9  topics: ["office"],
10  onCallReceived: async (call) => {
11    console.log("Call received");
12    // Answer the call
13    call.answer();
14    // Play TTS on the call
15    await call.promptTTS({
16      text: "Please enter your 5 digit pin number.",
17      duration: 10,
18      digits: {
19        max: 5,
20        digitTimeout: 5,
21        terminators: "#*",
22      },
23      listen: {
24        onStarted: () => console.log("Prompt TTS started"),
25        onFailed: () => console.log("Prompt TTS failed"),
26        onUpdated: (event) => console.log("Prompt TTS updated", event.result),
27        onEnded: (event) => {
28          console.log("Prompt TTS ended", event.result);
29          // Hangup the call
30          call.hangup();
31        }
32      }
33    }).onStarted();
34  }
35});

Speech Example

In this example, we dial a phone number and prompt for speech while playing TTS in the background. After the user speaks or a timeout occurs, the prompt session will end and return the speech results, and the call will hangup.

1import { SignalWire } from "@signalwire/realtime-api";
2
3const client = await SignalWire({ project: "ProjectID Here", token: "Token Here" })
4
5const voiceClient = client.voice;
6
7// Listen for incoming calls
8await voiceClient.listen({
9
10  topics: ["office"],
11  onCallReceived: async (call) => {
12    console.log("Call received");
13    // Answer the call
14    call.answer();
15    // Play TTS on the call
16    await call.promptTTS({
17      text: "Please say your name.",
18      duration: 10,
19      speech: {
20        model: "enhanced.phone_call"
21      },
22      listen: {
23        onStarted: () => console.log("Prompt TTS started"),
24        onFailed: () => console.log("Prompt TTS failed"),
25        onUpdated: (event) => console.log("Prompt TTS updated", event.result),
26        onEnded: (event) => {
27          console.log("Prompt TTS ended", event.result)
28          // Hangup the call
29          call.hangup();
30        }
31      }
32    }).onStarted();
33  }
34});

SSML Example

In this example, we are using SSML to play a TTS message. We dial a phone number and prompt for digits while playing TTS in the background. After the digits are entered or a timeout occurs, the prompt session will end and return the digits results, and the call will hangup.

1import { SignalWire } from "@signalwire/realtime-api";
2
3const client = await SignalWire({ project: "ProjectID Here", token: "Token Here" })
4
5const voiceClient = client.voice;
6
7// Listen for incoming calls
8await voiceClient.listen({
9
10  topics: ["office"],
11  onCallReceived: async (call) => {
12    console.log("Call received");
13    // Answer the call
14    call.answer();
15    // Play TTS on the call
16    await call.promptTTS({
17      text: `<speak>
18        Please enter your <say-as interpret-as="characters">UUID</say-as>.
19        It should be a <say-as interpret-as="cardinal">5</say-as> digit number.
20      </speak>`,
21      voice: "polly.Joey",
22      duration: 20,
23      digits: {
24        max: 5,
25        digitTimeout: 20,
26        terminators: "#*",
27      },
28      listen: {
29        onStarted: () => console.log("Prompt TTS started"),
30        onFailed: () => console.log("Prompt TTS failed"),
31        onUpdated: (event) => console.log("Prompt TTS updated", event.result),
32        onEnded: (event) => {
33          console.log("Prompt TTS ended", event.result)
34          // Hangup the call
35          call.hangup();
36        }
37      }
38    }).onStarted();
39  }
40});