Skip to main content

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

state​

• state: created | ringing | answered | ending | ended

The current state of the 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​

NameTypeDescription
paramsObject-
params.continuous?booleanDetect utterances and digits until stopped. Defaults to false.
params.digits?CollectDigitsConfigConfiguration for collecting digits. You must either set this, or speech.
params.speech?CollectSpeechConfigConfiguration for collecting speech. You must either set this, or digits.
params.initialTimeout?numberNumber 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?booleanIf true, partial result events are fired. Default is false.
params.sendStartOfInput?booleanIf true, the startOfInput event is fired when input is detected. Default is false.
params.startInputTimers?booleanIf 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​

NameTypeDescription
paramsVoiceDeviceBuilder | { 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​

NameTypeDescription
paramsObject-
params.callStateEventsstring[]An optional array of event names to be notified about. Allowed values are created, ringing, answered, and ended. Default is ended.
params.callStateUrlstringOptional webhook URL to which SignalWire will send call status change notifications. See the payload specifications under CallState.
params.fromstringThe party the call is coming from. Must be a SignalWire number or SIP endpoint that you own.
params.maxPricePerMinute?numberThe 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?VoicePlaylistRingback audio to play to call leg. You can play audio, TTS, silence or ringtone.
params.timeout?numberThe time, in seconds, the call will ring before it is considered unanswered.
params.tostringThe 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​

NameTypeDescription
paramsObject-
params.callStateEventsstring[]An optional array of event names to be notified about. Allowed values are created, ringing, answered, and ended. Default is ended.
params.callStateUrlstringOptional 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.fromstringThe 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?numberThe 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?VoicePlaylistRingback audio to play to call leg. You can play audio, TTS, silence or ringtone.
params.timeout?numberThe time, in seconds, the call will ring before it is considered unanswered.
params.tostringThe party you are attempting to call.
params.webrtcMedia?booleanIf true, WebRTC media is negotiated. Default is parent leg setting.
params.sessionTimeout?numberNon-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​

NameTypeDescription
paramsobject-
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​

NameTypeDescription
params?Object-
params.endSilenceTimeout?numberNumber of seconds to wait for voice to finish. Defaults to 1.0.
params.initialTimeout?numberNumber of seconds to wait for initial voice before giving up. Defaults to 4.5.
params.machineVoiceThreshold?numberHow many seconds of voice to decide it is a machine. Defaults to 1.25.
params.machineWordsThreshold?numberHow many words to count to decide it is a machine. Defaults to 6.
params.timeout?numberNumber of seconds to run the detector for. Defaults to 30.0.
params.waitForBeep?booleanWhether to wait until the device is ready for voicemail delivery. Defaults to false.
params.detect_interruptions?booleanIf 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​

NameTypeDescription
params?Object-
params.digits?stringThe digits to detect. Defaults to "0123456789#*".
params.timeout?numberNumber of seconds to run the detector for. Defaults to 30.0.
params.waitForBeep?booleanWhether 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​

NameTypeDescription
params?Object-
params.timeout?numberNumber 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?booleanWhether 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​

NameTypeDescription
paramsVoiceDeviceBuilder | { 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​

NameTypeDescription
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​

NameTypeDescription
eventstringName of the event. See Events for the list of available events.
fn?FunctionAn event handler which had been previously attached.

on​

â–¸ on(event, fn)

Attaches an event handler to the specified event.

Parameters​

NameTypeDescription
eventstringName of the event. See Events for the list of available events.
fnFunctionAn event handler.

Example​

In the below example, we are listening for the call.state event and logging the current call state to the console. This means this will be triggered every time the call state changes.

call.on("call.state", (call) => {
    console.log("call state changed:", call.state);
});

once​

â–¸ once(event, fn)

Attaches an event handler to the specified event. The handler will fire only once.

Parameters​

NameTypeDescription
eventstringName of the event. See Events for the list of available events.
fnFunctionAn 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​

NameTypeDescription
paramsVoicePlaylistA 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​

NameTypeDescription
paramsObject-
params.urlstringHTTP(s) URL to an audio resource to play.
params.volume?numberVolume 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​

NameTypeDescription
paramsObject-
params.duration?numberDuration of ringtone to play. Defaults to 1 ringtone iteration.
params.nameRingtoneNameThe name of the ringtone.
params.volume?numberVolume 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​

NameTypeDescription
paramsObject-
params.durationnumberSeconds 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​

NameTypeDescription
paramsObject-
params.gender?"male" | "female"Gender of the voice. Defaults to female.
params.language?stringLanguage of the text in ISO 639-1 (language name) + ISO 3166 (country code). Defaults to en-US.
Supported languages can be found here
params.textstringText 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?stringVoice to use (takes precedence on gender).
Supported voices can be found here
params.volume?numberVolume 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​

NameTypeDescription
paramsObject-
params.playlistVoicePlaylistA media playlist to play.
params.digits?CollectDigitsConfigConfiguration for collecting digits. You must either set this, or speech.
params.speech?CollectSpeechConfigConfiguration for collecting speech. You must either set this, or digits. Pass an empty object to use the default configuration.
params.initialTimeout?numberInitial 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​

NameTypeDescription
paramsObject-
params.digits?CollectDigitsConfigConfiguration for collecting digits. You must either set this, or speech.
params.speech?CollectSpeechConfigConfiguration for collecting speech. You must either set this, or digits. Pass an empty object to use the default configuration.
params.initialTimeout?numberInitial timeout in seconds. Default is 4 seconds.
params.urlstringHTTP(s) URL to an audio resource to play.
params.volume?numberVolume 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​

NameTypeDescription
paramsObject-
params.nameRingtoneNameThe name of the ringtone.
params.digits?CollectDigitsConfigConfiguration for collecting digits. You must either set this, or speech.
params.speech?CollectSpeechConfigConfiguration for collecting speech. You must either set this, or digits. Pass an empty object to use the default configuration.
params.duration?numberDuration of ringtone to play. Defaults to 1 ringtone iteration.
params.initialTimeout?numberInitial timeout in seconds. Default is 4 seconds.
params.volume?numberVolume 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​

NameTypeDescription
paramsObject-
params.textstringText 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?CollectDigitsConfigConfiguration for collecting digits. You must either set this, or speech.
params.speech?CollectSpeechConfigConfiguration 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?numberInitial timeout in seconds. Default is 4 seconds.
params.language?stringLanguage 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?numberVolume value between -40dB and +40dB where 0 is unchanged. Default is 0.
params.voice?stringVoice 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​

NameTypeDescription
paramsObject-
params.audioObjectSee 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​

NameTypeDescription
params?Object-
params.beep?booleanWhether 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?numberHow 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?numberHow long to wait (in seconds) until something is heard in the recording. Disable by passing 0. Default is 5.0.
params.inputSensitivity?numberControls 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?booleanWhether to record in stereo mode. Default is false.
params.terminators?stringDTMF 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​

NameTypeDescription
event?stringName 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​

NameType
digitsstring

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.

note

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​

NameTypeDescription
paramsObject-
params.deviceTapDeviceDestination device. Can be either WebSocket or RTP.
params.audioObjectAn object with the configuration for audio tapping. See "audio parameters" below.

Audio parameters

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

note

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​

NameTypeDescription
paramsObject-
params.deviceTapDeviceDestination 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​

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

caution

This method is deprecated. See disconnected instead.

Events​

call.created​

• call.created(call)

A call was created.

Parameters​

NameTypeDescription
callCallStateA object containing the call state.

call.ringing​

• call.ringing(call)

A call is ringing.

Parameters​

NameTypeDescription
callCallStateA object containing the call state.

call.answered​

• call.answered(call)

A call was answered.

Parameters​

NameTypeDescription
callCallStateA object containing the call state.

call.ending​

• call.ending(call)

A call is ending.

Parameters​

NameTypeDescription
callCallStateA object containing the call state.

call.ended​

• call.ended(call)

A call ended.

Parameters​

NameTypeDescription
callCallStateA object containing the call state.

collect.ended​

• collect.ended(collect)

A collect ended.

Parameters​

NameTypeDescription
collectCallCollectA collect object.

collect.failed​

• collect.failed(collect)

A collect failed.

Parameters​

NameTypeDescription
collectCallCollectA collect object.

collect.startOfInput​

• collect.startOfInput(collect)

User input began in a collect.

Parameters​

NameTypeDescription
collectCallCollectA collect object.

collect.started​

• collect.started(collect)

A collect started.

Parameters​

NameTypeDescription
collectCallCollectA collect object.

collect.updated​

• collect.updated(collect)

The state of a collect changed.

Parameters​

NameTypeDescription
collectCallCollectA collect object.

playback.ended​

• playback.ended(playback)

A playback ended.

Parameters​

NameTypeDescription
playbackCallPlaybackA playback object.

playback.started​

• playback.started(playback)

A playback has started.

Parameters​

NameTypeDescription
playbackCallPlaybackA playback object.

playback.updated​

• playback.updated(playback)

The state of a playback changed.

Parameters​

NameTypeDescription
playbackCallPlaybackA playback object.

prompt.ended​

• prompt.ended(prompt)

A prompt has ended.

Parameters​

NameTypeDescription
promptCallPromptA prompt object.

prompt.failed​

• prompt.failed(prompt)

A prompt has failed.

Parameters​

NameTypeDescription
promptCallPromptA prompt object.

prompt.started​

• prompt.started(prompt)

A prompt started.

Parameters​

NameTypeDescription
promptCallPromptA prompt object.

prompt.updated​

• prompt.updated(prompt)

The state of a prompt changed.

Parameters​

NameTypeDescription
promptCallPromptA prompt object.

recording.ended​

• recording.ended(recording)

A recording ended.

Parameters​

NameTypeDescription
recordingCallRecordingA recording object.

recording.failed​

• recording.failed(recording)

A recording failed.

Parameters​

NameTypeDescription
recordingCallRecordingA recording object.

recording.started​

• recording.started(recording)

A recording started.

Parameters​

NameTypeDescription
recordingCallRecordingA recording object.

recording.updated​

• recording.updated(recording)

The state of a recording changed.

Parameters​

NameTypeDescription
recordingCallRecordingA recording object.

tap.ended​

• tap.ended(tap)

A tap ended.

Parameters​

NameTypeDescription
tapCallTapA tap object.

tap.started​

• tap.started(tap)

A tap started.

Parameters​

NameTypeDescription
tapCallTapA tap object.