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 )