Overview

The Python Web Service wrapper module ("web_service_wrappers.py") uses the Python Requests HTTP library to communicate with the cloud.

The Wrapper module exposes an number of classes, each associated with a particular web service feature:

Wrapper Class

Web Service Feature

outbound_web_service

Starting an Outbound Service

application_status_web_service

Starting an Outbound Service

message_web_service

Managing Messages

file_web_service

Managing Files

voice_biometrics_users_web_service

Voice Biometrics: Managing Users

voice_biometrics_user_groups_web_service

Voice Biometrics: Managing User Groups

voice_biometrics_user_group_keys_web_service

Voice Biometrics: Managing User Group Keys

monitor_web_service

Accessing Monitor Recordings

rest_interrupt_web_service

Interrupt a REST Application

conference_web_service

Managing Conferences

telephone_numbers_web_service

Managing Telephone Numbers

number_lookup_web_service

Lookup a Telephone Number

reports_web_service

Generating Reports

webrtc_client_web_service

WebRTC Clients

security_web_service

Security

outbound_web_service

The outbound_web_service object is used to start an outbound service (UAS or REST) that you have set up on your account.

class web_service_wrappers.outbound_web_service(cloud_id, username, service_name, service_password, wsserver=None)

Required arguments:

  • cloud_id

    The Aculab Cloud region (e.g. 1-2-0).

  • username

    Cloud account username

  • service_name

    The outbound service to start

  • service_password

    The outbound service password as set on the outbound services web page.

Optional arguments:

  • wsserver

    The address of the cloud web server. By default the wrappers call web services on https://ws-<cloud_id>.aculabcloud.net. In certain circumstances you may need to use a different address which you can set here.

service_cancel(service_invocation_reference_id_list)

This attempts to cancel one or more services that have been queued, but that are not yet running. Once a service is running it cannot be cancelled.

Required arguments:

  • service_invocation_reference_id_list

    A list of Service Invocation Reference IDs.

Returns a dictionary. Each dictionary key is a Service Invocation Reference ID, the value is one of the following strings: "success", "unknown" or "failed".

service_start_rest(outbound_calls)

This invokes an outbound service that initiates an outbound application instance when using the REST application

Required arguments:

  • outbound_calls

    A list of dictionaries. Each dictionary contains the following keys:

    • 'to' - (Required) A string containing the outbound call's destination sip address / telephone number.

    • 'from' - (Required only if 'to' is a telephone number). A string containing the outbound call's originating sip address / telephone number.

    • 'token' - (Optional) A string containing a user-defined token that will be passed transparently to the Web Application in the token property of the instance_info argument to the page request.

    • 'outbound parameters' - (Optional) A string containing user-defined data that will be passed transparently to the Web Application in the this_call.outbound_parameters property of the instance_info argument to the page request.

Returns a list of Service Invocation Reference IDs

service_start_uas(count=None, outbound_parameters_list=None, delimiter=None)

This invokes an outbound service that initiates an outbound application instance when using a UAS application.

Optional arguments:

  • count

    An integer. By default a single instance is invoked. Specifying more than one (Production and Premium accounts only) invokes multiple instances.

  • outbound_parameters_list

    A list outbound parameters for each instance invoked

  • delimiter

    A string. The delimiting character when outbound_parameters_list contains more than one entry.

Returns a list of Service Invocation Reference IDs

service_status(service_invocation_reference_id_list)

Retrieve the status of one or more outbound service invocations given their service invocation reference IDs.

Required arguments:

  • service_invocation_reference_id_list

    A list of Service Invocation Reference IDs

Returns a dictionary. Each dictionary key is a Service Invocation Reference ID, the value is a dictionary containing the following keys:

  • 'status' - A string containing one of "queued", "running", "completed", "couldnotrun", "cancelled" or "unknown".

  • 'application_status_eta' - The time at which the application's status will be ready for retrieval.

  • 'application_instance_id' - The application instance ID. Use this ID to get the status of an application instance.

application_status_web_service

The application_status_web_service class is used to retrieve detailed status of a single application instance.

class web_service_wrappers.application_status_web_service(cloud_id, username, api_access_key, wsserver=None)

Required arguments:

  • cloud_id

    The Aculab Cloud region (e.g. 1-2-0).

  • username

    The Cloud account username.

  • api_access_key

    The Cloud API Access key.

Optional arguments:

  • wsserver

    The address of the cloud web server. By default the wrappers call web services on https://ws-<cloud_id>.aculabcloud.net. In certain circumstances you may need to use a different address which you can set here.

application_status(app_inst_id)

This retrieves the detailed status of a single application instance.

Required arguments:

  • app_inst_id

    A string. The application instance Id of the instance to check.

Returns an empty dictionary if the status is not available. Otherwise, a dictionary containing one or more of the following keys will be returned:

  • 'adr' - Its value is a dictionary containing application data record information.

  • 'cdrs' - Its value is a dictionary containing call data records.

  • 'fdrs' - Its value is a dictionary containing feature data records.

  • 'errs' - Its value is a dictionary containing error reports.

get_channel_type_desc(abbreviation)

Returns a description of a channel type abbreviation.

Required arguments:

  • abbreviation

    A string. The abbreviated channel type ('p', 'x', 'ca' or 'cv').

Returns a description of the channel type.

status_to_string(status)

This function creates an easy to read representation of the dictionary returned from the application_status method.

Required arguments:

  • status

    A dictionary. The dictionary that was returned after calling the application_status() method.

Returns a string that describes the application status.

message_web_service

The message_web_service class allows you to send SMS and MMS messages, check their progress and identify any numbers that have been blocked for sending or receiving messages.

class web_service_wrappers.message_web_service(cloud_id, username, api_access_key, wsserver=None)

Required arguments:

  • cloud_id

    The Aculab Cloud region (e.g. 1-2-0).

  • username

    The Cloud account username.

  • api_access_key

    The Cloud API Access key.

Optional arguments:

  • wsserver

    The address of the cloud web server. By default the wrappers call web services on https://ws-<cloud_id>.aculabcloud.net. In certain circumstances you may need to use a different address which you can set here.

msg_cancel(msg_refs)

