Lifecycle of a REST Application

Starting Applications

Outbound and inbound REST API applications are started differently. Both rely on you having set up a service on Aculab Cloud.

Making an Outbound Call

You call a web service on Aculab Cloud that starts an outbound service. This makes an outbound call to the destination you specified. When the call is answered Aculab Cloud makes a request to the first page of your outbound REST API application.

outbound call diagram

Receiving an Inbound Call

Aculab Cloud receives a call to one of your inbound services identified by name. Aculab Cloud then makes a request to the first page of your inbound REST API application.

inbound call diagram

Hanging Up a Call

When all of your actions have been run or an error has occurred the call is automatically hung up. Your Final page is then requested. This is always the last page of your application that Aculab Cloud requests. It allows you to perform any clean-up, populate any databases, etc. You can call the delete file action here.

Supported Features

Within your application you have access to the following REST API features:

  • Answering, rejecting, or hanging up a call
  • Playing a wav file
  • Playing text using Text-To-Speech
  • Playing telephone keypad tones
  • Recording the incoming audio to wav file
  • Recording the whole call to wav file (enabled in the service configuration)
  • Obtaining speech input see the get input action
  • Obtaining input from the telephone keypad see the get number and get input actions
  • Transcribing audio on a call
  • Connecting a call to a new call
  • Connecting a call to a conference
  • Sending and receiving a fax
  • Interactive menus see the run menu and run speech menu actions
  • Sleep for a number of seconds
  • Redirect to another web page
  • Deleting a media file

Within the Inbound and Outbound Service configurations you can configure the following features:

  • Outbound Call Type: What you'd like Aculab Cloud to call when you start this outbound service, a telephone or a conference. Calling a conference in this way is unusual, but allows operations such as recording or playing media to the conference.
  • Far-end Classification: Aculab Cloud can classify whether the outgoing call is answered by a human, answering machine or fax machine.
  • Seconds Ring Time: How long Aculab Cloud lets the incoming call ring before accessing your application's First page.
  • Whole Call Recording: Aculab Cloud can record a mix of the inbound and outbound audio for the primary call. The recording is saved to a file in your media file store under rest_api/call_recording/ and the date of the recording. The name of this file is sent to your application's Final page in the call recording filename property of call info.
  • Minutes Max Call Duration: How long your application can run before Aculab Cloud terminates it. This is useful for limiting the duration and cost of problems such as accidental loops in your application.

You can also use the Web Services API in your REST API.

Interrupting an Application

There may be times when you need to interrupt an application in the midst of running an action. For example, during a long play action when you decide you need to call a different action before the play has finished.

You can perform an interrupt using the rest_interrupt web service. You need to supply it with one or more application instance ids from the page request (see HTTP Request) that identify the applications to interrupt. Aculab Cloud will halt the currently running action.

Aculab Cloud will then request the application's final page or a redirect_page, if you have specified it in the call to the interrupt web service.

Handling Errors

If your application encounters a problem (perhaps it has specified a file to play that doesn't exist) your Error Page is accessed, the error result containing details of what went wrong. Although configuring this page is optional, it is useful to do so.

Diagnostic Log

Each time a Rest API application is run a log file will be written to the user's media file store under a directory related to the date it was run. When logged in, you can access this location via the REST Log Files Page.