Relay.Calling.Call

Relay.Calling.Call

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

Properties

Methods

amd

Alias for detect_answering_machine.

amd_async

Alias for detect_answering_machine_async.

answer

Answer an inbound call.

Parameters

None

Returns

coroutine - Coroutine that will return a Relay.Calling.AnswerResult object.

Examples

Answer an inbound call and check if it was successful:

1
result = await call.answer()
2
if result.successful:
3
  print('Call answered..')
4
else:
5
  print('Call failed or not answered.')

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

Returns

coroutine - Coroutine that will return a Relay.Calling.ConnectResult object.

Examples

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

1
devices = [
2
  { 'to_number': '+18991114444', 'timeout': 10 },
3
  { 'to_number': '+18991114445', 'timeout': 20 }
4
]
5
result = await call.connect(device_list=devices)
6
if result.successful:
7
  # result.call is the remote leg connected with yours
8
  remote_call = result.call

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
devices = [
2
  { 'to_number': '+18991114443', 'timeout': 30 },
3
  [
4
    { 'to_number': '+18991114444', 'timeout': 30 },
5
    { 'to_number': '+18991114445', 'timeout': 20 }
6
  ],
7
  [
8
    { 'to_number': '+18991114446', 'timeout': 30 },
9
    { 'to_number': '+18991114447', 'timeout': 20 }
10
  ]
11
]
12
result = await call.connect(device_list=devices)
13
14
if result.successful:
15
  # result.call is the remote leg connected with yours.
16
  remote_call = result.call

connect_async

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

coroutine - Coroutine that will return a Relay.Calling.ConnectAction object.

Examples

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

1
devices = [
2
  { 'to_number': '+18991114444', 'timeout': 10 },
3
  { 'to_number': '+18991114445', 'timeout': 20 }
4
]
5
action = await call.connect_async(device_list=devices)
6
# .. do other important things while Relay try to connect your call..
7
8
# .. check whether the action has completed
9
if action.completed:
10
  # Your call is now connected with a remote peer

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 detect_answering_machine, detect_digit or detect_fax for more specific usage.

Parameters

• To detect an answering machine:

• To detect digits:

• To detect a fax:

Returns

coroutine - Coroutine that will return a Relay.Calling.DetectResult object.

Examples

Detect a machine with custom parameters and timeout:

1
result = await call.detect(detect_type='machine', timeout=45, initial_timeout=3)
2
if result.successful:
3
  print(f'Detector Result: {result.result}')

Detect a Fax setting timeout only:

1
result = await call.detect(detect_type='fax', timeout=45)
2
if result.successful:
3
  print(f'Detector Result: {result.result}')

detect_async

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

coroutine - Coroutine that will return a Relay.Calling.DetectAction object.

Examples

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

1
import asyncio # to use sleep
2
3
action = await call.detect_async(detect_type='digit')
4
# For demonstration purposes only..
5
await asyncio.sleep(5)
6
await action.stop()

detect_answering_machine

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

Parameters

Returns

coroutine - Coroutine that will return a Relay.Calling.DetectResult object.

Examples

Perform an AMD and wait until the machine is ready:

1
result = await call.detect_answering_machine(wait_for_beep=True)
2
if result.successful:
3
  print(f'AMD result: {result.result}') # MACHINE || HUMAN || UNKNOWN

detect_answering_machine_async

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

Parameters

See detect_answering_machine for the parameter list.

Returns

coroutine - Coroutine that will return a Relay.Calling.DetectAction object.

Examples

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

1
action = await call.detect_answering_machine_async()
2
# Do other things while detector runs and then stop it...
3
if action.completed:
4
  detect_result = action.result.result # MACHINE || HUMAN || UNKNOWN
5
  await action.stop()

detect_digit

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

Parameters

Returns

coroutine - Coroutine that will return a Relay.Calling.DetectResult object.

Examples

Detect digits and then write a log with the result:

1
result = await call.detect_digit()
2
if result.successful:
3
  print(f'Digits detected: {result.result}')

detect_digit_async

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

Parameters

See detect_digit for the parameter list.

Returns

coroutine - Coroutine that will return a Relay.Calling.DetectAction object.

Examples

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

1
import asyncio # to use sleep
2
3
action = await call.detect_digit_async(digits='123')
4
await asyncio.sleep(5)
5
await action.stop()

detect_fax

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

Parameters

Returns