This attempts to cancel one or more messages that have been queued for sending.

Required arguments:

  • msg_refs

    A list of message reference IDs

Returns a dictionary. Each key is a message reference ID, the value is a string that indicates the status of the message.

msg_list_blocked(to_number=None, from_number=None)

This lists the numbers to and from which you're currently blocked for sending messages.

Optional arguments:

  • to_number

    A string. A remote number. If omitted, the 'from_number' must be supplied.

  • from_number

    A string. One of your numbers. If omitted, the 'to_number' must be supplied.

Returns a list of dictionaries. Each dictionary contains the following keys:

  • 'to' - A string. The mobile number you are blocked for sending to.

  • 'from' - A string. Your number you are blocked for sending from.

  • 'timestamp' - A naive datetime object. The UTC date and time at which the "STOP" message was received.

msg_query(msg_refs)

This retrieves the status of one or more messages given their message reference IDs.

Required arguments:

  • msg_refs

    A list of message reference IDs

Returns a dictionary. Each key is an Application Instance ID, the value is dictionary containing the following keys:

  • 'status' - A string. One of "queued", "cancelled", "submitted to carrier", "sent", "delivered", "accepted", "failed (reason)", "received" or "unknown".

  • 'multipart_uid' - A string (Available for multipart messages only). An ID for the overall message, shared by all its parts, which is unique among all recent messages in this direction.

  • 'multipart_pos' - integer (Available for multipart messages only). The position of this message part within the overall message, 1...multipart_count.

  • 'multipart_count' - integer (Available for multipart messages only). The number of message parts within the overall message.

  • 'type' - A string (Omitted when status is "unknown"). Either "sms" or "mms".

  • 'timestamp' - A naive datetime object (Omitted when status is "unknown"). The UTC date and time at which the status was last updated.

  • 'aculab_msg_err' - A string (Omitted when status is "unknown"). An Aculab message error code. A table of Aculab message error codes and their descriptions can be found on the Aculab website (In the "Cloud Documentation" / "Voice, Fax and Message Management" / "Managing Messages" / "Msg Status" section).

  • 'msg_from' - A string (Omitted when status is "unknown"). The number the message was sent from.

msg_send(to_number, from_number, content=None, request_delivery_report=None, status_page=None, status_method=None, status_authentication_name=None, status_authentication_password=None, status_ssl_check=None, type=None, alphanumeric_id=None, msg_media_list=None)

This queues an outbound SMS or MMS message for sending.

Required arguments:

  • to_number

    A string. The number of the phone you'd like to receive the message. This must be the full international number without any leading +.

  • from_number

    A string. The number from which you'd like to send the message. This must be one of your purchased numbers, in full international format without any leading +.

Optional arguments:

  • request_delivery_report

    A string. "true" to request a delivery report. Else "false". If "true", note that the carrier must support delivery reports otherwise this web service will fail. Default is "false".

  • status_page

    A string. The URL of a page, if any, hosted on your web server to which message status updates will be sent. The web page can use the msg_status_page_request method to process status updates. The default is "", meaning that no updates will be sent.

  • status_method

    A string. The method by which the above URL will be accessed, "POST" or "GET". Default is "POST".

  • status_authentication_name

    A string. Perform basic authentication with this username when accessing the above URL. Default is "", don't perform basic authentication.

  • status_authentication_password

    A string. Basic authentication password, ignored unless performing basic authentication. Default is ""

  • status_ssl_check

    A string. If using HTTPS, set "true" if you'd like Aculab Cloud to check your SSL certificate when accessing the above URL. Default is "false".

  • type

    A string. Either "sms" or "mms". Default is "sms".

  • alphanumeric_id

    A string. This string will be displayed (if supported) on the recipient's handset instead of the from number.

Conditional arguments:

  • content

    A string. Required if type is sms, optional for mms. The textual content of your message. If this includes characters not present in standard 7-bit ASCII, encode them using UTF-8.

  • msg_media_list

    A list of strings. Required if type is mms, must be omitted if type is sms. Each string is the name of a Message Media file that exists in your cloud message media file store. When sending an MMS message, msg_media_list must contain at least one entry.

Returns a list of strings. Each string is a Message Reference ID.

static msg_status_page_request(request_data)

This can be called by the web page that is to process message status updates. It decodes the status update dictionary from either a JSON formatted status update string, a Flask request object or a WSGI environment dictionary.

Required argument:

  • request_data

    A JSON formatted status update string, a Flask request object or a WSGI environment dictionary.

Returns a dictionary containing the following keys:

  • 'msg_ref' - A string. A unique reference ID for this message. If it's a sent message, it was returned by msg_send.

  • 'status' - A string. One of "submitted to carrier", "sent", "delivered", "accepted", "failed (reason)" or "received".

  • 'to' - A string. The number of the phone receiving the message. A full international number without any leading +.

  • 'from' - A string. The number of the phone sending the message. A full international number without any leading +.

  • 'direction' - A string. "send" if the message is being sent from Aculab Cloud, "receive" if it's being received.

  • 'type' - A string. Either "sms" or "mms".

  • 'content' - A string (Available for received messages only) The content of your message. If it includes characters not present in standard 7-bit ASCII, they'll be encoded as UTF-8.

  • 'msg_media' - A list of strings (Available for received mms messages only). The list of names of the files that have been received and stored in the message media file store. From there they can be downloaded. Note that they are only retained for 30 days.

  • 'multipart_uid' - A string (Available for multipart messages only) An ID for the overall message, shared by all its parts, which is unique among all recent messages in this direction.

  • 'multipart_pos' - An integer (Available for multipart messages only). The position of this message part within the overall message, 1...multipart_count.

  • 'multipart_count' - An integer (Available for multipart messages only). The number of message parts within the overall message.

  • 'timestamp' - A naive datetime object. The UTC date and time at which the status was last updated.

  • 'aculab_msg_err' - A string. An Aculab message error code. A table of Aculab message error codes and their descriptions can be found on the Aculab website (In the "Cloud Documentation" / "Voice, Fax and Message Management" / "Managing Messages" / "Msg Status" section).

Example of use in a Flask web application:

@app.route('/status_update_page', methods=['GET','POST'])
def handle_StatusUpdatePage():

    status_update_dict = message_web_service.msg_status_page_request(request)

    msg_ref = status_update_dict.get("msg_ref")
    status = status_update_dict.get("status")
    print("msg_ref={} status={}".format(msg_ref, status))

    return Response(status=200)

file_web_service

The files_web_service class allows you to manage media files, message media files and REST log files that reside on the file store for an account on Aculab Cloud.

class web_service_wrappers.file_web_service(cloud_id, username, api_access_key, wsserver=None)

Required arguments:

  • cloud_id

    The Aculab Cloud region (e.g. 1-2-0).

  • username

    The Cloud account username.

  • api_access_key

    The Cloud API Access key.

Optional arguments:

  • wsserver

    The address of the cloud web server. By default the wrappers call web services on https://ws-<cloud_id>.aculabcloud.net. In certain circumstances you may need to use a different address which you can set here.

file_delete(file_type, file_spec, from_datetime=None, to_datetime=None)

This deletes one or more files from the file store of a cloud account.

Required arguments:

  • file_type

    A string. The type of file to delete ("media", "msg_media" or "rest").

  • file_spec

    The name of the file to match (This parameter should be parenthesised and can accept a trailing '*' wildcard)

Optional arguments:

  • from_datetime

    A naive datetime object. Delete only files after the UTC date and time.

  • to_datetime

    A naive datetime object. Delete only files before the UTC date and time.

Returns a dictionary. The key is a token that identifies the deletion requested. This token can be used with the file_delete_progress web service to monitor the progress of a deletion.

file_delete_progress(token)

This retrieves the progress of a file deletion from a cloud account initiated by file_delete.

Required arguments:

  • token

    A string. The token returned by a call to the file_delete web service.

Returns a dictionary containing the following keys: * 'status' - A string. The status of the deletion. Either "in progress" or "completed". * 'files_deleted' - An integer. The number of files deleted. This value will be updated in chunks of up to 10k files while status is 'in progress'. Once the status is 'deleted' then it will contain the total number of files deleted.

file_get(file_type, remote_file, local_file)

This downloads a file present on the file store of a cloud account.

Required arguments:

  • file_type

    A string. The type of file to get ("media", "msg_media" or "rest").

  • remote_file

    A string. The filename of a file on the file stored on the cloud to download.

  • local_file

    A string. The filename for the downloaded file.

Returns nothing.

file_list(file_type, file_spec=None, start_pos=None, max_count=None, from_datetime=None, to_datetime=None, start_after=None)

This lists all the files of a specified type present on the file store of a cloud account.

Required arguments:

  • file_type

    A string. The type of file to list ("media", "msg_media" or "rest").

Optional arguments:

  • file_spec

    A string. The name of the file to match (This parameter should be parenthesised and can accept a trailing '*' wildcard)

  • start_pos

    Deprecated since version v1.3.6: Use start_after instead.

    An integer. Zero-based index of the first file to list.

  • max_count

    An integer. Maximum number of files to list.

  • from_datetime

    A naive datetime object. List only files after the UTC date and time.

  • to_datetime

    A naive datetime object. List only files before the UTC date and time.

  • start_after

    A string. If listing a large number of files, this specifies the last filename in the previous file list after which to list more files. It is the name of a file on the media, message media or rest logs cloud file store including path. If specified this should be the filename from the previous list which has its startafter property set.

Returns a dictionary. Each key is a recording filename, the value is a dictionary containing the following keys:

  • 'modified' - A naive datetime object. The last modification UTC date and time for the file.

  • 'size' - An integer. The size of the file in bytes.

  • 'encrypted' - Boolean true if the file is encrypted, false if the file is unencrypted.

  • 'expiry_date' - A naive datetime object. The expiry UTC date and time of the file. It is set to None if time to live has not been set.

file_move(file_type, remote_filename, new_remote_filename)

This renames a file that is present on the file store of a cloud account.

Required arguments:

  • file_type

    A string. The type of file to move ("media" or "msg_media").

  • remote_filename

    A string. The filename of the file to rename, including path.

  • new_remote_filename

    A string. The target filename, including path.

Returns nothing.

file_write(file_type, local_file, remote_file, encrypted=None, time_to_live=None, content_type=None)

This uploads a local file onto the cloud file store for a cloud account.

Required arguments:

  • file_type

    A string. The type of file to upload ("media" or "msg_media").

  • local_file

    A string. The filename of the file stored locally (To be uploaded).

  • remote_file

    A string. The filename of a file when uploaded to the cloud.

Optional arguments:

  • encrypted

    A string. Set to 'true' to indicate this is an encrypted file and should not be validated.

  • time_to_live

    A string. The time to live (TTL) of the file, expressed as Xm (X minutes), Xh (X hours) or Xd (X days). If omitted, the default is infinite time to live.

  • content_type

    A string. The content type (also called the MIME type) of the uploaded file(s) (e.g. "image/jpeg"). If not specified this is derived from the filename extension. Set it here if it needs to be overridden.

Returns nothing.

folder_list(file_type, folder_name=None, prefix=None, max_count=None, from_datetime=None, to_datetime=None, start_after=None)

This shows a folder view of a given prefix on the file store of an account, listing all the files and folders within that folder prefix.

Required arguments:

  • file_type

    A string. The type of file to list ("media", "msg_media" or "rest").

Optional arguments:

  • folder_name

    A string. A folder name to list. Matches the folder whose name equals the string. A trailing '/' is allowed, but not required. An empty string (or None) matches the root folder.

  • prefix

    A string. A prefix to match. Matches any file whose name within the folder starts with the string. An empty string (or None) matches all the files.

  • max_count

    An integer. Maximum number of files to list.

  • from_datetime

    A naive datetime object. List only files after the UTC date and time.

  • to_datetime

    A naive datetime object. List only files before the UTC date and time.

  • start_after

    A string. If listing a large number of files, this specifies the last filename in the previous file list after which to list more files. It is the name of a file on the media, message media or rest logs cloud file store including path. If specified this should be the filename from the previous list which has its startafter property set.

