HTTP Response

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

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.

JSONC#VBJavaPythonPHP

Examples:

Example 1Example 2Example 3

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.

.Net Framework.Net Standard.Net Core

public class TelephonyResponse : SerializableObject
{
    // Constructors
    public TelephonyResponse(string token);
    public TelephonyResponse(List&lt;TelephonyAction&gt; actions);
    public TelephonyResponse(List&lt;TelephonyAction&gt; actions, string token);

    // Members
    public Cipher CallRecordingCipher;
    public override string ToString();
    public void ToHttpResponse(HttpResponse response);
}

Examples:

Example 1Example 2Example 3

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&lt;TelephonyAction&gt; actions);
    public TelephonyResponse(List&lt;TelephonyAction&gt; actions, string token);

    // Members
    public Cipher CallRecordingCipher;
    public override string ToString();
}

Examples:

Example 1Example 2Example 3

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&lt;TelephonyAction&gt; actions);
    public TelephonyResponse(List&lt;TelephonyAction&gt; 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:

Example 1Example 2Example 3

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.

.Net Framework.Net Standard

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:

Example 1Example 2Example 3

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:

Example 1Example 2Example 3

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:

Example 1Example 2Example 3

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:

Example 1Example 2Example 3

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:

Example 1Example 2Example 3

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;

Property	Required/Optional	Description
actions	required	An array of Action objects.
token	optional	An optional user-defined string of up to 5000 characters. This defaults to null.
call recording cipher	optional	A 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 version	required	The 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.