coroutine - Coroutine that will return a Relay.Calling.DetectResult object.

Examples

Detect fax on the current call:

1
result = await call.detect_fax()
2
if result.successful:
3
  # A fax has been detected!

detect_fax_async

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

Parameters

See detect_fax for the parameter list.

Returns

coroutine - Coroutine that will return a Relay.Calling.DetectAction object.

Examples

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

1
import asyncio # to use sleep
2
3
action = await call.detect_fax_async()
4
await asyncio.sleep(5)
5
await action.stop()

dial

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

Parameters

None

Returns

coroutine - Coroutine that will return a Relay.Calling.DialResult object.

Examples

1
call = client.calling.new_call(from_number='+1XXXXXXXXXX', to_number='+1YYYYYYYYYY')
2
result = await call.dial()
3
if result.successful:
4
  print('Call answered..')
5
else:
6
  print('Call failed or not answered.')

fax_receive

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

Parameters

None

Returns

coroutine - Coroutine that will return a Relay.Calling.FaxResult object.

Examples

Receiving a fax on the call and grab URL and number of received pages from the FaxResult object:

1
result = await call.fax_receive()
2
if result.successful:
3
  url = result.document # URL location of the document
4
  num_pages = result.pages

fax_receive_async

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

Parameters

None

Returns

coroutine - Coroutine that will return a Relay.Calling.FaxAction object.

Examples

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

1
import asyncio # to use sleep
2
3
action = await call.fax_receive_async()
4
# For demonstration purposes only..
5
await asyncio.sleep(5)
6
await action.stop()

fax_send

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

Parameters

Returns

coroutine - Coroutine that will return a Relay.Calling.FaxResult object.

Examples

Sending a fax on the call and grab URL and number of received pages from the FaxResult object:

1
result = await call.fax_send(url='https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf', header='Custom Header')
2
if result.successful:
3
  url = result.document # URL location of the document
4
  num_pages = result.pages

fax_send_async

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

Parameters

See fax_send for the parameter list.

Returns

coroutine - Coroutine that will return a Relay.Calling.FaxAction object.

Examples

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

1
import asyncio # to use sleep
2
3
action = await call.fax_send_async(url='https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf', header='Custom Header')
4
# For demonstration purposes only..
5
await asyncio.sleep(5)
6
await action.stop()

hangup

Hangup the call.

Parameters

None

Returns

coroutine - Coroutine that will return a Relay.Calling.HangupResult object.

Examples

Hangup a call and check if it was successful:

1
result = await call.hangup()
2
if result.successful:
3
  print('Call hanged up..')

on

Attach an event handler for the event.

Parameters

Returns

Relay.Calling.Call - The call object itself.

Examples

Subscribe to the answered events for a given call:

1
def on_answered():
2
  # Call has been answered from the remote party!
3
4
call.on('answered', on_answered)

off

Remove an event handler that were attached with .on(). If you don’t pass a callback, 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
def on_ended():
2
  pass
3
4
call.on('ended', on_ended)
5
6
# .. later
7
call.off('ended', on_ended)

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 play_audio, play_silence or play_tts for more specific usage.

Parameters

• To play an audio file:

• To play a text to speech string:

• To play silence:

Returns

coroutine - Coroutine that will return a Relay.Calling.PlayResult object.

Examples

Play multiple media elements in the call:

1
media_list = [
2
  { 'type': 'tts', 'text': 'Listen this awesome file!' },
3
  { 'type': 'audio', 'url': 'https://cdn.signalwire.com/default-music/welcome.mp3' },
4
  { 'type': 'silence', 'duration': 5 },
5
  { 'type': 'tts', 'text': 'Did you like it?' }
6
]
7
result = await call.play(media_list)

play_async

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

coroutine - Coroutine that will return a Relay.Calling.PlayAction object.

Examples

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

