Skip to content

HTTP Response

See also: HTTP request, actions

The HTTP response sent by your web page should contain a JSON format string representing an object with the following properties:

PropertyRequired/OptionalDescription
actions required An array of Action objects.
token optional An optional user-defined string. This defaults to null.
call recording cipher optional A cipher object specifying how to encrypt the whole call recording. Defaults to null.

call recording cipher contains the details of the cipher to be used to encrypt the whole call recording:

PropertyRequired/OptionalDescription
type required The cipher type, currently only "aescbc" (AES algorithm, CBC mode) is supported.

For the aescbc cipher the following properties must be supplied in the cipher object:

PropertyRequired/OptionalDescription
key required The cipher key as a string, either 128, 192 or 256 bits represented as 16, 24 or 32 hexadecimal bytes.
initialisation vector required The initialisation vector as a string, 128 bits represented as 16 hexadecimal bytes.

Remarks

The actions sent in the response are executed in the order they are specified.

Some actions can return a result and these have a next page property. When a request is made to a next page the returned action list supercedes the original action list and its remaining actions are discarded.

When there are no actions remaining the call is hung up and the Final page is requested.

Whole call recording for the primary call can optionally be enabled on the service configuration page. If this recording is to be encrypted, supply the cipher in the response to the request on the first page. Whole call recording for a secondary call can be specified in the connect or connect to conference actions. If this is enabled, and is to be encrypted, supply the cipher in the response to the request on the secondary call's first page.

Examples:

Return a simple action list: 

    {
        "actions" :
        [
            {
                "play" :
                { 
                    "play_list" :                 
                    [
                        {
                            "text_to_say" : "Please leave a message after the beep."
                        }                    
                    ]
                }
            },
            {
                "record" :
                {
                    "beep_on_start" : true
                }
            }
        ],
        "token" : "my token id 13324"
    }

Return a simple action list and a cipher to be used to encrypt whole call recording (enabled on the service configuration page): 

    {
        "actions" :
        [
            {
                "run_menu" :
                {
                    "prompt" :
                    {
                        "play" :
                        {
                            "play_list" :
                            [
                                {
                                    "text_to_say" : "Please press 1 for yes and 2 for no."
                                }
                            ]
                        }
                    },
                    "menu_options" : 
                    [
                        {
                            "digit" : "1",
                            "next_page" : 
                            {
                                "url" : "optionyespage"
                            }
                        },
                        {
                            "digit" : "2",
                            "next_page" : 
                            {
                                "url" : "optionnopage"
                            }
                        }
                    ]
                }
            }
        ],
        "token" : "my token id 13325",
        "call_recording_cipher" :
        {
            "type" : "aescbc",
            "key" : "1F2DEB2E502A4C8CBA58AB5018BD1506419EEA86DF595D3A431F43FAF57534C9",
            "initialisation_vector" : "9B85FAED9AB17570D5A82A31F846443B"
        }
    }

Return an empty action list: 

    {
        "actions" :
        [
        ],
        "token" : "my token id 13326"
    }

class TelephonyResponse

Constructors:

  TelephonyResponse(List<TelephonyAction> actions);
  TelephonyResponse(List<TelephonyAction> actions, String token);
  TelephonyResponse(String token);

Members:

  ToHttpResponse(HttpResponse response);
  Cipher CallRecordingCipher;
class Cipher Represents a cipher to be used for file encryption/decryption.

Members:

String Type;
class AesCbcCipher : Cipher Represents the AES cipher in CBC mode.

Constructors:

AesCbcCipher(byte[] key, byte[] initialisationVector);

Members:

byte[] InitialisationVector;

Examples:

Return a simple action list: 

  using System;
  using System.Collections.Generic;
  using System.Web;
  using RestAPIWrapper;

  public partial class Acknowledgement : System.Web.UI.Page
  {
    protected void Page_Load(object sender, EventArgs e)
    {
      // Unpack the request
      TelephonyRequest myRequest = new TelephonyRequest(Request);
      if (!myRequest.IsValid)
      {
        return;
      }

      // Access the request properties
      String token = myRequest.InstanceInfo.Token;

      // Set up some actions to perform
      List<TelephonyAction> actions = new List<TelephonyAction>();
      actions.Add(Play.SayText("Please leave a message after the beep."));
      Record recordAction = new Record();
      recordAction.BeepOnStart = true;
      actions.Add(recordAction);

      // Respond
      TelephonyResponse myResponse = new TelephonyResponse(actions, token);
      myResponse.ToHttpResponse(Response);
  }

Return a simple action list and a cipher to be used to encrypt whole call recording (enabled on the service configuration page): 

  using System;
  using System.Collections.Generic;
  using System.Web;
  using RestAPIWrapper;

  public partial class Acknowledgement : System.Web.UI.Page
  {
    protected void Page_Load(object sender, EventArgs e)
    {
      // Unpack the request
      TelephonyRequest myRequest = new TelephonyRequest(Request);
      if (!myRequest.IsValid)
      {
        return;
      }

      // Access the request properties
      String token = myRequest.InstanceInfo.Token;

      // Set up some actions to perform
      List<TelephonyAction> actions = new List<TelephonyAction>();
      Play prompt = Play.SayText("Please press 1 for yes and 2 for no.");
      List<MenuOption> options = new List<MenuOption>();
      options.Add(new MenuOption('1', new WebPageRequest("OptionYesPage.aspx")));
      options.Add(new MenuOption('2', new WebPageRequest("OptionNoPage.aspx")));
      actions.Add(new RunMenu(prompt, options));

      // Specify a 256 bit cipher to be used to encrypt the whole call recording
      byte[] key = new byte[] {
          0x1F, 0x2D, 0xEB, 0x2E, 0x50, 0x2A, 0x4C, 0x8C,
          0xBA, 0x58, 0xAB, 0x50, 0x18, 0xBD, 0x15, 0x06,
          0x41, 0x9E, 0xEA, 0x86, 0xDF, 0x59, 0x5D, 0x3A,
          0x43, 0x1F, 0x43, 0xFA, 0xF5, 0x75, 0x34, 0xC9 };

      byte[] initialisationVector = new byte[] {
          0x9B, 0x85, 0xFA, 0xED, 0x9A, 0xB1, 0x75, 0x70,
          0xD5, 0xA8, 0x2A, 0x31, 0xF8, 0x46, 0x44, 0x3B };

      Cipher cipher = new AesCbcCipher(key, initialisationVector);

      // Respond
      TelephonyResponse myResponse = new TelephonyResponse(actions, token);
      myResponse.CallRecordingCipher = cipher;
      myResponse.ToHttpResponse(Response);
  }

Return an empty action list: 

  using System;
  using System.Collections.Generic;
  using System.Web;
  using RestAPIWrapper;

  public partial class Acknowledgement : System.Web.UI.Page
  {
    protected void Page_Load(object sender, EventArgs e)
    {
      // Unpack the request
      TelephonyRequest myRequest = new TelephonyRequest(Request);
      if (!myRequest.IsValid)
      {
        return;
      }

      // Access the request properties
      String token = myRequest.InstanceInfo.Token;

      // Respond
      TelephonyResponse myResponse = new TelephonyResponse(token);
      myResponse.ToHttpResponse(Response);
  }

Class TelephonyResponse

Constructors:

  New(actions As List(Of TelephonyAction))
  New(actions As List(Of TelephonyAction), token As String)
  New(token As String)

Members:

  ToHttpResponse(response As HttpResponse)
  CallRecordingCipher As Cipher
class Cipher Represents a cipher to be used for file encryption/decryption.

Members:

  Type As String
class AesCbcCipher : Cipher Represents the AES cipher in CBC mode.

Constructors:

  AesCbcCipher(ByVal key As Byte(), ByVal initialisationVector As Byte())

Members:

  InitialisationVector As Byte()

Examples:

Return a simple action list: 

  Imports System
  Imports System.Collections.Generic
  Imports System.Web
  Imports RestAPIWrapper

  Partial Class Acknowledgement 
    Inherits System.Web.UI.Page

    Protected Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs)

      ' Unpack the request
      Dim ourRequest As TelephonyRequest = New TelephonyRequest(Request)
      If Not ourRequest.IsValid Then
        Return
      End If

      ' Access the request properties
      Dim token As String = myRequest.InstanceInfo.Token

      ' Set up some actions to perform
      Dim actions As List(Of TelephonyAction) = New List(Of TelephonyAction)
      actions.Add(Play.SayText("Please leave a message after the beep."))
      Dim recordAction As Record = New Record()
      recordAction.BeepOnStart = True
      actions.Add(recordAction)

      ' Respond
      Dim ourResponse As TelephonyResponse = New TelephonyResponse(actions, token)
      ourResponse.ToHttpResponse(Response)

    End Sub
  End Class

Return a simple action list and a cipher to be used to encrypt whole call recording (enabled on the service configuration page): 

  Imports System
  Imports System.Collections.Generic
  Imports System.Web
  Imports RestAPIWrapper

  Partial Class Acknowledgement 
    Inherits System.Web.UI.Page

    Protected Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs)

      ' Unpack the request
      Dim ourRequest As TelephonyRequest = New TelephonyRequest(Request)
      If Not ourRequest.IsValid Then
        Return
      End If

      ' Access the request properties
      Dim token As String = myRequest.InstanceInfo.Token

      ' Set up some actions to perform
      Dim actions As List(Of TelephonyAction) = New List(Of TelephonyAction)
      Dim prompt As Play = Play.SayText("Please press 1 for yes and 2 for no.")
      Dim options As List(Of MenuOption) = New List(Of MenuOption)
      options.Add(New MenuOption("1", New WebPageRequest("OptionYesPage.aspx")))
      options.Add(New MenuOption("2", New WebPageRequest("OptionNoPage.aspx")))
      actions.Add(New RunMenu(prompt, options))

      ' Specify a 256 bit cipher to be used to encrypt the whole call recording
      Dim key As Byte() = {
          &H1F, &H2D, &HEB, &H2E, &H50, &H2A, &H4C, &H8C,
          &HBA, &H58, &HAB, &H50, &H18, &HBD, &H15, &H06,
          &H41, &H9E, &HEA, &H86, &HDF, &H59, &H5D, &H3A,
          &H43, &H1F, &H43, &HFA, &HF5, &H75, &H34, &HC9 }

      Dim initialisationVector As Byte() = {
          &H9B, &H85, &HFA, &HED, &H9A, &HB1, &H75, &H70,
          &HD5, &HA8, &H2A, &H31, &HF8, &H46, &H44, &H3B }

      Dim encryptionCipher As Cipher = New AesCbcCipher(key, initialisationVector)

      ' Respond
      Dim ourResponse As TelephonyResponse = New TelephonyResponse(actions, token)
      ourResponse.CallRecordingCipher = encryptionCipher
      ourResponse.ToHttpResponse(Response)

    End Sub
  End Class

Return an empty action list: 

  Imports System
  Imports System.Collections.Generic
  Imports System.Web
  Imports RestAPIWrapper

  Partial Class Acknowledgement 
    Inherits System.Web.UI.Page

    Protected Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs)

      ' Unpack the request
      Dim ourRequest As TelephonyRequest = New TelephonyRequest(Request)
      If Not ourRequest.IsValid Then
        Return
      End If

      ' Access the request properties
      Dim token As String = myRequest.InstanceInfo.Token

      ' Respond
      Dim ourResponse As TelephonyResponse = New TelephonyResponse(token)
      ourResponse.ToHttpResponse(Response)

    End Sub
  End Class

class TelephonyResponse

Constructors:

  TelephonyResponse(List<TelephonyAction> actions);
  TelephonyResponse(List<TelephonyAction> actions, String token);
  TelephonyResponse(String token);

Members:

  setHttpServletResponse(HttpServletResponse response);
  setCallRecordingCipher(Cipher cipher);
class Cipher Represents a cipher to be used for file encryption/decryption.

Members:

String getType();
class AesCbcCipher extends Cipher Represents the AES cipher in CBC mode.

Constructors:

AesCbcCipher(byte[] key, byte[] initialisationVector);

Members:

byte[] getInitialisationVector();
setInitialisationVector(byte[] iv);

Examples:

Return a simple action list: 

  public void doGet(HttpServletRequest request, HttpServletResponse response) 
  // or doPost()
  {
    // Unpack the request
    TelephonyRequest ourRequest = new TelephonyRequest(request);
    if (!ourRequest.isValid())
    {
      return;
    }

    // Access the request properties
    String token = myRequest.getToken();

    // Set up some actions to perform
    List<TelephonyAction> actions = new ArrayList<TelephonyAction>();
    actions.add(Play.sayText("Please leave a message after the beep."));
    Record record = new Record();
    record.setBeepOnStart(true);
    actions.add(record);

    // Respond
    TelephonyResponse ourResponse = new TelephonyResponse(actions, token);
    ourResponse.setHttpServletResponse(response);
  }

