Call
A Call object represents an active call. You can get instances of a Call object from a Voice.Client, by answering or initiating calls.
Examples
Dialing a phone number and playing a message.
import { Voice } from "@signalwire/realtime-api";
const client = new Voice.Client({
project: "<project-id>",
token: "<api-token>",
topics: ["office"],
});
const call = await client.dialPhone({
from: "+YYYYYYYYYY",
to: "+XXXXXXXXXX",
});
await call.playTTS({ text: "Welcome to SignalWire!" });
Answering an incoming phone call and playing a message.
import { Voice } from "@signalwire/realtime-api";
const client = new Voice.Client({
project: "<project-id>",
token: "<api-token>",
topics: ["office"],
});
client.on("call.received", async (call) => {
console.log("Got call", call.from, call.to);
try {
await call.answer();
console.log("Inbound call answered");
await call.playTTS({ text: "Welcome to SignalWire!" });
} catch (error) {
console.error("Error answering inbound call", error);
}
});
Properties
device
• device: any
direction
• direction: "inbound" | "outbound"
Whether you are making or receiving the call.
from
• from: string
The phone number that the call is coming from.
headers
• Optional headers: SipHeader[]
id
• Readonly id: string
Unique id for this voice call
to
• to: string
The phone number you are attempting to call.
type
• type: "phone" | "sip"
The type of call. Only phone and sip are currently supported.
Methods
amd
▸ amd(params?): Promise<CallDetect> - See CallDetect for more details.
Detects the presence of an answering machine. Alias for detectAnsweringMachine.
answer
▸ answer(): Promise<Call> - See Call for more details.
Answers the incoming call.
Returns
Promise<Call> - See Call for more details.
Example
client.on("call.received", async (call) => {
try {
await call.answer();
console.log("Inbound call answered");
} catch (error) {
console.error("Error answering inbound call", error);
}
});
collect
collect(params): Promise<CallCollect> - See CallCollect for more details.
Collect user input. For methods that include a prompt to the user, please see promptAudio, promptRingtone, or promptTTS.
Parameters
| Name | Type | Description |
|---|---|---|
params | Object | - |
params.continuous? | boolean | Detect utterances and digits until stopped. Defaults to false. |
params.digits? | CollectDigitsConfig | Configuration for collecting digits. You must either set this, or speech. |
params.speech? | CollectSpeechConfig | Configuration for collecting speech. You must either set this, or digits. |
params.initialTimeout? | number | Number of seconds to wait for initial input before giving up. Default is 4 seconds. Will be used only when startInputTimers is true or when the timer is started manually via the startInputTimers method. |
params.partialResults? | boolean | If true, partial result events are fired. Default is false. |
params.sendStartOfInput? | boolean | If true, the startOfInput event is fired when input is detected. Default is false. |
params.startInputTimers? | boolean | If true, the initialTimeout timer is started. Default is false. |
Returns
Promise<CallCollect> - See CallCollect for more details.
Examples
Collecting digits input:
const collect = await call.collect({
digits: {
max: 5,
digitTimeout: 2,
terminators: "#*",
},
});
const { type, digits, terminator } = await collect.ended();
Collecting speech input:
const collect = await call.collect({
speech: {
endSilenceTimeout: 2,
speechTimeout: 10,
language: "en-US",
hints: ["sales", "support", "representative"],
},
});
const { type, speech } = await collect.ended();
Collecting digits and listening for results using the events:
call.on("collect.started", (collect) => {
console.log("collect.started", collect);
});
call.on("collect.startOfInput", (collect) => {
console.log("Input collection started.");
});
call.on("collect.updated", (collect) => {
console.log("collect.updated", collect.digits);
});
call.on("collect.ended", (collect) => {
console.log("collect.ended", collect.digits);
});
call.on("collect.failed", (collect) => {
console.log("collect.failed", collect.reason);
});
const collect = await call.collect({
digits: {
max: 4,
digitTimeout: 10,
terminators: "#",
},
partialResults: true,
sendStartOfInput: true,
});
connect
▸ connect(params): Promise<Call> - See Call for more details.
Attempt to connect an existing call to a new outbound call. The two devices will hear each other. You can wait until the new peer is disconnected by calling disconnected.
This is a generic method that allows you to connect to multiple devices in series, parallel, or combinations of both with the use of a DeviceBuilder. For simpler use cases, prefer using connectPhone or connectSip.
Parameters
| Name | Type | Description |
|---|---|---|
params | VoiceDeviceBuilder | { devices: VoiceDeviceBuilder ; ringback?: VoicePlaylist } | Pass only the Dialer specifying the devices to call or an object with the Dialer and Ringback audio to play to call leg. You can play audio, TTS, silence or ringtone. See VoicePlaylist for more details. |
Returns
Promise<Call> - See Call for more details.
A promise that resolves to a Call object that you can use to control the new peer. The promise resolves only after the new peer picks up the call.
Examples
Connecting to a new SIP call.
const plan = new Voice.DeviceBuilder().add(
Voice.DeviceBuilder.Sip({
from: "sip:user1@domain.com",
to: "sip:user2@domain.com",
timeout: 30,
})
);
const peer = await call.connect(plan);
await call.playTTS({ text: "You are peer 1" });
await peer.playTTS({ text: "You are peer 2" });
await call.disconnected();
await call.playTTS({ text: "The peer disconnected" });
Connecting to a new SIP call, while playing ringback audio.
const plan = new Voice.DeviceBuilder().add(
Voice.DeviceBuilder.Sip({
from: "sip:user1@domain.com",
to: "sip:user2@domain.com",
timeout: 30,
})
);
const ringback = new Voice.Playlist().add(
Voice.Playlist.Ringtone({
name: "it",
})
);
const peer = await call.connect({
devices: plan,
ringback: ringback,
});
connectPhone
▸ connectPhone(params): Promise<Call> - See Call for more details.
Attempt to connect an existing call to a new outbound phone call. The two devices will hear each other. You can wait until the new peer is disconnected by calling disconnected.
Parameters
| Name | Type | Description |
|---|---|---|
params | Object | - |
params.callStateEvents | string[] | An optional array of event names to be notified about. Allowed values are created, ringing, answered, and ended. Default is ended. |
params.callStateUrl | string | Optional webhook URL to which SignalWire will send call status change notifications. See the payload specifications under CallState. |
params.from | string | The party the call is coming from. Must be a SignalWire number or SIP endpoint that you own. |
params.maxPricePerMinute? | number | The maximum price in USD acceptable for the call to be created. If the rate for the call is greater than this value, the call will not be created. If not set, all calls will be created. Price can have a maximum of four decimal places, i.e. 0.0075. |
params.ringback? | VoicePlaylist | Ringback audio to play to call leg. You can play audio, TTS, silence or ringtone. |
params.timeout? | number | The time, in seconds, the call will ring before it is considered unanswered. |
params.to | string | The party you are attempting to call. |
Returns
Promise<Call> - See Call for more details.
A promise that resolves to a Call object that you can use to control the new peer. The promise resolves only after the new peer picks up the call.
Example
const peer = await call.connectPhone({
from: "+xxxxxx",
to: "+yyyyyy",
timeout: 30,
});
await call.playTTS({ text: "You are peer 1" });
await peer.playTTS({ text: "You are peer 2" });
await call.disconnected();
await call.playTTS({ text: "The peer disconnected" });
connectSip
▸ connectSip(params): Promise<Call> - See Call for more details.
Attempt to connect an existing call to a new outbound SIP call. The two devices will hear each other. You can wait until the new peer is disconnected by calling disconnected.
Parameters
| Name | Type | Description |
|---|---|---|
params | Object | - |
params.callStateEvents | string[] | An optional array of event names to be notified about. Allowed values are created, ringing, answered, and ended. Default is ended. |
params.callStateUrl | string | Optional webhook URL to which SignalWire will send call status change notifications. See the payload specifications under CallState. |
params.codecs? | SipCodec[] | Optional array of desired codecs in order of preference. Supported values are PCMU, PCMA, OPUS, G729, G722, VP8, H264. Default is parent leg codec(s). |
params.from | string | The party the call is coming from. Must be a SignalWire number or SIP endpoint that you own. |
params.headers? | SipHeader[] | Array of SipHeader objects. Must be X- headers only, see example below. |
params.maxPricePerMinute? | number | The maximum price in USD acceptable for the call to be created. If the rate for the call is greater than this value, the call will not be created. If not set, all calls will be created. Price can have a maximum of four decimal places, i.e. 0.0075. |
params.ringback? | VoicePlaylist | Ringback audio to play to call leg. You can play audio, TTS, silence or ringtone. |
params.timeout? | number | The time, in seconds, the call will ring before it is considered unanswered. |
params.to | string | The party you are attempting to call. |
params.webrtcMedia? | boolean | If true, WebRTC media is negotiated. Default is parent leg setting. |
params.sessionTimeout? | number | Non-negative value, in seconds, to use for the SIP Session-Expires header. If 0 or unset, SignalWire will pick the default (typically 600). |
Returns
Promise<Call> - See Call for more details.
A promise that resolves to a Call object that you can use to control the new peer. The promise resolves only after the new peer picks up the call.
Example
const peer = await call.connectSip({
from: "sip:user1@domain.com",
to: "sip:user2@domain.com",
timeout: 30,
headers: [
{ name: "X-SomeKeyA", value: "SomeValueA" },
{ name: "X-SomeKeyB", value: "SomeValueB" },
],
});
await call.playTTS({ text: "You are peer 1" });
await peer.playTTS({ text: "You are peer 2" });
await call.disconnected();
await call.playTTS({ text: "The peer disconnected" });
detect
▸ detect(params): Promise<CallDetect> - See CallDetect for more details.
Generic method. Please see amd, detectFax, detectDigit.
Parameters
| Name | Type | Description |
|---|---|---|
params | object | - |
params.type | "fax" | "machine" | "digit" | "beep" |
|
Returns
Promise<CallDetect> - See CallDetect for more details.
detectAnsweringMachine
▸ detectAnsweringMachine(params?): Promise<CallDetect> - See CallDetect for more details.
Detects the presence of an answering machine.
Parameters
| Name | Type | Description |
|---|---|---|
params? | Object | - |
params.endSilenceTimeout? | number | Number of seconds to wait for voice to finish. Defaults to 1.0. |
params.initialTimeout? | number | Number of seconds to wait for initial voice before giving up. Defaults to 4.5. |
params.machineVoiceThreshold? | number | How many seconds of voice to decide it is a machine. Defaults to 1.25. |
params.machineWordsThreshold? | number | How many words to count to decide it is a machine. Defaults to 6. |
params.timeout? | number | Number of seconds to run the detector for. Defaults to 30.0. |
params.waitForBeep? | boolean | Whether to wait until the device is ready for voicemail delivery. Defaults to false. |
params.detect_interruptions? | boolean | If set to true, a NOT_READY event is fired if speech is detected after the READY event. This allows application to restart message delivery to answering machine. Defaults to false. |
Returns
Promise<CallDetect> - See CallDetect for more details.
Example
const detect = await call.detectAnsweringMachine();
const result = await detect.ended();
console.log("Detect result:", result.type);
detectDigit
▸ detectDigit(params?): Promise<CallDetect> - See CallDetect for more details.
Detects when a digit is pressed in an audio stream. To gather digit input from a caller, please see prompt.
Parameters
| Name | Type | Description |
|---|---|---|
params? | Object | - |
params.digits? | string | The digits to detect. Defaults to "0123456789#*". |
params.timeout? | number | Number of seconds to run the detector for. Defaults to 30.0. |
params.waitForBeep? | boolean | Whether to wait until the device is ready for voicemail delivery. Defaults to false. |
Returns
Promise<CallDetect> - See CallDetect for more details.
Example
const detect = await call.detectDigit();
const result = await detect.ended();
console.log("Detect result:", result.type);
detectFax
▸ detectFax(params?): Promise<CallDetect> - See CallDetect for more details.
Detects the presence of a fax machine.
Parameters
| Name | Type | Description |
|---|---|---|
params? | Object | - |
params.timeout? | number | Number of seconds to run the detector for. Defaults to 30.0. |
params.tone? | "CED" | "CNG" | The fax tone to detect: CED or CNG. Defaults to CED. |
params.waitForBeep? | boolean | Whether to wait until the device is ready for voicemail delivery. Defaults to false. |
Returns
Promise<CallDetect> - See CallDetect for more details.
Example
const detect = await call.detectFax();
const result = await detect.ended();
console.log("Detect result:", result.type);
dial
▸ dial(params): Promise<Call> - See Call for more details.
Create a new outbound call.
This is a generic method that allows you to dial multiple devices in series, parallel, or combinations of both with the use of a DeviceBuilder. For simpler use cases, prefer using dialPhone or dialSip.
Parameters
| Name | Type | Description |
|---|---|---|
params | VoiceDeviceBuilder | { devices: VoiceDeviceBuilder ; region: string } | Pass only the Dialer specifying the devices to call or an object with the Dialer and a Region of the world to originate the message from. |
Returns
Promise<Call> - See Call for more details.
disconnect
▸ disconnect(): Promise<void>
Returns
Promise<void>
disconnected
▸ disconnected(): Promise<Call> - See Call for more details.
Call this method after connecting a peer (e.g., using connect, connectPhone, or connectSip) to wait until the peer disconnects.
This is equivalent to calling peer.waitFor("ended") on the connected peer.
Returns
Promise<Call> - See Call for more details.
Example
const plan = new Voice.DeviceBuilder().add(
Voice.DeviceBuilder.Sip({
from: "sip:user1@domain.com",
to: "sip:user2@domain.com",
timeout: 30,
})
);
const peer = await call.connect(plan);
await call.disconnected(); // same as `peer.waitFor("ended")`
await call.playTTS({ text: "The peer disconnected" });
hangup
▸ hangup(reason?): Promise<void>
Hangs up the call.
Parameters
| Name | Type | Description |
|---|---|---|
reason? | "error" | "hangup" | "cancel" | "busy" | "noAnswer" | "decline" | Optional reason for hanging up. |
Returns
Promise<void>
Example
call.hangup();
off
▸ off(event, fn?)
Remove an event handler.
Parameters
| Name | Type | Description |
|---|---|---|
event | string | Name of the event. See Events for the list of available events. |
fn? | Function | An event handler which had been previously attached. |
on
▸ on(event, fn)
Attaches an event handler to the specified event.
Parameters
| Name | Type | Description |
|---|---|---|
event | string | Name of the event. See Events for the list of available events. |
fn | Function | An event handler. |
once
▸ once(event, fn)
Attaches an event handler to the specified event. The handler will fire only once.
Parameters
| Name | Type | Description |
|---|---|---|
event | string | Name of the event. See Events for the list of available events. |
fn | Function | An event handler. |
pass
▸ pass(params): Promise<Call> - See Call for more details.
This will allow a client to decline incoming calls without ending the call and redirect the call to another Voice client
Will trigger on the call.received event.
Returns
Promise<Call> - See Call for more details.
Example
client.on("call.received", async (call) => {
await call.pass();
// Every method on the "call" object will fail after calling "pass".
});
play
▸ play(params): Promise<CallPlayback> - See CallPlayback for more details.
Play one or multiple media in a Call and waits until the playing has ended.
The play method is a generic method for all types of media, see playAudio, playSilence, playTTS or playRingtone for more specific usages.
Parameters
| Name | Type | Description |
|---|---|---|
params | VoicePlaylist | A media playlist. |
Returns
Promise<CallPlayback> - See CallPlayback for more details.
Example
await call.play(
new Voice.Playlist({ volume: 1.0 }).add(
Voice.Playlist.TTS({
text: "Welcome to SignalWire! Please enter your 4 digits PIN",
})
)
);
playAudio
▸ playAudio(params): Promise<CallPlayback> - See CallPlayback for more details.
Plays an audio file.
Parameters
| Name | Type | Description |
|---|---|---|
params | Object | - |
params.url | string | HTTP(s) URL to an audio resource to play. |
params.volume? | number | Volume value between -40dB and +40dB where 0 is unchanged. Default is 0. |
Returns
Promise<CallPlayback> - See CallPlayback for more details.
Example
const playback = await call.playAudio({
url: "https://cdn.signalwire.com/default-music/welcome.mp3",
});
await playback.ended();
playRingtone
▸ playRingtone(params): Promise<CallPlayback> - See CallPlayback for more details.
Plays a ringtone.
Parameters
| Name | Type | Description |
|---|---|---|
params | Object | - |
params.duration? | number | Duration of ringtone to play. Defaults to 1 ringtone iteration. |
params.name | RingtoneName | The name of the ringtone. |
params.volume? | number | Volume value between -40dB and +40dB where 0 is unchanged. Default is 0. |
Returns
Promise<CallPlayback> - See CallPlayback for more details.
Example
const playback = await call.playRingtone({ name: "it" });
await playback.ended();
playSilence
▸ playSilence(params): Promise<CallPlayback> - See CallPlayback for more details.
Plays some silence.
Parameters
| Name | Type | Description |
|---|---|---|
params | Object | - |
params.duration | number | Seconds of silence to play. |
Returns
Promise<CallPlayback> - See CallPlayback for more details.
Example
const playback = await call.playSilence({ duration: 3 });
await playback.ended();
playTTS
▸ playTTS(params): Promise<CallPlayback> - See CallPlayback for more details.
Plays text-to-speech.
Parameters
| Name | Type | Description |
|---|---|---|
params | Object | - |
params.gender? | "male" | "female" | Gender of the voice. Defaults to female. |
params.language? | string | Language of the text in ISO 639-1 (language name) + ISO 3166 (country code). Defaults to en-US.Supported languages can be found here |
params.text | string | 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. |
params.voice? | string | Voice to use (takes precedence on gender).Supported voices can be found here |
params.volume? | number | Volume value between -40dB and +40dB where 0 is unchanged. Default is 0. |
Returns
Promise<CallPlayback> - See CallPlayback for more details.
Examples
const playback = await call.playTTS({ text: "Welcome to SignalWire!" });
await playback.ended();
Using SSML:
const playback = await call.playTTS({
text: `<speak>
Here are <say-as interpret-as="characters">SSML</say-as> samples.
I can pause <break time="3s"/>.
I can speak in cardinals. Your number is <say-as interpret-as="cardinal">10</say-as>.
Or I can speak in ordinals. You are <say-as interpret-as="ordinal">10</say-as> in line.
Or I can even speak in digits. The digits for ten are <say-as interpret-as="characters">10</say-as>.
I can also substitute phrases, like the <sub alias="World Wide Web Consortium">W3C</sub>.
Finally, I can speak a paragraph with two sentences.
<p><s>This is sentence one.</s><s>This is sentence two.</s></p>
</speak>
`,
voice: "polly.Joey",
});
await playback.ended();
prompt
▸ prompt(params): Promise<CallPrompt> - See CallPrompt for more details.
Generic method to prompt the user for input. Please see promptAudio, promptRingtone, promptTTS for the more specific methods.
Parameters
| Name | Type | Description |
|---|---|---|
params | Object | - |
params.playlist | VoicePlaylist | A media playlist to play. |
params.digits? | CollectDigitsConfig | Configuration for collecting digits. You must either set this, or speech. |
params.speech? | CollectSpeechConfig | Configuration for collecting speech. You must either set this, or digits. Pass an empty object to use the default configuration. |
params.initialTimeout? | number | Initial timeout in seconds. Default is 4 seconds. |
Returns
Promise<CallPrompt> - See CallPrompt for more details.
Examples
Prompting for digits and waiting for a result:
const prompt = await call.prompt({
playlist: new Voice.Playlist().add(
Voice.Playlist.TTS({ text: "Please enter your PIN" })
),
digits: {
max: 5,
digitTimeout: 2,
terminators: "#*",
},
});
const { type, digits, terminator } = await prompt.ended();
Prompting for speech and waiting for a result:
const prompt = await call.prompt({
playlist: new Voice.Playlist().add(
Voice.Playlist.TTS({ text: "Please say your PIN" })
),
speech: {
endSilenceTimeout: 1,
speechTimeout: 60,
language: "en-US",
hints: [],
},
});
const { type, speech } = await prompt.ended();
Prompting for speech and listening for results using the events:
call.on("prompt.started", (p) => {
console.log("prompt.started", p.id);
});
call.on("prompt.updated", (p) => {
console.log("prompt.updated", p.id);
});
call.on("prompt.failed", (p) => {
console.log("prompt.failed", p.id, p.reason);
});
call.on("prompt.ended", (p) => {
console.log("prompt.ended", p.id, p.text);
});
const prompt = await call.prompt({
playlist: new Voice.Playlist().add(
Voice.Playlist.TTS({ text: "Please say your PIN" })
),
speech: {},
});
promptAudio
▸ promptAudio(params): Promise<CallPrompt> - See CallPrompt for more details.
Play an audio while collecting user input from the call, such as digits or speech.
Parameters
| Name | Type | Description |
|---|---|---|
params | Object | - |
params.digits? | CollectDigitsConfig | Configuration for collecting digits. You must either set this, or speech. |
params.speech? | CollectSpeechConfig | Configuration for collecting speech. You must either set this, or digits. Pass an empty object to use the default configuration. |
params.initialTimeout? | number | Initial timeout in seconds. Default is 4 seconds. |
params.url | string | HTTP(s) URL to an audio resource to play. |
params.volume? | number | Volume value between -40dB and +40dB where 0 is unchanged. Default is 0. |
Returns
Promise<CallPrompt> - See CallPrompt for more details.
Examples
Prompting for digits and waiting for a result:
const prompt = await call.promptAudio({
url: "https://cdn.signalwire.com/default-music/welcome.mp3",
digits: {
max: 5,
digitTimeout: 2,
terminators: "#*",
},
});
const { type, digits, terminator } = await prompt.ended();
Prompting for speech and waiting for a result:
const prompt = await call.promptAudio({
url: "https://cdn.signalwire.com/default-music/welcome.mp3",
speech: {
endSilenceTimeout: 1,
speechTimeout: 60,
language: "en-US",
hints: [],
},
});
const { type, text, terminator } = await prompt.ended();
Prompting for speech and listening for results using the events:
call.on("prompt.started", (p) => {
console.log("prompt.started", p.id);
});
call.on("prompt.updated", (p) => {
console.log("prompt.updated", p.id);
});
call.on("prompt.failed", (p) => {
console.log("prompt.failed", p.id, p.reason);
});
call.on("prompt.ended", (p) => {
console.log(prompt.ended, p.id, p.text);
});
const prompt = await call.promptAudio({
url: "https://cdn.signalwire.com/default-music/welcome.mp3",
speech: {},
});
promptRingtone
▸ promptRingtone(params): Promise<CallPrompt> - See CallPrompt for more details.
Play a ringtone while collecting user input from the call, such as digits or speech.
Parameters
| Name | Type | Description |
|---|---|---|
params | Object | - |
params.name | RingtoneName | The name of the ringtone. |
params.digits? | CollectDigitsConfig | Configuration for collecting digits. You must either set this, or speech. |
params.speech? | CollectSpeechConfig | Configuration for collecting speech. You must either set this, or digits. Pass an empty object to use the default configuration. |
params.duration? | number | Duration of ringtone to play. Defaults to 1 ringtone iteration. |
params.initialTimeout? | number | Initial timeout in seconds. Default is 4 seconds. |
params.volume? | number | Volume value between -40dB and +40dB where 0 is unchanged. Default is 0. |
Returns
Promise<CallPrompt> - See CallPrompt for more details.
Examples
Prompting for digits and waiting for a result:
const prompt = await call.promptRingtone({
name: "it",
duration: 10,
digits: {
max: 5,
digitTimeout: 2,
terminators: "#*",
},
});
const { type, digits, terminator } = await prompt.ended();
Prompting for speech and waiting for a result:
const prompt = await call.promptRingtone({
name: "it",
duration: 10,
speech: {
endSilenceTimeout: 1,
speechTimeout: 60,
language: "en-US",
hints: [],
},
});
const { type, text, terminator } = await prompt.ended();
Prompting for speech and listening for results using the events:
call.on("prompt.started", (p) => {
console.log("prompt.started", p.id);
});
call.on("prompt.updated", (p) => {
console.log("prompt.updated", p.id);
});
call.on("prompt.failed", (p) => {
console.log("prompt.failed", p.id, p.reason);
});
call.on("prompt.ended", (p) => {
console.log(prompt.ended, p.id, p.text);
});
const prompt = await call.promptRingtone({
name: "it",
duration: 10,
speech: {},
});
promptTTS
▸ promptTTS(params): Promise<CallPrompt> - See CallPrompt for more details.
Play text-to-speech while collecting user input from the call, such as digits or speech.
Parameters
| Name | Type | Description |
|---|---|---|
params | Object | - |
params.text | string | 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. |
params.digits? | CollectDigitsConfig | Configuration for collecting digits. You must either set this, or speech. |
params.speech? | CollectSpeechConfig | Configuration for collecting speech. You must either set this, or digits. Pass an empty object to use the default configuration. |
params.gender? | "male" | "female" | Gender of the voice (male or female). Defaults to female. |
params.initialTimeout? | number | Initial timeout in seconds. Default is 4 seconds. |
params.language? | string | Language of the text in ISO 639-1 (language name) + ISO 3166 (country code). Defaults to en-US.Supported languages can be found here |
params.volume? | number | Volume value between -40dB and +40dB where 0 is unchanged. Default is 0. |
params.voice? | string | Voice to use (takes precedence on gender).Supported voices can be found here |
Returns
Promise<CallPrompt> - See CallPrompt for more details.
Examples
Prompting for digits and waiting for a result:
const prompt = await call.promptTTS({
text: "Please enter your PIN",
digits: {
max: 5,
digitTimeout: 2,
terminators: "#*",
},
});
const { type, digits, terminator } = await prompt.ended();
Prompting for speech and waiting for a result:
const prompt = await call.promptTTS({
text: "Please enter your PIN",
speech: {
endSilenceTimeout: 1,
speechTimeout: 60,
language: "en-US",
hints: [],
},
});
const { type, text, terminator } = await prompt.ended();
Prompting for speech and listening for results using the events:
call.on("prompt.started", (p) => {
console.log("prompt.started", p.id);
});
call.on("prompt.updated", (p) => {
console.log("prompt.updated", p.id);
});
call.on("prompt.failed", (p) => {
console.log("prompt.failed", p.id, p.reason);
});
call.on("prompt.ended", (p) => {
console.log(prompt.ended, p.id, p.text);
});
const prompt = await call.promptTTS({
text: "Please enter your PIN",
speech: {},
});
Prompting for digits with SSML and waiting for a result:
const prompt = await call.promptTTS({
text: `<speak>
Please enter your <say-as interpret-as="characters">UUID</say-as>.
It should be a <say-as interpret-as="cardinal">10</say-as> digit number.
</speak>`,
voice: "polly.Joey",
digits: {
max: 5,
digitTimeout: 2,
terminators: "#*",
},
});
const { type, speech, terminator } = await prompt.ended();
record
▸ record(params): Promise<CallRecording> - See CallRecording for more details.
Generic method to record a call. Please prefer using recordAudio.
Parameters
| Name | Type | Description |
|---|---|---|
params | Object | - |
params.audio | Object | See the parameters for recordAudio. |
Returns
Promise<CallRecording> - See CallRecording for more details.
recordAudio
▸ recordAudio(params?): Promise<CallRecording> - See CallRecording for more details.
Records the audio from the call.
Parameters
| Name | Type | Description |
|---|---|---|
params? | Object | - |
params.beep? | boolean | Whether to play a beep. Default is false. |
params.direction? | "listen" | "speak" | "both" | Direction to record. Can be listen (what the caller hears), speak (what the caller says), or both. Default is speak. |
params.endSilenceTimeout? | number | How long to wait (in seconds) until the caller has stopped speaking. Disable by passing 0. Default is 1.0. |
params.format? | "mp3" | "wav" | Format of the recording. Default is mp3. |
params.initialTimeout? | number | How long to wait (in seconds) until something is heard in the recording. Disable by passing 0. Default is 5.0. |
params.inputSensitivity? | number | Controls how sensitive the voice activity detector is to background noise, where 0 is least sensitive and 100 is most sensitive. Default is 44.0. |
params.stereo? | boolean | Whether to record in stereo mode. Default is false. |
params.terminators? | string | DTMF digits that, when dialed, will end the recording. Default is #\*. |
Returns
Promise<CallRecording> - See CallRecording for more details.
Example
const recording = await call.recordAudio({ direction: "both" });
await recording.stop();
removeAllListeners
▸ removeAllListeners(event?)
Detaches all event listeners for the specified event.
Parameters
| Name | Type | Description |
|---|---|---|
event? | string | Name of the event (leave this undefined to detach listeners for all events). See Events for the list of available events. |
sendDigits
▸ sendDigits(digits): Promise<Call> - See Call for more details.
Play DTMF digits to the other party on the call.
Parameters
| Name | Type |
|---|---|
digits | string |
Returns
Promise<Call> - See Call for more details.
Example
await call.sendDigits("123");
tap
▸ tap(params): Promise<CallTap> - See CallTap for more details.
Intercept call media and stream it to the specified WebSocket endpoint. Prefer using tapAudio if you only need to tap audio.
This is an experimental method. The destination must be a hosted WebSocket/RTP server, with an address that SignalWire can reach.
A current limitation of this method is that the destination device does not receive any metadata regarding the origin of the stream.
Parameters
| Name | Type | Description |
|---|---|---|
params | Object | - |
params.device | TapDevice | Destination device. Can be either WebSocket or RTP. |
params.audio | Object | An object with the configuration for audio tapping. See "audio parameters" below. |
Audio parameters
| Name | Type | Description |
|---|---|---|
audio | Object | - |
audio.direction | "listen" | "speak" | "both" | Direction to tap. Can be "listen" (what the caller hears), "speak" (what the caller says), or "both". |
Returns
Promise<CallTap> - See CallTap for more details.
Example
const tap = await call.tapAudio({
device: {
type: "ws",
uri: "wss://example.domain.com/endpoint",
},
audio: {
direction: "both",
},
});
await tap.stop();
tapAudio
▸ tapAudio(params): Promise<CallTap> - See CallTap for more details.
Intercept call audio and stream it to the specified WebSocket endpoint.
This is an experimental method. The destination must be a hosted WebSocket/RTP server, with an address that SignalWire can reach.
A current limitation of this method is that the destination device does not receive any metadata regarding the origin of the stream.
Parameters
| Name | Type | Description |
|---|---|---|
params | Object | - |
params.device | TapDevice | Destination device. Can be either WebSocket or RTP. |
params.direction | "listen" | "speak" | "both" | Direction to tap. Can be "listen" (what the caller hears), "speak" (what the caller says), or "both". |
Returns
Promise<CallTap> - See CallTap for more details.
Example
const tap = await call.tapAudio({
direction: "both",
device: {
type: "ws",
uri: "wss://example.domain.com/endpoint",
},
});
await tap.stop();
waitFor
▸ waitFor(params): Promise<boolean>
Returns a promise that is resolved only after the current call is in one of the specified states.
Parameters
| Name | Type |
|---|---|
params | "ended" | "ending" | ("ended" | "ending")[] |
Returns
Promise<boolean>
true if the requested states have been reached, false if they won't be reached because the call ended.
Example
await call.waitFor("ended");
waitForDisconnected
▸ waitForDisconnected(): Promise<Call> - See Call for more details.
This method is deprecated. See disconnected instead.
Events
call.created
• call.created(call)
A call was created.
Parameters
| Name | Type | Description |
|---|---|---|
call | CallState | A object containing the call state. |
call.ringing
• call.ringing(call)
A call is ringing.
Parameters
| Name | Type | Description |
|---|---|---|
call | CallState | A object containing the call state. |
call.answered
• call.answered(call)
A call was answered.
Parameters
| Name | Type | Description |
|---|---|---|
call | CallState | A object containing the call state. |
call.ending
• call.ending(call)
A call is ending.
Parameters
| Name | Type | Description |
|---|---|---|
call | CallState | A object containing the call state. |
call.ended
• call.ended(call)
A call ended.
Parameters
| Name | Type | Description |
|---|---|---|
call | CallState | A object containing the call state. |
collect.ended
• collect.ended(collect)
A collect ended.
Parameters
| Name | Type | Description |
|---|---|---|
collect | CallCollect | A collect object. |
collect.failed
• collect.failed(collect)
A collect failed.
Parameters
| Name | Type | Description |
|---|---|---|
collect | CallCollect | A collect object. |
collect.startOfInput
• collect.startOfInput(collect)
User input began in a collect.
Parameters
| Name | Type | Description |
|---|---|---|
collect | CallCollect | A collect object. |
collect.started
• collect.started(collect)
A collect started.
Parameters
| Name | Type | Description |
|---|---|---|
collect | CallCollect | A collect object. |
collect.updated
• collect.updated(collect)
The state of a collect changed.
Parameters
| Name | Type | Description |
|---|---|---|
collect | CallCollect | A collect object. |
playback.ended
• playback.ended(playback)
A playback ended.
Parameters
| Name | Type | Description |
|---|---|---|
playback | CallPlayback | A playback object. |
playback.started
• playback.started(playback)
A playback has started.
Parameters
| Name | Type | Description |
|---|---|---|
playback | CallPlayback | A playback object. |
playback.updated
• playback.updated(playback)
The state of a playback changed.
Parameters
| Name | Type | Description |
|---|---|---|
playback | CallPlayback | A playback object. |
prompt.ended
• prompt.ended(prompt)
A prompt has ended.
Parameters
| Name | Type | Description |
|---|---|---|
prompt | CallPrompt | A prompt object. |
prompt.failed
• prompt.failed(prompt)
A prompt has failed.
Parameters
| Name | Type | Description |
|---|---|---|
prompt | CallPrompt | A prompt object. |
prompt.started
• prompt.started(prompt)
A prompt started.
Parameters
| Name | Type | Description |
|---|---|---|
prompt | CallPrompt | A prompt object. |
prompt.updated
• prompt.updated(prompt)
The state of a prompt changed.
Parameters
| Name | Type | Description |
|---|---|---|
prompt | CallPrompt | A prompt object. |
recording.ended
• recording.ended(recording)
A recording ended.
Parameters
| Name | Type | Description |
|---|---|---|
recording | CallRecording | A recording object. |
recording.failed
• recording.failed(recording)
A recording failed.
Parameters
| Name | Type | Description |
|---|---|---|
recording | CallRecording | A recording object. |
recording.started
• recording.started(recording)
A recording started.
Parameters
| Name | Type | Description |
|---|---|---|
recording | CallRecording | A recording object. |
recording.updated
• recording.updated(recording)
The state of a recording changed.
Parameters
| Name | Type | Description |
|---|---|---|
recording | CallRecording | A recording object. |
tap.ended
• tap.ended(tap)
A tap ended.
Parameters
| Name | Type | Description |
|---|---|---|
tap | CallTap | A tap object. |
tap.started
• tap.started(tap)
A tap started.
Parameters
| Name | Type | Description |
|---|---|---|
tap | CallTap | A tap object. |