VoiceCallMethods

promptRingtone

View as Markdown

promptRingtone

Play a ringtone 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 a ringtone.

name
RingtoneNameRequired

The name of the ringtone. See RingtoneName.

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.

duration
number

Duration of ringtone to play in seconds. Defaults to 1 ringtone iteration.

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 a ringtone 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.promptRingtone({
16
17      name: "it",
18      duration: 10,
19      digits: {
20        max: 5,
21        digitTimeout: 5,
22        terminators: "#*",
23      },
24      listen: {
25        onStarted: () => console.log("Prompt Ringtone started"),
26        onFailed: () => console.log("Prompt Ringtone failed"),
27        onUpdated: (event) => console.log("Prompt Ringtone updated", event.result),
28        onEnded: (event) => {
29          console.log("Prompt Ringtone ended", event.result);
30          // Hangup the call
31          call.hangup();
32        }
33      }
34    }).onStarted();
35  }
36});

Speech Example

In this example, we dial a phone number and prompt for speech while playing a ringtone in the background. After the ringtone ends, we hangup the call.

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.promptRingtone({
17
18      name: "it",
19      duration: 10,
20      speech: {
21        model: "enhanced.phone_call"
22      },
23      listen: {
24        onStarted: () => console.log("Prompt Ringtone started"),
25        onFailed: () => console.log("Prompt Ringtone failed"),
26        onUpdated: (event) => console.log("Prompt Ringtone updated", event.result),
27        onEnded: (event) => {
28          console.log("Prompt Ringtone ended", event.result);
29          // Hangup the call
30          call.hangup();
31        }
32      }
33    }).onStarted()
34  }
35});