User Application Server (UAS)

Version: 1.2.265.

Created: May 02, 2018.

Have a look at the quickstart guide on cloud.aculab.com to get started quickly.

If you have already installed a UAS, and want to get started on your own application, you might want to have a look at the tutorial or the call channel API first.

Introduction

The User Application Server (UAS) is designed to work with cloud.aculab.com, which provides cloud-based telephony media processing. The UAS runs voice and fax applications developed using high-level languages such as Python Java and .Net. These applications run within the UAS in response to specific instructions on cloud.aculab.com.

The applications are developed by the user using an API which is described in The call channel API section below.

The UAS consists of three parts - two applications and an API module. The API module is called prosody; the applications are called The UAS and The UAS Management Console.

  1. The UAS is an application that will launch user applications and record statistics.
  2. The UAS Management Console communicates with the UAS to provide a management console via your web browser.
  3. prosody is a python module that provides the API to which applications are written.

The UAS and The UAS Management Console are run as a Windows service or as a Linux daemon.

The UAS package is downloaded as a zip (Windows or Linux) or an exe (Windows) and should be extracted/installed to the location where it is required.

To get started, it is recommended that you follow the online quickstart guide which is available on cloud.aculab.com after you have logged in.

Below is an illustration of the components that make up the telephony system.

_images/CloudOverview.png

The UAS can be configured and monitored remotely via the UAS Management Console.

Users create their own accounts on cloud.aculab.com. This allows them to configure how individual applications are invoked and to manage their media files on cloud.aculab.com.

A web services API provides a programmatic means of handling media files and initiating outgoing calls.

Architecture

Python UAS applications use the API provided by the prosody module. This provides call handling, media processing, file handling and diagnostic facilities. Other Python applications may use the Web Services APIs to invoke outbound applications and manage media files.

_images/CloudArchitecture.jpg

The Python UAS receives a request from cloud.aculab.com instructing it to run a selected user application that is currently loaded in the UAS. User applications typically handle a primary call, either inbound or outbound, and may make other secondary outbound calls. A call may be connected to another call.

A UAS application is invoked by cloud.aculab.com in response to either an incoming call to a specific address or to a request to invoke an application that makes an outbound call.

Inbound calls

The target address of an incoming call (1 in the image below) is used to determine which application is to be executed. A message is sent to the UAS to run an instance of the specified application (2). The application is handed an active incoming call and its first task is typically either to answer it or reject it (3). Optionally, the application can also make an additional outbound call (4).

_images/InboundDiagCloud.png

Outbound calls

The Web Services API can be used to write a web services application that invokes an outbound service (1 in the image below). The service will send a message to the UAS to run an instance of the outbound application specified by the service (2). The outbound application typically then makes an outbound call (3 and 4). Like inbound applications, an outbound application can usually also make additional outbound calls on its extra channels.

_images/OutboundDiagCloud.png

The API

The following descriptions are of the application programmer’s interface. These are the functions and modules that enable the user to implement a telephony application that will be run by the UAS (when prompted to do so by cloud.aculab.com). The primary API is provided by the call channel which is an object that is passed to the application’s main function. The call channel object provides the API that is used to manage the telephone call, it also makes available other objects that can be used to play a file, speak TTS etc. The channel object itself is created and destroyed by the UAS Launcher.

Almost every API function will send a message to cloud.aculab.com and wait for a response before returning. To prevent an infinite wait, in the unlikely event of the response not being received, most API calls implement a timeout for the round-trip delay. Functions that can time-out will mention this in their documentation. Some functions take a timeout as a parameter, this has a different purpose and is not to be confused with the timeout mentioned above.

SIP headers

Send and receive custom SIP headers using an attribute provided by the channel object.

Playing files

Play audio files using an attribute provided by the channel object.

Text to speech

Convert text to speech using the file player attribute provided by the channel object.

Recording

Record incoming audio using an attribute provided by the channel object.

Whole call recording

Record incoming and outgoing audio using an attribute provided by the channel object.

Playing DTMF

Play DTMF digits using an attribute provided by the channel object.

Detecting DTMF

Detect and report DTMF digits using an attribute provided by the channel object.

Speech recognition

Detect and recognise speech using an attribute provided by the channel object.

Conferencing

Before reading up on the UAS conferencing API, please have a look at the online documentation on conferencing which will explain a number of important concepts.

If you are considering running a particularly large conference, this will have to be reserved in advance using the web services API.

Faxing

To send or receive a fax using the call channel API you first create a fax document object and then pass that to the send or receive function exposed by the channel’s FaxSender or FaxReceiver properties. For details on how to use these properties please see the FaxSender and FaxReceiver documentation in the call channel API section.

It is important to note that the API can send only TIFF files. Please see the documentation on protocols and formats for details of the compatible TIFF formats.

Two brief examples are given below. First, sending a fax:

from prosody.uas import FaxToSend

# create the fax document object
my_fax = FaxToSend()

# read the content of a TIFF file into the document
# the TIFF file must be present in your cloud media store
my_fax.set_content('my_outbound_fax.tif')

# send the fax document
channel.FaxSender.send(my_fax)

Second, receiving a fax:

from prosody.uas import FaxToSend

# create the fax document object
my_fax = FaxToReceive()

# set the name of the TIFF file in which the fax will be stored
my_fax.set_file_name('my_inbound_fax.tif')

# receive the fax
channel.FaxReceiver.receive(my_fax)

When sending a fax, it might be desirable to perform some processing on the fax document before sending it, for example, to add some text to each page. In order to facilitate this, the fax document object provides a number of useful functions. The fax document object for the fax receiver would primarily be used to access details of the received fax.

Encrypting and decrypting

Aculab Cloud provides the ability to encrypt and decrypt files that are to be played, recorded or faxed.

The high level API

The high level API is provided to make it easier to perform certain common application tasks. It comes as a wrapper for the channel object and provides some additional functions.

The file manager

Use this object to manage files in your cloud media store.

The tone manager

Create and play custom tones.

Examples

The source for several example applications.

Index