Call – Home

A Call object represents an active call. You can get instances of a Call object from a [Voice.Client](./voice-client.mdx), by answering or initiating calls. #### Examples Dialing a phone number and playing a message. js import { Voice } from @signalwire/realtime-api; const client = new Voice.Client({ project: , 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. js import { Voice } from @signalwire/realtime-api; const client = new Voice.Client({ project: , 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](./types.mdx#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 - See [CallDetect](./calldetect.mdx) for more details. Detects the presence of an answering machine. Alias for [detectAnsweringMachine](#detectansweringmachine). ### answer ▸ **answer**(): Promise - See [Call](./voice-call.mdx) for more details. Answers the incoming call. #### Returns Promise - See [Call](./voice-call.mdx) for more details. #### Example js 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 - See [CallCollect](./callcollect.mdx) for more details. Collect user input. For methods that include a prompt to the user, please see [promptAudio](./voice-call.mdx#promptaudio), [promptRingtone](./voice-call.mdx#promptringtone), or [promptTTS](./voice-call.mdx#prompttts). #### Parameters | Name | Type | Description | |:|:|:--| | params | Object | - | | params.continuous? | boolean | Detect utterances and digits until stopped. Defaults to false. | | params.digits? | [CollectDigitsConfig](./types.mdx#collectdigitsconfig) | Configuration for collecting digits. You must either set this, or speech. | | params.speech? | [CollectSpeechConfig](./types.mdx#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](./callcollect.mdx#startinputtimers) method. | | params.partialResults? | boolean | If true, partial result events are fired. Default is false. | | params.sendStartOfInput? | boolean | If true, the [startOfInput](#collectstartofinput) 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 - See [CallCollect](./callcollect.mdx) for more details. #### Examples Collecting digits input: js const collect = await call.collect({ digits: { max: 5, digitTimeout: 2, terminators: #*, }, }); const { type, digits, terminator } = await collect.ended(); Collecting speech input: js 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: js 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 - See [Call](./voice-call.mdx) 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](./voice-call.mdx#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](./voice-devicebuilder.md). For simpler use cases, prefer using [connectPhone](./voice-call.mdx#connectphone) or [connectSip](./voice-call.mdx#connectsip). #### Parameters | Name | Type | Description | |:|:--|:-| | params | [VoiceDeviceBuilder](./voice-devicebuilder.md) \| { 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](./voice-playlist.md) for more details. | #### Returns Promise - See [Call](./voice-call.mdx) for more details. A promise that resolves to a [Call](./voice-call.mdx) 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. js 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. js 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 - See [Call](./voice-call.mdx) 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](./voice-call.mdx#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](./callstate.mdx). | | 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](./voice-playlist.md) | 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 - See [Call](./voice-call.mdx) for more details. A promise that resolves to a [Call](./voice-call.mdx) object that you can use to control the new peer. The promise resolves only after the new peer picks up the call. #### Example js 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 - See [Call](./voice-call.mdx) 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](./voice-call.mdx#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](./callstate.mdx). | | 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](./types.mdx#sipheader)[] | Array of [SipHeader](./types.mdx#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](./voice-playlist.md) | 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 - See [Call](./voice-call.mdx) for more details. A promise that resolves to a [Call](./voice-call.mdx) object that you can use to control the new peer. The promise resolves only after the new peer picks up the call. #### Example js 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 - See [CallDetect](./calldetect.mdx) for more details. Generic method. Please see [amd](#amd), [detectFax](#detectfax), [detectDigit](#detectdigit). #### Parameters | Name | Type | Description | |:--|:|:--| | params | object | - | | params.type | fax \| machine \| digit \| beep |

