Relay.Calling.Call

All calls in SignalWire have a common generic interface, Relay.Calling.Call. A Relay.Calling.Call is a connection between SignalWire and another device.

Properties

Methods

amd

Alias for detectAnsweringMachine.

amdAsync

Alias for detectAnsweringMachineAsync.

answer

Answer an inbound call.

Parameters

None

Returns

Promise<Relay.Calling.AnswerResult> - Promise object that will be fulfilled with a Relay.Calling.AnswerResult object.

Examples

Answer an inbound call and check if it was successful.

1
// within an async function ..
2
const answerResult = await call.answer()
3
if (answerResult.successful) {
4
5
}

connect

Attempt to connect an existing call to a new outbound call and waits until one of the remote party picks the call or the connect fails.

This method involves complex nested parameters. You can connect to multiple devices in series, parallel, or any combination of both with creative use of the parameters. Series implies one device at a time, while parallel implies multiple devices at the same time.

Parameters

• Structure of a device:

Returns

Promise<Relay.Calling.ConnectResult> - Promise object that will be fulfilled with a Relay.Calling.ConnectResult object.

Examples

Try connecting by calling +18991114444 and +18991114445 in series.

1
const connectResult = await call.connect(
2
  { type: 'phone', to: '+18991114444', timeout: 30 },
3
  { type: 'phone', to: '+18991114445', timeout: 20 }
4
)
5
6
if (connectResult.successful) {
7
  // connectResult.call is the remote leg connected with yours.
8
}

Combine serial and parallel calling. Call +18991114443 first and - if it doesn’t answer - try calling in parallel +18991114444 and +18991114445. If none of the devices answer, continue the same process with +18991114446 and +18991114447.

1
const result = await call.connect(
2
  { type: 'phone', to: '+18991114443', timeout: 30 },
3
  [
4
    { type: 'phone', to: '+18991114444', timeout: 30 },
5
    { type: 'phone', to: '+18991114445', timeout: 20 }
6
  ],
7
  [
8
    { type: 'phone', to: '+18991114446', timeout: 30 },
9
    { type: 'phone', to: '+18991114447', timeout: 20 }
10
  ]
11
)
12
13
if (connectResult.successful) {
14
  // connectResult.call is the remote leg connected with yours.
15
}

Try connecting by calling +18991114444 and +18991114445 in series playing the US ringtone.

1
const params = {
2
  devices: [
3
    { type: 'phone', to: '+18991114444' },
4
    { type: 'phone', to: '+18991114445' }
5
  ],
6
  ringback: { type: 'ringtone', name: 'us' }
7
}
8
const connectResult = await call.connect(params)
9
if (connectResult.successful) {
10
  // connectResult.call is the remote leg connected with yours.
11
}

connectAsync

Asynchronous version of connect. It does not wait the connect to completes or fails but returns a Relay.Calling.ConnectAction you can interact with.

Parameters

See connect for the parameter list.

Returns

Promise<Relay.Calling.ConnectAction> - Promise object that will be fulfilled with a Relay.Calling.ConnectAction object.

Examples

Trying to connect a call by calling in series +18991114444 and +18991114445.

1
async function main() {
2
  const connectAction = await call.connectAsync(
3
    { type: 'phone', to: '+18991114444', timeout: 30 },
4
    { type: 'phone', to: '+18991114445', timeout: 20 }
5
  )
6
  // .. do other important things while Relay try to connect your call..
7
8
  // Check whether the action has completed
9
  if (connectAction.completed) {
10
11
  }
12
}
13
14
main().catch(console.error)

faxReceive

Prepare the call to receive an inbound fax. It waits until the fax has been received or failed.

Parameters

None

Returns

Promise<Relay.Calling.FaxResult> - Promise object that will be fulfilled with a Relay.Calling.FaxResult object.

Examples

Receiving a fax on the call and print logs for URL and number of received pages.

1
async function main() {
2
  const faxResult = await call.faxReceive()
3
  if (faxResult.successful) {
4
    console.log('URL: ', faxResult.document)
5
    console.log('Total pages: ', faxResult.pages)
6
  }
7
}
8
9
main().catch(console.error)

faxReceiveAsync

Asynchronous version of faxReceive. It does not wait the fax to be received but returns a Relay.Calling.FaxAction you can interact with.

Parameters

None

Returns

Promise<Relay.Calling.FaxAction> - Promise object that will be fulfilled with a Relay.Calling.FaxAction object.

Examples

Trying to receive a fax. Stop the attempt after 5 seconds.