Returns a dictionary containing the following keys:

  • 'folders' - Its value contains a list of folder objects.

  • 'files' - Its value contains a list of file objects.

  • 'startafter' - Its value is a string. It indicates the name of a file within the specified folder path that can be used to obtain the next available folders and files. Only present if additional files are available from a further folder_list call.

A folder object is a dictionary containing the following keys:

  • 'name' - The name of the folder, including the trailing '/'.

A file object is a dictionary containing the following keys:

  • 'name' - The name of the file.

  • 'modified' - A naive datetime object. The last modification UTC date and time for the file.

  • 'size' - An integer. The size of the file in bytes.

  • 'encrypted' - Boolean true if the file is encrypted, false if the file is unencrypted.

  • 'expiry_date' - A naive datetime object. The expiry UTC date and time of the file. It is set to None if time to live has not been set.

voice_biometrics_users_web_service

The voice_biometrics_users_web_service class provides access to the voice biometrics users facilities of the Aculab Cloud Web Services APIs.

class web_service_wrappers.voice_biometrics_users_web_service(cloud_id, username, wsserver=None)

Required arguments:

  • cloud_id

    The Aculab Cloud region (e.g. 1-2-0).

  • username

    Cloud account username.

Optional arguments:

  • wsserver

    The address of the cloud web server. By default the wrappers call web services on https://ws-<cloud_id>.aculabcloud.net. In certain circumstances you may need to use a different address which you can set here.

delete(user_id, user_group_key)

This deletes a specified registered user and removes any trained audio voice model data.

Required arguments:

  • user_id

    A string. A user-defined Id that uniquely identifies the user.

  • user_group_key

    A string. An access key from the associated user group.

Returns a dictionary containing the following keys:

  • 'user_id' - A string. The Id of the user.

  • 'transaction_id' - A string. A transaction Id identifying the deletion.

  • 'deleted' - A naive datetime object. The UTC date and time of the deletion.

  • 'to_string' - A String. An easy to read representation of this dictionary.

exists(user_id, user_group_key)

This determines whether a specified user is currently registered.

Required arguments:

  • user_id

    A string. A user-defined Id that uniquely identifies the user.

  • user_group_key

    A string. An access key from the associated user group.

Returns a dictionary containing the following keys:

  • 'user_id' - A string. The Id of the user.

  • 'transaction_id' - A string. A transaction Id identifying the check.

  • 'exists' - A boolean. Whether the user registration exists.

  • 'to_string' - A String. An easy to read representation of this dictionary.

register(method, user_id, user_group_key, audio_sources)

This registers a user as part of a user group and creates an initial voice model for that user from the supplied audio data.

You can supply a single WAV file using PUT, or multiple WAV files/URLs using POST. Alternatively you can stream the user's audio data on a WebSocket using GET.

Required arguments:

  • method

    A string. The HTTP Request method to use (GET, PUT or POST).

  • user_id

    A string. A user-defined Id that uniquely identifies the user.

  • user_group_key

    A string. An access key from the associated user group.

  • audio_sources
    This can be:

    • A string specifying a single audio source.

    • A comma-delimited string specifying multiple audio sources.

    • A list where each element is a string that specifies an audio source.

    For a GET and PUT, only a single audio source can be specified and this must be a local audio WAV file. For POST, multiple audio sources can be specified. These can be either local audio WAV files or multiple URLs. Lists that contain a mixture of WAV files and URLs are not permitted.

Returns a dictionary containing the following keys:

  • 'application_instance_id' - Its value is an application instance Id identifying the voice biometric call.

  • 'transaction_id' - Its value is a transaction Id string identifying the registration.

  • 'sources' - Its value is a list of dictionaries. In each dictionary are 'name' and 'accepted' keys indicating whether the file/URL was successfully processed.

  • 'to_string' - A String. An easy to read representation of this dictionary.

stats(user_id, user_group_key)

This obtains statistics relating to a specified registered user.

Required arguments:

  • user_id

    A string. A user-defined Id that uniquely identifies the user.

  • user_group_key

    A string. An access key from the associated user group.

Returns a dictionary containing the following keys:

  • 'user_group_name' - A string. The name of the user group in which this user is registered.

  • 'transaction_id' - A string. A transaction Id identifying the check.

  • 'registration_date' - A naive datetime object. The UTC date and time of the registration.

  • 'update_date' - A naive datetime object. The UTC date and time of the last update for the user.

  • 'verification_date' - A naive datetime object. The UTC date and time of the last verification for the user.

  • 'verification_attempts' - An integer. The number of verifications attempted

  • 'verifications_passed' - An integer. The number of verifications that passed

  • 'verifications_failed' - An integer. The number of verifications that failed

  • 'to_string' - A String. An easy to read representation of this dictionary.

update(method, user_id, user_group_key, audio_sources)

This updates a user's voice model that has been created by calling register. It should only be called with audio data that is guaranteed (confirmed by other means) to be authentic user voice data.

You can supply a single WAV file using PUT, or multiple WAV files/URLs using POST. Alternatively you can stream the user's audio data on a WebSocket using GET.

Required arguments:

  • method

    A string. The HTTP Request method to use (GET, PUT or POST).

  • user_id

    A string. A user-defined Id that uniquely identifies the user.

  • user_group_key

    A string. An access key from the associated user group.

  • audio_sources
    This can be:

    • A string specifying a single audio source.

    • A comma-delimited string specifying multiple audio sources.

    • A list where each element is a string that specifies an audio source.

    For a GET and PUT, only a single audio source can be specified and this must be a local audio WAV file. For POST, multiple audio sources can be specified. These can be either local audio WAV files or multiple URLs. Lists that contain a mixture of WAV files and URLs are not permitted.

Returns a dictionary containing the following keys:

  • 'application_instance_id' - Its value is an application instance Id identifying the voice biometric call.

  • 'transaction_id' - Its value is a transaction Id string identifying the registration.

  • 'sources' - Its value is a list of dictionaries. In each dictionary are 'name' and 'accepted' keys indicating whether the file/URL was successfully processed.

  • 'to_string' - A String. An easy to read representation of this dictionary.