Return a simple action list and a cipher to be used to encrypt whole call recording (enabled on the service configuration page): 

  public void doPost(HttpServletRequest request, HttpServletResponse response) 
  {
    // Unpack the request
    TelephonyRequest ourRequest = new TelephonyRequest(request);
    if (!ourRequest.isValid())
    {
      return;
    }

    // Access the request properties
    String token = myRequest.getToken();

    // Set up some actions to perform
    List<TelephonyAction> actions = new ArrayList<TelephonyAction>();
    Play prompt = Play.sayText("Please press 1 for yes and 2 for no.");
    List<MenuOption> options = new ArrayList<MenuOption>();
    options.add(new MenuOption('1', new WebPageRequest("optionYesPage")));
    options.add(new MenuOption('2', new WebPageRequest("optionNoPage")));
    actions.add(new RunMenu(prompt, options));

    // Specify a 256 bit cipher to be used to encrypt the whole call recording
    byte[] key = new byte[] {
        0x1F, 0x2D, 0xEB, 0x2E, 0x50, 0x2A, 0x4C, 0x8C,
        0xBA, 0x58, 0xAB, 0x50, 0x18, 0xBD, 0x15, 0x06,
        0x41, 0x9E, 0xEA, 0x86, 0xDF, 0x59, 0x5D, 0x3A,
        0x43, 0x1F, 0x43, 0xFA, 0xF5, 0x75, 0x34, 0xC9 };
    byte[] initialisationVector = new byte[] {
        0x9B, 0x85, 0xFA, 0xED, 0x9A, 0xB1, 0x75, 0x70,
        0xD5, 0xA8, 0x2A, 0x31, 0xF8, 0x46, 0x44, 0x3B };
    Cipher cipher = new AesCbcCipher(key, initialisationVector);

    // Respond
    TelephonyResponse ourResponse = new TelephonyResponse(actions, token);
    ourResponse.setCallRecordingCipher(cipher);
    ourResponse.setHttpServletResponse(response);
  }

Return an empty action list: 

  public void doGet(HttpServletRequest request, HttpServletResponse response) 
  {
    // Unpack the request
    TelephonyRequest ourRequest = new TelephonyRequest(request);
    if (!ourRequest.isValid())
    {
      return;
    }

    // Access the request properties
    String token = myRequest.getToken();

    // Respond
    TelephonyResponse ourResponse = new TelephonyResponse(token);
    ourResponse.setHttpServletResponse(response);
  }

The telephony response. The response body is returned by a call to the Actions class' get_json() function, once all the required actions have been added.

Examples:

Getting the response body: 

from aculab.telephony_rest_api import Actions, Sleep

my_actions = Actions(token='Usage example: Sleep')
my_actions.add(Sleep(seconds=10))

response_body = my_actions.get_json()

Getting the response body. Include a cipher to be used with whole call recording: 

from aculab.telephony_rest_api import Actions, Sleep

my_actions = Actions(token='Usage example: Sleep')
my_actions.add(Sleep(seconds=10))

my_cipher=AESCBCCipher(my_key, my_vector)
my_actions.set_cipher(cipher)

response_body = my_actions.get_json()

The Actions class

Introduction

Represents the actions the application wishes to perform.

Class synopsis

class Actions {

    /* methods */
    public __construct()
    public void setToken(string $token)
    public void setCallRecordingCipher(Cipher $cipher)
    public void add(ActionBase $action)
    public string __toString()
}
The Cipher class

Introduction

An abstract class to represent ciphers.

Class synopsis

abstract class Cipher {

    /* methods */
    public __construct(string $type)
}
The AesCbcCipher class

Introduction

A class to represent a cipher using AES in CBC mode.

Class synopsis

$key and $initialisation_vector are strings of hexadecimal bytes. 

class AesCbcCipher extends Cipher{

    /* methods */
    public __construct(string $key, string $initialisation_vector)
}

Examples:

Return a simple action list: 

$actions = new Aculab\TelephonyRestAPI\Actions();
$actions->setToken('my token id 13325');

$actions->add(Aculab\TelephonyRestAPI\Play::sayText('Please leave a message after the beep.'));

$record = new Aculab\TelephonyRestAPI\Record();
$record->setBeepOnStart(true);
$actions->add($record);

// output the JSON
print $actions;

Return a simple action list and a cipher to be used to encrypt whole call recording (enabled on the service configuration page): 

$actions = new Aculab\TelephonyRestAPI\Actions();
$actions->setToken('my token id 13325');

$mp = new Aculab\TelephonyRestAPI\Play();
$mp->addText('Please press 1 for yes and 2 for no.');
$menu = new Aculab\TelephonyRestAPI\RunMenu($mp);
$menu->addMenuOption('1', 'optionyespage');
$menu->addMenuOption('2', 'optionnopage');
$actions->add($menu);

$cipher = new Aculab\TelephonyRestAPI\AesCbcCipher(
    "1F2DEB2E502A4C8CBA58AB5018BD1506419EEA86DF595D3A431F43FAF57534C9",
    "9B85FAED9AB17570D5A82A31F846443B"
);
$actions->setCallRecordingCipher($cipher);

// output the JSON
print $actions;

return an empty action list: 

$actions = new Aculab\TelephonyRestAPI\Actions();
$actions->setToken('my token id 13326');

// output the JSON
print $actions;