HTTP Request

Each HTTP request made to your web application includes an instance info object represented as a JSON format string. You can POST or GET to make your request. The default is POST. When using POST the request body contains just the instance info JSON string. When using GET the query string contains an instance_info argument.

Examples:

Example 1Example 2Example 3Example 4Example 5Example 6Example 7

instance info for an inbound call:

{
    "token" : "my token id 13324",
    "application_instance_id" : "058d242936dcc5f9.47610",
    "log_filename" : "/2013/11/07/rest_16_39_23_058d242936dcc5f9.47610.log",
    "this_call" : 
    {
        "call_id" : "058d242936dcc5f9.47610.663748630",
        "call_direction" : "in",
        "call_from" : "443069999876",
        "call_to" : "443069990123",
        "call_target" : "443069990123",
        "call_divert": "",
        "seconds_call_duration" : 23.9,
        "call_state" : "answered",
        "application_parameters" : ""
    },
    "is_notification" : false
}

instance info for an outbound call:

{
    "token" : "my token id 13325",
    "application_instance_id" : "058d242936dcc5f9.3437",
    "log_filename" : "/2013/11/07/rest_16_39_23_058d242936dcc5f9.3437.log",
    "this_call" : 
    {
        "call_id" : "058d242936dcc5f9.3437.486306637",
        "call_direction" : "out",
        "call_from" : "443069999876",
        "call_to" : "443069990123",
        "call_target" : "443069990123",
        "call_divert": "",
        "seconds_call_duration" : 13.7,
        "call_state" : "answered",
        "application_parameters" : "",
        "outbound_parameters" : "",
        "far_end_type" : "human"
    }
    "is_notification" : false
}

instance info to an application's Final page:

{
    "token" : "my token id 13324",
    "application_instance_id" : "058d242936dcc5f9.47610",
    "log_filename" : "/2013/11/07/rest_16_39_23_058d242936dcc5f9.47610.log",
    "this_call" : 
    {
        "call_id" : "058d242936dcc5f9.47610.663748630",
        "call_direction" : "in",
        "call_from" : "sip:bill&#64;anothercompany.com",
        "call_to" : "sip:bob&#64;acompany.com",
        "call_target" : "sip:bob&#64;acompany.com",
        "call_divert": "",
        "seconds_call_duration" : 27.2,
        "call_state" : "idle",
        "call_cause" : "completed",
        "call_raw_cause" : "0",
        "application_parameters" : "",
        "call_recording_filename" : "/rest_api/recordings/2013/11/07/rest_16_39_23_058d242936dcc5f9.47610.wav"
    },
    "is_notification" : false
}

instance info for an error:

{
    "token" : "my token id 13326",
    "application_instance_id" : "058d242936dcc5f9.8277",
    "log_filename" : "/2013/11/07/rest_16_39_23_058d242936dcc5f9.8277.log",
    "this_call" : 
    {
        "call_id" : "058d242936dcc5f9.7364558.8277",
        "call_direction" : "in",
        "call_from" : "443069999876
        "call_to" : "443069990123",
        "call_target" : "443069990123",
        "call_divert": "",
        "seconds_call_duration" : 0.0,
        "call_state" : "inbound",
        "application_parameters": "441234567890;441234567891;441234567892"
    },
    "error_result" :
    {
        "action": "reject", 
        "result": "Bad action: reject; parameters: {'cause': 'bisy'}. Unknown reject cause: bisy"
    },
    "is_notification" : false
}

instance info for a transcription result:

{
   "token": "my transcription",
   "application_instance_id": "06e122c3364cc74c.787379",
   "log_filename": "2014/07/18/rest_10_18_43_06e122c3364cc74c.787379.log",
   "action_result": 
   {
        "action": "start_transcription",
        "result" :
        {   
            "transcription" : 
            [
                {
                    "alternatives" : 
                    [
                        {
                            "text" : "hello which department would you like",
                            "confidence" : 0.91
                        }
                    ],
                    "final" : true,
                    "direction" : "outbound"
                }
            ],
            "completed" : false,
            "id" : ""
        }
   },
   "is_notification" : true
}

instance info for a record availability result:

