Calls

list_calls

Client.list_calls(bridge_id=None, conference_id=None, from_=None, to=None, size=None, sort_order=None, **kwargs)

Get a list of calls

Parameters:
  • bridge_id (str) – The id of the bridge for querying a list of calls history
  • conference_id (str) – The id of the conference for querying a list of calls history
  • from_ (str) – The number to filter calls that came from
  • to (str) – The number to filter calls that was called to
  • sort_order (str) – How to sort the calls. Values are asc or desc If no value is specified the default value is desc
  • size (int) – Used for pagination to indicate the size of each page requested for querying a list of items. If no value is specified the default value is 25. (Maximum value 1000)
Return type:

types.GeneratorType

Returns:

list of calls

Example: Fetch calls from specific telephone number:

call_list = api.list_calls(from_ = '+19192223333', size = 1000)

total_chargeable_duration = 0

for call in call_list:
    total_chargeable_duration += call['chargeable_duration']

print(total_chargeable_duration)
## 240

Example: List Calls:

call_list = api.list_calls(to = '+19192223333', size = 2)
print(list(call_list))
## [
##   {
##     'active_time'          : '2017-01-26T16:10:23Z',
##     'callback_url'         : 'http://yoursite.com/calls',
##     'chargeable_duration'  : 60,
##     'direction'           : 'out',
##     'end_time'             : '2017-01-26T16:10:33Z',
##     'events'              : 'https://api.catapult.inetwork.com/v1/users/u-abc123/calls/c-abc123/events',
##     'from'                : '+17079311113',
##     'id'                  : 'c-abc123',
##     'recording_enabled'    : False,
##     'recording_file_format' : 'wav',
##     'recordings'          : 'https://api.../v1/users/u-abc123/calls/c-abc123/recordings',
##     'start_time'           : '2017-01-26T16:10:11Z',
##     'state'               : 'completed',
##     'to'                  : '+19192223333',
##     'transcription_enabled': False,
##     'transcriptions'      : 'https://api.../v1/users/u-abc123/calls/c-abc123/transcriptions'
##   },
##   {
##     'active_time'          : '2016-12-29T23:50:35Z',
##     'chargeable_duration'  : 60,
##     'direction'           : 'out',
##     'end_time'             : '2016-12-29T23:50:41Z',
##     'events'              : 'https://api.catapult.inetwork.com/v1/users/u-abc123/calls/c-xyz987/events',
##     'from'                : '+19194443333',
##     'id'                  : 'c-xyz987',
##     'recording_enabled'    : False,
##     'recording_file_format' : 'wav',
##     'recordings'          : 'https://api.../v1/users/u-abc123/calls/c-xyz987/recordings',
##     'start_time'           : '2016-12-29T23:50:15Z',
##     'state'               : 'completed',
##     'to'                  : '+19192223333',
##     'transcription_enabled': False,
##     'transcriptions'      : 'https://api.../v1/users/u-abc123/calls/c-xyz987/transcriptions'
##   }
## ]

create_call

Client.create_call(from_, to, call_timeout=None, callback_url=None, callback_timeout=None, callback_http_method=None, fallback_url=None, bridge_id=None, conference_id=None, recording_enabled=False, recording_file_format=None, recording_max_duration=None, transcription_enabled=False, tag=None, sip_headers=None, **kwargs)

Create a call

Parameters:
  • from_ (str) – A Bandwidth phone number on your account the call should come from (required)
  • to (str) – The number to call (required)
  • call_timeout (str) – Determine how long should the platform wait for call answer before timing out in seconds.
  • callback_url (str) – The full server URL where the call events related to the Call will be sent to.
  • callback_timeout (str) – Determine how long should the platform wait for callbackUrl’s response before timing out in milliseconds.
  • callback_http_method (str) – Determine if the callback event should be sent via HTTP GET or HTTP POST. Values are “GET” or “POST” (if not set the default is POST).
  • fallback_url (str) – The full server URL used to send the callback event if the request to callbackUrl fails.
  • bridge_id (str) – The id of the bridge where the call will be added.
  • conference_id (str) – Id of the conference where the call will be added. This property is required if you want to add this call to a conference.
  • recording_enabled (bool) – Indicates if the call should be recorded after being created. Set to “true” to enable. Default is “false”.
  • recording_file_format (str) – The file format of the recorded call. Supported values are wav (default) and mp3.
  • recording_max_duration (str) – Indicates the maximum duration of call recording in seconds. Default value is 1 hour.
  • transcription_enabled (bool) – Recordings for this call is going to be automatically transcribed.
  • tag (str) – A string that will be included in the callback events of the call.
  • sip_headers (str) – Map of Sip headers prefixed by “X-”. Up to 5 headers can be sent per call.
Return type:

str

Returns:

id of created call

Example: Create an outbound phone call:

call_id = api.create_call(from_='+1234567890',
                          to='+1234567891',
                          callback_url='http://yoursite.com/calls')