verify(method, user_id, user_group_key, audio_source, sensitivity=0.0, text_dependent=True, enable_pad=False)

This verifies that the supplied audio matches the specified registered user.

You can supply a single WAV file using PUT, or single WAV file or URL using POST. Alternatively you can stream the user's audio data on a WebSocket using GET.

Required arguments:

  • method

    A string. The HTTP Request method to use (GET, PUT or POST).

  • user_id

    A string. A user-defined Id that uniquely identifies the user.

  • user_group_key

    A string. An access key from the associated user group.

  • audio_source

    A string. The name of the local audio WAV file or a URL.

Optional arguments:

  • sensitivity

    A float. The sensitivity of the biometric analysis. Allowable range is -10.0 to 10.0. The default value is 0.0.

  • text_dependent

    A boolean. When this is set to True, all audio data supplied to register, update and verify must contain the same spoken phrase. The default value is True.

  • enable_pad

    A boolean. This enables or disables Presentation Attack Detection (PAD). The default value is True.

Returns a dictionary containing the following keys:

  • 'application_instance_id' - Its value is an application instance Id identifying the voice biometric call.

  • 'transaction_id' - Its value is a transaction Id string identifying the registration.

  • 'sources' - Its value is a list of dictionaries. In each dictionary are 'name' and 'accepted' keys indicating whether the file/URL was successfully processed.

  • 'verified' - Its value is a Boolean that indicates whether the supplied audio has been verified against the user.

  • 'confidence' - Its value is a float and is a measure of confidence that the audio has been matched against the user. A value of greater than 1.0 is considered to have been verified.

  • 'pad_detected - Its value is a dictionary. Only present if a Presentation Attack was detected. This dictionary contains a 'type' key (Its value will be either 'TypeA' for duplicate audio, 'TypeB' for replayed recording or 'TypeC' for synthetic speech) and a 'description' key (Its value being a verbose description of the PAD type detected).

  • 'to_string' - A String. An easy to read representation of this dictionary.

voice_biometrics_user_groups_web_service

The voice_biometrics_user_groups_web_service class provides access to the voice biometrics user groups facilities of the Aculab Cloud Web Services APIs.

class web_service_wrappers.voice_biometrics_user_groups_web_service(cloud_id, username, api_access_key, wsserver=None)

Required arguments:

  • cloud_id

    The Aculab Cloud region (e.g. 1-2-0).

  • username

    Cloud account username.

  • api_access_key

    The Cloud API Access key.

Optional arguments:

  • wsserver

    The address of the cloud web server. By default the wrappers call web services on https://ws-<cloud_id>.aculabcloud.net. In certain circumstances you may need to use a different address which you can set here.

create(user_group_name)

This creates a user group.

Required arguments:

  • user_group_name

    A string. The name of the user group to create.

Returns a dictionary containing the following keys:

  • 'created' - A naive datetime object. The UTC date and time when user group was created.

  • 'to_string' - A String. An easy to read representation of this dictionary.

delete(user_group_name)

This deletes a user group.

Required arguments:

  • user_group_name

    A string. The name of the user group to delete.

Returns a dictionary containing the following key:

  • 'deleted' - A naive datetime object. The UTC date and time when user group was deleted.

  • 'to_string' - A String. An easy to read representation of this dictionary.

list(user_group_name=None)

List the user groups.

Optional arguments:

  • user_group_name

    A string. The name of a specific user group to list.

Returns a list of dictionaries. Each dictionary contains details about a particular user group. The list is ordered by the user group creation date.

In each dictionary are the following dictionary keys:

  • 'name' - A string. The name of the user group.

  • 'registrations' - An integer. The number of registrations currently on the user group.

  • 'created' - A naive datetime object. The UTC date and time when user group was created.

  • 'to_string' - A String. An easy to read representation of this dictionary.

voice_biometrics_user_group_keys_web_service

The voice_biometrics_user_group_keys_web_service class provides access to the voice biometrics user group keys facilities of the Aculab Cloud Web Services APIs.

class web_service_wrappers.voice_biometrics_user_group_keys_web_service(cloud_id, username, api_access_key, wsserver=None)

Required arguments:

  • cloud_id

    The Aculab Cloud region (e.g. 1-2-0).

  • username

    Cloud account username.

  • api_access_key

    The Cloud API Access key.

Optional arguments:

  • wsserver

    The address of the cloud web server. By default the wrappers call web services on https://ws-<cloud_id>.aculabcloud.net. In certain circumstances you may need to use a different address which you can set here.

create(user_group_name)

This creates a user group access key.

Required arguments:

  • user_group_name

    A string. The name of the user group in which to create the access key.

Returns a dictionary containing the following keys:

  • 'user_group_key' - A string. The newly created user group key.

  • 'created' - A naive datetime object. The UTC date and time when user group key was created.

  • 'enabled' - A boolean. The enabled state of the key after creation.

  • 'retain_data' - A boolean. Whether diagnostic data is retained when using this key.

  • 'to_string' - A String. An easy to read representation of this dictionary.

delete(user_group_key)

This deletes a user group access key.

Required arguments:

  • user_group_key

    A string. The name of the user group key to delete.

Returns a dictionary containing the following keys:

  • 'deleted' - A naive datetime object. The UTC date and time when user group key was deleted.

  • 'to_string' - A String. An easy to read representation of this dictionary.

list(user_group_name)

List the access keys in a user group.

Required arguments:

  • user_group_name

    A string. The name of the user group.

Returns a list of dictionaries. Each dictionary contains details about a particular user group key. The list is ordered by the user group key creation date.

In each dictionary are the following dictionary keys:

  • 'user_group_key' - A string. The user group key.

  • 'created' - A naive datetime object. The UTC date and time when user group key was created.

  • 'enabled' - A boolean. Whether the key is currently enabled.

  • 'retain_data' - A boolean. Whether diagnostic data is retained when using this key.

  • 'to_string' - A String. An easy to read representation of this dictionary.

modify(user_group_key, enabled, retain_data=False)

This modifies a user group access key.

Required arguments:

  • user_group_key

    A string. The name of the user group key to modify.

  • enabled

    A boolean. Enable or disable the specified access key. If disabled, the key cannot be used to register, update or verify a user.