{
   "token": "my outbound record",
   "application_instance_id": "06e122c3364cc74c.787379",
   "log_filename": "2014/07/18/rest_10_18_43_06e122c3364cc74c.787379.log",
   "this_call": 
   {
      "call_id": "06e122c3364cc74c.787379.359661569",
      "call_direction": "out",
      "call_from" : "443069999876
      "call_to" : "443069990123",
      "call_target" : "443069990123",
      "call_divert": "",
      "seconds_call_duration": 29.2,
      "call_state": "answered",
      "application_parameters": "my application parameters",
      "outbound_parameters": ""
   },
   "action_result": 
   {
      "action": "record",
      "result": 
      {
            "id": "",
            "filename" : "/rest_api/recordings/2018/06/16/14_35_03_04f01fb92e8913a8.62100.wav",
            "file_available" : true,
            "contains_sound" : true,
            "seconds_duration" : 16.7,
            "reason" : "silence"
      }
   },
   "is_notification" : true
}

instance info for an interrupted action:

{
   "token": "my outbound fax",
   "application_instance_id": "06e122c3364cc74c.787379",
   "log_filename": "2014/07/18/rest_10_18_43_06e122c3364cc74c.787379.log",
   "this_call": 
   {
      "call_id": "06e122c3364cc74c.787379.359661569",
      "call_direction": "out",
      "call_from" : "443069999876
      "call_to" : "443069990123",
      "call_target" : "443069990123",
      "call_divert": "",
      "seconds_call_duration": 29.2,
      "call_state": "answered",
      "application_parameters": "my application parameters",
      "outbound_parameters": "my outbound parameters"
   },
   "action_result": 
   {
      "action": "send_fax",
      "result": 
      {
          "description": "not delivered",
          "pages_sent": 0,
          "seconds_duration": 25.7
      },
      "interrupted": true
   },
   "is_notification" : false
}

TelephonyRequest Class

Namespace: Aculab.Cloud.RestAPIWrapper

Assembly: Aculab.Cloud.RestAPIWrapper.dll

A class representing an HTTP request to an Aculab REST API application.

.Net Framework.Net Standard.Net Core

public class TelephonyRequest 
{
    // Static Members
    public static async Task&lt;TelephonyRequest&gt; UnpackRequestAsync(HttpRequest request);

    // Constructors
    public TelephonyRequest(string instanceInfoArgument);
    public TelephonyRequest(HttpRequest request);

    // Members
    [Obsolete] public bool IsValid;
    public InstanceInfo InstanceInfo;
}

public class TelephonyRequest 
{
    // Constructors
    public TelephonyRequest(string instanceInfoArgument);

    // Members
    [Obsolete] public bool IsValid;
    public InstanceInfo InstanceInfo;
}

public class TelephonyRequest 
{
    // Static Members
    public static async Task&lt;TelephonyRequest&gt; UnpackRequestAsync(HttpRequest request);

    // Constructors
    public TelephonyRequest(string instanceInfoArgument);
    public TelephonyRequest(HttpRequest request);

    // Members
    [Obsolete] public bool IsValid;
    public InstanceInfo InstanceInfo;
}

InstanceInfo Class

Namespace: Aculab.Cloud.RestAPIWrapper

Assembly: Aculab.Cloud.RestAPIWrapper.dll

A class representing the information that is presented to an application instance by each HTTP request.

.Net Framework.Net Standard.Net Core

public class InstanceInfo 
{
    // Members
    public string Token;
    public string ApplicationInstanceId;
    public string LogFilename;
    public CallInfo ThisCall;
    public ActionResult ActionResult;
    public ActionProgress ActionProgress;
    public bool IsNotification;
    public ErrorResult ErrorResult;
    public List&lt;CallInfo&gt; DroppedCalls;
}

Examples:

Example 1Example 2Example 3Example 4Example 5Example 6Example 7

Get the caller's number or SIP address from the instance info of an inbound call:

var instanceInfo = new TelephonyRequest(Request).InstanceInfo;
var callInfo = instanceInfo.ThisCall;
var callFrom = callInfo.CallFrom;

Get the result of classification of the far end of the call from the instance info of an outbound call:

var instanceInfo = new TelephonyRequest(Request).InstanceInfo;
var callInfo = instanceInfo.ThisCall;
var farEndType = callInfo.FarEndType;

Get the call duration and call recording filename from the instance info to an application's Final page:

var instanceInfo = new TelephonyRequest(Request).InstanceInfo;
var callInfo = instanceInfo.ThisCall;
var duration = callInfo.SecondsCallDuration;
var callRecordingFilename = callInfo.CallRecordingFilename;

Get the error result and action from the instance info:

var instanceInfo = new TelephonyRequest(Request).InstanceInfo;
var error = instanceInfo.ErrorResult;
var errorAction = error.Action;
var errorResult = error.Result;

