Call

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

Detects the presence of an answering machine.

Parameters

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

Returns

Promise<VoiceCallDetectContract>

Example

const detect = await call.amd()
const result = await detect.waitForResult()

console.log('Detect result:', result.type)

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<VoiceCallContract<any>>

Attempt to connect an existing call to a new outbound call. You can wait until the call is disconnected by calling waitForDisconnected.

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

NameType
paramsVoiceCallConnectMethodParams

Returns

Promise<VoiceCallContract<any>>

Examples

Connecting to a new SIP call.

const plan = new Voice.DeviceBuilder().add(
  Voice.DeviceBuilder.Sip({
    from: 'sip:[email protected]',
    to: 'sip:[email protected]',
    timeout: 30,
  })
)

const peer = await call.connect(plan)

Connecting to a new SIP call, while playing ringback audio.

const plan = new Voice.DeviceBuilder().add(
  Voice.DeviceBuilder.Sip({
    from: 'sip:[email protected]',
    to: 'sip:[email protected]',
    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<VoiceCallContract<any>>

Attempt to connect an existing call to a new outbound phone call. You can wait until the call is disconnected by calling waitForDisconnected.

Parameters

NameTypeDescription
paramsObject-
params.from?string

The party the call is coming from. Must be a SignalWire number or SIP endpoint that you own.

params.ringback?VoicePlaylist

Ringback audio to play to call leg. You can play audio, tts, silence or ringtone. See {@link VoicePlaylist} for details.

params.timeout?number

The time, in seconds, the call will ring before it is considered unanswered.

params.tostring

The party you are attempting to call.

Returns

Promise<VoiceCallContract<any>>

Example

const peer = await call.connectPhone({
  from: '+xxxxxx',
  to: '+yyyyyy',
  timeout: 30
})

connectSip

connectSip(params): Promise<VoiceCallContract<any>>

Attempt to connect an existing call to a new outbound SIP call. You can wait until the call is disconnected by calling waitForDisconnected.

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

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 like: { name: string, value: string }. Must be X- headers only, see example below.

params.ringback?VoicePlaylist

Ringback audio to play to call leg. You can play audio, tts, silence or ringtone. See {@link VoicePlaylist} for details.

params.timeout?number

The time, in seconds, the call will ring before it is considered unanswered.

params.tostring

The party you are attempting to call.

params.webrtcMedia?boolean

If true, WebRTC media is negotiated. Default is parent leg setting.

Returns

Promise<VoiceCallContract<any>>

Example

const peer = await call.connectPhone({
  from: 'sip:[email protected]',
  to: 'sip:[email protected]',
  timeout: 30
})

detect

detect(params): Promise<VoiceCallDetectContract>

Generic method. Please see amd, detectFax, detectDigit.

Parameters

NameType
paramsVoiceCallDetectMethodParams

Returns

Promise<VoiceCallDetectContract>


detectDigit

detectDigit(params?): Promise<VoiceCallDetectContract>

Detects digits in the audio stream.

Parameters

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

Example

const detect = await call.detectDigit()
const result = await detect.waitForResult()

console.log('Detect result:', result.type)

detectFax

detectFax(params?): Promise<VoiceCallDetectContract>

Detects the presence of a fax machine.

Parameters

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

Example

const detect = await call.detectFax()
const result = await detect.waitForResult()

console.log('Detect result:', result.type)

dial

dial(params): Promise<Call>

Parameters

NameType
paramsVoiceDeviceBuilder | { devices: VoiceDeviceBuilder ; region: string }

Returns

Promise<Call>


disconnect

disconnect(): Promise<void>

Returns

Promise<void>


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<T>(event, fn?): EmitterContract<RealTimeCallApiEventsDocs>

Type parameters

NameType
Textends keyof RealTimeCallApiEventsDocs

Parameters

NameType
eventT
fn?(...args: ArgumentMap<RealTimeCallApiEventsDocs>[Extract<T, keyof RealTimeCallApiEventsDocs>]) => void

Returns

EmitterContract<RealTimeCallApiEventsDocs>


on

on<T>(event, fn): EmitterContract<RealTimeCallApiEventsDocs>

Type parameters

NameType
Textends keyof RealTimeCallApiEventsDocs

Parameters

NameType
eventT
fn(...args: ArgumentMap<RealTimeCallApiEventsDocs>[Extract<T, keyof RealTimeCallApiEventsDocs>]) => void

Returns

EmitterContract<RealTimeCallApiEventsDocs>


once

once<T>(event, fn): EmitterContract<RealTimeCallApiEventsDocs>

Type parameters

NameType
Textends keyof RealTimeCallApiEventsDocs

Parameters

NameType
eventT
fn(...args: ArgumentMap<RealTimeCallApiEventsDocs>[Extract<T, keyof RealTimeCallApiEventsDocs>]) => void

Returns

EmitterContract<RealTimeCallApiEventsDocs>


play

play(params): Promise<VoiceCallPlaybackContract>

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
paramsVoicePlaylist

a media playlist. See Voice.Playlist.

Returns

Promise<VoiceCallPlaybackContract>

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

Plays an audio file.

Parameters

NameTypeDescription
paramsObject-
params.urlstring

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

Example

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

playRingtone

playRingtone(params): Promise<VoiceCallPlaybackContract>

Plays a ringtone.

Parameters

NameTypeDescription
paramsObject-
params.duration?number

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

params.nameRingtoneName

The name of the ringtone. See {@link RingtoneName} for the supported values.

params.volume?number

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

Returns

Promise<VoiceCallPlaybackContract>

Example

const playback = await call.playRingtone({ name: 'it' });
await playback.waitForEnded();

playSilence

playSilence(params): Promise<VoiceCallPlaybackContract>

Plays some silence.

Parameters

NameTypeDescription
paramsObject-
params.durationnumber

Seconds of silence to play.

Returns

Promise<VoiceCallPlaybackContract>

Example

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

playTTS

playTTS(params): Promise<VoiceCallPlaybackContract>

Plays text-to-speech.

Parameters

NameTypeDescription
paramsObject-
params.gender?"male" | "female"

Gender of the voice (male or female). Defaults to female.

params.language?string

Language of the text. Defaults to en-US.

params.textstring

Text to play

params.volume?number

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

Returns

Promise<VoiceCallPlaybackContract>

Example

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

prompt

prompt(params): Promise<VoiceCallPromptContract>

Generic method to prompt the user for input. Please see promptAudio, promptRingtone, promptTTS.

Parameters

NameType
paramsObject
params.initialTimeout?number
params.partialResults?boolean
params.playlistVoicePlaylist

Returns

Promise<VoiceCallPromptContract>


promptAudio

promptAudio(params): Promise<VoiceCallPromptContract>

Play an audio while collecting user input from the call, such as digits or speech.

Parameters

NameTypeDescription
paramsObject-
params.digits?CollectDigitsConfig

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

params.initialTimeout?number

Initial timeout in seconds. Default is 4 seconds.

params.partialResults?boolean

If true, partial result events are fired. Default is false.

params.speech?CollectSpeechConfig

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

params.urlstring

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

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.waitForResult()

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.waitForResult()

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

Play a ringtone while collecting user input from the call, such as digits or speech.

Parameters

NameTypeDescription
paramsObject-
params.digits?CollectDigitsConfig

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

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

The name of the ringtone. See {@link RingtoneName} for the supported values.

params.partialResults?boolean

If true, partial result events are fired. Default is false.

params.speech?CollectSpeechConfig

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

params.volume?number

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

Returns

Promise<VoiceCallPromptContract>

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.waitForResult()

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.waitForResult()

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

Play a ringtone while collecting user input from the call, such as digits or speech.

Parameters

NameTypeDescription
paramsObject-
params.digits?CollectDigitsConfig

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

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. Defaults to en-US.

params.partialResults?boolean

If true, partial result events are fired. Default is false.

params.speech?CollectSpeechConfig

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

params.textstring

Text to play

params.volume?number

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

Returns

Promise<VoiceCallPromptContract>

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.waitForResult()

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.waitForResult()

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

Generic method to record a call. Please see recordAudio.

Parameters

NameType
paramsVoiceCallRecordMethodParams

Returns

Promise<VoiceCallRecordingContract>


recordAudio

recordAudio(params?): Promise<VoiceCallRecordingContract>

Records the audio from the call.

Parameters

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

Example

const recording = await call.recordAudio({ direction: 'both' })
await recording.stop()

removeAllListeners

removeAllListeners<T>(event?): EmitterContract<RealTimeCallApiEventsDocs>

Type parameters

NameType
Textends keyof RealTimeCallApiEventsDocs

Parameters

NameType
event?T

Returns

EmitterContract<RealTimeCallApiEventsDocs>


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

Intercept call media and stream it to the specified WebSocket endpoint. Prefer using tapAudio if you only need to tap audio.

Parameters

NameType
paramsVoiceCallTapMethodParams

Returns

Promise<VoiceCallTapContract>

Example

const tap = await call.tapAudio({
  audio: {
    direction: 'both',
  },
  device: {
    type: 'ws',
    uri: 'wss://example.domain.com/endpoint',
  },
})

await tap.stop()

tapAudio

tapAudio(params): Promise<VoiceCallTapContract>

Intercept call audio and stream it to the specified WebSocket endpoint.

Parameters

NameTypeDescription
paramsObject-
params.deviceTapDevice

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

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>

Returns a promise that is resolved only after the current call has been connected. Also see connect.

Returns

Promise<Call>

Example

const plan = new Voice.DeviceBuilder().add(
  Voice.DeviceBuilder.Sip({
    from: 'sip:[email protected]',
    to: 'sip:[email protected]',
    timeout: 30,
  })
)

const peer = await call.connect(plan)
await call.waitForDisconnected()