Optional arguments:

  • retain_data

    A boolean. Enable to retain diagnostic audio and transaction data when using this key. During normal operation this should be disabled.

Returns a dictionary containing the following keys:

  • 'user_group_key' - A string. The user group key.

  • 'created' - A naive datetime object. The UTC date and time when user group key was created.

  • 'enabled' - A boolean. The enabled state of the key after the modification.

  • 'retain_data' - A boolean. The enabled state of the retain_data property after the modification.

  • 'to_string' - A String. An easy to read representation of this dictionary.

monitor_web_service

The monitor_web_service class is used to discover the monitor recordings for a given application instance, and then download them.

class web_service_wrappers.monitor_web_service(cloud_id, username, api_access_key, wsserver=None)

Required arguments:

  • cloud_id

    The Aculab Cloud region (e.g. 1-2-0).

  • username

    The Cloud account username.

  • api_access_key

    The Cloud API Access key.

Optional arguments:

  • wsserver

    The address of the cloud web server. By default the wrappers call web services on https://ws-<cloud_id>.aculabcloud.net. In certain circumstances you may need to use a different address which you can set here.

monitor_get(recording, local_file)

This downloads the specified monitor recording file.

Required arguments:

  • recording

    A string. The monitor recording filename as returned by monitor_list.

  • local_file

    A string. The filename for the downloaded file.

Returns nothing.

monitor_list(app_inst_id)

This lists the filenames of monitor recordings created for the given application instance id.

Required arguments:

  • app_inst_id

    A string. An Application Instance ID.

Returns a dictionary. Each key is a recording filename, the value is a dictionary containing the following keys:

  • 'created_date' - A string representing the time that the file was created in UTC.

  • 'size' - An integer. The size of the file in bytes.

rest_interrupt_web_service

The rest_interrupt_web_service class is used to interrupt an instance of a REST application running on Aculab Cloud.

class web_service_wrappers.rest_interrupt_web_service(cloud_id, username, api_access_key, wsserver=None)

Required arguments:

  • cloud_id

    The Aculab Cloud region (e.g. 1-2-0).

  • username

    The Cloud account username.

  • api_access_key

    The Cloud API Access key.

Optional arguments:

  • wsserver

    The address of the cloud web server. By default the wrappers call web services on https://ws-<cloud_id>.aculabcloud.net. In certain circumstances you may need to use a different address which you can set here.

rest_interrupt(app_inst_id_list, redirect_page=None, redirect_method=None)

This will interrupt one or more REST application instances that are running on Aculab Cloud.

Required arguments:

  • app_inst_id_list

    A list of Application Instance IDs.

Optional arguments:

  • redirect_page

    A string. The page to which to send the result of the interrupt.

  • redirect_method

    A string. The method (GET, POST) to use when accessing redirect_page.

Returns a dictionary.Each key is an Application Instance ID, the value is one of the following strings:

  • "no such application" - An application with the given instance ID does not exist. Perhaps it completed some time ago.

  • "application already completed" - No action was interrupted because the application has recently completed.

  • "interrupted" - The application instance was interrupted.

conference_web_service

The conference_web_service class is used to reserve conferences and manage participants of the conferences.

class web_service_wrappers.conference_web_service(cloud_id, username, api_access_key, wsserver=None)

Required arguments:

  • cloud_id

    The Aculab Cloud region (e.g. 1-2-0).

  • username

    The Cloud account username.

  • api_access_key

    The Cloud API Access key.

Optional arguments:

  • wsserver

    The address of the cloud web server. By default the wrappers call web services on https://ws-<cloud_id>.aculabcloud.net. In certain circumstances you may need to use a different address which you can set here.

conference_list()

This lists all of the user's reserved and currently active conferences.

Returns a list of dictionaries. Each dictionary describes a conference.

conference_participant_eject(conference_name, participant_id)

This ejects the named participant from the named active conference.

Required arguments:

  • conference_name

    A string. A conference name as returned by conference_list().

  • participant_id

    A string. A conference participant_id as returned by Conference Participant List.

Returns a dictionary that contains the "ejected" key. Its value is Boolean True if the ejection was a success.

conference_participant_list(conference_name=None, reservation_token=None)

This obtains a list of currently connected participants in the named conference.

Optional arguments:

  • conference_name

    A string. A conference name as returned by conference_list(). If omitted, the reservation_token argument must be supplied.

  • reservation_token

    A string. Alternate instead of conference_name. a conference reservation token as returned by Conference. If omitted, the conference_name argument must be supplied.

Returns a dictionary containing the following keys:

  • 'status' - A string. The current state of the conference

  • 'participant' - List of dictionaries. Each dictionary corresponds to each participant in the conference.

conference_participant_set_options(conference_name, participant_id, muted, dtmf_enabled)

This sets the values of the muted and dtmf_enabled properties of the named participant in the named conference.

Required arguments:

  • conference_name

    A string. A conference name as returned by conference_list().

  • participant_id

    A string. A conference participant_id as returned by conference_participant_list().

  • muted

    A boolean. True to mute the participant, or False to unmute the participant.

  • dtmf_enabled

    A boolean. True to enable dtmf key actions for the participant, or False to disable these.

Returns a dictionary that contains the "options_set" key. Its value is True if the options were set successfully, otherwise the value is 'false'.

conference_reservation_create(conference_name, max_participants, start_datetime, duration, divert=None)

This makes a conference reservation on the Aculab Cloud for a number of participants, at a specified time and for a specified duration.

Required arguments:

  • conference_name

    A string. A conference name as returned by conference_list().

  • max_participants

    An integer. The maximum expected number of participants. Must be between 40 and 350.

  • start_datetime

    A naive datetime object. The required start time in UTC. Must be at least 5 minutes in the future, but no more than 24 hours.

  • duration

    An integer. The required duration in minutes. Must be between 15 and 480.

Optional arguments:

  • divert

    A string. The inbound service to bounce early participants to. If not present, early callers will be busied instead.

Returns a dictionary that contains the "reservation_token" key. Its value is the reservation token that corresponds to the reserved conference.