1
async function main() {
2
  const faxAction = await call.faxReceiveAsync()
3
4
  setTimeout(async () => {
5
    await faxAction.stop()
6
  }, 5000)
7
}
8
9
main().catch(console.error)

faxSend

Send a Fax through the call. It waits until the fax has been sent or failed.

Parameters

Returns

Promise<Relay.Calling.FaxResult> - Promise object that will be fulfilled with a Relay.Calling.FaxResult object.

Examples

Sending a fax on the call and print logs the number of sent pages.

1
async function main() {
2
  const faxResult = await call.faxSend('https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf', null, 'Custom Header')
3
  if (faxResult.successful) {
4
    console.log('URL: ', faxResult.document)
5
    console.log('Total pages: ', faxResult.pages)
6
  }
7
}
8
9
main().catch(console.error)

faxSendAsync

Asynchronous version of faxSend. It does not wait the fax to be sent but returns a Relay.Calling.FaxAction you can interact with.

Parameters

See faxSend for the parameter list.

Returns

Promise<Relay.Calling.FaxAction> - Promise object that will be fulfilled with a Relay.Calling.FaxAction object.

Examples

Trying to send a fax. Stop sending it after 5 seconds.

1
async function main() {
2
  const faxAction = await call.faxSendAsync('https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf', null, 'Custom Header')
3
4
  setTimeout(async () => {
5
    await faxAction.stop()
6
  }, 5000)
7
}
8
9
main().catch(console.error)

dial

This will start a call that was created with newCall and waits until the Call has been answered or hung up.

Parameters

None

Returns

Promise<Relay.Calling.DialResult> - Promise object that will be fulfilled with a Relay.Calling.DialResult object.

Examples

1
async function main() {
2
  const call = client.calling.newCall({ type: 'phone', from: '+1XXXXXXXXXX', to: '+1YYYYYYYYYY' })
3
4
  const dialResult = await call.dial()
5
}
6
7
main().catch(console.error)

hangup

Hangup the call.

Parameters

None

Returns

Promise<Relay.Calling.HangupResult> - Promise object that will be fulfilled with a Relay.Calling.HangupResult object.

Examples

Hangup a call and check if it was successful.

1
// within an async function ..
2
const hangupResult = await call.hangup()
3
if (hangupResult.successful) {
4
5
}

play

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 playing, see playAudio, playSilence, playTTS or playRingtone for more specific usage.

Parameters

• To play an audio file:

• To play a text to speech string:

• To play silence:

• To play ringtone:

Returns

Promise<Relay.Calling.PlayResult> - Promise object that will be fulfilled with a Relay.Calling.PlayResult object.

Examples

Play multiple media in one request setting volume to 6dB.

1
async function main() {
2
  const params = {
3
    media: [
4
      { type: 'tts', text: 'Listen this awesome file!' },
5
      { type: 'audio', url: 'https://cdn.signalwire.com/default-music/welcome.mp3' },
6
      { type: 'silence', duration: 5 },
7
      { type: 'tts', text: 'Did you like it?' }
8
    ],
9
    volume: 6
10
  }
11
  const playResult = await call.play(params)
12
}
13
14
main().catch(console.error)

playAsync

Asynchronous version of play. It does not wait the playing to completes but returns a Relay.Calling.PlayAction you can interact with.

Parameters

See play for the parameter list.

Returns

Promise<Relay.Calling.PlayAction> - Promise object that will be fulfilled with a Relay.Calling.PlayAction object.

Examples

Play multiple media elements in the call and stop them after 5 seconds.

1
async function main() {
2
  const params = {
3
    media: [
4
      { type: 'tts', text: 'Listen this awesome file!' },
5
      { type: 'audio', url: 'https://cdn.signalwire.com/default-music/welcome.mp3' },
6
      { type: 'silence', duration: 5 },
7
      { type: 'tts', text: 'Did you like it?' }
8
    ],
9
    volume: 6
10
  }
11
  const playAction = await call.playAsync(params)
12
13
  setTimeout(async () => {
14
    await playAction.stop()
15
  }, 5000)
16
}
17
18
main().catch(console.error)

playAudio

This is a helper function that refines the use of play. This simplifies playing an audio file.

Parameters

Returns

Promise<Relay.Calling.PlayResult> - Promise object that will be fulfilled with a Relay.Calling.PlayResult object.

Examples

Play an Mp3 file using the signature with a string as parameter.

1
// within an async function ..
2
const playResult = await call.playAudio('https://cdn.signalwire.com/default-music/welcome.mp3')

Play an Mp3 file setting volume level to 4dB.

