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

Property	Type	Description
id	string	The unique identifier of the call.
call_type	string	The type of call. Only phone is currently supported.
from_number	string	The phone number that the call is coming from.
to_number	string	The phone number you are attempting to call.
timeout	number	The seconds the call rings before being transferred to voicemail.
state	string	The current state of the call. See Relay.Calling.Call State Events for all the possible call states.
prev_state	string	The previous state of the call.
context	string	The context the call belongs to.
active	boolean	Whether the call is active.
ended	boolean	Whether the call has ended.
answered	boolean	Whether the call has been answered.
failed	boolean	Whether the call has failed.
busy	boolean	Whether the call was busy.

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:

result = await call.answer()
if result.successful:
  print('Call answered..')
else:
  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

Parameter	Type	Required	Description
device_list	list	required	List or nested list of dict with the following structure: Nested depends on whether to dial in serial or parallel.
call_type	string	optional	The device type. Only phone is currently supported and is the default.
from_number	string	optional	The party the call is coming from. If not provided, the SDK will use the from_number of the originator call. Must be a SignalWire number or SIP endpoint that you own.
to_number	string	required	The party you are attempting to connect with.
timeout	number	optional	The time, in seconds, the call will ring before going to voicemail.

Returns

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

Examples

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

devices = [
  { 'to_number': '+18991114444', 'timeout': 10 },
  { 'to_number': '+18991114445', 'timeout': 20 }
]
result = await call.connect(device_list=devices)
if result.successful:
  # result.call is the remote leg connected with yours
  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:

devices = [
  { 'to_number': '+18991114443', 'timeout': 30 },
  [
    { 'to_number': '+18991114444', 'timeout': 30 },
    { 'to_number': '+18991114445', 'timeout': 20 }
  ],
  [
    { 'to_number': '+18991114446', 'timeout': 30 },
    { 'to_number': '+18991114447', 'timeout': 20 }
  ]
]
result = await call.connect(device_list=devices)

if result.successful:
  # result.call is the remote leg connected with yours.
  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:

devices = [
  { 'to_number': '+18991114444', 'timeout': 10 },
  { 'to_number': '+18991114445', 'timeout': 20 }
]
action = await call.connect_async(device_list=devices)
# .. do other important things while Relay try to connect your call..

# .. check whether the action has completed
if action.completed:
  # 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:

Parameter	Type	Required	Description
detect_type	string	required	machine
timeout	number	optional	Number of seconds to run the detector. Defaults to 30.0.
wait_for_beep	boolean	optional	Whether to wait until the AM is ready for voicemail delivery. Defaults to false.
initial_timeout	number	optional	Number of seconds to wait for initial voice before giving up. Defaults to 4.5.
end_silence_timeout	number	optional	Number of seconds to wait for voice to finish. Defaults to 1.0.
machine_voice_threshold	number	optional	How many seconds of voice to decide is a machine. Defaults to 1.25.
machine_words_threshold	number	optional	How many words to count to decide is a machine. Defaults to 6.

• To detect digits:

Parameter	Type	Required	Description
detect_type	string	required	digit
timeout	number	optional	Number of seconds to run the detector. Defaults to 30.0.
digits	string	optional	The digits to detect. Defaults to "0123456789#*".

• To detect a fax:

Parameter	Type	Required	Description
detect_type	string	required	fax
timeout	number	optional	Number of seconds to run the detector. Defaults to 30.0.
tone	string	optional	The fax tone to detect: CED or CNG. Defaults to "CED".

Returns

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

Examples

Detect a machine with custom parameters and timeout:

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

Detect a Fax setting timeout only:

result = await call.detect(detect_type='fax', timeout=45)
if result.successful:
  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:

import asyncio # to use sleep

action = await call.detect_async(detect_type='digit')
# For demonstration purposes only..
await asyncio.sleep(5)
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

Parameter	Type	Required	Description
timeout	number	optional	Number of seconds to run the detector. Defaults to 30.0.
wait_for_beep	boolean	optional	Whether to wait until the AM is ready for voicemail delivery. Defaults to false.
initial_timeout	number	optional	Number of seconds to wait for initial voice before giving up. Defaults to 4.5.
end_silence_timeout	number	optional	Number of seconds to wait for voice to finish. Defaults to 1.0.
machine_voice_threshold	number	optional	How many seconds of voice to decide is a machine. Defaults to 1.25.
machine_words_threshold	number	optional	How many words to count to decide is a machine. Defaults to 6.

Returns

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

