User Application Server (UAS)

Version: 1.3.19.

Created: Jul 03, 2024.

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.

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.

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).

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.

The UAS

The UAS consists of two applications that can run as Windows services or Linux daemons.

The UAS Launcher

• Running the UAS
  • UAS configuration
  • Guidance on updating a UAS on a live system
  • The UAS connection model
  • The applications
  • The application data records
  • The UAS monitor
• Logging
  • The log levels
  • The ADR log file
  • The UAS log
  • The applications log

The UAS management console

• Running the UAS management console
  • UAS management console username and password
  • UAS management console configuration
  • Using the UAS management console

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
  • Working with media files
• 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.

• The call channel object
  • The call control API
  • The Details property
  • The FilePlayer property
  • The FileRecorder property
  • The SpeechDetector result
  • The SpeechDetector property
  • The WholeCallRecorder property
  • The DTMFPlayer property
  • The DTMFDetector property
  • The FaxSender property
  • The FaxReceiver property
  • The SIP property

Call control

Inbound and outbound call control provided by the channel object.

• The call control API
  • Call channel media helper class
  • Call channel settings and states
  • Call channel methods
  • The tone manager
  • The tone player
  • Conference Rooms and Conferences
• The Details property
  • CallDetails

SIP headers

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

• The SIP property
  • HeaderFieldsToSend
  • SIPHeaderField
  • SIPInfo
  • SIPInfoDTMFRelay
  • SIPInfoPlainText
  • SIPMessage
  • SIPMessagePlainText
  • UASCallSIP

Playing files

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

• The FilePlayer property
  • UASCallFilePlayer

Text to speech

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

• The FilePlayer property
  • UASCallFilePlayer

Recording

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

• The FileRecorder property
  • UASCallFileRecorder

Whole call recording

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

• The WholeCallRecorder property
  • UASWholeCallFileRecorder

Playing DTMF

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

• The DTMFPlayer property
  • DTMFPlayer

Detecting DTMF

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

• The DTMFDetector property
  • DTMFDetector

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.

• The fax document objects
  • FaxToSend
  • FaxToReceive

Encrypting and decrypting

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

• The AES CBC cipher object
  • AESCBCCipher

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 high level channel API
  • Speech recognition grammar object
  • Speech recognition digit options
  • The high level call channel

The file manager

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

• The file handler
  • UASFileManagement
  • UASFileManagement.exists()
  • UASFileManagement.delete_file()
  • UASFileManagement.rename()
  • UASFileManagement.validate()

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.

The tone manager

Create and play custom tones.

• The tone manager
• The tone player
  • TonePlayer

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.

• Applications sample code
  • Introduction
  • The samples

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

Index

• Index