1
// within an async function ..
2
const params = {
3
  url: 'https://cdn.signalwire.com/default-music/welcome.mp3',
4
  volume: 4
5
}
6
const playResult = await call.playAudio(params)

playAudioAsync

Asynchronous version of playAudio. It does not wait the playing to completes but returns a Relay.Calling.PlayAction you can interact with.

Parameters

See playAudio for the parameter list.

Returns

Promise<Relay.Calling.PlayAction> - Promise object that will be fulfilled with a Relay.Calling.PlayAction object.

Examples

Play an Mp3 file and stop it after 5 seconds.

1
// within an async function ..
2
const playAction = await call.playAudioAsync('https://cdn.signalwire.com/default-music/welcome.mp3')
3
4
setTimeout(async () => {
5
  await playAction.stop()
6
}, 5000)

playTTS

This is a helper function that refines the use of play. This simplifies playing TTS.

Parameters

Returns

Promise<Relay.Calling.PlayResult> - Promise object that will be fulfilled with a Relay.Calling.PlayResult object.

Examples

Play TTS.

1
// within an async function ..
2
const playResult = await call.playTTS({ text: 'Welcome to SignalWire!', gender: 'male' })

playTTSAsync

Asynchronous version of playTTS. It does not wait the playing to completes but returns a Relay.Calling.PlayAction you can interact with.

Parameters

See playTTS for the parameter list.

Returns

Promise<Relay.Calling.PlayAction> - Promise object that will be fulfilled with a Relay.Calling.PlayAction object.

Examples

Play TTS and stop it after 5 seconds.

1
// within an async function ..
2
const playAction = await call.playTTSAsync({ text: 'Welcome to SignalWire!', gender: 'male' })
3
4
setTimeout(async () => {
5
  await playAction.stop()
6
}, 5000)

playSilence

This is a helper function that refines the use of play. This simplifies playing silence.

Parameters

Returns

Promise<Relay.Calling.PlayResult> - Promise object that will be fulfilled with a Relay.Calling.PlayResult object.

Examples

Play silence for 10 seconds.

1
// within an async function ..
2
const playResult = await call.playSilence(10)

playSilenceAsync

Asynchronous version of playSilence. It does not wait the playing to completes but returns a Relay.Calling.PlayAction you can interact with.

Parameters

See playSilence for the parameter list.

Returns

Promise<Relay.Calling.PlayAction> - Promise object that will be fulfilled with a Relay.Calling.PlayAction object.

Examples

Play silence for 60 seconds, if Agent is available, stop the play.

1
// within an async function ..
2
const playAction = await call.playSilenceAsync(60)
3
4
if (Agent.available()) {
5
  await playAction.stop()
6
}

playRingtone

This is a helper function that refines the use of play. This simplifies playing ringtones.

Parameters

Returns

Promise<Relay.Calling.PlayResult> - Promise object that will be fulfilled with a Relay.Calling.PlayResult object.

Examples

Play a single US ringtone.

1
// within an async function ..
2
const playResult = await call.playRingtone({ name: 'us' })

playRingtoneAsync

Asynchronous version of playRingtone. It does not wait the playing to completes but returns a Relay.Calling.PlayAction you can interact with.

Parameters

See playRingtone for the parameter list.

Returns

Promise<Relay.Calling.PlayAction> - Promise object that will be fulfilled with a Relay.Calling.PlayAction object.

Examples

Play US ringtone for 30 seconds and stop it after 5 seconds.

1
// within an async function ..
2
const playAction = await call.playRingtoneAsync({ name: 'us', duration: 30 })
3
4
setTimeout(async () => {
5
  await playAction.stop()
6
}, 5000)

detect

Start a detector on the call and waits until it has finished or failed.

The detect method is a generic method for all types of detecting, see detectAnsweringMachine, detectDigit or detectFax for more specific usage.

Parameters

• To detect an answering machine:

• To detect digits:

• To detect a fax:

Returns

Promise<Relay.Calling.DetectResult> - Promise object that will be fulfilled with a Relay.Calling.DetectResult object.

Examples

Detect a machine with custom parameters and timeout.

1
// within an async function ..
2
const detectResult = await call.detect({ type: 'machine', timeout: 45, initial_timeout: 3 })
3
if (detectResult.successful) {
4
5
}

Detect a Fax setting timeout only.

1
// within an async function ..
2
const detectResult = await call.detect({ type: 'fax', timeout: 45 })
3
if (detectResult.successful) {
4
5
}

detectAsync

Asynchronous version of detect. It does not wait the detector ends but returns a Relay.Calling.DetectAction you can interact with.