Extract the transcription from the action result:

var instanceInfo = new TelephonyRequest(Request).InstanceInfo;
var transcriptionResult = (StartTranscriptionResult)instanceInfo.ActionResult;
var completed = transcriptionResult.Completed;
var id = transcriptionResult.Id;
var phrases = transcriptionResult.Transcription;
foreach (var phrase in phrases)
{
    var direction = phrase.Direction;
    var alternatives = phrase.Alternatives;
    foreach (var alternative in alternatives)
    {
        if (phrase.Final)
        {
            var text = alternative.Text;
            var confidence = alternative.Confidence;
            // process final speech result...
        }
        else
        {
            var stability = phrase.Stability;
            var text = alternative.Text;
            // process interim speech result...
        }
    }
}

Extract the recorded filename from the action result:

var instanceInfo = new TelephonyRequest(Request).InstanceInfo;
if (instanceInfo.IsNotification)
{
    var recordResult = (RecordResult)instanceInfo.ActionResult;
    if (recordResult.FileAvailable)
    {
        var recordFilename = recordResult.Filename;
        // The file is now available for general use
    }
    // Return NoContent as it is a notification
    Response.StatusCode = (int)HttpStatusCode.NoContent;
}

Get the action that was interrupted from the instance info:

var instanceInfo = new TelephonyRequest(Request).InstanceInfo;
var actionResult = instanceInfo.ActionResult;
var interrupted = actionResult.Interrupted;
var action = actionResult.Action;

public class InstanceInfo 
{
    // Members
    public string Token;
    public string ApplicationInstanceId;
    public string LogFilename;
    public CallInfo ThisCall;
    public ActionResult ActionResult;
    public ActionProgress ActionProgress;
    public bool IsNotification;
    public ErrorResult ErrorResult;
    public List&lt;CallInfo&gt; DroppedCalls;
}

Examples:

Example 1Example 2Example 3Example 4Example 5Example 6Example 7

Get the caller's number or SIP address from the instance info of an inbound call:

var instanceInfo = new TelephonyRequest(Request).InstanceInfo;
var callInfo = instanceInfo.ThisCall;
var callFrom = callInfo.CallFrom;

Get the result of classification of the far end of the call from the instance info of an outbound call:

var instanceInfo = new TelephonyRequest(Request).InstanceInfo;
var callInfo = instanceInfo.ThisCall;
var farEndType = callInfo.FarEndType;

Get the call duration and call recording filename from the instance info to an application's Final page:

var instanceInfo = new TelephonyRequest(Request).InstanceInfo;
var callInfo = instanceInfo.ThisCall;
var duration = callInfo.SecondsCallDuration;
var callRecordingFilename = callInfo.CallRecordingFilename;

Get the error result and action from the instance info:

var instanceInfo = new TelephonyRequest(Request).InstanceInfo;
var error = instanceInfo.ErrorResult;
var errorAction = error.Action;
var errorResult = error.Result;

Extract the transcription from the action result:

var instanceInfo = new TelephonyRequest(Request).InstanceInfo;
var transcriptionResult = (StartTranscriptionResult)instanceInfo.ActionResult;
var completed = transcriptionResult.Completed;
var id = transcriptionResult.Id;
var phrases = transcriptionResult.Transcription;
foreach (var phrase in phrases)
{
    var direction = phrase.Direction;
    var alternatives = phrase.Alternatives;
    foreach (var alternative in alternatives)
    {
        if (phrase.Final)
        {
            var text = alternative.Text;
            var confidence = alternative.Confidence;
            // process final speech result...
        }
        else
        {
            var stability = phrase.Stability;
            var text = alternative.Text;
            // process interim speech result...
        }
    }
}

Extract the recorded filename from the action result:

var instanceInfo = new TelephonyRequest(Request).InstanceInfo;
if (instanceInfo.IsNotification)
{
    var recordResult = (RecordResult)instanceInfo.ActionResult;
    if (recordResult.FileAvailable)
    {
        var recordFilename = recordResult.Filename;
        // The file is now available for general use
    }
    // Return NoContent as it is a notification
    Response.StatusCode = (int)HttpStatusCode.NoContent;
}

Get the action that was interrupted from the instance info:

var instanceInfo = new TelephonyRequest(Request).InstanceInfo;
var actionResult = instanceInfo.ActionResult;
var interrupted = actionResult.Interrupted;
var action = actionResult.Action;

public class InstanceInfo 
{
    // Members
    public string Token;
    public string ApplicationInstanceId;
    public string LogFilename;
    public CallInfo ThisCall;
    public ActionResult ActionResult;
    public ActionProgress ActionProgress;
    public bool IsNotification;
    public ErrorResult ErrorResult;
    public List&lt;CallInfo&gt; DroppedCalls;
}

Examples:

Example 1Example 2Example 3Example 4Example 5Example 6Example 7

Get the caller's number or SIP address from the instance info of an inbound call:

var telephonyRequest = await TelephonyRequest.UnpackRequestAsync(Request);
var callInfo = instanceInfo.ThisCall;
var callFrom = callInfo.CallFrom;

Get the result of classification of the far end of the call from the instance info of an outbound call:

var telephonyRequest = await TelephonyRequest.UnpackRequestAsync(Request);
var callInfo = instanceInfo.ThisCall;
var farEndType = callInfo.FarEndType;

Get the call duration and call recording filename from the instance info to an application's Final page:

var telephonyRequest = await TelephonyRequest.UnpackRequestAsync(Request);
var callInfo = instanceInfo.ThisCall;
var duration = callInfo.SecondsCallDuration;
var callRecordingFilename = callInfo.CallRecordingFilename;

Get the error result and action from the instance info:

var telephonyRequest = await TelephonyRequest.UnpackRequestAsync(Request);
var error = instanceInfo.ErrorResult;
var errorAction = error.Action;
var errorResult = error.Result;

Extract the transcription from the action result:

var telephonyRequest = await TelephonyRequest.UnpackRequestAsync(Request);
var transcriptionResult = (StartTranscriptionResult)instanceInfo.ActionResult;
var completed = transcriptionResult.Completed;
var id = transcriptionResult.Id;
var phrases = transcriptionResult.Transcription;
foreach (var phrase in phrases)
{
    var direction = phrase.Direction;
    var alternatives = phrase.Alternatives;
    foreach (var alternative in alternatives)
    {
        if (phrase.Final)
        {
            var text = alternative.Text;
            var confidence = alternative.Confidence;
            // process final speech result...
        }
        else
        {
            var stability = phrase.Stability;
            var text = alternative.Text;
            // process interim speech result...
        }
    }
}

Extract the recorded filename from the action result:

var telephonyRequest = await TelephonyRequest.UnpackRequestAsync(Request);
if (instanceInfo.IsNotification)
{
    var recordResult = (RecordResult)instanceInfo.ActionResult;
    if (recordResult.FileAvailable)
    {
        var recordFilename = recordResult.Filename;
        // The file is now available for general use
    }
    // Return NoContent as it is a notification
    Response.StatusCode = (int)HttpStatusCode.NoContent;
}

Get the action that was interrupted from the instance info:

var telephonyRequest = await TelephonyRequest.UnpackRequestAsync(Request);
var actionResult = instanceInfo.ActionResult;
var interrupted = actionResult.Interrupted;
var action = actionResult.Action;

TelephonyRequest Class

Namespace: Aculab.Cloud.RestAPIWrapper

Assembly: Aculab.Cloud.RestAPIWrapper.dll

A class representing an HTTP request to an Aculab REST API application.

.Net Framework.Net Standard

Public Class TelephonyRequest
    ' Shared Members
    Public Static Async Function UnpackRequestAsync(request As Httprequest) As Task<Telephonyrequest>

    ' Constructors
    Public Sub New (instanceInfoArgument As String)
    Public Sub New (request As Httprequest)

    ' Members
    [Obsolete] Public Property IsValid As Bool
    Public Property InstanceInfo As Instanceinfo
End Class

Public Class TelephonyRequest
    ' Constructors
    Public Sub New (instanceInfoArgument As String)

    ' Members
    [Obsolete] Public Property IsValid As Bool
    Public Property InstanceInfo As Instanceinfo
End Class

InstanceInfo Class

Namespace: Aculab.Cloud.RestAPIWrapper

Assembly: Aculab.Cloud.RestAPIWrapper.dll

A class representing the information that is presented to an application instance by each HTTP request.

.Net Framework.Net Standard

Public Class InstanceInfo
    ' Members
    Public Property Token As String
    Public Property ApplicationInstanceId As String
    Public Property LogFilename As String
    Public Property ThisCall As Callinfo
    Public Property ActionResult As Actionresult
    Public Property ActionProgress As Actionprogress
    Public Property IsNotification As Bool
    Public Property ErrorResult As Errorresult
    Public Property DroppedCalls As List(Of Callinfo)
End Class

Examples:

Example 1Example 2Example 3Example 4Example 5Example 6Example 7

Get the caller's number or SIP address from the instance info of an inbound call:

Dim instanceInfo = New TelephonyRequest(Request).InstanceInfo
Dim callInfo = instanceInfo.ThisCall
Dim callFrom = callInfo.CallFrom

Get the result of classification of the far end of the call from the instance info of an outbound call:

Dim instanceInfo = New TelephonyRequest(Request).InstanceInfo
Dim callInfo = instanceInfo.ThisCall
Dim farEndType = callInfo.FarEndType

Get the call duration and call recording filename from the instance info to an application's Final page:

Dim instanceInfo = New TelephonyRequest(Request).InstanceInfo
Dim callInfo = instanceInfo.ThisCall
Dim duration = callInfo.SecondsCallDuration
Dim callRecordingFilename = callInfo.CallRecordingFilename

Get the error result and action from the instance info:

Dim instanceInfo = New TelephonyRequest(Request).InstanceInfo
Dim errorResult = instanceInfo.ErrorResult
Dim errorAction = errorResult.Action
Dim result = errorResult.Result

Extract the transcription from the action result:

Dim instanceInfo = New TelephonyRequest(Request).InstanceInfo
Dim transcriptionResult As StartTranscriptionResult = instanceInfo.ActionResult
Dim completed = transcriptionResult.Completed
Dim id = transcriptionResult.Id
Dim phrases = transcriptionResult.Transcription
For Each phrase In phrases
    Dim direction = phrase.Direction
    Dim alternatives = phrase.Alternatives
    For Each alternative In alternatives
        If phrase.Final Then
            Dim text = alternative.Text
            Dim confidence = alternative.Confidence
            ' process final speech result...
        Else
            Dim stability = phrase.Stability
            Dim text = alternative.Text
            ' process interim speech result...
        End If
    Next
Next

Extract the recorded filename from the action result:

Dim instanceInfo = New TelephonyRequest(Request).InstanceInfo
If instanceInfo.IsNotification Then
    Dim recordResult As RecordResult = instanceInfo.ActionResult
    If recordResult.FileAvailable Then
        Dim recordFilename = recordResult.Filename
        ' The file Is now available for general use
    End If
    ' Return NoContent as it Is a notification
    Response.StatusCode = HttpStatusCode.NoContent
End If

Get the action that was interrupted from the instance info:

Dim instanceInfo = New TelephonyRequest(Request).InstanceInfo
Dim actionResult = instanceInfo.ActionResult
Dim interrupted = actionResult.Interrupted
Dim action = actionResult.Action

Public Class InstanceInfo
    ' Members
    Public Property Token As String
    Public Property ApplicationInstanceId As String
    Public Property LogFilename As String
    Public Property ThisCall As Callinfo
    Public Property ActionResult As Actionresult
    Public Property ActionProgress As Actionprogress
    Public Property IsNotification As Bool
    Public Property ErrorResult As Errorresult
    Public Property DroppedCalls As List(Of Callinfo)
End Class

Examples:

Example 1Example 2Example 3Example 4Example 5Example 6Example 7

Get the caller's number or SIP address from the instance info of an inbound call:

Dim instanceInfo = New TelephonyRequest(Request).InstanceInfo
Dim callInfo = instanceInfo.ThisCall
Dim callFrom = callInfo.CallFrom

Get the result of classification of the far end of the call from the instance info of an outbound call:

Dim instanceInfo = New TelephonyRequest(Request).InstanceInfo
Dim callInfo = instanceInfo.ThisCall
Dim farEndType = callInfo.FarEndType

Get the call duration and call recording filename from the instance info to an application's Final page:

Dim instanceInfo = New TelephonyRequest(Request).InstanceInfo
Dim callInfo = instanceInfo.ThisCall
Dim duration = callInfo.SecondsCallDuration
Dim callRecordingFilename = callInfo.CallRecordingFilename

Get the error result and action from the instance info:

Dim instanceInfo = New TelephonyRequest(Request).InstanceInfo
Dim errorResult = instanceInfo.ErrorResult
Dim errorAction = errorResult.Action
Dim result = errorResult.Result

Extract the transcription from the action result:

Dim instanceInfo = New TelephonyRequest(Request).InstanceInfo
Dim transcriptionResult As StartTranscriptionResult = instanceInfo.ActionResult
Dim completed = transcriptionResult.Completed
Dim id = transcriptionResult.Id
Dim phrases = transcriptionResult.Transcription
For Each phrase In phrases
    Dim direction = phrase.Direction
    Dim alternatives = phrase.Alternatives
    For Each alternative In alternatives
        If phrase.Final Then
            Dim text = alternative.Text
            Dim confidence = alternative.Confidence
            ' process final speech result...
        Else
            Dim stability = phrase.Stability
            Dim text = alternative.Text
            ' process interim speech result...
        End If
    Next
Next

Extract the recorded filename from the action result:

Dim instanceInfo = New TelephonyRequest(Request).InstanceInfo
If instanceInfo.IsNotification Then
    Dim recordResult As RecordResult = instanceInfo.ActionResult
    If recordResult.FileAvailable Then
        Dim recordFilename = recordResult.Filename
        ' The file Is now available for general use
    End If
    ' Return NoContent as it Is a notification
    Response.StatusCode = HttpStatusCode.NoContent
End If

Get the action that was interrupted from the instance info:

Dim instanceInfo = New TelephonyRequest(Request).InstanceInfo
Dim actionResult = instanceInfo.ActionResult
Dim interrupted = actionResult.Interrupted
Dim action = actionResult.Action

class TelephonyRequest

This represents a POST or GET request via the REST API. It takes an HttpRequest and unpacks the JSON request instance_info object from the contents of the body of a POST or the argument of a GET request. It can also be used to unpack the raw instance_info string.

Class synopsis:

// Constructors:
public TelephonyRequest(String jsonInstanceInfo)
public TelephonyRequest(HttpServletRequest request)

// Members:
public InstanceInfo getInstanceInfo()

class InstanceInfo

Represents the application instance information passed in the HTTP request.

Class synopsis:

// Members:
public String getToken()
public String getApplicationInstanceId()
public String getLogFilename()
public CallInfo getThisCall()
public ActionResult getActionResult()
public ActionProgress getActionProgress()
public boolean getIsNotification()
public ErrorResult getErrorResult()
public List<CallInfo> getDroppedCalls()

Examples:

Example 1Example 2Example 3Example 4Example 5Example 6Example 7

Get the caller's number or SIP address from the instance info of an inbound call:

TelephonyRequest myRequest = new TelephonyRequest(request);

CallInfo thisCall = myRequest.getInstanceInfo().getThisCall();
if (thisCall.getCallDirection() == "in")
{
    String callFrom = thisCall.getCallFrom();

    // Your code here...
}

Get the result of classification of the far end of the call from the instance info of an outbound call:

TelephonyRequest myRequest = new TelephonyRequest(request);

CallInfo thisCall = myRequest.getInstanceInfo().getThisCall();
if (thisCall.getCallDirection() == "out")
{
    String farEndType = thisCall.getFarEndType();

    // Your code here...
}

Get the call duration and call recording filename from the instance info to an application's Final page:

TelephonyRequest myRequest = new TelephonyRequest(request);

CallInfo thisCall = myRequest.getInstanceInfo().getThisCall();
if (thisCall.getCallCause() == "completed")
{
    double secondsCallDuration = thisCall.getSecondsCallDuration();
    String recordingFilename = thisCall.getCallRecordingFilename();

    // Your code here...
}

Get the error result and action from the instance info:

TelephonyRequest myRequest = new TelephonyRequest(request);

ErrorResult errorResult = myRequest.getInstanceInfo().getErrorResult();
String result = errorResult.getResult();
String action = errorResult.getAction();
long actionIndex = errorResult.getActionIndex();

//Your code here...

Extract the transcription from the action result:

TelephonyRequest myRequest = new TelephonyRequest(request);

ActionResult actionResult = myRequest.getInstanceInfo().getActionResult();

if (actionResult.getAction() == "start_transcription")
{
    StartTranscriptionResult transcriptionResult = (StartTranscriptionResult)ourRequest.getInstanceInfo().getActionResult();

    boolean completed = transcriptionResult.getCompleted();
    String id = transcriptionResult.getId();
    List<Phrase> phrases = transcriptionResult.getTranscription();

    for (Phrase phrase : phrases)
    {
        String dir = phrase.getDirection();
        List<Speech> alternatives = phrase.getAlternatives();

        for (Speech alternative : alternatives)
        {
            if (phrase.getFinal())
            {
                String text = alternative.getText();
                double confidence = alternative.getConfidence();

                /* process final speech */
            }
            else
            {
                String text = alternative.getText();
                double stability = phrase.getStability();

                /* process interim speech */
            }
        }
    }
}

Extract the recorded filename from the action result:

TelephonyRequest myRequest = new TelephonyRequest(request);
ActionResult actionResult = myRequest.getInstanceInfo().getActionResult();

if (actionResult.getAction() == "record")
{
    RecordResult recordResult = (RecordResult)actionResult;
    String filename = recordResult.getFilename();

    // Your code here...
}

Get the action that was interrupted from the instance info:

TelephonyRequest myRequest = new TelephonyRequest(request);

ActionResult actionResult = myRequest.getInstanceInfo().getActionResult();
if (actionResult.getInterrupted())
{
    String interruptedAction = actionResult.getAction();

    //Your code here...
}

class TelephonyRequest

This represents a POST or GET request via the REST API. The class constructor extracts the instance info data from either a JSON formatted instance info string, a Flask Request object or a WSGI environment dictionary.

Class synopsis:

# TelephonyRequest object:
TelephonyRequest(request_data)

# Instance methods:
TelephonyRequest.get_instance_info()
TelephonyRequest.get_application_instance_id()
TelephonyRequest.get_token()
TelephonyRequest.get_log_filename()
TelephonyRequest.get_this_call()
TelephonyRequest.get_action_result()
TelephonyRequest.get_action_progress()
TelephonyRequest.get_is_notification()
TelephonyRequest.get_dropped_calls()
TelephonyRequest.get_error_result()

Examples:

Example 1Example 2Example 3Example 4Example 5Example 6Example 7

Get the caller's number or SIP address from the instance info of an inbound call:

my_request = TelephonyRequest(request)

this_call = my_request.get_this_call()

if this_call.get("call_direction") == "in":
    call_from = this_call.get("call_from")
    calling_party_info_str = "call_from={}".format(call_from)

Get the result of classification of the far end of the call from the instance info of an outbound call:

my_request = TelephonyRequest(request)

this_call = my_request.get_this_call()

if this_call.get("call_direction") == "out":
    far_end_type = this_call.get("far_end_type")
    called_party_info_str = "far end type={}".format(far_end_type)

Get the call duration and call recording filename from the instance info to an application's Final page:

my_request = TelephonyRequest(request)

this_call = my_request.get_this_call()

if this_call.get("call_cause", "") == "completed":
    seconds_call_duration = this_call.get("seconds_call_duration")
    call_summary_info_str = "Duration={}".format(seconds_call_duration)

Get the error result and action from the instance info:

my_request = TelephonyRequest(request)

error_result = my_request.get_error_result()

if error_result != None:
    err_res = error_result.get("result")
    err_action = error_result.get("action", "?")
    err_action_index = error_result.get("action_index", "?")
    error_info_str = "Error result={} action={} action_index={}".format(err_res, err_action, err_action_index)

Extract the transcription from the action result:

my_request = TelephonyRequest(request)
action_result = my_request.get_action_result()

if action_result.get("action") == "start_transcription":

    transcription_result = action_result.get("result")

    completed = transcription_result.get("completed")
    id = transcription_result.get("id")
    phrases = transcription_result.get("transcription")

    for phrase in phrases:

        alternatives = phrase.get("alternatives")
        direction = phrase.get("direction")
        final = phrase.get("final")

        for alternative in alternatives:

            if final:

                text = alternative.get("text")
                confidence = alternative.get("confidence")

                # Process final speech

            else:

                text = alternative.get("text")
                stability = phrase.get("stability")

                # Process interim speech

Extract the recorded filename from the action result:

my_request = TelephonyRequest(request)
if my_request.get_is_notification():
    if action_result.get("action") == "record":
        record_result = action_result.get("result")

        if record_result.get("file_available"):
            filename = record_result.get("filename")

            # note that the file is now available

    # Return 'No content' response code if is_notification
    # is true.
    http_response_code = 204

    # If this code is being run in a function bound to a URL
    # using Flask, then returning the following at this point
    # would ensure a 'No content' response to the request:
    #   empty_json = '{}'.encode('utf-8')
    #   return empty_json, http_response_code

Get the action that was interrupted from the instance info:

my_request = TelephonyRequest(request)

action_result = my_request.get_action_result()

if action_result != None:
    action = action_result.get("action")

    is_interrupted = action_result.get("interrupted", False)

    if is_interrupted:
        action_info_str = "action={} was interrupted.".format(action)

The InstanceInfo class

Introduction

Represents the application instance information passed in the HTTP request.