conference_reservation_modify(reservation_token, duration)

This modifies an existing conference reservation identified by its reservation token.

Required arguments:

  • reservation_token

    A string. The reservation token that corresponds to the reserved conference.

  • duration

    An integer. The number of minutes by which to extend the existing conference reservation. Must be between 15 and 60 minutes, and cannot take the total conference duration beyond 480 minutes.

Returns a dictionary that contains the "extended" key. Its value is Boolean True if the modification was a success.

conference_reservation_remove(reservation_token)

This removes an existing conference reservation.

Required arguments:

  • reservation_token

    A string. The reservation token that corresponds to the reserved conference.

Returns a dictionary that contains the "removed" key. Its value is Boolean True if the removal was a success.

telephone_numbers_web_service

The telephone_numbers_web_service class is used to manage purchase and deletion of inbound telephone numbers.

class web_service_wrappers.telephone_numbers_web_service(cloud_id, username, api_access_key, wsserver=None)

Required arguments:

  • cloud_id

    The Aculab Cloud region (e.g. 1-2-0).

  • username

    The Cloud account username.

  • api_access_key

    The Cloud API Access key.

Optional arguments:

  • wsserver

    The address of the cloud web server. By default the wrappers call web services on https://ws-<cloud_id>.aculabcloud.net. In certain circumstances you may need to use a different address which you can set here.

tel_delete_numbers(numbers_list)

This deletes one or more of the purchased telephone numbers.

Required arguments:

  • numbers_list

    A list of telephone numbers (strings) to delete.

Returns a dictionary containing the following keys:

  • 'status' - A status string containing "OK" if all the specified numbers were deleted, "PARTIAL" if at least one, but not all the numbers were deleted and "FAIL" if none of the numbers were deleted.

  • 'numbers' - If the status string is not "OK", then the 'numbers' key will be present. Its value is a dictionary, keyed by the numbers that failed to delete.

tel_get_supported_countries(did_type=None)

This obtains a list of the countries for which telephone numbers can be purchased.

Optional arguments:

  • did_type

    A string. A string. One of "geographic", "national", "mobile" or "tollfree". Default is "geographic".

Returns a list that contain the names of the countries supported.

tel_get_supported_regions(country, state=None, did_type=None)

This obtains a list of the regions in a specified country for which telephone numbers can be purchased.

Required arguments:

  • country

    A string. The country in which to list the supported regions.

Optional arguments:

  • state

    A string. The state in which to list the supported regions (Only required for some countries).

  • did_type

    A string. One of "geographic", "national", "mobile" or "tollfree". Default is "geographic".

Returns a list that contain the names of the regions supported.

tel_get_supported_states(country)

This obtains a list of the states in a specified country for which telephone numbers can be purchased.

Required arguments:

  • country

    A string. The country in which to list the supported states.

Returns a list that contain the names of the countries supported.

tel_list_numbers(country=None, state=None, region=None, did_type=None)

This lists purchased telephone numbers. It can be filtered by location.

Required arguments:

  • country

    A string. The country where the number is located.

Optional arguments:

  • state

    A string. The state where the number is located (Required for some countries).

  • region

    A string. The region where the number is located. This is a region name for geographic numbers or a number prefix for toll free or national numbers.

  • did_type

    A string. One of "geographic", "national", "mobile" or "tollfree". Default is "geographic".

Returns a dictionary. Each dictionary key is a telephone number. Its value is a dictionary containing details about that number.

tel_list_regulation_addresses()

This lists any regulation addresses that have been registered on a cloud account.

Returns a dictionary. Each dictionary key is a regulation address. Its value is a dictionary containing details about the location of the address.

tel_purchase(country, region, state=None, regulation_address=None, quantity=None, based_on=None, allow_partial=None, did_type=None, allow_landline=None, allow_cellular=None, allow_payphone=None)

This purchases an inbound telephone number in the region, state (optional) and country you choose - for example London, United Kingdom. Please note that this service results in an immediate and subsequent monthly cost.

Required arguments:

  • country

    A string. The country where the number is located.

  • region

    A string. The region where the number is located. This is a region name for geographic numbers or a number prefix for toll free or national numbers.

Optional arguments:

  • state

    A string. The state where the number is located (Required for some countries).

  • regulation_address

    A string. The name of registered regulation address that exists on the cloud account being used (Required for some countries).

  • quantity

    An integer. The quantity of telephone numbers to purchase. Default is 1.

  • based_on

    A string. The name of an existing inbound service. If set then a new service will be created for each new number purchased, based on the specified service.

  • allow_partial

    A string. "true" or "false". Determines whether the request responds as having succeeded even if not all the requested telephone numbers are available. Defaults to "false".

  • did_type

    A string. The type of each new number purchased. One of "geographic", "national", "mobile" or "tollfree". Default is "geographic".

  • allow_landline

    A string. "true" or "false". For toll free numbers only. "true" to allow calls from landline numbers. Otherwise calls from landlines are blocked. Defaults to "false".

  • allow_cellular

    A string. "true" or "false". For toll free numbers only. "true" to allow calls from cellular (mobile) phones. Otherwise calls from cell phones (mobiles) are blocked. Defaults to "false".

  • allow_payphone

    A string. "true" or "false". For toll free numbers only. "true" to allow calls from payphones. Otherwise calls from payphones are blocked. Defaults to "false".

Returns a list containing the numbers purchased

tel_purchase_development(country, region, state=None, regulation_address=None, quantity=None, based_on=None, allow_partial=None, did_type=None, allow_landline=None, allow_cellular=None, allow_payphone=None)

This mimics the actual purchase service, and is provided for development use. It does not result in a purchase so no cost is incurred.

Returns a list containing the development numbers purchased

number_lookup_web_service

The number_lookup_web_service class is used to check the line type and the carrier name of a phone number.

class web_service_wrappers.number_lookup_web_service(cloud_id, username, api_access_key, wsserver=None)

Required arguments:

  • cloud_id

    The Aculab Cloud region (e.g. 1-2-0).

  • username

    The Cloud account username.

  • api_access_key

    The Cloud API Access key.

