Http Response

The HTTP response sent by your web page should contain a JSON format string representing an object as defined here.

See also: HTTP request, actions

language wrappers and examples

The response object properties are:

PropertyRequired/OptionalDescription
actionsrequiredAn array of Action objects.
tokenoptionalAn optional user-defined string of up to 5000 characters. This defaults to null.
call recording cipheroptionalA cipher object that specifies how to encrypt the whole call recording. Defaults to null. Enabling Call Recording Encryption in the service configuration requires that a cipher is supplied here. For a Connect or ConnectToConference action that has encrypted whole call recording enabled, the cipher can be supplied here or in the action's secondary call object.
api versionrequiredThe version of REST API that this response adheres to (e.g. "2.0"). This must match the REST API version set in the service configuration for the current application. This property is automatically inserted by the REST API Wrappers. If you are writing to the REST API by other means you should populate this property.

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.

Call Recording for the primary call can 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. 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 or in the secondary call configuration.

  • 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,
                          "next_page" :
                          {
                              "url": "my_record_handler_page"
                          }
                      }
                  }
              ],
              "token" : "my token id 13324",
              "api_version": "2.0"
          }
      
    • 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",
              "api_version": "2.0",
              "call_recording_cipher" :
              {
                  "type" : "aescbc",
                  "key" : "1F2DEB2E502A4C8CBA58AB5018BD1506419EEA86DF595D3A431F43FAF57534C9",
                  "initialisation_vector" : "9B85FAED9AB17570D5A82A31F846443B"
              }
          }
      
    • Return an empty action list:

          {
              "actions" :
              [
              ],
              "token" : "my token id 13326",
              "api_version": "2.0"
          }
      
  • TelephonyResponse Class
    Namespace: Aculab.Cloud.RestAPIWrapper
    Assembly: Aculab.Cloud.RestAPIWrapper.dll

    A class representing the HTTP response to be returned by an application that determines what actions should be invoked next.

    • public class TelephonyResponse : SerializableObject
      {
          // Constructors
          public TelephonyResponse(string token);
          public TelephonyResponse(List<TelephonyAction> actions);
          public TelephonyResponse(List<TelephonyAction> actions, string token);
      
          // Members
          public Cipher CallRecordingCipher;
          public override string ToString();
          public void ToHttpResponse(HttpResponse response);
      }
      

      Examples:

      • Return a simple action list:

        List<TelephonyAction> actions = new List<TelephonyAction>();
        
        actions.Add(Play.SayText("Please leave a message after the beep."));
        
        var recordAction = new Record(new WebPageRequest("MyRecordHandlerPage.aspx"));
        recordAction.BeepOnStart = true;
        actions.Add(recordAction);
        
        // Respond
        var token = "my token id 13324";
        TelephonyResponse response = new TelephonyResponse(actions, token);
        response.ToHttpResponse(Response);
        
      • Return a simple action list and a cipher to be used to encrypt whole call recording (enabled on the service configuration page):

        List<TelephonyAction> actions = new List<TelephonyAction>();
        
        var prompt = Play.SayText("Please press 1 for yes and 2 for no.");
        var menuOptions = new List<MenuOption>()
        {
            new MenuOption('1', new WebPageRequest("OptionYesPage.aspx")),
            new MenuOption('2', new WebPageRequest("OptionNoPage.aspx"))
        };
        var menuAction = new RunMenu(menuOptions, prompt);
        actions.Add(menuAction);
        
        byte[] key = new byte[] {
            0x1F, 0x2D, 0xEB, 0x2E, 0x50, 0x2A, 0x4C, 0x8C,
            0xBA, 0x58, 0xAB, 0x50, 0x18, 0xBD, 0x15, 0x06,
            0x41, 0x9E, 0xEA, 0xB6, 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 };
        
        var cipher = new AesCbcCipher(key, initialisationVector);
        
        // Respond
        var token = "my token id 13325";
        TelephonyResponse response = new TelephonyResponse(actions, token);
        response.ToHttpResponse(Response);
        
      • Return an empty action list:

        var token = "my token id 13326";
        TelephonyResponse response = new TelephonyResponse(token);
        response.ToHttpResponse(Response);
        
    • public class TelephonyResponse : SerializableObject
      {
          // Constructors
          public TelephonyResponse(string token);
          public TelephonyResponse(List<TelephonyAction> actions);
          public TelephonyResponse(List<TelephonyAction> actions, string token);
      
          // Members
          public Cipher CallRecordingCipher;
          public override string ToString();
      }
      

      Examples:

      • Return a simple action list:

        List<TelephonyAction> actions = new List<TelephonyAction>();
        
        actions.Add(Play.SayText("Please leave a message after the beep."));
        
        var recordAction = new Record(new WebPageRequest("MyRecordHandlerPage.aspx"));
        recordAction.BeepOnStart = true;
        actions.Add(recordAction);
        
        // Respond
        var token = "my token id 13324";
        TelephonyResponse response = new TelephonyResponse(actions, token);
        response.ToHttpResponse(Response);
        
      • Return a simple action list and a cipher to be used to encrypt whole call recording (enabled on the service configuration page):

        List<TelephonyAction> actions = new List<TelephonyAction>();
        
        var prompt = Play.SayText("Please press 1 for yes and 2 for no.");
        var menuOptions = new List<MenuOption>()
        {
            new MenuOption('1', new WebPageRequest("OptionYesPage.aspx")),
            new MenuOption('2', new WebPageRequest("OptionNoPage.aspx"))
        };
        var menuAction = new RunMenu(menuOptions, prompt);
        actions.Add(menuAction);
        
        byte[] key = new byte[] {
            0x1F, 0x2D, 0xEB, 0x2E, 0x50, 0x2A, 0x4C, 0x8C,
            0xBA, 0x58, 0xAB, 0x50, 0x18, 0xBD, 0x15, 0x06,
            0x41, 0x9E, 0xEA, 0xB6, 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 };
        
        var cipher = new AesCbcCipher(key, initialisationVector);
        
        // Respond
        var token = "my token id 13325";
        TelephonyResponse response = new TelephonyResponse(actions, token);
        response.ToHttpResponse(Response);
        
      • Return an empty action list:

        var token = "my token id 13326";
        TelephonyResponse response = new TelephonyResponse(token);
        response.ToHttpResponse(Response);
        
    • public class TelephonyResponse : SerializableObject
      {
          // Constructors
          public TelephonyResponse(string token);
          public TelephonyResponse(List<TelephonyAction> actions);
          public TelephonyResponse(List<TelephonyAction> actions, string token);
      
          // Members
          public Cipher CallRecordingCipher;
          public override string ToString();
          public IActionResult ToJson(Controller controller);
          public string ToJson(ControllerBase controller);
          public void ToHttpResponse(HttpResponse response);
      }
      

      Examples:

      • Return a simple action list:

        List<TelephonyAction> actions = new List<TelephonyAction>();
        
        actions.Add(Play.SayText("Please leave a message after the beep."));
        
        var recordAction = new Record(new WebPageRequest("MyRecordHandlerPage.aspx"));
        recordAction.BeepOnStart = true;
        actions.Add(recordAction);
        
        // Respond
        var token = "my token id 13324";
        TelephonyResponse response = new TelephonyResponse(actions, token);
        return new OkObjectResult(response.ToJson(this));
        
      • Return a simple action list and a cipher to be used to encrypt whole call recording (enabled on the service configuration page):

        List<TelephonyAction> actions = new List<TelephonyAction>();
        
        var prompt = Play.SayText("Please press 1 for yes and 2 for no.");
        var menuOptions = new List<MenuOption>()
        {
            new MenuOption('1', new WebPageRequest("OptionYesPage.aspx")),
            new MenuOption('2', new WebPageRequest("OptionNoPage.aspx"))
        };
        var menuAction = new RunMenu(menuOptions, prompt);
        actions.Add(menuAction);
        
        byte[] key = new byte[] {
            0x1F, 0x2D, 0xEB, 0x2E, 0x50, 0x2A, 0x4C, 0x8C,
            0xBA, 0x58, 0xAB, 0x50, 0x18, 0xBD, 0x15, 0x06,
            0x41, 0x9E, 0xEA, 0xB6, 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 };
        
        var cipher = new AesCbcCipher(key, initialisationVector);
        
        // Respond
        var token = "my token id 13325";
        TelephonyResponse response = new TelephonyResponse(actions, token);
        return new OkObjectResult(response.ToJson(this));
        
      • Return an empty action list:

        var token = "my token id 13326";
        TelephonyResponse response = new TelephonyResponse(token);
        return new OkObjectResult(response.ToJson(this));
        
  • TelephonyResponse Class
    Namespace: Aculab.Cloud.RestAPIWrapper
    Assembly: Aculab.Cloud.RestAPIWrapper.dll

    A class representing the HTTP response to be returned by an application that determines what actions should be invoked next.

    • Public Class TelephonyResponse
          Inherits SerializableObject
      
          ' Constructors
          Public Sub New (token As String)
          Public Sub New (actions As List(Of Telephonyaction))
          Public Sub New (actions As List(Of Telephonyaction), token As String)
      
          ' Members
          Public Property CallRecordingCipher As Cipher
          Public Overrides Function ToString() As String
          Public Function ToHttpResponse(response As Httpresponse) As Void
      End Class
      

      Examples:

      • Return a simple action list:

        Dim actions = New List(Of TelephonyAction)
        
        actions.Add(Play.SayText("Please leave a message after the beep."))
        
        Dim recordAction = New Record(New WebPageRequest("MyRecordHandlerPage.aspx"))
        recordAction.BeepOnStart = True
        actions.Add(recordAction)
        
        ' Respond
        Dim token = "my token id 13324"
        Dim appResponse = New TelephonyResponse(actions, token)
        appResponse.ToHttpResponse(Response)
        
      • Return a simple action list and a cipher to be used to encrypt whole call recording (enabled on the service configuration page):

        Dim actions = New List(Of TelephonyAction)
        
        Dim prompt = Play.SayText("Please press 1 for yes and 2 for no.")
        Dim menuOptions = New List(Of MenuOption)
        menuOptions.Add(New MenuOption("1", New WebPageRequest("OptionYesPage.aspx")))
        menuOptions.Add(New MenuOption("2", New WebPageRequest("OptionNoPage.aspx")))
        Dim menuAction = New RunMenu(menuOptions, prompt)
        actions.Add(menuAction)
        
        Dim key As Byte() = {
            &H1F, &H2D, &HEB, &H2E, &H50, &H2A, &H4C, &H8C,
            &HBA, &H58, &HAB, &H50, &H18, &HBD, &H15, &H6,
            &H41, &H9E, &HEA, &HB6, &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 cipher = new AesCbcCipher(key, initialisationVector)
        
        ' Respond
        Dim token = "my token id 13325"
        Dim appResponse = New TelephonyResponse(actions, token)
        appResponse.ToHttpResponse(Response)
        
      • Return an empty action list:

        Dim token = "my token id 13326"
        Dim appResponse = New TelephonyResponse(token)
        appResponse.ToHttpResponse(Response)
        
    • Public Class TelephonyResponse
          Inherits SerializableObject
      
          ' Constructors
          Public Sub New (token As String)
          Public Sub New (actions As List(Of Telephonyaction))
          Public Sub New (actions As List(Of Telephonyaction), token As String)
      
          ' Members
          Public Property CallRecordingCipher As Cipher
          Public Overrides Function ToString() As String
      End Class
      

      Examples:

      • Return a simple action list:

        Dim actions = New List(Of TelephonyAction)
        
        actions.Add(Play.SayText("Please leave a message after the beep."))
        
        Dim recordAction = New Record(New WebPageRequest("MyRecordHandlerPage.aspx"))
        recordAction.BeepOnStart = True
        actions.Add(recordAction)
        
        ' Respond
        Dim token = "my token id 13324"
        Dim appResponse = New TelephonyResponse(actions, token)
        appResponse.ToHttpResponse(Response)
        
      • Return a simple action list and a cipher to be used to encrypt whole call recording (enabled on the service configuration page):

        Dim actions = New List(Of TelephonyAction)
        
        Dim prompt = Play.SayText("Please press 1 for yes and 2 for no.")
        Dim menuOptions = New List(Of MenuOption)
        menuOptions.Add(New MenuOption("1", New WebPageRequest("OptionYesPage.aspx")))
        menuOptions.Add(New MenuOption("2", New WebPageRequest("OptionNoPage.aspx")))
        Dim menuAction = New RunMenu(menuOptions, prompt)
        actions.Add(menuAction)
        
        Dim key As Byte() = {
            &H1F, &H2D, &HEB, &H2E, &H50, &H2A, &H4C, &H8C,
            &HBA, &H58, &HAB, &H50, &H18, &HBD, &H15, &H6,
            &H41, &H9E, &HEA, &HB6, &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 cipher = new AesCbcCipher(key, initialisationVector)
        
        ' Respond
        Dim token = "my token id 13325"
        Dim appResponse = New TelephonyResponse(actions, token)
        appResponse.ToHttpResponse(Response)
        
      • Return an empty action list:

        Dim token = "my token id 13326"
        Dim appResponse = New TelephonyResponse(token)
        appResponse.ToHttpResponse(Response)
        
  • class TelephonyResponse

    Represents the response to the REST API request.

    Class synopsis:

    // Constructors:
    public TelephonyResponse(String token)
    public TelephonyResponse(List<TelephonyAction> actions)
    public TelephonyResponse(List<TelephonyAction> actions, String token)
    
    // Members:
    public void setCallRecordingCipher(Cipher cipher)
    public void setHttpServletResponse(HttpServletResponse response)
    public String toString()
    

    Examples:

    • Return a simple action list:

      // Unpack the request
      TelephonyRequest myRequest = new TelephonyRequest(request);
      
      // Access the request properties
      String token = myRequest.getInstanceInfo().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(new WebPageRequest("my_record_handler_page"));
      record.setBeepOnStart(true);
      actions.add(record);
      
      // Respond
      TelephonyResponse myResponse = new TelephonyResponse(actions, "my token id 13324");
      myResponse.setHttpServletResponse(response);
      
    • Return a simple action list and a cipher to be used to encrypt whole call recording (enabled on the service configuration page):

      // Unpack the request
      TelephonyRequest myRequest = new TelephonyRequest(request);
      
      // Access the request properties
      String token = myRequest.getInstanceInfo().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[] {
          (byte)0x1F, (byte)0x2D, (byte)0xEB, (byte)0x2E, (byte)0x50, (byte)0x2A, (byte)0x4C, (byte)0x8C,
          (byte)0xBA, (byte)0x58, (byte)0xAB, (byte)0x50, (byte)0x18, (byte)0xBD, (byte)0x15, (byte)0x06,
          (byte)0x41, (byte)0x9E, (byte)0xEA, (byte)0x86, (byte)0xDF, (byte)0x59, (byte)0x5D, (byte)0x3A,
          (byte)0x43, (byte)0x1F, (byte)0x43, (byte)0xFA, (byte)0xF5, (byte)0x75, (byte)0x34, (byte)0xC9 };
      byte[] initialisationVector = new byte[] {
              (byte)0x9B, (byte)0x85, (byte)0xFA, (byte)0xED, (byte)0x9A, (byte)0xB1, (byte)0x75, (byte)0x70,
              (byte)0xD5, (byte)0xA8, (byte)0x2A, (byte)0x31, (byte)0xF8, (byte)0x46, (byte)0x44, (byte)0x3B };
      Cipher cipher = new AesCbcCipher(key, initialisationVector);
      
      // Respond
      TelephonyResponse myResponse = new TelephonyResponse(actions, "my token id 13325");
      myResponse.setCallRecordingCipher(cipher);
      myResponse.setHttpServletResponse(response);
      
    • Return an empty action list:

      // Unpack the request
      TelephonyRequest myRequest = new TelephonyRequest(request);
      
      // Access the request properties
      String token = myRequest.getInstanceInfo().getToken();
      
      // Respond
      TelephonyResponse myResponse = new TelephonyResponse("my token id 13326");
      myResponse.setHttpServletResponse(response);
      
  • class TelephonyResponse

    Represents the response to the REST API request. Once all the required actions have been added, the get_json() method is called which returns a JSON formatted string suitable for the HTTP response.

    Class synopsis:

    # TelephonyResponse object:
    TelephonyResponse(list_of_actions, token=None, call_recording_cipher=None)
    
    # Instance methods:
    TelephonyResponse.add_actions(list_of_actions)
    TelephonyResponse.set_token(token)
    TelephonyResponse.set_call_recording_cipher(call_recording_cipher)
    TelephonyResponse.get_json()
    

    Examples:

    • Return a simple action list:

      record_action = Record(WebPage(url='my_record_handler_page'))
      record_action.set_beep_on_start(True)
      
      # Play a prompt and then record
      list_of_actions = []    
      list_of_actions.append(Play(text_to_say='Please leave a message after the beep.'))
      list_of_actions.append(record_action)
      my_response = TelephonyResponse(list_of_actions, token='my token id 13324')    
      
      # Get the JSON formatted string to send in the HTTP response.
      response_body =  my_response.get_json() 
      
    • Return a simple action list and a cipher to be used to encrypt whole call recording (enabled on the service configuration page):

      menu_options = []
      menu_options.append(MenuOption('1',WebPage(url='option_yes_page')))
      menu_options.append(MenuOption('2',WebPage(url='option_no_page')))
      
      run_menu_action = RunMenu(menu_options)
      run_menu_action.set_prompt(Play(text_to_say='Please press 1 for yes and 2 for no.'))
      
      aescbc_cipher = AESCBCCipher(key='1F2DEB2E502A4C8CBA58AB5018BD1506419EEA86DF595D3A431F43FAF57534C9', 
                                   initialisation_vector='9B85FAED9AB17570D5A82A31F846443B')
      
      list_of_actions = []
      list_of_actions.append(run_menu_action)
      my_response = TelephonyResponse(list_of_actions, token='my token id 13325')
      my_response.set_call_recording_cipher(aescbc_cipher)
      
      # Get the JSON formatted string to send in the HTTP response.
      response_body =  my_response.get_json() 
      
    • Return an empty action list:

      my_response = TelephonyResponse([], token='my token id 13326')
      
      # Get the JSON formatted string to send in the HTTP response.
      response_body =  my_response.get_json() 
      
  • The Response class

    Introduction

    Represents the response to the REST API request.

    Class synopsis

    class Response {
    
        /* methods */
        public __construct(boolean $pretty_output = false)
        public self setToken(string $token)
        public self setCallRecordingCipher(Cipher $cipher)
        public self addAction(ActionBase $action)
        public string __toString()
    }
    

    Examples:

    • Return a simple action list:

      $response = new Aculab\TelephonyRestAPI\Response();
      $response->setToken('my token id 13324');
      
      $response->addAction(Aculab\TelephonyRestAPI\Play::sayText('Please leave a message after the beep.'));
      
      $record = new Aculab\TelephonyRestAPI\Record('my_record_handler_page');
      $record->setBeepOnStart(true);
      $response->addAction($record);
      
      

      output the JSON

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

      $response = new Aculab\TelephonyRestAPI\Response();
      $response->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();
      $menu->setPrompt($mp);
      $menu->addMenuOption('1', 'optionyespage');
      $menu->addMenuOption('2', 'optionnopage');
      $response->addAction($menu);
      
      $cipher = new Aculab\TelephonyRestAPI\AesCbcCipher(
          "1F2DEB2E502A4C8CBA58AB5018BD1506419EEA86DF595D3A431F43FAF57534C9",
          "9B85FAED9AB17570D5A82A31F846443B"
      );
      $response->setCallRecordingCipher($cipher);
      
      

      output the JSON

      print $response;
      
    • Return an empty action list:

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

      output the JSON

      print $response;