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.

See also: HTTP response, actions

language wrappers and examples

The instance info properties are:

PropertyAvailabilityDescription
application instance idalwaysA string that uniquely identifies the application instance associated with this request.
tokenalwaysA 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 filenamealwaysThe filename of the diagnostic log associated with this application instance, in on your REST Log Files store.
this callalways, except for notifications or start transcription resultsA call info object containing details of the call associated with this request. Actions returned in the corresponding response will act on this call.
action resultrequests to next page (excluding redirect) and interrupted actionsAn 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 progressonly for applications that support progress notifications and only if a progress page is suppliedAn action progress object containing information on the fax session currently running.
is notification
from API V2.0
alwaysWhether 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 callsrequest to the final page of a connect actionAn array of call info objects containing details of any outbound calls attempted during a connect action that were dropped automatically.
error resultrequest to error page.An error result object pertaining to a previous response.
  • Examples:

    • 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@anothercompany.com",
                  "call_to" : "sip:bob@acompany.com",
                  "call_target" : "sip:bob@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.

    • public class TelephonyRequest 
      {
          // Static Members
          public static async Task<TelephonyRequest> 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<TelephonyRequest> 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.

    • 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<CallInfo> DroppedCalls;
      }
      

      Examples:

      • 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<CallInfo> DroppedCalls;
      }
      

      Examples:

      • 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<CallInfo> DroppedCalls;
      }
      

      Examples:

      • 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.

    • Public Class TelephonyRequest
          ' Shared Members
          Public Static Async Function UnpackRequestAsync(request As Httprequest) As Task
      
          ' 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.

    • 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:

      • 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:

      • 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:

    • 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:

    • 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:

    • 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();