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.

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>

Detects the presence of an answering machine. Alias for detectAnsweringMachine.


answer

answer(): Promise<Call>

Answers the incoming call.

Returns

Promise<Call>

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);
}
});

connect

connect(params): Promise<VoiceCall>

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 Voice.DeviceBuilder. For simpler use cases, prefer using connectPhone or connectSip.

Parameters

NameTypeDescription
paramsVoiceDeviceBuilder | { devices: VoiceDeviceBuilder ; ringback?: playlist }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.

Returns

Promise<VoiceCall>

A promise that resolves to a VoiceCall 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<VoiceCall>

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.from?stringThe party the call is coming from. Must be a SignalWire number or SIP endpoint that you own.
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<VoiceCall>

A promise that resolves to a VoiceCall 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<VoiceCall>

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

Returns

Promise<VoiceCall>

A promise that resolves to a VoiceCall 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>

Generic method. Please see amd, detectFax, detectDigit.

Parameters

NameTypeDescription
paramsobject-
params.type"fax" | "machine" | "digit"
  • if type="digit", see the method parameters for detectDigit
  • if type="fax", see the method parameters for detectFax
  • if type="machine", see the method parameters for detectMachine

Returns

Promise<CallDetect>


detectAnsweringMachine

detectAnsweringMachine(params?): Promise<CallDetect>

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.

Returns

Promise<CallDetect`>

Example

const detect = await call.detectAnsweringMachine();
const result = await detect.ended();

console.log("Detect result:", result.type);

detectDigit

detectDigit(params?): Promise<CallDetect>

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>

Example

const detect = await call.detectDigit();
const result = await detect.ended();

console.log("Detect result:", result.type);

detectFax

detectFax(params?): Promise<CallDetect>

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>

Example

const detect = await call.detectFax();
const result = await detect.ended();

console.log("Detect result:", result.type);

dial

dial(params): Promise<Call>

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>


disconnect

disconnect(): Promise<void>

Returns

Promise<void>


disconnected

disconnected(): Promise<Call>

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>

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.

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.

play

play(params): Promise<CallPlayback>

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>

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>

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>

Example

const playback = await call.playAudio({
url: "https://cdn.signalwire.com/default-music/welcome.mp3",
});
await playback.ended();

playRingtone

playRingtone(params): Promise<CallPlayback>

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>

Example

const playback = await call.playRingtone({ name: "it" });
await playback.ended();

playSilence

playSilence(params): Promise<CallPlayback>

Plays some silence.

Parameters

NameTypeDescription
paramsObject-
params.durationnumberSeconds of silence to play.

Returns

Promise<CallPlayback>

Example

const playback = await call.playSilence({ duration: 3 });
await playback.ended();

playTTS

playTTS(params): Promise<CallPlayback>

Plays text-to-speech.

Parameters

NameTypeDescription
paramsObject-
params.gender?"male" | "female"Gender of the voice. Defaults to female.
params.language?stringLanguage of the text. Defaults to en-US.
params.textstringText to play.
params.voice?stringVoice to use (takes precedence on gender). Use "polly.<name>" for Amazon Polly voices, or "gcloud.<name>" for Google Cloud voices.
params.volume?numberVolume value between -40dB and +40dB where 0 is unchanged. Default is 0.

Returns

Promise<CallPlayback>

Example

const playback = await call.playTTS({ text: "Welcome to SignalWire!" });
await playback.ended();

prompt

prompt(params): Promise<CallPrompt>

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.
params.partialResults?booleanIf true, partial result events are fired. Default is false.

Returns

Promise<CallPrompt>

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, 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.prompt({
playlist: new Voice.Playlist().add(
Voice.Playlist.TTS({ text: "Please say your PIN" })
)
speech: {},
});

promptAudio

promptAudio(params): Promise<CallPrompt>

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.partialResults?booleanIf true, partial result events are fired. Default is false.
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>

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, speech, 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>

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.partialResults?booleanIf true, partial result events are fired. Default is false.
params.volume?numberVolume value between -40dB and +40dB where 0 is unchanged. Default is 0.

Returns

Promise<CallPrompt>

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, speech, 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>

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

Parameters

NameTypeDescription
paramsObject-
params.textstringText 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.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. Defaults to "en-US".
params.partialResults?booleanIf true, partial result events are fired. Default is false.
params.volume?numberVolume value between -40dB and +40dB where 0 is unchanged. Default is 0.

Returns

Promise<CallPrompt>

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, speech, 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: {},
});

record

record(params): Promise<CallRecording>

Generic method to record a call. Please prefer using recordAudio.

Parameters

NameTypeDescription
paramsObject-
params.audioObjectSee the parameters for recordAudio.

Returns

Promise<CallRecording>


recordAudio

recordAudio(params?): Promise<CallRecording>

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>

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>

Play DTMF digits to the other party on the call.

Parameters

NameType
digitsstring

Returns

Promise<Call>

Example

await call.sendDigits("123");

tap

tap(params): Promise<CallTap>

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>

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>

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>

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>

caution

This method is deprecated. See disconnected instead.