User Application Server (UAS)¶
Version: 1.3.8.
Created: Nov 16, 2022.
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.
The UAS is an application that will launch user applications and record statistics.
The UAS Management Console communicates with the UAS to provide a management console via your web browser.
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](_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 API to invoke outbound applications and manage media files.
![_images/CloudArchitecture.jpg](_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](_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](_images/OutboundDiagCloud.png)
The UAS¶
The UAS consists of two applications that can run as Windows services or Linux daemons.
The UAS Launcher¶
Writing a UAS application¶
The UAS supports three types of application: an inbound call application that is triggered by an incoming telephone call; an inbound media application that is triggered by incoming media (such as an SMS message); and an outbound application that is triggered by the Web Services API.
- Introduction
- Call duration limiter
- Creating loops within an application
- Applications and Services
- Placing an outbound call
- Importing applications
- Importing other files
- Modifying applications
- Modifying common files
- Application return codes
- The Error exception
- The Hangup exception
- The ToneManager class
- The application main function
- application_parameters
- outbound_parameters
- The call channel class
- The file manager class
- The logger class
- The unique application ID
- Text to Speech
- Automatic Speech Recognition
- Application templates
- Common file template
- Global variables
- Recording, replacing and deleting
- Directories
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.
Call control¶
Inbound and outbound call control provided by the channel object.
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 Web Services API¶
Aculab Cloud provides a number of web services that implement features such as initiating outbound services, managing files, telephone numbers and other resources on the cloud. You can make requests to these web services directly or you can use one of our high-level language wrappers (The languages available are .Net, Python, Java and PHP).
Download a High-Level Language Web Services Wrapper Package from the Aculab cloud website and get everything you need to start using the web services. Each wrapper package contains a library that wraps the calls to the web services and the responses obtained. The packages also contain standalone sample applications that illustrate how to use each service wrapper.
Tutorial¶
A step-by-step guide to writing UAS applications.
- The applications tutorial
- Introduction
- The application version
- The application identifier
- The main function
- A very basic inbound application
- Checking the call state
- The Hangup exception
- The Error exception
- Creating loops within an application
- Introducing the logger
- The outbound call
- SIP Headers, INFO and MESSAGE
- Media recording and playback
- Encryption and Decryption
- Text to Speech
- Whole call recording
- Dual Tone Multi-Frequency (DTMF)
- Speech Detection (ASR)
- File handling
- The extra channel
- Connecting calls
- Retrievable call transfer
- Transfer to a conference room
- Connect to a conference room
- Calling a local application
- Calling a conference room
- Fax
- Multiple file applications
- Further reading
Examples¶
The source for several example applications.
Troubleshoot¶
- Troubleshooting
- The Windows service or Linux daemon won’t start
- My browser can’t access the UAS management console
- The UAS is very slow
- The UAS runs out of file descriptors
- The UAS management console can’t upload applications
- Uploading an application results in an import error
- How do I manually control the Windows services
- I have moved or deleted a file from my media store but it is still there