1
import asyncio # to use sleep
2
3
media_list = [
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
action = await call.play_async(media_list)
10
await asyncio.sleep(5)
11
await action.stop()

play_audio

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

Parameters

Returns

coroutine - Coroutine that will return a Relay.Calling.PlayResult object.

Examples

Play an Mp3 file:

1
result = await call.play_audio('https://cdn.signalwire.com/default-music/welcome.mp3')

play_audio_async

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

Parameters

See play_audio for the parameter list.

Returns

coroutine - Coroutine that will return a Relay.Calling.PlayAction object.

Examples

Play an Mp3 file and stop it after 5 seconds:

1
import asyncio # to use sleep
2
3
action = await call.play_audio_async('https://cdn.signalwire.com/default-music/welcome.mp3')
4
await asyncio.sleep(5)
5
await action.stop()

play_silence

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

Parameters

Returns

coroutine - Coroutine that will return a Relay.Calling.PlayResult object.

Examples

Play silence for 10 seconds:

1
result = await call.play_silence(10)

play_silence_async

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

Parameters

See play_silence for the parameter list.

Returns

coroutine - Coroutine that will return a Relay.Calling.PlayAction object.

Examples

Play silence for 60 seconds then stop it after 5 seconds:

1
import asyncio # to use sleep
2
3
action = await call.play_silence_async(60)
4
await asyncio.sleep(5)
5
await action.stop()

play_ringtone

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

Parameters

Returns

coroutine - Coroutine that will return a Relay.Calling.PlayResult object.

Examples

Play a single US ringtone:

1
result = await call.play_ringtone(name='us')

play_ringtone_async

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

Parameters

See play_ringtone for the parameter list.

Returns

coroutine - Coroutine that will return a Relay.Calling.PlayAction object.

Examples

Play the US ringtone for 30 seconds but stop it after 5 seconds:

1
import asyncio # to use sleep
2
3
action = await call.play_ringtone_async(name='us', duration=30)
4
# For demonstration purposes only..
5
await asyncio.sleep(5)
6
await action.stop()

play_tts

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

Parameters

Returns

coroutine - Coroutine that will return a Relay.Calling.PlayResult object.

Examples

Play TTS:

1
result = await call.play_tts(text='Welcome to SignalWire!', gender='male')

play_tts_async

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

Parameters

See play_tts for the parameter list.

Returns

coroutine - Coroutine that will return a Relay.Calling.PlayAction object.

Examples

Play TTS and stop it after 5 seconds:

1
import asyncio # to use sleep
2
3
action = await call.play_tts_async(text='Welcome to SignalWire!', gender='male')
4
await asyncio.sleep(5)
5
await action.stop()

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 prompt_audio, prompt_tts or prompt_ringtone for more specific usage.

Parameters

• To collect digits:

• To collect speech:

Returns

coroutine - Coroutine that will return a Relay.Calling.PromptResult object.

Examples

Ask user to enter their PIN and collect the digits:

1
media_list = [
2
  { 'type': 'tts', 'text': 'Welcome at SignalWire. Please, enter your PIN and then # to proceed' }
3
]
4
result = await call.prompt(prompt_type='digits', media_list=media_list, digits_max=4, digits_terminators='#')
5
if result.successful:
6
  pin = result.result # pin entered by the user

prompt_async

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

coroutine - Coroutine that will return a Relay.Calling.PromptAction object.

Examples

Ask user to enter their PIN and collect the digits:

1
media_list = [
2
  { 'type': 'tts', 'text': 'Welcome at SignalWire. Please, enter your PIN and then # to proceed' }
3
  { 'type': 'audio', 'url': 'https://cdn.signalwire.com/default-music/welcome.mp3' }
4
]
5
action = await call.prompt_async(prompt_type='digits', media_list=media_list, digits_max=4, digits_terminators='#')
6
# .. do other important things while collecting user digits..
7
8
if action.completed:
9
  result = action.result # => [`PromptResult`][relay-calling-promptresult] object

prompt_audio

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_list with:

The SDK will build the media_list for you.

Returns

coroutine - Coroutine that will return a Relay.Calling.PromptResult object.

Examples

Collect user’s digits while playing an Mp3 file:

1
result = await call.prompt_audio(prompt_type='digits', url='https://cdn.signalwire.com/default-music/welcome.mp3', digits_max=4)
2
if result.successful:
3
  digits = result.result # digits entered by the user

prompt_audio_async

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

Parameters

See prompt_audio for the parameter list.

Returns

coroutine - Coroutine that will return a Relay.Calling.PromptAction object.

Examples

Ask user to enter their PIN and collect the digits:

1
action = await call.prompt_audio_async(prompt_type='digits', url='https://cdn.signalwire.com/default-music/welcome.mp3', digits_max=4)
2
# .. do other important things while collecting user digits..
3
if action.completed:
4
  result = action.result # => [`PromptResult`][relay-calling-promptresult] object

prompt_ringtone

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_list with:

The SDK will build the media_list for you.

Returns

coroutine - Coroutine that will return a Relay.Calling.PromptResult object.

Examples

Play US ringtone for 30 seconds while collect digits:

1
result = await call.prompt_ringtone(prompt_type='digits', name='us', duration=30, digits_max=4)
2
if result.successful:
3
  digits = result.result # digits entered by the user

prompt_ringtone_async

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

Parameters

See prompt_ringtone for the parameter list.

Returns

coroutine - Coroutine that will return a Relay.Calling.PromptAction object.

Examples

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

1
action = await call.prompt_ringtone_async(prompt_type='digits', name='us', duration=30, digits_max=4)
2
# .. do other important things while collecting user digits..
3
if action.completed:
4
  result = action.result # => [`PromptResult`][relay-calling-promptresult] object

prompt_tts

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_list with:

The SDK will build the media_list for you.

Returns

coroutine - Coroutine that will return a Relay.Calling.PromptResult object.

Examples

Ask user to enter their PIN and collect the digits:

1
result = await call.prompt_tts(prompt_type='digits', text='Please, enter your 3 digit PIN', digits_max=3)
2
if result.successful:
3
  pin = result.result # PIN entered by the user

prompt_tts_async

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

Parameters

See prompt_tts for the parameter list.

Returns

coroutine - Coroutine that will return a Relay.Calling.PromptAction object.

Examples

Ask user to enter their PIN and collect the digits:

1
action = await call.prompt_tts_async(prompt_type='digits', text='Please, enter your 3 digit PIN', gender='male', digits_max=3)
2
# .. do other important things while collecting user digits..
3
if action.completed:
4
  result = action.result # => [`PromptResult`][relay-calling-promptresult] object

record

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

Parameters

Returns

coroutine - Coroutine that will return 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
result = await call.record(stereo=True, direction='both')
2
if result.successful:
3
  print(f'Url: {result.url}')
4
  print(f'Duration: {result.duration}')
5
  print(f'Size: {result.size}')

record_async

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

coroutine - Coroutine that will return 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
import asyncio # to use sleep
2
3
action = await call.record_async(stereo=True, direction='both')
4
await asyncio.sleep(5)
5
await action.stop()

send_digits

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

Parameters

Returns

coroutine - Coroutine that will return a Relay.Calling.SendDigitsResult object.

Examples

Send some digits:

1
result = await call.send_digits('123')

send_digits_async

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

Parameters

See send_digits for the parameter list.

Returns

coroutine - Coroutine that will return a Relay.Calling.SendDigitsAction

Examples

Send some digits and stop the operation after 3 seconds:

1
import asyncio # to use sleep
2
3
action = await call.send_digits_async('1W2W3W4w5w6W7W8W9')
4
5
await asyncio.sleep(3)
6
await action.stop()

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

coroutine - Coroutine that will return a Relay.Calling.TapResult object.

Examples

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

1
result = await call.tap(audio_direction='listen', target_type='rtp', target_addr='192.168.1.1', target_port=1234)
2
if result.successful:
3
  # Print source and destination devices..
4
  print(result.source_device)
5
  print(result.destination_device)

tap_async

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

coroutine - Coroutine that will return a Relay.Calling.TapAction object.

Examples

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

1
import asyncio # to use sleep
2
3
action = await call.tap_async(audio_direction='listen', target_type='rtp', target_addr='192.168.1.1', target_port=1234)
4
# Do other things while tapping the media and then stop it..
5
await asyncio.sleep(3)
6
await action.stop()

wait_for

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

Parameters

Returns

coroutine - Coroutine object that will be resolved with true or false.

Examples

Wait for ending or ended events:

1
success = await call.waitFor('ending', 'ended')

wait_for_answered

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

Parameters

None

Returns

coroutine - Coroutine that will return true or false.

Examples

Wait for the answered event:

1
success = await call.wait_for_answered()

wait_for_ended

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

Parameters

None

Returns

coroutine - Coroutine that will return true or false.

Examples

Wait for the ended event:

1
success = await call.wait_for_ended()

wait_for_ending

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

Parameters

None

Returns

coroutine - Coroutine that will return true or false.

Examples

Wait for the ending event:

1
success = await call.waitForEnding()

wait_for_ringing

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

Parameters

None

Returns

coroutine - Coroutine that will return true or false.

Examples

Wait for ending or ended events:

1
success = await call.wait_for_ringing()

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.

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: