Migrating an Application from Version 1 to 2

The main differences between Version 1 and 2 are the changes to the speech recognition from a connected word to a natural language recogniser and the addition of transcription features. Details of these changes in the JSON REST API are listed in the Release Notes page.

Each langugage wrapper has been updated to accommodate these changes, and some have been upgraded to make all the wrappers more consistent. The following notes describe how to migrate an application from version 1 of the REST API to version 2.

JSON
C#
VB
Java
Python
PHP

See the Release Notes for details of what's changed in the JSON REST API.

When migrating a CSharp REST API application you will need to take account of the following changes:

The .Net REST API wrapper has been renamed:

using RestAPIWrapper;

becomes:

using Aculab.Cloud.RestAPIWrapper;

TelephonyRequest.IsValid is obsolete.
Remove references to:
```
TelephonyRequest.IsValid
```

The GetInput constructor requires a next page argument and prompt is optional. It now uses a natural language recogniser and has new properties for configuration. Primarily the SpeechRecognitionOptions class.

var getInputAction = new GetInput(prompt, SpeechRecognitionGrammar.FourDigits, 20);

becomes:

var speechRecognitionOptions = new SpeechRecognitionOptions("en-GB");
var getInputAction = new GetInput(nextPage, prompt, speechRecognitionOptions);

It also returns an enhanced speech result that contain one or more distinct phrases. e.g.:

var result = (GetInputResult)ourRequest.InstanceInfo.ActionResult;
if (getInputResult.SpeechInput.Equals("speech"))
{
    foreach (Phrase phrase in getInputResult.SpeechInput)
    {
        // Get the first alternative
        var speech = phrase.Alternatives[0];
        var text = speech.Text;
		...
    }
}

The GetNumber constructor requires a next page argument and prompt is optional. The digit timeout properties have also changed:

var getNumberAction = new GetNumber(prompt);
getNumberAction.NextPage = new WebPageRequest("ReadEnteredDigits.aspx");
getNumberAction.SecondsDigitTimeout = 5;

becomes:

var nextPage = new WebPageRequest("ReadEnteredDigits.aspx");
var getNumberAction = new GetNumber(nextPage, prompt);
getNumberAction.MillisecondsInterDigitTimeout = 5000;

The Play action's digit barge in property name has changed:

var playAction = Play.PlayFile("message.wav");
playAction.BargeIn = true;

becomes:

var playAction = Play.PlayFile("message.wav");
playAction.BargeInOnDigit = true;

The Record constructor requires a next page argument:

var recordAction = new Record();
recordAction.NextPage = new WebPageRequest("recordHandler.aspx");

becomes:

var nextPage = new WebPageRequest("recordHandler.aspx");
var recordAction = new Record(nextPage);

The RunMenu constructor requires menuOptions and prompt is optional.

var runMenuAction = new RunMenu(menuPrompt, menuOptions);

becomes:

var runMenuAction = new RunMenu(menuOptions, menuPrompt);

The RunSpeechMenu constructor requires menuOptions and prompt is optional. SecondsInputTimeout has been renamed.

var runSpeechMenuAction = new RunSpeechMenu(menuPrompt, menuOptions);
runSpeechMenuAction.SecondsInputTimeout = 5;

becomes:

var runSpeechMenuAction = new RunSpeechMenu(menuOptions, menuPrompt);
runSpeechMenuAction.SecondsTimeout = 5;

When migrating a VB REST API application you will need to take account of the following changes:

The .Net REST API wrapper has been renamed:

Imports RestAPIWrapper

becomes:

Imports Aculab.Cloud.RestAPIWrapper

TelephonyRequest.IsValid is obsolete.
Remove references to:
```
TelephonyRequest.IsValid
```

Dim getInputAction = New GetInput(prompt, SpeechRecognitionGrammar.FourDigits, 20)

becomes:

Dim speechRecognitionOptions = New SpeechRecognitionOptions("en-GB")
Dim getInputAction = New GetInput(nextPage, prompt, speechRecognitionOptions)

It also returns an enhanced speech result that contain one or more distinct phrases. e.g.:

Dim result as GetInputResult = ourRequest.InstanceInfo.ActionResult
If (getInputResult.SpeechInput.Equals("speech")) Then
    For Each phrase As Phrase In getInputResult.SpeechInput
        ' Get the first alternative
        Dim speech = phrase.Alternatives(0)
        Dim text = speech.Text
		...
    Next
End If

The GetNumber constructor requires a next page argument and prompt is optional. The digit timeout properties have also changed:

Dim getNumberAction = New GetNumber(prompt)
getNumberAction.NextPage = New WebPageRequest("ReadEnteredDigits.aspx")
getNumberAction.SecondsDigitTimeout = 5

becomes:

Dim nextPage = New WebPageRequest("ReadEnteredDigits.aspx")
Dim getNumberAction = New GetNumber(nextPage, prompt)
getNumberAction.MillisecondsInterDigitTimeout = 5000

The Play action's digit barge in property name has changed:

Dim playAction = Play.PlayFile("message.wav")
playAction.BargeIn = true

becomes:

Dim playAction = Play.PlayFile("message.wav")
playAction.BargeInOnDigit = true

The Record constructor requires a next page argument:

Dim recordAction = New Record()
recordAction.NextPage = New WebPageRequest("recordHandler.aspx")

becomes:

Dim nextPage = New WebPageRequest("recordHandler.aspx")
Dim recordAction = New Record(nextPage)

The RunMenu constructor requires menuOptions and prompt is optional.

Dim runMenuAction = New RunMenu(menuPrompt, menuOptions)

becomes:

Dim runMenuAction = New RunMenu(menuOptions, menuPrompt)

The RunSpeechMenu constructor requires menuOptions and prompt is optional. SecondsInputTimeout has been renamed.

Dim runSpeechMenuAction = New RunSpeechMenu(menuPrompt, menuOptions)
runSpeechMenuAction.SecondsInputTimeout = 5

becomes:

Dim runSpeechMenuAction = New RunSpeechMenu(menuOptions, menuPrompt)
runSpeechMenuAction.SecondsTimeout = 5

When migrating a Java REST API application you will need to take account of the following changes:

The TelephonyRequest.isValid() method is obsolete.
Remove references to:
```
TelephonyRequest.isValid()
```
The GetInput action functionality has changed in version 2. Version 1 applications using GetInput will need significant changes.

The GetNumber constructor requires a next page argument and prompt is optional. The digit timeout properties have also changed:

GetNumber getNumberAction = new GetNumber(Play.sayText("Please enter your id followed by a hash."));
getNumberAction.setNextPage(new WebPageRequest("UseNumberPage"));
getNumberAction.setSecondsDigitTimeout(10);

becomes:

GetNumber getNumberAction = new GetNumber(new WebPageRequest("UseNumberPage"));
getNumberAction.setPrompt(Play.sayText("Please enter your id followed by a hash."));
getNumberAction.setMilliSecondsInterDigitTimeout(10000);

The Play action's digit barge in property name has changed:

Play playAction = Play.playFile("welcome.wav");
playAction.setBargeIn(true);

becomes:

Play playAction = Play.playFile("welcome.wav");
playAction.setBargeInOnDigit(true);

The Record constructor requires a next page argument:

Record recordAction = new Record();
recordAction.setNextPage(new WebPageRequest("myRecordHandlerPage"));

becomes:

Record recordAction = new Record(new WebPageRequest("myRecordHandlerPage"));

When migrating a Python REST API application you will need to take account of the following changes:

The REST API wrapper is now installed using PIP.
In V1, the REST API wrapper module was not installed using PIP. Applications wishing to import the V1 REST API wrapper had to do so by explicitly specifying its path.
In V2, the REST API wrapper module is installed using PIP. Applications that import the V2 REST API wrapper should do so implicitly.
Thus:
```
sys.path.append(os.path.abspath('../..'))
from aculab.telephony_rest_api import *
```
Becomes:
```
from aculab.telephony_rest_api import *
```
The RESTQuery class has been replaced by the TelephonyRequest class.
In V1, unpacking the instance info from the HTTP Request was achieved using the RESTQuery class. The RESTQuery constructor took a single argument (A WSGI environment dictionary) and would extract the instance info properties from it. The instance info properties were stored as RESTQuery class variables (For example, the 'application instance id' property was stored in RESTQuery.ID).
In V2, unpacking the instance info from the HTTP Request is achieved using the TelephonyRequest class. The TelephonyRequest constructor takes a single argument (That may either be a JSON formatted instance info string, a Flask Request object or a WSGI environment dictionary) and will extract the instance info properties from it. The instance info properties are stored as TelephonyRequest class variables and can be retrieved by calling the appropriate 'get_' method (For example, the 'application instance id' property can be retrieved by calling TelephonyRequest.get_application_instance_id()).
Thus:
```
# Where the 'request_data' argument is a WSGI environment dictionary.
my_request = RESTQuery(request_data)
my_app_inst_id = my_request.ID
my_token = my_request.Token
```
Becomes:
```
# Where the 'request_data' argument can be either a JSON formatted instance
# info string, a Flask Request object or a WSGI environment dictionary.
my_request = TelephonyRequest(request_data)
my_app_inst_id = my_request.get_application_instance_id()
my_token = my_request.get_token()
```
The Actions class has been replaced with the TelephonyResponse class.
In V1, the Actions class was used to generate JSON data for the body of the HTTP response. Actions were added using the Actions.add() method. The Actions.get_json() method was then called to generate the JSON for the HTTP response body.
In V2, the TelephonyResponse class is used to generate the JSON data for the body of the HTTP response. The TelephonyResponse constructor takes a Python list off actions. The TelephonyResponse.get_json() method is then called to generate the JSON for the HTTP response body.
Thus:
```
my_actions = Actions(token='my_token_1234')
my_actions.add(Play(text_to_say='Hello, good evening and welcome.'))
my_actions.add(Sleep(10))
response_body = my_actions.get_json()
```
Becomes:
```
my_actions = []
my_actions.append(Play(text_to_say='Hello, good evening and welcome.'))
my_actions.append(Sleep(10))
my_response = TelephonyResponse(my_actions, token='my_token_1234')
response_body = my_response.get_json()
```

The Connect set_call_origin method has been renamed set_call_from.

connect_action = Connect()
connect_action.set_call_origin('441908273801')

becomes:

connect_action = Connect()
connect_action.set_call_from('441908273801')

The GetInput action functionality has changed in version 2. Version 1 applications using GetInput will need significant changes.

The GetNumber constructor requires a next page argument. The on_prompt_play method has been renamed set_prompt. The digit timeout properties have also changed:

get_number_action = GetNumber()
get_number_action.set_next_page(WebPage(url='usenumberpage'))
get_number_action.on_prompt_play(Play(text_to_say='Please enter your id followed by a hash.'))
get_number_action.set_seconds_digit_timeout(10)

becomes:

get_number_action = GetNumber(WebPage(url='usenumberpage'))
get_number_action.set_prompt(Play(text_to_say='Please enter your id followed by a hash.'))
get_number_action.set_milliseconds_inter_digit_timeout(10000)

The Play action's digit barge in property name has changed:

play_action = Play(text_to_say='Hello, good evening and welcome.')
play_action.set_barge_in(True)

becomes:

play_action = Play(text_to_say='Hello, good evening and welcome.')
play_action.set_barge_in_on_digit(True)

The ReceiveFax constructor parameters have been reordered making next_page (Which is now a required property) the first parameter.

receive_fax_action = ReceiveFax(WebPage(url='my_progress_handler'), WebPage(url='my_next_page_handler'))

becomes:

receive_fax_action = ReceiveFax(WebPage(url='my_next_page_handler'), WebPage(url='my_progress_handler'))

The Record constructor parameters have been reordered making next_page (Which is now a required property) the first parameter.

record_action = Record()
record_action.set_next_page(WebPage(url='my_record_handler_page'))

becomes:

record_action = Record(WebPage(url='my_record_handler_page'))

The RunMenu constructor requires menu_options. The on_prompt_play method has been renamed set_prompt. The append_on_digit_timeout_message method has been replaced by the set_on_digit_timeout_messages method. The append_on_invalid_digit_message method has been replaced by the set_on_invalid_digit_messages method.