print(call_id)
## c-abc123

my_call = api.get_call(call_id)
print(my_call)
## {   'callback_url'         : 'http://yoursite.com/calls',
##     'direction'           : 'out',
##     'events'              : 'https://api.catapult.inetwork.com/v1/users/u-abc/calls/c-abc123/events',
##     'from'                : '+1234567890',
##     'id'                  : 'c-abc123',
##     'recording_enabled'    : False,
##     'recording_file_format' : 'wav',
##     'recordings'          : 'https://api.catapult.inetwork.com/v1/users/u-abc/calls/c-abc123/recordings',
##     'start_time'           : '2017-01-26T16:10:11Z',
##     'state'               : 'started',
##     'to'                  : '+1234567891',
##     'transcription_enabled': False,
##     'transcriptions'      : 'https://api.../v1/users/u-abc/calls/c-abc123/transcriptions'}

get_call

Client.get_call(call_id)

Get information about a call

Parameters:call_id (str) – id of a call
Return type:dict
Returns:call information

Fetch and Print Call:

my_call = api.get_call(call_id)
print(my_call)
## {   'callback_url'         : 'http://yoursite.com/calls',
##     'direction'           : 'out',
##     'events'              : 'https://api.catapult.inetwork.com/v1/users/u-abc/calls/c-abc123/events',
##     'from'                : '+1234567890',
##     'id'                  : 'c-abc123',
##     'recording_enabled'    : False,
##     'recording_file_format' : 'wav',
##     'recordings'          : 'https://api.catapult.inetwork.com/v1/users/u-abc/calls/c-abc123/recordings',
##     'start_time'           : '2017-01-26T16:10:11Z',
##     'state'               : 'started',
##     'to'                  : '+1234567891',
##     'transcription_enabled': False,
##     'transcriptions'      : 'https://api..../v1/users/u-abc/calls/c-abc123/transcriptions'}

update_call

Client.update_call(call_id, state=None, recording_enabled=None, recording_file_format=None, transfer_to=None, transfer_caller_id=None, whisper_audio=None, callback_url=None, **kwargs)

Update a call

Parameters:
  • call_id (str) – id of a call
  • state (str) – The call state. Possible values: rejected to reject not answer, active to answer the call, completed to hangup the call, transferring to start and connect call to a new outbound call.
  • recording_enabled (bool) – Indicates if the call should be recorded. Values true or false. You can turn recording on/off and have multiple recordings on a single call.
  • recording_file_format (str) – The file format of the recorded call. Supported values are wav (default) and mp3.
  • transfer_to (str) – Phone number or SIP address that the call is going to be transferred to.
  • transfer_caller_id (str) – This is the caller id that will be used when the call is transferred.
  • whisper_audio (dict) – Audio to be played to the caller that the call will be transferred to.
  • callback_url (str) – The server URL where the call events for the new call will be sent upon transferring.

Update call with state = completed. (Hang up the call):

my_call = api.get_call(call_id)
my_call_state = my_call['state']
print(my_call_state)
## started

api.update_call(my_call['id'], state='completed')

my_call = api.get_call(my_call['id'])
print(my_call['state'])
## completed

play_audio_to_call

Client.play_audio_to_call(call_id, file_url=None, sentence=None, gender=None, locale=None, voice=None, loop_enabled=None, **kwargs)

Play audio to a call

Parameters:
  • call_id (str) – id of a call
  • file_url (str) – The location of an audio file to play (WAV and MP3 supported).
  • sentence (str) – The sentence to speak.
  • gender (str) – The gender of the voice used to synthesize the sentence.
  • locale (str) – The locale used to get the accent of the voice used to synthesize the sentence.
  • voice (str) – The voice to speak the sentence.
  • loop_enabled (bool) – When value is true, the audio will keep playing in a loop.

Play audio in file:

api.play_audio_to_call('call_id', file_url='http://host/path/file.mp3')
api.play_audio_to_call('call_id', sentence='Press 0 to complete call', gender='female')
# or with extension methods
api.play_audio_file_to_call('call_id', 'http://host/path/file.mp3')
api.speak_sentence_to_call('call_id', 'Hello')

send_dtmf_to_call

Client.send_dtmf_to_call(call_id, dtmf_out, **kwargs)

Send DTMF (phone keypad digit presses).

Parameters:
  • call_id (str) – id of a call
  • dtmf_out (str) – String containing the DTMF characters to be sent in a call.

Example: Send Digits to call:

api.send_dtmf_to_cal('c-callId', '1234')

list_call_recordings

Client.list_call_recordings(call_id)

Get a list of recordings of a call

Parameters:call_id (str) – id of a call
Return type:types.GeneratorType
Returns:list of recordings

Fetch all call recordings for a call:

list = api.get_call_recordings('callId')

list_call_transcriptions

Client.list_call_transcriptions(call_id)

Get a list of transcriptions of a call

Parameters:call_id (str) – id of a call
Return type:types.GeneratorType
Returns:list of transcriptions

Get all transcriptions for calls:

list = api.get_call_transcriptions('callId')

list_call_events

Client.list_call_events(call_id)

Get a list of events of a call

Parameters:call_id (str) – id of a call
Return type:types.GeneratorType
Returns:list of events

Fetch all events for calls:

list = api.get_call_events('callId')

get_call_event

Client.get_call_event(call_id, event_id)

Get an event of a call

Parameters:
  • call_id (str) – id of a call
  • event_id (str) – id of an event
Return type:

dict

Returns:

data of event

Fetch information on a specific event:

data = api.get_call_event('callId', 'eventId')

create_call_gather

Client.create_call_gather(call_id, max_digits=None, inter_digit_timeout=None, terminating_digits=None, tag=None, **kwargs)

Create a gather for a call

Parameters:
  • call_id (str) – id of a call
  • max_digits (int) – The maximum number of digits to collect, not including terminating digits (maximum 30).
  • inter_digit_timeout (int) – Stop gathering if a DTMF digit is not detected in this many seconds (default 5.0; maximum 30.0).
  • terminating_digits (str) – A string of DTMF digits that end the gather operation immediately if any one of them is detected
  • tag (str) – A string you choose that will be included with the response and events for this gather operation.
Return type:

str

Returns:

id of create of gather

Create gather for only single digit:

gather_id = api.create_call_gather('callId', max_digits = 1)

get_call_gather

Client.get_call_gather(call_id, gather_id)

Get a gather of a call

Parameters:
  • call_id (str) – id of a call
  • gather_id (str) – id of a gather
Return type:

dict

Returns:

data of gather

Get Gather information for a previously created gather:

data = api.get_call_gather('callId', 'gatherId')

update_call_gather

Client.update_call_gather(call_id, gather_id, state=None, **kwargs)

Update a gather of a call

Parameters:
  • call_id (str) – id of a call
  • gather_id (str) – id of a gather
  • state (str) – The only update allowed is state:completed to stop the gather.

End gather:

api.update_call_gather('callId', 'gatherId', state = 'completed')

answer_call

Client.answer_call(call_id)

Answer incoming call

Parameters:call_id (str) – id of a call

Example: Answer incoming call:

api.answer_call('callId')

reject_call

Client.reject_call(call_id)

Reject incoming call

Parameters:call_id (str) – id of a call

Example: Reject incoming call:

api.reject_call('callId')

hangup_call

Client.hangup_call(call_id)

Complete active call

Parameters:call_id (str) – id of a call

Example: Hangup call:

api.hangup_call('callId')

enable_call_recording

Client.enable_call_recording(call_id)

Turn on call recording

Parameters:call_id (str) – id of a call

Example: Enable Call Recording:

api.enable_call_recording('c-callId')

disable_call_recording

Client.disable_call_recording(call_id)

Turn off call recording

Parameters:call_id (str) – id of a call

Example: Disable Call Recording:

api.disable_call_recording('c-callId')

toggle_call_recording

Client.toggle_call_recording(call_id)

Fetches the current call state and either toggles recording on or off

Parameters:call_id (str) – id of the call to toggle

Example: Toggle the call recording:

my_call_id = api.create_call(to='+19192223333', from_='+18281114444')
my_call = api.get_call(my_call_id)
print(my_call['recording_enabled'])
## False

api.toggle_call_recording(my_call_id)
my_call = api.get_call(my_call_id)
print(my_call['recording_enabled'])
## True

api.toggle_call_recording(my_call_id)
my_call = api.get_call(my_call_id)
print(my_call['recording_enabled'])
## False

transfer_call

Client.transfer_call(call_id, to, caller_id=None, whisper_audio=None, callback_url=None, **kwargs)

Transfer a call

Parameters:
  • call_id (str) – id of a call
  • to (str) – number that the call is going to be transferred to.
  • caller_id (str) – caller id that will be used when the call is transferred
  • whisper_audio (dict) – audio to be played to the caller that the call will be transferred to
  • callback_url (str) – URL where the call events for the new call will be sent upon transferring
Returns str:

id of created call

Example: Transfer with whisper:

my_sentence = api.build_sentence(sentence = "Hello from Bandwidth",
                     gender="Female",
                     locale="en_UK",
                     voice="Bridget",
                     loop_enabled=True
                    )
my_call = api.get_call('c-callId')
api.transfer_call('c-callId', to = '+1234564890', caller_id = my_call['from'], whisper_audio = my_sentence )

Example: Transfer with whisper audio playback:

my_audio = api.build_audio_playback('http://my_site.com/file.mp3', loop_enabled=True)
my_call = api.get_call('c-callId')
api.transfer_call('c-callId', to = '+1234564890', whisper_audio = my_audio )