Optional arguments:

  • wsserver

    The address of the cloud web server. By default the wrappers call web services on https://ws-<cloud_id>.aculabcloud.net. In certain circumstances you may need to use a different address which you can set here.

check(phone_number)

This is used to check the details of the specified telephone number.

Required arguments:

  • phone_number

    A string. The telephone number to check in international format.

Returns a dictionary containing the following keys:

  • 'number_found' - A bool. Whether the specified telephone number was found.

  • 'country_name' - A string. (Only present if the number was found) The full country name assigned to the specified telephone number.

  • 'country_code' - A string. (Only present if the number was found) The two-letter ISO 3166-1 alpha-2 country code assigned to the specified telephone number.

  • 'line_type' - A string. (Only present if the number was found) The line type of this telephone number.

  • 'carrier' - A string. (Only present if the number was found) The name of the carrier with which the specified phone number is registered.

reports_web_service

The reports_web_service class allows you to request and retrieve reports from Aculab Cloud.

class web_service_wrappers.reports_web_service(cloud_id, username, api_access_key, wsserver=None)

Required arguments:

  • cloud_id

    The Aculab Cloud region (e.g. 1-2-0).

  • username

    The Cloud account username.

  • api_access_key

    The Cloud API Access key.

Optional arguments:

  • wsserver

    The address of the cloud web server. By default the wrappers call web services on https://ws-<cloud_id>.aculabcloud.net. In certain circumstances you may need to use a different address which you can set here.

report_cancel(filename)

This cancels generation of a report.

Required arguments:

  • filename

    A string. The filename of the report to cancel.

Returns nothing.

report_delete(filename)

This deletes a completed report from Aculab Cloud.

Required arguments:

  • filename

    A string. The filename of the report to delete.

Returns nothing.

report_get(filename, local_file)

This downloads a completed report from Aculab Cloud.

Required arguments:

  • filename

    A string. The filename of the report that is stored on the cloud.

  • local_file

    A string. The filename for the downloaded file.

Returns nothing.

report_list()

This lists all completed reports.

Returns a dictionary. Each dictionary key is a name of a completed report. Its value is a dictionary containing the following keys:

  • 'modified' - A string. The last modification time of the report.

  • 'size' - A string. The size of the report in bytes.

report_progress()

This queries the status of any reports currently in progress.

Returns a dictionary. Each dictionary key is a name of a report in progress. Its value is a dictionary containing the following keys:

  • 'record' - An integer. The number of records written to the report.

  • 'progress' - A string. A progress percentage (based on the start and end time).

report_start(report, from_datetime, to_datetime=None)

This starts generation of a new report containing comma-separated values.

Required arguments:

  • report

    A string. The required content of the report. Set this to either adr (For an application data record), cdr (For a call data record), fdr (For a feature data record), msg (For an SMS message record) or err (For an error record).

  • from_datetime

    A naive datetime object. The point at which at the report should start.

Optional arguments:

  • to_datetime

    A naive datetime object. The point at which the report should end. Defaults to UTC time now.

Returns a dictionary that contains the "filename" key. Its value is the filename of the report.

webrtc_client_web_service

The webrtc_client_web_service class allows you to register to receive calls from Aculab Cloud applications.

class web_service_wrappers.webrtc_client_web_service(cloud_id, username, api_access_key, wsserver=None)

Required arguments:

  • cloud_id

    The Aculab Cloud region (e.g. 1-2-0).

  • username

    The Cloud account username.

  • api_access_key

    The Cloud API Access key.

Optional arguments:

  • wsserver

    The address of the cloud web server. By default the wrappers call web services on https://ws-<cloud_id>.aculabcloud.net. In certain circumstances you may need to use a different address which you can set here.

generate_token(client_id, time_to_live=0, enable_incoming=True, call_clients=None)

This generates a token to allow WebRTC clients to register for calls.

Required arguments:

  • client_id

    A string. The client id of the WebRTC client that will be registered. This is the same as the clientId used when creating the WebRTC client.

Optional arguments:

  • time_to_live

    An integer. The time, in seconds, that the token is valid for. This must be between 600 and 86400 inclusive. The default is 3600 (1 hour).

  • enable_incoming

    A boolean. If True, the client that uses the generated token will be able to receive calls.

  • call_clients

    A string. One or more Ids for clients that can be called by the client. For each id, the last character can be a '*' wildcard in which case it matches any client whose Id starts with the string. A single '*' matches all clients. If no value is given the token cannot be used for calling other clients.

Returns the token generated.

list_registered_clients()

This returns a list of clients that are currently registered for calls.

Returns a list of dictionaries. Each dictionary contains the following keys:

  • 'client_id' - A string. The client id used to register the client.

  • 'last_modified' - A naive datetime object. The UTC date and time when the registration was last modified.

  • 'expires' - A naive datetime object. The UTC date and time when the registration expires.

security_web_service

The security_web_service class allows you to check that web service requests are made in a secure manner.

class web_service_wrappers.security_web_service(cloud_id, username, api_access_key, protocol=None, wsserver=None)

Required arguments:

  • cloud_id

    The Aculab Cloud region (e.g. 1-2-0).

  • username

    The Cloud account username.

  • api_access_key

    The Cloud API Access key.

Optional arguments:

  • protocol

    A string representing the protocol to support. Can be set to "tls10", "tls11", "tls12" or "tls13". By default, the wrappers will use the latest available protocols. For diagnostic purposes you can specify your own protocol to support.

  • wsserver

    The address of the cloud web server. By default the wrappers call web services on https://ws-<cloud_id>.aculabcloud.net. In certain circumstances you may need to use a different address which you can set here.

protocol_check()

Check if the security protocol used for web service requests is sufficiently secure.

Returns a dictionary containing the following keys:

  • 'pass' - boolean true if the connection is secure, false otherwise.

  • 'protocol' - A string. The protocol used, e.g. TLSv1.2.

  • 'cipher' - A string. The cipher used.

  • 'user_agent' - A string. The User-Agent header passed in the request. If the header was not present, an empty string is returned.

  • 'source_address'- A string. The source address of the request that reached the web services server.

  • 'reason' - A string. A description of the cause of a failed check. Not present if the check passed.