run_menu_action = RunMenu()
run_menu_action.on_prompt_play(Play(file_to_play='voicemailmenu.wav'))
run_menu_action.append_menu_option('1',WebPage(url='voicemail_option1_page'))
run_menu_action.append_menu_option('2',WebPage(url='voicemail_option2_page'))
run_menu_action.append_menu_option('3',WebPage(url='voicemail_option3_page'))
run_menu_action.append_on_digit_timeout_message(Play(text_to_say='I didn't catch your entry.'))
run_menu_action.append_on_digit_timeout_message(Play(text_to_say='Please select an option.'))
run_menu_action.append_on_digit_timeout_message(Play(file_to_play='oneMoreTime.wav'))
run_menu_action.append_on_invalid_digit_message(Play(text_to_say='That wasn't one of the options. Please try again.'))
run_menu_action.append_on_invalid_digit_message(Play(file_to_play='oneMoreTime.wav'))

becomes:

menu_options = []
menu_options.append(MenuOption('1',WebPage(url='voicemail_option1_page')))
menu_options.append(MenuOption('2',WebPage(url='voicemail_option2_page')))
menu_options.append(MenuOption('3',WebPage(url='voicemail_option3_page')))

timeout_messages = []
timeout_messages.append(Play(text_to_say="I didn't catch your entry."))
timeout_messages.append(Play(text_to_say="Please select an option."))
timeout_messages.append(Play(file_to_play="oneMoreTime.wav"))

invalid_messages = []
invalid_messages.append(Play(text_to_say="That wasn't one of the options. Please try again."))
invalid_messages.append(Play(file_to_play="oneMoreTime.wav"))

run_menu_action = RunMenu(menu_options)
run_menu_action.set_prompt(Play(file_to_play='voicemailmenu.wav'))
run_menu_action.set_on_digit_timeout_messages(timeout_messages)
run_menu_action.set_on_invalid_digit_messages(invalid_messages)

The RunSpeechMenu constructor requires menu_options. The on_prompt_play method has been renamed set_prompt. The append_on_input_timeout_message method has been replaced by the set_on_input_timeout_messages method. The append_on_invalid_input_message method has been replaced by the set_on_invalid_input_messages method. The set_seconds_input_timeout method has been renamed set_seconds_timeout.

speech_menu_action = RunSpeechMenu()
speech_menu_action.on_prompt_play(Play(file_to_play='voicemailmenu.wav'))
speech_menu_action.append_menu_option('1', 'one', WebPage(url='voicemail_option1_page'))
speech_menu_action.append_menu_option('2', 'two', WebPage(url='voicemail_option2_page'))
speech_menu_action.append_menu_option('3', 'three', WebPage(url='voicemail_option3_page'))
speech_menu_action.set_seconds_input_timeout(10)
speech_menu_action.append_on_input_timeout_message(Play(text_to_say='I didn't catch your entry.'))
speech_menu_action.append_on_input_timeout_message(Play(text_to_say='Please select an option.'))
speech_menu_action.append_on_input_timeout_message(Play(file_to_play='oneMoreTime.wav'))
speech_menu_action.append_on_invalid_input_message(Play(text_to_say='That wasn't one of the options. Please try again.'))
speech_menu_action.append_on_invalid_input_message(Play(file_to_play='oneMoreTime.wav'))

becomes:

speech_menu_opts = []
speech_menu_opts.append(SpeechMenuOption('1', 'one', WebPage(url='voicemail_option1_page')))
speech_menu_opts.append(SpeechMenuOption('2', 'two', WebPage(url='voicemail_option2_page')))
speech_menu_opts.append(SpeechMenuOption('3', 'three', WebPage(url='voicemail_option3_page')))

timeout_messages = []
timeout_messages.append(Play(text_to_say="I didn't catch your entry."))
timeout_messages.append(Play(text_to_say="Please select an option."))
timeout_messages.append(Play(file_to_play="oneMoreTime.wav"))

invalid_messages = []
invalid_messages.append(Play(text_to_say="That wasn't one of the options. Please try again."))
invalid_messages.append(Play(file_to_play="oneMoreTime.wav"))

speech_menu_action = RunSpeechMenu(speech_menu_opts)
speech_menu_action.set_prompt(Play(file_to_play='voicemailmenu.wav'))
speech_menu_action.set_seconds_timeout(10)
speech_menu_action.set_on_input_timeout_messages(timeout_messages)
speech_menu_action.set_on_invalid_input_messages(invalid_messages)

When migrating a PHP REST API application you will need to take account of the following changes:

The version 2 package is designed for use with Composer. As such, the method for including the classes has changed, so:
```
spl_autoload_register();
```
is not needed by the package. It is replaced by a require of an autoload file, such as:
```
require __DIR__ . '/vendor/autoload.php';
```

The Actions class has been replaced with the Response class and the function to add actions has been renamed:

$response = new Aculab\TelephonyRestAPI\Actions();
$response->add(Aculab\TelephonyRestAPI\Play::sayText("Hello"));
print $response;

becomes:

$response = new Aculab\TelephonyRestAPI\Response();
$response->addAction(Aculab\TelephonyRestAPI\Play::sayText("Hello"));
print $response;

The ClassifyCalleeConfiguration object function for configuring answer machine ready to record has been renamed:

$classify_configuration = new \Aculab\TelephonyRestAPI\ClassifyCalleeConfiguration();
$classify_configuration->setReadyToRecordConfiguration(300, 2000, 10000, 30);

becomes:

$classify_configuration = new \Aculab\TelephonyRestAPI\ClassifyCalleeConfiguration();
$classify_configuration->setAnsweringMachineReadyToRecordConfiguration(300, 2000, 10000, 30);

The GetInput action functionality has changed in version 2. Version 1 applications using GetInput will need significant changes.

The GetNumber action constructor requires a next page, the prompt is set using a function, and the digit timeout function name and expected values have changed:

$get_number = new Aculab\TelephonyRestAPI\GetNumber(Play::sayText("Please enter a number"));
$get_number->setNextPage("get_number_result.php");
$get_number->setDigitTimeout(5);

becomes:

$get_number = new Aculab\TelephonyRestAPI\GetNumber("get_number_result.php");
$get_number->setPrompt(Play::sayText("Please enter a number"));
$get_number->setMillisecondsInterDigitTimeout(5000);

The Play action's digit barge in function name has changed:

$play = Play::playFile("message.wav");
$play->setBargeIn(false);

becomes:

$play = Play::playFile("message.wav");
$play->setBargeInOnDigit(false);

The ReceiveFax action constructor requires a next page:

$fax = new Aculab\TelephonyRestAPI\ReceiveFax();
$fax->setNextPage("my_fax_handler_page.php");

becomes:

$fax = new Aculab\TelephonyRestAPI\ReceiveFax("my_fax_handler_page.php");

The Record action constructor requires a next page:

$rec = new Aculab\TelephonyRestAPI\Record();
$rec->setNextPage("my_record_handler_page.php");

becomes:

$rec = new Aculab\TelephonyRestAPI\Record("my_record_handler_page.php");

The RunMenu action constructor no longer takes a prompt, it is set by a function, and the digit timeout function has been renamed:

$menu = new Aculab\TelephonyRestAPI\RunMenu(Play::playFile("menu.wav"));
$menu->setDigitTimeout(5);

becomes:

$menu = new Aculab\TelephonyRestAPI\RunMenu();
$menu->setPrompt(Play::playFile("menu.wav"));
$menu->setSecondsDigitTimeout(5);

The RunSpeechMenu action constructor no longer takes a prompt, it is set by a function, and the input timeout function has been renamed:

$menu = new Aculab\TelephonyRestAPI\RunSpeechMenu(Play::playFile("menu.wav"));
$menu->setInputTimeout(5);

becomes:

$menu = new Aculab\TelephonyRestAPI\RunSpeechMenu();
$menu->setPrompt(Play::playFile("menu.wav"));
$menu->setSecondsTimeout(5);

Note that the next page for each speech menu option is now required.

Cloud documentation

Migrating an Application from Version 1 to 2

Contact Aculab