Examples

Perform an AMD and wait until the machine is ready:

result = await call.detect_answering_machine(wait_for_beep=True)
if result.successful:
  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:

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

detect_digit

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

Parameters

Parameter	Type	Required	Description
timeout	number	optional	Number of seconds to run the detector. Defaults to 30.0.
digits	string	optional	The digits to detect. Defaults to "0123456789#*".

Returns

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

Examples

Detect digits and then write a log with the result:

result = await call.detect_digit()
if result.successful:
  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:

import asyncio # to use sleep

action = await call.detect_digit_async(digits='123')
await asyncio.sleep(5)
await action.stop()

detect_fax

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

Parameters

Parameter	Type	Required	Description
timeout	number	optional	Number of seconds to run the detector. Defaults to 30.0.
tone	string	optional	The fax tone to detect: CED or CNG. Defaults to "CED".

Returns

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

Examples

Detect fax on the current call:

result = await call.detect_fax()
if result.successful:
  # 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:

import asyncio # to use sleep

action = await call.detect_fax_async()
await asyncio.sleep(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

call = client.calling.new_call(from_number='+1XXXXXXXXXX', to_number='+1YYYYYYYYYY')
result = await call.dial()
if result.successful:
  print('Call answered..')
else:
  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:

result = await call.fax_receive()
if result.successful:
  url = result.document # URL location of the document
  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:

import asyncio # to use sleep

action = await call.fax_receive_async()
# For demonstration purposes only..
await asyncio.sleep(5)
await action.stop()

fax_send

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

Parameters

Parameter	Type	Required	Description
document	string	required	Http(s) URL to the document to send. PDF format only.
identity	string	optional	Identity to display on receiving fax. Defaults to SignalWire DID.
header	string	optional	Custom string to add to header of each fax page. Set to empty string to disable sending any header.

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:

result = await call.fax_send(url='https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf', header='Custom Header')
if result.successful:
  url = result.document # URL location of the document
  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:

import asyncio # to use sleep

action = await call.fax_send_async(url='https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf', header='Custom Header')
# For demonstration purposes only..
await asyncio.sleep(5)
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:

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

on

Attach an event handler for the event.

Parameters

Parameter	Type	Required	Description
event	string	required	Event name. Full list of events Relay.Calling.Call events
callback	function	required	Function to call when the event comes.

Returns

Relay.Calling.Call - The call object itself.

Examples

Subscribe to the answered events for a given call:

def on_answered():
  # Call has been answered from the remote party!

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

Parameter	Type	Required	Description
event	string	required	Event name. Full list of events Relay.Calling.Call events
callback	function	optional	Function to remove. Note: callback will be removed from the stack by reference so make sure to use the same reference in both .on() and .off() methods.

Returns

Relay.Calling.Call - The call object itself.

Examples

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

def on_ended():
  pass

call.on('ended', on_ended)

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

Parameter	Type	Required	Description
media_list	list	required	List of media to play. See below for each type.
volume	float	optional	Volume value between -40dB and +40dB where 0 is unchanged. Default is 0.

• To play an audio file:

Parameter	Type	Required	Description
type	string	required	audio
url	string	required	Http(s) URL to audio resource to play.

• To play a text to speech string:

Parameter	Type	Required	Description
type	string	required	tts
text	string	required	TTS to play.
language	string	optional	Default to en-US.
gender	string	optional	male or female. Default to female.

• To play silence:

Parameter	Type	Required	Description
type	string	required	silence
duration	number	required	Seconds of silence to play.

Returns

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

Examples

Play multiple media elements in the call:

media_list = [
  { 'type': 'tts', 'text': 'Listen this awesome file!' },
  { 'type': 'audio', 'url': 'https://cdn.signalwire.com/default-music/welcome.mp3' },
  { 'type': 'silence', 'duration': 5 },
  { 'type': 'tts', 'text': 'Did you like it?' }
]
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:

import asyncio # to use sleep

media_list = [
  { 'type': 'tts', 'text': 'Listen this awesome file!' },
  { 'type': 'audio', 'url': 'https://cdn.signalwire.com/default-music/welcome.mp3' },
  { 'type': 'silence', 'duration': 5 },
  { 'type': 'tts', 'text': 'Did you like it?' }
]
action = await call.play_async(media_list)
await asyncio.sleep(5)
await action.stop()

play_audio

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

Parameters

Parameter	Type	Required	Description
url	string	required	Http(s) URL to audio resource to play.
volume	float	optional	Volume value between -40dB and +40dB where 0 is unchanged. Default is 0.

Returns

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

Examples

Play an Mp3 file:

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:

import asyncio # to use sleep

action = await call.play_audio_async('https://cdn.signalwire.com/default-music/welcome.mp3')
await asyncio.sleep(5)
await action.stop()

play_silence

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

Parameters

Parameter	Type	Required	Description
duration	number	required	Seconds of silence to play.

Returns

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

Examples

Play silence for 10 seconds:

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:

import asyncio # to use sleep

action = await call.play_silence_async(60)
await asyncio.sleep(5)
await action.stop()

play_ringtone

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

Parameters

Parameter	Type	Required	Description
name	string	required	The name of the ringtone. See ringtones for the supported values.
duration	float	optional	Duration of ringtone to play. Default to 1 ringtone iteration.
volume	float	optional	Volume value between -40dB and +40dB where 0 is unchanged. Default is 0.

Returns

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

Examples

Play a single US ringtone:

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:

import asyncio # to use sleep

action = await call.play_ringtone_async(name='us', duration=30)
# For demonstration purposes only..
await asyncio.sleep(5)
await action.stop()

play_tts

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

Parameters

Parameter	Type	Required	Description
text	string	required	TTS to play.
language	string	optional	Default to en-US.
gender	string	optional	male or female. Default to female.
volume	float	optional	Volume value between -40dB and +40dB where 0 is unchanged. Default is 0.

Returns

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

Examples

Play TTS:

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:

import asyncio # to use sleep

action = await call.play_tts_async(text='Welcome to SignalWire!', gender='male')
await asyncio.sleep(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

Parameter	Type	Required	Description
prompt_type	string	required	digits, speech or both.
media_list	list	required	List of media elements to play. See play parameters for the list structure.
initial_timeout	number	optional	Initial timeout in seconds. Default to 4 seconds.
volume	number	optional	Volume value between -40dB and +40dB where 0 is unchanged. Default is 0.

• To collect digits:

Parameter	Type	Required	Description
digits_max	number	required	Max digits to collect.
digits_terminators	string	optional	DTMF digits that will end the recording. Default not set.
digits_timeout	number	optional	Timeout in seconds between each digit.

• To collect speech:

Parameter	Type	Required	Description
end_silence_timeout	number	optional	How much silence to wait for end of speech. Default to 1 second.
speech_timeout	number	optional	Maximum time to collect speech. Default to 60 seconds.
speech_language	string	optional	Language to detect. Default to en-US.
speech_hints	array	optional	Array of expected phrases to detect.

Returns

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

Examples

Ask user to enter their PIN and collect the digits:

media_list = [
  { 'type': 'tts', 'text': 'Welcome at SignalWire. Please, enter your PIN and then # to proceed' }
]
result = await call.prompt(prompt_type='digits', media_list=media_list, digits_max=4, digits_terminators='#')
if result.successful:
  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:

media_list = [
  { 'type': 'tts', 'text': 'Welcome at SignalWire. Please, enter your PIN and then # to proceed' }
  { 'type': 'audio', 'url': 'https://cdn.signalwire.com/default-music/welcome.mp3' }
]
action = await call.prompt_async(prompt_type='digits', media_list=media_list, digits_max=4, digits_terminators='#')
# .. do other important things while collecting user digits..

if action.completed:
  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:

Parameter	Type	Required	Description
url	string	required	Http(s) URL to audio resource to play.

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:

result = await call.prompt_audio(prompt_type='digits', url='https://cdn.signalwire.com/default-music/welcome.mp3', digits_max=4)
if result.successful:
  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:

action = await call.prompt_audio_async(prompt_type='digits', url='https://cdn.signalwire.com/default-music/welcome.mp3', digits_max=4)
# .. do other important things while collecting user digits..
if action.completed:
  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:

Parameter	Type	Required	Description
name	string	required	The name of the ringtone. See ringtones for the supported values.
duration	number	optional	Duration of ringtone to play. Default to 1 ringtone iteration.

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:

result = await call.prompt_ringtone(prompt_type='digits', name='us', duration=30, digits_max=4)
if result.successful:
  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:

action = await call.prompt_ringtone_async(prompt_type='digits', name='us', duration=30, digits_max=4)
# .. do other important things while collecting user digits..
if action.completed:
  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:

Parameter	Type	Required	Description
text	string	required	Text-to-speech string to play.
language	string	optional	Default to en-US.
gender	string	optional	male or female. Default to female.

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:

result = await call.prompt_tts(prompt_type='digits', text='Please, enter your 3 digit PIN', digits_max=3)
if result.successful:
  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:

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

record

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

Parameters

Parameter	Type	Required	Description
beep	boolean	optional	Default to false.
stereo	boolean	optional	Default to false.
record_format	string	optional	mp3 or wav. Default mp3.
direction	string	optional	listen, speak or both. Default to speak.
initial_timeout	number	optional	How long to wait in seconds until something is heard in the recording. Disable with 0. Default 5.0.
end_silence_timeout	number	optional	How long to wait in seconds until caller has stopped speaking. Disable with 0. Default 1.0.
terminators	string	optional	DTMF digits that will end the recording. Default #*.

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:

result = await call.record(stereo=True, direction='both')
if result.successful:
  print(f'Url: {result.url}')
  print(f'Duration: {result.duration}')
  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:

import asyncio # to use sleep

action = await call.record_async(stereo=True, direction='both')
await asyncio.sleep(5)
await action.stop()

send_digits

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

Parameters

Parameter	Type	Required	Description
digits	string	required	String of DTMF digits to send. Allowed digits are 1234567890*#ABCD and wW for short and long waits. If any invalid characters are present, the entire operation is rejected.

Returns

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

Examples

Send some digits:

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:

import asyncio # to use sleep

action = await call.send_digits_async('1W2W3W4w5w6W7W8W9')

await asyncio.sleep(3)
await action.stop()

tap

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

Parameters

Parameter	Type	Required	Description
audio_direction	string	required	listen what the caller hears, speak what the caller says or both.
target_type	string	required	Protocol to use: rtp or ws, defaults to rtp.
target_ptime	number	optional	Packetization time in ms. It will be the same as the tapped media if not set.
codec	string	optional	Codec to use. It will be the same as the tapped media if not set.

• To tap through RTP:

Parameter	Type	Required	Description
target_addr	string	required	RTP IP v4 address.
target_port	number	required	RTP port.

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:

result = await call.tap(audio_direction='listen', target_type='rtp', target_addr='192.168.1.1', target_port=1234)
if result.successful:
  # Print source and destination devices..
  print(result.source_device)
  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:

import asyncio # to use sleep

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

wait_for

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

Parameters

Parameter	Type	Required	Description
*events	list of strings	required	One or more Relay.Calling.Call state events

Returns

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

Examples

Wait for ending or ended events:

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:

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:

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:

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:

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.

Event	Description
stateChange	Event dispatched when Call state changes.
created	The call has been created in Relay.
ringing	The call is ringing and has not yet been answered.
answered	The call has been picked up.
ending	The call is hanging up.
ended	The call has ended.

Connect Events

To track the connect state of a call.

Event	Description
connect.stateChange	Event dispatched when the Call connect state changes.
connect.connecting	Currently calling the phone number(s) to connect.
connect.connected	The calls are being connected together.
connect.failed	The last call connection attempt failed.
connect.disconnected	The call was either never connected or the last call connection completed.

Play Events

To track a playback state.

Event	Description
play.stateChange	Event dispatched when the state of a playing changes.
play.playing	A playback in playing on the call.
play.error	A playback failed to start.
play.finished	The playback has ended.

Record Events

To track a recording state.

Event	Description
record.stateChange	Event dispatched when the state of a recording changes.
record.recording	The call is being recorded.
record.no_input	The recording failed due to no input.
record.finished	The recording has ended.

Prompt Events

To track a prompt state.

Event	Description
prompt	The prompt action on the call has ended.

Fax Events

To track a fax state.

Event	Description
fax.stateChange	Event dispatched when the state of a fax changes.
fax.error	Faxing failed.
fax.finished	Faxing has finished.
fax.page	A fax page has been sent or received.

Detect Events

To track a detector state.

Event	Description
detect.error	The detector has failed.
detect.finished	The detector has finished.
detect.update	There is a notification from the detector (eg: a new DTMF).

Tap Events

To track a tapping state.

Event	Description
tap.tapping	The tap action has started on the call.
tap.finished	Tap has finished.

Digits Events

To track a send digits action state.

Event	Description
sendDigits.finished	Digits have been sent.

Ringtones

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

Event	Description
name	at, au, bg, br, be, ch, cl, cn, cz, de, dk, ee, es, fi, fr, gr, hu, il, in, it, lt, jp, mx, my, nl, no, nz, ph, pl, pt, ru, se, sg, th, uk, us, tw, ve, za