Parameters

See detect for the parameter list.

Returns

Promise<Relay.Calling.DetectAction> - Promise object that will be fulfilled with a Relay.Calling.DetectAction object.

Examples

Detect all the digits using default parameters. Stop the action after 5 seconds.

1
async function main() {
2
  call.on('detect.update', (call, params) => {
3
    console.log('Detector event:', params)
4
  })
5
6
  const detectAction = await call.detectAsync('fax')
7
  // Do other things while detector runs and then stop it..
8
  setTimeout(async () => {
9
    await detectAction.stop()
10
  }, 5000)
11
}
12
13
main().catch(console.error)

detectAnsweringMachine

This is a helper function that refines the use of detect. The Promise will be resolved with a Relay.Calling.DetectResult object as soon as the detector decided who answered the call: MACHINE, HUMAN or UNKNOWN.

Parameters

Returns

Promise<Relay.Calling.DetectResult> - Promise object that will be fulfilled with a Relay.Calling.DetectResult object.

Examples

Perform an AMD and wait until the machine is ready.

1
// within an async function ..
2
const { successful, result } = await call.detectAnsweringMachine({ wait_for_beep: true })
3
if (successful) {
4
  console.log('AMD result:', result) // MACHINE || HUMAN || UNKNOWN
5
}

detectAnsweringMachineAsync

Asynchronous version of detectAnsweringMachine. It does not wait the detector ends but returns a Relay.Calling.DetectAction you can interact with.

Parameters

See detectAnsweringMachine for the parameter list.

Returns

Promise<Relay.Calling.DetectAction> - Promise object that will be fulfilled with a Relay.Calling.DetectAction object.

Examples

Perform an asynchronous AMD on the call. Then stop the action if not completed yet.

1
// within an async function ..
2
call.on('detect.update', (call, params) => {
3
  // Handle a detector event here..
4
  console.log(params)
5
})
6
const detectAction = await call.detectAnsweringMachineAsync()
7
// Do other things while detector runs and then stop it.
8
if (detectAction.completed) {
9
  detectAction.stop()
10
}

detectDigit

This is a helper function that refines the use of detect. This simplifies detecting digits on a call.

Parameters

Returns

Promise<Relay.Calling.DetectResult> - Promise object that will be fulfilled with a Relay.Calling.DetectResult object.

Examples

Detect digits and then write a log with the result.

1
// within an async function ..
2
const detectResult = await call.detectDigit()
3
if (detectResult.successful) {
4
  console.log('Digits detected:', detectResult.result)
5
}

detectDigitAsync

Asynchronous version of detectDigit. It does not wait the detector ends but returns a Relay.Calling.DetectAction you can interact with.

Parameters

See detectDigit for the parameter list.

Returns

Promise<Relay.Calling.DetectAction> - Promise object that will be fulfilled with a Relay.Calling.DetectAction object.

Examples

Detect only 1-3 digits. Stop the action after 5 seconds.

1
async function main() {
2
  const detectAction = await call.detectDigitAsync({ digits: '123' })
3
4
  setTimeout(async () => {
5
    await detectAction.stop()
6
  }, 5000)
7
}
8
9
main().catch(console.error)

detectFax

This is a helper function that refines the use of detect. This simplifies detecting a fax.

Parameters

Returns

Promise<Relay.Calling.DetectResult> - Promise object that will be fulfilled with a Relay.Calling.DetectResult object.

Examples

Detect fax on the current call.

1
// within an async function ..
2
const detectResult = await call.detectFax()
3
if (detectResult.successful) {
4
  // A fax has been detected!
5
}

detectFaxAsync

Asynchronous version of detectFax. It does not wait the detector ends but returns a Relay.Calling.DetectAction you can interact with.

Parameters

See detectFax for the parameter list.

Returns

Promise<Relay.Calling.DetectAction> - Promise object that will be fulfilled with a Relay.Calling.DetectAction object.

Examples

Detect fax on the current call. Stop the action after 5 seconds.

1
async function main() {
2
  const detectAction = await call.detectFaxAsync()
3
4
  setTimeout(async () => {
5
    await detectAction.stop()
6
  }, 5000)
7
}
8
9
main().catch(console.error)

prompt

Play one or multiple media while collecting user’s input from the call at the same time, such as digits and speech. It waits until the collection succeed or timeout is reached.

The prompt method is a generic method, see promptAudio, promptTTS or promptRingtone for more specific usage.

Parameters

• To collect digits:

• To collect speech:

Returns

Promise<Relay.Calling.PromptResult> - Promise object that will be fulfilled with a Relay.Calling.PromptResult object.

Examples

Ask user to enter their PIN and collect the digits.

1
async function main() {
2
  const params = {
3
    type: 'digits',
4
    digits_max: 4,
5
    digits_terminators: '#',
6
    media: [
7
      { type: 'tts', text: 'Welcome at SignalWire. Please, enter your PIN and then # to proceed' }
8
    ]
9
  }
10
  const promptResult = await call.prompt(params)
11
12
  if (promptResult.successful) {
13
    const type = promptResult.type // digit
14
    const pin = promptResult.result // pin entered by the user
15
  }
16
}
17
18
main().catch(console.error)

promptAsync

Asynchronous version of prompt. It does not wait the collection to completes but returns a Relay.Calling.PromptAction you can interact with.

Parameters

See prompt for the parameter list.

Returns

Promise<Relay.Calling.PromptAction> - Promise object that will be fulfilled with a Relay.Calling.PromptAction object.

Examples

Ask user to enter their PIN and collect the digits.

1
async function main() {
2
  const params = {
3
    type: 'digits',
4
    digits_max: 4,
5
    digits_terminators: '#',
6
    media: [
7
      { type: 'tts', text: 'Welcome at SignalWire. Please, enter your PIN and then # to proceed' },
8
      { type: 'audio', url: 'https://cdn.signalwire.com/default-music/welcome.mp3' }
9
    ]
10
  }
11
  const promptAction = await call.promptAsync(params)
12
  // .. do other important things while collecting user digits..
13
14
  if (promptAction.completed) {
15
    const result = promptAction.result // => PromptResult object
16
  }
17
}
18
19
main().catch(console.error)

promptAudio

This is a helper function that refines the use of prompt. This function simplifies playing an audio file while collecting user’s input from the call, such as digits and speech.

Parameters

You can set all the properties that prompt accepts replacing media with:

The SDK will build the media for you.

Returns

Promise<Relay.Calling.PromptResult> - Promise object that will be fulfilled with a Relay.Calling.PromptResult object.

Examples

Collect user’s digits while playing an Mp3 file.

1
async function main() {
2
  const params = {
3
    type: 'digits',
4
    digits_max: 4,
5
    url: 'https://cdn.signalwire.com/default-music/welcome.mp3'
6
  }
7
  const promptResult = await call.promptAudio(params)
8
9
  if (promptResult.successful) {
10
    const type = promptResult.type // digit
11
    const digits = promptResult.result // digits entered by the user
12
  }
13
}
14
15
main().catch(console.error)

promptAudioAsync

Asynchronous version of promptAudio. It does not wait the collection to completes but returns a Relay.Calling.PromptAction you can interact with.

Parameters

See promptAudio for the parameter list.

Returns

Promise<Relay.Calling.PromptAction> - Promise object that will be fulfilled with a Relay.Calling.PromptAction object.

Examples

Ask user to enter their PIN and collect the digits.

1
async function main() {
2
  const params = {
3
    type: 'digits',
4
    digits_max: 4,
5
    url: 'https://cdn.signalwire.com/default-music/welcome.mp3'
6
  }
7
  const promptAction = await call.promptAudioAsync(params)
8
  // .. do other important things while collecting user digits..
9
10
  if (promptAction.completed) {
11
    const result = promptAction.result // => PromptResult object
12
  }
13
}
14
15
main().catch(console.error)

promptTTS

This is a helper function that refines the use of prompt. This function simplifies playing TTS while collecting user’s input from the call, such as digits and speech.

Parameters

You can set all the properties that prompt accepts replacing media with:

The SDK will build the media for you.

Returns

Promise<Relay.Calling.PromptResult> - Promise object that will be fulfilled with a Relay.Calling.PromptResult object.

Examples

Ask user to enter their PIN and collect the digits.

1
async function main() {
2
  const params = {
3
    type: 'digits',
4
    digits_max: 3,
5
    text: 'Please, enter your 3 digit PIN',
6
    gender: 'male'
7
  }
8
  const promptResult = await call.promptTTS(params)
9
  if (promptResult.successful) {
10
    const type = promptResult.type // digit
11
    const pin = promptResult.result // pin entered by the user
12
  }
13
}
14
15
main().catch(console.error)

promptTTSAsync

Asynchronous version of promptTTS. It does not wait the collection to completes but returns a Relay.Calling.PromptAction you can interact with.

Parameters

See promptTTS for the parameter list.

Returns

Promise<Relay.Calling.PromptAction> - Promise object that will be fulfilled with a Relay.Calling.PromptAction object.

