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;