if type=digit, see the method parameters for [detectDigit](#detectdigit)
if type=fax, see the method parameters for [detectFax](#detectfax)
if type=machine, see the method parameters for [detectAnsweringMachine](#detectansweringmachine)
if type=beep, see the method parameters for [detectAnsweringMachine](#detectansweringmachine)

| #### Returns Promise - See [CallDetect](./calldetect.mdx) for more details. ### detectAnsweringMachine ▸ **detectAnsweringMachine**(params?): Promise - See [CallDetect](./calldetect.mdx) 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 - See [CallDetect](./calldetect.mdx) for more details. #### Example js const detect = await call.detectAnsweringMachine(); const result = await detect.ended(); console.log(Detect result:, result.type); ### detectDigit ▸ **detectDigit**(params?): Promise - See [CallDetect](./calldetect.mdx) for more details. Detects when a digit is pressed in an audio stream. To gather digit input from a caller, please see [prompt](#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 - See [CallDetect](./calldetect.mdx) for more details. #### Example js const detect = await call.detectDigit(); const result = await detect.ended(); console.log(Detect result:, result.type); ### detectFax ▸ **detectFax**(params?): Promise - See [CallDetect](./calldetect.mdx) 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 - See [CallDetect](./calldetect.mdx) for more details. #### Example js const detect = await call.detectFax(); const result = await detect.ended(); console.log(Detect result:, result.type); ### dial ▸ **dial**(params): Promise - See [Call](./voice-call.mdx) 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](./voice-devicebuilder.md). For simpler use cases, prefer using [dialPhone](./voice-client.mdx#dialphone) or [dialSip](./voice-client#dialsip). #### Parameters | Name | Type | Description | |:|:-|:| | params | [VoiceDeviceBuilder](./voice-devicebuilder.md) \| { 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 - See [Call](./voice-call.mdx) for more details. ### disconnect ▸ **disconnect**(): Promise #### Returns Promise ### disconnected ▸ **disconnected**(): Promise - See [Call](./voice-call.mdx) for more details. Call this method after connecting a peer (e.g., using [connect](#connect), [connectPhone](#connectphone), or [connectSip](#connectsip)) to wait until the peer disconnects. This is equivalent to calling peer.waitFor(ended) on the connected peer. #### Returns Promise - See [Call](./voice-call.mdx) for more details. #### Example js 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 Hangs up the call. #### Parameters | Name | Type | Description | |:-|:|:--| | reason? | error \| hangup \| cancel \| busy \| noAnswer \| decline | Optional reason for hanging up. | #### Returns Promise #### Example js call.hangup(); ### off ### on ### once ### pass ▸ **pass**(params): Promise - See [Call](./voice-call.mdx) for more details. This will allow a client to decline incoming calls without ending the call and redirect the call to another [Voice client](./voice-client.mdx) Will trigger on the [call.received](./voice-client.mdx#callreceived) event. #### Returns Promise - See [Call](./voice-call.mdx) for more details. #### Example js client.on(call.received, async (call) => { await call.pass(); // Every method on the call object will fail after calling pass. }); ### play ▸ **play**(params): Promise - See [CallPlayback](./callplayback.mdx) 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](./voice-call.mdx#playaudio), [playSilence](./voice-call.mdx#playsilence), [playTTS](./voice-call.mdx#playtts) or [playRingtone](./voice-call.mdx#playringtone) for more specific usages. #### Parameters | Name | Type | Description | |:|:|:| | params | [VoicePlaylist](./voice-playlist.md) | A media playlist. | #### Returns Promise - See [CallPlayback](./callplayback.mdx) for more details. #### Example js 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 - See [CallPlayback](./callplayback.mdx) 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 - See [CallPlayback](./callplayback.mdx) for more details. #### Example js const playback = await call.playAudio({ url: https://cdn.signalwire.com/default-music/welcome.mp3, }); await playback.ended(); ### playRingtone ▸ **playRingtone**(params): Promise - See [CallPlayback](./callplayback.mdx) 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](./types.mdx#ringtonename) | The name of the ringtone. | | params.volume? | number | Volume value between -40dB and +40dB where 0 is unchanged. Default is 0. | #### Returns Promise - See [CallPlayback](./callplayback.mdx) for more details. #### Example js const playback = await call.playRingtone({ name: it }); await playback.ended(); ### playSilence ▸ **playSilence**(params): Promise - See [CallPlayback](./callplayback.mdx) for more details. Plays some silence. #### Parameters | Name | Type | Description | |:|:|:-| | params | Object | - | | params.duration | number | Seconds of silence to play. | #### Returns Promise - See [CallPlayback](./callplayback.mdx) for more details. #### Example js const playback = await call.playSilence({ duration: 3 }); await playback.ended(); ### playTTS ▸ **playTTS**(params): Promise - See [CallPlayback](./callplayback.mdx) 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](/voice/getting-started/voice-and-languages/) | | params.text | string | Text to play. SSML may be entered as a string wrapped in tags.
See our [supported voices and languages](/voice/getting-started/voice-and-languages) documentation for usage and supported tags. | | params.voice? | string | Voice to use (takes precedence on gender).
Supported voices can be found [here](/voice/getting-started/voice-and-languages/) | | params.volume? | number | Volume value between -40dB and +40dB where 0 is unchanged. Default is 0. | #### Returns Promise - See [CallPlayback](./callplayback.mdx) for more details. #### Examples js const playback = await call.playTTS({ text: Welcome to SignalWire! }); await playback.ended(); Using SSML: js const playback = await call.playTTS({ text: Here are SSML samples. I can pause . I can speak in cardinals. Your number is 10. Or I can speak in ordinals. You are 10 in line. Or I can even speak in digits. The digits for ten are 10. I can also substitute phrases, like the _W3C. Finally, I can speak a paragraph with two sentences.

~~This is sentence one.This is sentence two.~~

, voice: polly.Joey, }); await playback.ended(); ### prompt ▸ **prompt**(params): Promise - See [CallPrompt](./callprompt.mdx) for more details. Generic method to prompt the user for input. Please see [promptAudio](./voice-call.mdx#promptaudio), [promptRingtone](./voice-call.mdx#promptringtone), [promptTTS](./voice-call.mdx#prompttts) for the more specific methods. #### Parameters | Name | Type | Description | |:-|:|:--| | params | Object | - | | params.playlist | [VoicePlaylist](./voice-playlist.md) | A media playlist to play. | | params.digits? | [CollectDigitsConfig](./types.mdx#collectdigitsconfig) | Configuration for collecting digits. You must either set this, or speech. | | params.speech? | [CollectSpeechConfig](./types.mdx#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 - See [CallPrompt](./callprompt.mdx) for more details. #### Examples Prompting for digits and waiting for a result: js 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: js const prompt = await call.prompt({ // prettier-ignore 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: js 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({ // prettier-ignore playlist: new Voice.Playlist().add( Voice.Playlist.TTS({ text: Please say your PIN }) ), speech: {}, }); ### promptAudio ▸ **promptAudio**(params): Promise - See [CallPrompt](./callprompt.mdx) 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](./types.mdx#collectdigitsconfig) | Configuration for collecting digits. You must either set this, or speech. | | params.speech? | [CollectSpeechConfig](./types.mdx#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 - See [CallPrompt](./callprompt.mdx) for more details. #### Examples Prompting for digits and waiting for a result: js 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: js 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: js 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 - See [CallPrompt](./callprompt.mdx) 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](./types.mdx#ringtonename) | The name of the ringtone. | | params.digits? | [CollectDigitsConfig](./types.mdx#collectdigitsconfig) | Configuration for collecting digits. You must either set this, or speech. | | params.speech? | [CollectSpeechConfig](./types.mdx#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 - See [CallPrompt](./callprompt.mdx) for more details. #### Examples Prompting for digits and waiting for a result: js 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: js 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: js 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 - See [CallPrompt](./callprompt.mdx) 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 tags.
See our [supported voices and languages](/voice/getting-started/voice-and-languages) documentation for usage and supported tags. | | params.digits? | [CollectDigitsConfig](./types.mdx#collectdigitsconfig) | Configuration for collecting digits. You must either set this, or speech. | | params.speech? | [CollectSpeechConfig](./types.mdx#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](/voice/getting-started/voice-and-languages/) | | 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](/voice/getting-started/voice-and-languages/) | #### Returns Promise - See [CallPrompt](./callprompt.mdx) for more details. #### Examples Prompting for digits and waiting for a result: js 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: js 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: js 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: js const prompt = await call.promptTTS({ text: Please enter your UUID. It should be a 10 digit number. , voice: polly.Joey, digits: { max: 5, digitTimeout: 2, terminators: #*, }, }); const { type, speech, terminator } = await prompt.ended(); ### record ▸ **record**(params): Promise - See [CallRecording](./callrecording.mdx) for more details. Generic method to record a call. Please prefer using [recordAudio](#recordaudio). #### Parameters | Name | Type | Description | |:|:|:-| | params | Object | - | | params.audio | Object | See the parameters for [recordAudio](#recordaudio). | #### Returns Promise - See [CallRecording](./callrecording.mdx) for more details. ### recordAudio ▸ **recordAudio**(params?): Promise - See [CallRecording](./callrecording.mdx) 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 - See [CallRecording](./callrecording.mdx) for more details. #### Example js const recording = await call.recordAudio({ direction: both }); await recording.stop(); ### removeAllListeners ### sendDigits ▸ **sendDigits**(digits): Promise - See [Call](./voice-call.mdx) for more details. Play DTMF digits to the other party on the call. #### Parameters | Name | Type | |:|:| | digits | string | #### Returns Promise - See [Call](./voice-call.mdx) for more details. #### Example js await call.sendDigits(123); ### tap ▸ **tap**(params): Promise - See [CallTap](./calltap.mdx) for more details. Intercept call media and stream it to the specified WebSocket endpoint. Prefer using [tapAudio](./voice-call.mdx#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 | Name | Type | Description | |:-|:-|:-| | params | Object | - | | params.device | [TapDevice](./types.mdx#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 - See [CallTap](./calltap.mdx) for more details. #### Example js const tap = await call.tapAudio({ device: { type: ws, uri: wss://example.domain.com/endpoint, }, audio: { direction: both, }, }); await tap.stop(); ### tapAudio ▸ **tapAudio**(params): Promise - See [CallTap](./calltap.mdx) 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 | Name | Type | Description | |:-|:-|:| | params | Object | - | | params.device | [TapDevice](./types.mdx#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 - See [CallTap](./calltap.mdx) for more details. #### Example js const tap = await call.tapAudio({ direction: both, device: { type: ws, uri: wss://example.domain.com/endpoint, }, }); await tap.stop(); ### waitFor ▸ **waitFor**(params): Promise 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 true if the requested states have been reached, false if they wont be reached because the call ended. #### Example js await call.waitFor(ended); ### ~~waitForDisconnected~~ ▸ **waitForDisconnected**(): Promise - See [Call](./voice-call.mdx) for more details. :::caution This method is deprecated. See [disconnected](#disconnected) instead. ::: ## Events ### call.created • **call.created**(call) A call was created. #### Parameters | Name | Type | Description | |:-|:-|:| | call | [CallState](./callstate.mdx) | A object containing the call state. | ### call.ringing • **call.ringing**(call) A call is ringing. #### Parameters | Name | Type | Description | |:-|:-|:| | call | [CallState](./callstate.mdx) | A object containing the call state. | ### call.answered • **call.answered**(call) A call was answered. #### Parameters | Name | Type | Description | |:-|:-|:| | call | [CallState](./callstate.mdx) | A object containing the call state. | ### call.ending • **call.ending**(call) A call is ending. #### Parameters | Name | Type | Description | |:-|:-|:| | call | [CallState](./callstate.mdx) | A object containing the call state. | ### call.ended • **call.ended**(call) A call ended. #### Parameters | Name | Type | Description | |:-|:-|:| | call | [CallState](./callstate.mdx) | A object containing the call state. | ### collect.ended • **collect.ended**(collect) A collect ended. #### Parameters | Name | Type | Description | |:-|:--|:| | collect | [CallCollect](./callcollect.mdx) | A collect object. | ### collect.failed • **collect.failed**(collect) A collect failed. #### Parameters | Name | Type | Description | |:-|:--|:| | collect | [CallCollect](./callcollect.mdx) | A collect object. | ### collect.startOfInput • **collect.startOfInput**(collect) User input began in a collect. #### Parameters | Name | Type | Description | |:-|:--|:| | collect | [CallCollect](./callcollect.mdx) | A collect object. | ### collect.started • **collect.started**(collect) A collect started. #### Parameters | Name | Type | Description | |:-|:--|:| | collect | [CallCollect](./callcollect.mdx) | A collect object. | ### collect.updated • **collect.updated**(collect) The state of a collect changed. #### Parameters | Name | Type | Description | |:-|:--|:| | collect | [CallCollect](./callcollect.mdx) | A collect object. | ### playback.ended • **playback.ended**(playback) A playback ended. #### Parameters | Name | Type | Description | |:--|:-|:-| | playback | [CallPlayback](./callplayback.mdx) | A playback object. | ### playback.started • **playback.started**(playback) A playback has started. #### Parameters | Name | Type | Description | |:--|:-|:-| | playback | [CallPlayback](./callplayback.mdx) | A playback object. | ### playback.updated • **playback.updated**(playback) The state of a playback changed. #### Parameters | Name | Type | Description | |:--|:-|:-| | playback | [CallPlayback](./callplayback.mdx) | A playback object. | ### prompt.ended • **prompt.ended**(prompt) A prompt has ended. #### Parameters | Name | Type | Description | |:|:|:--| | prompt | [CallPrompt](./callprompt.mdx) | A prompt object. | ### prompt.failed • **prompt.failed**(prompt) A prompt has failed. #### Parameters | Name | Type | Description | |:|:|:--| | prompt | [CallPrompt](./callprompt.mdx) | A prompt object. | ### prompt.started • **prompt.started**(prompt) A prompt started. #### Parameters | Name | Type | Description | |:|:|:--| | prompt | [CallPrompt](./callprompt.mdx) | A prompt object. | ### prompt.updated • **prompt.updated**(prompt) The state of a prompt changed. #### Parameters | Name | Type | Description | |:|:|:--| | prompt | [CallPrompt](./callprompt.mdx) | A prompt object. | ### recording.ended • **recording.ended**(recording) A recording ended. #### Parameters | Name | Type | Description | |:|:|:--| | recording | [CallRecording](./callrecording.mdx) | A recording object. | ### recording.failed • **recording.failed**(recording) A recording failed. #### Parameters | Name | Type | Description | |:|:|:--| | recording | [CallRecording](./callrecording.mdx) | A recording object. | ### recording.started • **recording.started**(recording) A recording started. #### Parameters | Name | Type | Description | |:|:|:--| | recording | [CallRecording](./callrecording.mdx) | A recording object. | ### recording.updated • **recording.updated**(recording) The state of a recording changed. #### Parameters | Name | Type | Description | |:|:|:--| | recording | [CallRecording](./callrecording.mdx) | A recording object. | ### tap.ended • **tap.ended**(tap) A tap ended. #### Parameters | Name | Type | Description | |:|:|:--| | tap | [CallTap](./calltap.mdx) | A tap object. | ### tap.started • **tap.started**(tap) A tap started. #### Parameters | Name | Type | Description | |:|:|:--| | tap | [CallTap](./calltap.mdx) | A tap object. |