Examples

Ask user to enter their PIN and collect the digits.

1
async function main() {
2
  const params = {
3
    type: 'digits',
4
    digits_max: 3,
5
    text: 'Please, enter your 3 digit PIN',
6
    gender: 'male'
7
  }
8
  const promptAction = await call.promptTTSAsync(params)
9
  // .. do other important things while collecting user digits..
10
11
  if (promptAction.completed) {
12
    const result = promptAction.result // => PromptResult object
13
  }
14
}
15
16
main().catch(console.error)

detectHuman

This is a helper function that refines the use of detect. This simplifies detecting a human on the call and is the inverse of detectMachine.

Deprecated since: v2.2 - Use detectAnsweringMachine instead.

Parameters

Returns

Promise<Relay.Calling.DetectResult> - Promise object that will be fulfilled with a Relay.Calling.DetectResult object.

Examples

Detect a human on the current call.

1
// within an async function ..
2
const detectResult = await call.detectHuman()
3
if (detectResult.successful) {
4
  // Human has been detected!
5
}

detectHumanAsync

Asynchronous version of detectHuman. It does not wait the detector ends but returns a Relay.Calling.DetectAction you can interact with.

Deprecated since: v2.2 - Use detectAnsweringMachineAsync instead.

Parameters

See detectHuman for the parameter list.

Returns

Promise<Relay.Calling.DetectAction> - Promise object that will be fulfilled with a Relay.Calling.DetectAction object.

Examples

Detect a human on the current call. Stop the action after 5 seconds.

1
async function main() {
2
  const detectAction = await call.detectHumanAsync()
3
4
  setTimeout(async () => {
5
    await detectAction.stop()
6
  }, 5000)
7
}
8
9
main().catch(console.error)

detectMachine

This is a helper function that refines the use of detect. This simplifies detecting a machine on the call and is the inverse of detectHuman.

Deprecated since: v2.2 - Use detectAnsweringMachine instead.

Parameters

Returns

Promise<Relay.Calling.DetectResult> - Promise object that will be fulfilled with a Relay.Calling.DetectResult object.

Examples

Detect a machine on the current call.

1
// within an async function ..
2
const detectResult = await call.detectMachine()
3
if (detectResult.successful) {
4
  // A machine has been detected!
5
}

detectMachineAsync

Asynchronous version of detectMachine. It does not wait the detector ends but returns a Relay.Calling.DetectAction you can interact with.

Deprecated since: v2.2 - Use detectAnsweringMachineAsync instead.

Parameters

See detectMachine for the parameter list.

Returns

Promise<Relay.Calling.DetectAction> - Promise object that will be fulfilled with a Relay.Calling.DetectAction object.

Examples

Detect a machine on the current call. Stop the action after 5 seconds.

1
async function main() {
2
  const detectAction = await call.detectMachineAsync()
3
4
  setTimeout(async () => {
5
    await detectAction.stop()
6
  }, 5000)
7
}
8
9
main().catch(console.error)

on

Attach an event handler for the event.

Parameters

Returns

Relay.Calling.Call - The call object itself.

Examples

Subscribe to the answered and ended events for a given call.

1
call.on('answered', (call) => {
2
  // Call has been answered from the remote party!
3
}).on('ended', (call) => {
4
  // Call has ended.. cleanup something?
5
})

off

Remove an event handler that were attached with .on(). If you don’t pass a handler, all listeners for that event will be removed.

Parameters

Returns

Relay.Calling.Call - The call object itself.

Examples

Subscribe to the call ended state change and then, remove the event handler.

1
const callEndedHandler = (call) => {
2
  // Call has ended.
3
})
4
5
call.on('ended', callEndedHandler)
6
7
// .. later
8
call.off('ended', callEndedHandler)

pass

This will allow a consumer to decline incoming calls without ending the call and redirect the call to another RELAY consumer.

Parameters

None

Returns

Promise<Relay.Calling.PassResult> - Promise object that will be fulfilled with a Relay.Calling.PassResult object.

Examples

Pass the inbound call.

1
import { RelayConsumer } from '@signalwire/node'
2
3
const consumer = new RelayConsumer({
4
    project: process.env.PROJECT,
5
    token: process.env.TOKEN,
6
    contexts: ['home', 'office'],
7
    onIncomingCall: async (call) => {
8
        console.log('Inbound call', call.id, call.from, call.to)
9
10
        // Pass call to another consumer 
11
        const passResult = await call.pass()
12
        if (!passResult.successful) {
13
            console.error('Error passing the call')
14
            return
15
        }
16
17
        console.log('Call passed to another consumer!')
18
    }
19
})
20
21
consumer.run()