getInstanceInfo() extracts the data from the HTTP request and returns an InstanceInfo object.
getToken() will return an empty string if no token was specified in the request.
getActionResult() will return null, an ActionResult object or an object that extends ActionResult such as a RecordResult or StartTranscriptionResult object depending on which action initiated the current HTTP request or was interrupted.
getActionProgress() will return null or a ReceiveFaxProgress or SendFaxProgress object depending on the action that initiated the current HTTP request.

Class synopsis

class InstanceInfo {

    /* methods */
    public static InstanceInfo getInstanceInfo()
    public string getToken()
    public CallInfo getThisCallInfo()
    public string getApplicationInstanceId()
    public string getLogFilename()
    public boolean getIsNotification()
    public array[CallInfo] getDroppedCallInfo()
    public mixed getActionResult()
    public mixed getErrorResult()
    public mixed getActionProgress()
}

Examples:

Example 1Example 2Example 3Example 4Example 5Example 6Example 7

Get the caller's number or SIP address from the instance info of an inbound call

$info = \Aculab\TelephonyRestAPI\InstanceInfo::getInstanceInfo();
$thisCallInfo = $info->getThisCallInfo();
$callFrom = $thisCallInfo->getCallFrom();

Get the result of classification of the far end of the call from the instance info of an outbound call

$info = \Aculab\TelephonyRestAPI\InstanceInfo::getInstanceInfo();
$thisCallInfo = $info->getThisCallInfo();
$farEndType = $thisCallInfo->getFarEndType();

Get the call duration and call recording filename from the instance info to an application's Final page

$info = \Aculab\TelephonyRestAPI\InstanceInfo::getInstanceInfo();
$thisCallInfo = $info->getThisCallInfo();
$duration = $thisCallInfo->getSecondsCallDuration();
$callRecordingFilename = $thisCallInfo->getCallRecordingFilename();

Get the error result and action from the instance info

$info = \Aculab\TelephonyRestAPI\InstanceInfo::getInstanceInfo();
$error = $info->getErrorResult();
$errorAction = $error->getAction();
$errorResult = $error->getResult();

Extract the transcription from the action result

$info = \Aculab\TelephonyRestAPI\InstanceInfo::getInstanceInfo();

$transcriptionResult = $info->getActionResult();

$completed = $transcriptionResult->getCompleted();
$id = $transcriptionResult->getID();
$phrases = $transcriptionResult->getTranscription();
foreach($phrases as $phrase) {
    $dir = $phrase->getDirection();
    $alternatives = $phrase->getAlternatives();
    foreach($alternatives as $speech) {
        if ($phrase->getFinal()) {
            if ($speech) {
                $text = $speech->getText();
                $confidence = $speech->getConfidence();
                /* process final speech */
            }
        } else {
            $stability = $phrase->getStability();
            if ($speech) {
                $text = $speech->getText();
                /* process interim speech */
            }
        }
    }
}

Extract the recorded filename from the action result

$info = \Aculab\TelephonyRestAPI\InstanceInfo::getInstanceInfo();
if ($info->getIsNotification()) {
    $recordResult = $info->getActionResult();
    if ($recordResult->getFileAvailable()) {
        $recordFilename = $recordResult->getFilename();
        /* note that the file is now available */
    }
    /* return 204 as it is a notification */
    http_response_code(204);
}

Get the action that was interrupted from the instance info

$info = \Aculab\TelephonyRestAPI\InstanceInfo::getInstanceInfo();
$actionResult = $info->getActionResult();
$action = $actionResult->getAction();

Property	Availability	Description
application instance id	always	A string that uniquely identifies the application instance associated with this request.
token	always	A user-defined string as supplied in your application's HTTP response. This defaults to null. This token will be empty for speech transcription results sent to a results page.
log filename	always	The filename of the diagnostic log associated with this application instance, in on your REST Log Files store.
this call	always, except for notifications or start transcription results	A call info object containing details of the call associated with this request. Actions returned in the corresponding response will act on this call.
action result	requests to `next page` (excluding redirect) and interrupted actions	An action result object containing a result property from the previous action or no result property if the action was interrupted by a call to the rest_interrupt web service.
action progress	only for applications that support progress notifications and only if a `progress page` is supplied	An action progress object containing information on the fax session currently running.
is notification from API V2.0	always	Whether this page request is a notification only and cannot determine the application call flow. If `true` the response to this request should be a 204 response code indicating no content.
dropped calls	request to the `final page` of a connect action	An array of call info objects containing details of any outbound calls attempted during a connect action that were dropped automatically.
error result	request to `error page`.	An error result object pertaining to a previous response.