record

Start recording the call and waits until the recording ends or fails.

Parameters

Returns

Promise<Relay.Calling.RecordResult> - Promise object that will be fulfilled with a Relay.Calling.RecordResult object.

Examples

Start recording audio in the call for both direction in stereo mode, if successful, grab url, duration and size from the RecordResult object.

1
async function main() {
2
  const params = {
3
    stereo: true,
4
    direction: 'both'
5
  }
6
  const recordResult = await call.record(params)
7
8
  if (recordResult.successful) {
9
    const { url, duration, size } = recordResult
10
  }
11
}
12
13
main().catch(console.error)

recordAsync

Asynchronous version of record. It does not wait the end of recording but returns a Relay.Calling.RecordAction you can interact with.

Parameters

See record for the parameter list.

Returns

Promise<Relay.Calling.RecordAction> - Promise object that will be fulfilled with a Relay.Calling.RecordAction object.

Examples

Start recording audio in the call for both direction in stereo mode and stop it after 5 seconds.

1
async function main() {
2
  const params = {
3
    stereo: true,
4
    direction: 'both'
5
  }
6
  const recordAction = await call.recordAsync(params)
7
8
  setTimeout(async () => {
9
    await recordAction.stop()
10
  }, 5000)
11
}
12
13
main().catch(console.error)

refer

Transfer a SIP call to an external SIP endpoint.

Parameters

Returns

Promise<Relay.Calling.ReferResult> - Promise object that will be fulfilled with a Relay.Calling.ReferResult object.

Examples

Transfer the call to another SIP endpoint.

1
async function main() {
2
  const params = {
3
    to: 'sip:user@sip.example.com',
4
  }
5
  const referResult = await call.refer(params)
6
7
  if (referResult.successful) {
8
    const { referTo, referNotifyCode, referResponseCode } = referResult
9
  }
10
}
11
12
main().catch(console.error)

referAsync

Asynchronous version of refer. It does not wait the end of the REFER but returns a Relay.Calling.ReferAction you can interact with.

Parameters

See refer for the parameter list.

Returns

Promise<Relay.Calling.ReferAction> - Promise object that will be fulfilled with a Relay.Calling.ReferAction object.

Examples

Async transfer the call to another SIP endpoint.

1
async function main() {
2
  const params = {
3
    to: 'sip:user@sip.example.com',
4
  }
5
6
  call.on('refer.success', (params) => {
7
    // listen for the success event
8
    console.log('Refer success', params)
9
  })
10
11
  const referAction = await call.referAsync(params)
12
}
13
14
main().catch(console.error)

sendDigits

This method sends DTMF digits to the other party on the call.

Parameters

Returns

Promise<Relay.Calling.SendDigitsResult> - Promise object that will be fulfilled with a Relay.Calling.SendDigitsResult object.

Examples

Send some digits.

1
async function main() {
2
  const result = await call.sendDigits('123')
3
}
4
5
main().catch(console.error)

sendDigitsAsync

Asynchronous version of sendDigits. It does not wait for the sending event to complete, and immediately returns a Relay.Calling.SendDigitsAction object you can interact with.

Parameters

See sendDigits for the parameter list.

Returns

Promise<Relay.Calling.SendDigitsAction> - Promise object that will be fulfilled with a Relay.Calling.SendDigitsAction object.

Examples

Send some digits and then check if the operation is completed using the SendDigitsAction object.

1
async function main() {
2
  const action = await call.sendDigitsAsync('123')
3
4
  setTimeout(() => {
5
    if (action.completed) {
6
      // ...
7
    }
8
  }, 1000)
9
}
10
11
main().catch(console.error)

tap

Intercept call media and stream it to the specify endpoint. It waits until the end of the call.

Parameters

• To tap through RTP:

Returns

Promise<Relay.Calling.TapResult> - Promise object that will be fulfilled with a Relay.Calling.TapResult object.

Examples

Tapping audio from the call, if successful, print both source and destination devices from the TapResult object.

1
// within an async function ..
2
const params = {
3
  audio_direction: 'both',
4
  target_type: 'rtp',
5
  target_addr: '192.168.1.1',
6
  target_port: 1234
7
}
8
const tapResult = await call.tap(params)
9
if (tapResult.successful) {
10
  const { sourceDevice, destinationDevice } = tapResult
11
  console.log(sourceDevice)
12
  console.log(destinationDevice)
13
}

tapAsync

Asynchronous version of tap. It does not wait the end of tapping but returns a Relay.Calling.TapAction you can interact with.

Parameters

See tap for the parameter list.

Returns

Promise<Relay.Calling.TapAction> - Promise object that will be fulfilled with a Relay.Calling.TapAction object.

Examples

Tapping audio from the call and then stop it using the TapAction object.

1
// within an async function ..
2
const params = {
3
  audio_direction: 'both',
4
  target_type: 'rtp',
5
  target_addr: '192.168.1.1',
6
  target_port: 1234
7
}
8
const tapAction = await call.tapAsync(params)
9
// Do other things while tapping the media and then stop it..
10
setTimeout(async () => {
11
  await tapAction.stop()
12
}, 5000)

promptRingtone

This is a helper function that refines the use of prompt. This function simplifies playing ringtones while collecting user’s input from the call, such as digits and speech.

Parameters

You can set all the properties that prompt accepts replacing media with:

The SDK will build the media for you.

Returns

Promise<Relay.Calling.PromptResult> - Promise object that will be fulfilled with a Relay.Calling.PromptResult object.

Examples

Play US ringtone for 30 seconds while collect digits.

1
async function main() {
2
  const params = {
3
    type: 'digits',
4
    digits_max: 3,
5
    name: 'us',
6
    duration: 30
7
  }
8
  const promptResult = await call.promptRingtone(params)
9
  if (promptResult.successful) {
10
    const type = promptResult.type // digit
11
    const pin = promptResult.result // pin entered by the user
12
  }
13
}
14
15
main().catch(console.error)

promptRingtoneAsync

Asynchronous version of promptRingtone. It does not wait the collection to completes but returns a Relay.Calling.PromptAction you can interact with.

Parameters

See promptRingtone for the parameter list.

Returns

Promise<Relay.Calling.PromptAction> - Promise object that will be fulfilled with a Relay.Calling.PromptAction object.

Examples

Play US ringtone for 30 seconds while collect digits in asynchronous.

1
async function main() {
2
  const params = {
3
    type: 'digits',
4
    digits_max: 3,
5
    name: 'us',
6
    duration: 30
7
  }
8
  const promptAction = await call.promptRingtoneAsync(params)
9
  // .. do other important things while collecting user digits..
10
11
  if (promptAction.completed) {
12
    const result = promptAction.result // => PromptResult object
13
  }
14
}
15
16
main().catch(console.error)

waitFor

Wait for specific events on the Call or returns false if the Call ends without getting them.

Parameters

Returns

Promise<boolean> - Promise resolved with true or false.

Examples

Wait for ending or ended events.

1
// within an async function ..
2
const success = await call.waitFor('ending', 'ended')
3
if (success) {
4
  // ...
5
}

waitForAnswered

This is a helper function that refines the use of waitFor. This simplifies waiting for the answered state.

Parameters

None

Returns

Promise<boolean> - Promise resolved with true or false.

Examples

Wait for the answered event.

1
// within an async function ..
2
const success = await call.waitForAnswered()
3
if (success) {
4
  // ...
5
}

waitForEnded

This is a helper function that refines the use of waitFor. This simplifies waiting for the ended state.

Parameters

None

Returns

Promise<boolean> - Promise resolved with true or false.

Examples

Wait for the ended event.

1
// within an async function ..
2
const success = await call.waitForEnded()
3
if (success) {
4
  // ...
5
}

waitForEnding

This is a helper function that refines the use of waitFor. This simplifies waiting for the ending state.

Parameters

None

Returns

Promise<boolean> - Promise resolved with true or false.

Examples

Wait for the ending event.

1
// within an async function ..
2
const success = await call.waitForEnding()
3
if (success) {
4
  // ...
5
}

waitForRinging

This is a helper function that refines the use of waitFor. This simplifies waiting for the ringing state.

Parameters

None

Returns

Promise<boolean> - Promise resolved with true or false.

Examples

Wait for the ringing event.

1
// within an async function ..
2
const success = await call.waitForRinging()
3
if (success) {
4
  // ...
5
}

Events

All these events can be used to track the calls lifecycle and instruct SignalWire on what to do for each different state.

State Events

To track the state of a call.

Connect Events

To track the connect state of a call.

Play Events

To track a playback state.

Record Events

To track a recording state.

Refer Events

To track a REFER state.

Prompt Events

To track a prompt state.

Fax Events

To track a fax state.

Detect Events

To track a detector state.

Tap Events

To track a tapping state.

Digits Events

To track a send digits action state.

Ringtones

Here you can find all the accepted values for the ringtone to play, based on short country codes: