Http Request

 See also: HTTP response, actions

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.

instance info contains the properties:

PropertyAvailabilityDescription
tokenalwaysA user-defined string as supplied in your application's HTTP response. This defaults to null.
application instance idalwaysA string that uniquely identifies the application instance associated with this request.
log filenamealwaysThe filename of the diagnostic log associated with this application and stored on the Aculab server.
this callalwaysA 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 the result of the previous action or an empty object if the action was interrupted by a call to the rest_interrupt web service.
error resultrequest to error page.An error result object pertaining to a previous response.
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.
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.

call info provides details associated with a call:

PropertyAvailabilityDescription
call idalwaysA string uniquely identifying this call.
call directionalwaysEither "in" or "out".
call fromalwaysThe caller's number or SIP address.
call toalwaysThe final destination of the call. For inbound calls, this is the number or SIP address that resulted in the call being routed here.
call targetalwaysThe original destination of the call. This is the number or SIP address specified by the endpoint making the call. For outbound calls this will be the same as call to.
seconds call durationalwaysA floating point value to one decimal place. The call duration in seconds.
call statealwaysThe current state of the call. One of "idle", "inbound" or "answered".
call causerequest to final pageThe call completion cause, available once the call has gone idle. One of:
  • "completed" - all the actions have completed
  • "hung_up" - the far end of the call hung up
  • "no_answer" - the call was not answered
  • "busy" - the call was rejected indicating busy
  • "unobtainable" - the call was unobtainable
  • "dropped" - the call was dropped during the connect action
  • "failed" - the call failed
application parametersalwaysThe application parameter string as supplied in the service configuration.
outbound parametersoutbound calls onlyThe parameter string supplied in the outbound parameters property when the service was started.
far end typeoutbound calls only, when classification enabledA result of classification of the far end of the call. One of:
  • "human"
  • "answering_machine"
  • "fax_machine"
  • "unknown"
call recording filenamewhen call recording enabledThe filename of the recording of the whole call, available once the call has gone idle.

action result contains the following properties:

PropertyAvailabilityDescription
actionalwaysThe name of the action that generated this result.
resultalwaysA JSON object that contains the result of the action specified. The following actions generate an action result: record, get number, run menu, connect and connect to conference. See these actions for the contents of this object.
interruptedinterrupted actions onlyA boolean (True) to indicate that the action was interrupted by the web-services interrupt command

error result contains the following properties:

PropertyAvailabilityDescription
action indexgenerallyA zero-based index identifying the specific action that generated this result within the list of actions. This will not be present if the error is generated before any actions are interpreted from the response.
actiongenerallyThe name of the action that generated this result. This will not be present if the error is generated before any actions are interpreted from the response.
resultalwaysA string that contains an error description.

action progress contains the following properties:

PropertyAvailabilityDescription
actionalwaysThe name of the fax action that generated this result.
progressalwaysA JSON object that contains the progress information of the fax action specified. See the fax actions for the contents of this object
  • 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_to" : "sip:bob@acompany.com",
                  "call_from" : "sip:bill@anothercompany.com",
                  "call_target" : "sip:bob@acompany.com",
                  "call_direction" : "in",
                  "call_state" : "answered",
                  "seconds_call_duration" : 23.9,
                  "application_parameters" : ""
              }
          }
      
    • 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_to" : "sip:bob@acompany.com",
                  "call_from" : "sip:bill@anothercompany.com",
                  "call_target" : "sip:bob@acompany.com",
                  "call_direction" : "out",
                  "call_state" : "answered",
                  "seconds_call_duration" : 13.7,
                  "far_end_type" : "human",
                  "application_parameters" : "",
                  "outbound_parameters" : ""
              }
          }
      
    • 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_to" : "sip:bob@acompany.com",
                  "call_from" : "sip:bill@anothercompany.com",
                  "call_target" : "sip:bob@acompany.com",
                  "call_direction" : "in",
                  "call_state" : "idle",
                  "call_cause" : "completed",
                  "seconds_call_duration" : 27.2,
                  "application_parameters" : "",
                  "call_recording_filename" : "/rest_api/recordings/2013/11/07/rest_16_39_23_058d242936dcc5f9.47610.wav"
              }
          }
      
    • 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_to" : "sip:bob@acompany.com",
                  "call_from" : "sip:bill@anothercompany.com",
                  "call_target" : "sip:bob@acompany.com",
                  "call_direction" : "in",
                  "call_state" : "inbound",
                  "seconds_call_duration" : 0.0,
                  "application_parameters": "441234567890;441234567891;441234567892"
              },
              "error_result" :
              {
                  "action": "reject", 
                  "result": "Bad action: reject; parameters: {'cause': 'bisy'}. Unknown reject cause: bisy"
              } 
          }
      
    • instance info for an interrupted action:

        
          {
            "action_result": {
                "action": "send_fax",
                "result": {
                    "description": "not delivered",
                    "pages_sent": 0,
                    "seconds_duration": 25.7
                },
                "interrupted": True
              },
             "application_instance_id": "06e122c3364cc74c.787379",
             "log_filename": "2014/07/18/rest_10_18_43_06e122c3364cc74c.787379.log",
             "this_call": {
                "application_parameters": "my application parameters",
                "call_direction": "out",
                "call_from": "my call from",
                "call_id": "06e122c3364cc74c.787379.359661569",
                "call_state": "answered",
                "call_target": "my fax target",
                "call_to": "my fax target",
                "outbound_parameters": "my outbound parameters",
                "seconds_call_duration": 29.2
             },
             "token": "my outbound fax"
          }
      
  • 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.

    Constructors:

    TelephonyRequest(String instanceInfoArgument);
    TelephonyRequest(HttpRequest request);
    

    Members:

    bool IsValid;
    InstanceInfo InstanceInfo;
    
    class InstanceInfo This represents the instance information sent by a request.

    Members:

    String Token;
    String ApplicationInstanceId;
    String LogFilename;
    CallInfo ThisCall;
    ActionResult ActionResult;
    ActionProgress ActionProgress;
    ErrorResult ErrorResult;
    List<CallInfo> DroppedCalls;
    
    class CallInfo This represents information associated with a single call.

    Members:

    String CallId;
    String CallDirection;
    String CallFrom;
    String CallTo;
    String CallTarget;
    double SecondsCallDuration;
    String CallState;
    String CallCause;
    String ApplicationParameters;
    String OutboundParameters;
    String FarEndType;
    String CallRecordingFilename;
    
    class ActionResult This is a base class for the classes that represent the result of an action.

    Members:

    String Action;
    bool Interrupted;
    
    class ErrorResult This represents an error result.

    Members:

    int ActionIndex;
    String Action;
    String Result;
    

    Examples:

    • Handle GET or POST:

        using System;
        using System.Collections.Generic;
        using System.Web;
        using RestAPIWrapper;
      
        public partial class MyWebApp : System.Web.UI.Page
        {
          protected void Page_Load(object sender, EventArgs e)
          {
            // Unpack the request
            TelephonyRequest myRequest = new TelephonyRequest(Request);
            if (!myRequest.IsValid)
            {
              return;
            }
      
            // Access some of the request properties
            String token = myRequest.InstanceInfo.Token;
            CallInfo thisCallInfo = myRequest.InstanceInfo.ThisCall;
            String callFrom = thisCallInfo.CallFrom;
            ...
            
            // Access the result of a record action
            RecordResult recordResult = (RecordResult)myRequest.InstanceInfo.ActionResult;
            String recordFilename = recordResult.Filename;
            ...
          }
        }
      
  • 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.

    Constructors:

    New(instanceInfoArgument As String)
    New(request As HttpRequest)
    

    Members:

    IsValid As Boolean
    InstanceInfo As RestAPIWrapper.InstanceInfo
    
    Class InstanceInfo This represents the instance information sent by a request.

    Members:

    Token As String
    ApplicationInstanceId As String
    LogFilename As String
    ThisCall As RestAPIWrapper.CallInfo
    ActionResult As RestAPIWrapper.ActionResult;
    ActionProgress As RestAPIWrapper.ActionProgress;
    ErrorResult As RestAPIWrapper.ErrorResult;
    DroppedCalls As List(Of RestAPIWrapper.CallInfo)
    
    Class CallInfo This represents information associated with a single call.

    Members:

    CallId As String
    CallDirection As String
    CallFrom As String
    CallTo As String
    CallTarget As String
    SecondsCallDuration As Double
    CallState As String
    CallCause As String
    ApplicationParameters As String
    OutboundParameters As String
    FarEndType As String
    CallRecordingFilename As String
    
    Class ActionResult This is a base class for the classes that represent the result of an action.

    Members:

    Action As String
    Interrupted As Boolean
    
    Class ErrorResult This represents an error result.

    Members:

    ActionIndex As Integer
    Action As String
    Result As String
    

    Examples:

    • Handle GET or POST:

        Imports System
        Imports System.Collections.Generic;
        Imports System.Web;
        Imports RestAPIWrapper;
      
        Partial Class MyWebApp 
          Inherits System.Web.UI.Page
        
          Protected Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs)
      
            ' Unpack the request
            Dim ourRequest As TelephonyRequest = New TelephonyRequest(Request)
            If Not ourRequest.IsValid Then
                Return
            End If
      
            ' Access some of the request properties
            Dim token As String = myRequest.InstanceInfo.Token
            Dim thisCallInfo As CallInfo = myRequest.InstanceInfo.ThisCall
            Dim callFrom As String = thisCallInfo.CallFrom
            
            ' Access the result of a record action
            Dim recordResult As RecordResult = myRequest.InstanceInfo.ActionResult
            Dim recordFilename As String = recordResult.Filename
      
            ...
      
          End Sub
        End Class
      
  • 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.

    Constructors:

    TelephonyRequest(String instanceInfo);
    TelephonyRequest(HttpServletRequest request);
    

    Members:

    boolean isValid();
    String getToken();
    CallInfo getThisCall();
    ActionResult getActionResult(); // One of RecordResult, GetNumberResult, RunMenuResult, ConnectResult or ConnectToConferenceResult
    List<CallInfo> getDroppedCalls();
    
    class CallInfo This represents information associated with a single call.

    Members:

    String getCallId();
    String getCallDirection();
    String getCallFrom();
    String getCallTo();
    String getCallTarget();
    double getSecondsCallDuration();
    String getCallState();
    String getCallCause();
    String getApplicationParameters();
    String getOutboundParameters();
    String getFarEndType();
    String getCallRecordingFilename();
    
    class ActionResult This is a base class for the classes that represent the result of an action.

    Members:

    String getAction();
    
    class ErrorResult This represents an error result.

    Members:

    long getActionIndex();
    String getAction();
    String getResult();
    

    Examples:

    • Handle POST:

        public void doPost(HttpServletRequest request, HttpServletResponse response) 
        {
          // Unpack the request
          TelephonyRequest myRequest = new TelephonyRequest(request);
          if (myRequest.isValid())
          {
            return;
          }
      
          // Access some of the request properties
          String token = myRequest.getToken();
          CallInfo thisCallInfo = myRequest.getThisCall();
          String callFrom = thisCallInfo.getCallFrom();
          ...
      
          // Access the result of a record action
          RecordResult recordResult = (RecordResult)myRequest.getInstanceInfo().getActionResult();
          String recordFilename = recordResult.getFilename();
          ...
        }
      
    • Handle GET:

        public void doGet(HttpServletRequest request, HttpServletResponse response) 
        {
          // Unpack the request
          TelephonyRequest myRequest = new TelephonyRequest(request);
          if (myRequest.isValid())
          {
            return;
          }
      
          // Access some of the request properties
          String token = myRequest.getToken();
          CallInfo thisCallInfo = myRequest.getThisCall();
          String callFrom = thisCallInfo.getCallFrom();
          ...
        }
      
  • class SimpleServer The samples provided in the Python wrapper package make use of a wrapper for Python's wsgiref.simple_server. The source is given in the examples below.

    Constructors:

    SimpleServer(application, host, port, keyfile='', certfile='')
    
    class RESTQuery This represents the data obtained from a POST or GET request via the SimpleServer. The samples' responder functions create one of these to parse the HTTP query. The source is given in the examples below.

    Constructors:

    RESTQuery(query)
    

    Members:

    self.modified_since   # the HTTP_IF_MODIFIED_SINCE value, for cache control
    self.none_match       # The HTTP_IF_NONE_MATCH value, for cache control
    self.server_protocol  # The SERVER_PROTOCOL value, the protocol used in the request
    self.http_host        # The host value
    self.instance_info    # The raw instance info dictionary
    self.Queries          # A dictionary of QUERY_STRING strings that are not instance_info
    self.Page             # The PATH_INFO string
    self.Token            # The instance_info token member
    self.ID               # The instance_info application_instance_id member
    self.Log              # The instance_info log_filename member
    self.ThisCall         # The instance_info this_call member
    self.ActionResult     # The instance_info action_result member
    self.ErrorResult      # The instance_info error_result member
    self.DroppedCalls     # The instance_info dropped_calls member
    self.Cookie           # The HTTP_COOKIE string
    self.Credentials      # The HTTP_AUTHORIZATION string
    self.Progress         # Fax progress information
    
    

    Examples:

    • SimpleServer source:

      The wrapper for Python's wsgiref.simple_server
      import threading
      import ssl
      import os
      from wsgiref.simple_server import make_server
      
      # Set your host and port information here
      import socket
      simple_server_host     = '0.0.0.0'
      simple_server_port     = 80
      simple_server_keyfile  = ''
      simple_server_certfile = ''
      
      class SimpleServer(threading.Thread):
      
          def __init__(self, application, host, port, keyfile='', certfile=''):
      
              threading.Thread.__init__(self)
              self._application = application
              self._application.exit[0] = self._exit
      
              self._httpd = make_server(host, port, self._application.responder)
              use_ssl = (keyfile != '' and certfile != '')
              if use_ssl is True:
                  if not os.path.isfile(keyfile):
                      print("No such key file: {0}".format(keyfile))
                  elif not os.path.isfile(certfile):
                      print("No such certificate file: {0}".format(certfile))
                  else:
                      self._httpd.socket = ssl.wrap_socket(self._httpd.socket,
                                                           keyfile=keyfile,
                                                           certfile=certfile,
                                                           server_side=True,
                                                           do_handshake_on_connect=True)
              # overwrite log message so no messages are written to the console
              self._httpd.RequestHandlerClass.log_message = self.log_message
      
      
          def _exit(self):
              try:
                  self._httpd.socket.close()
              except:
                  pass
      
      
          def log_message(self, *args):
              pass
      
      
          def run(self):
              try:
                  self._httpd.serve_forever()
              except:
                  pass
      
      
          def shutdown(self):
              self._httpd.shutdown()
      
    • RESTQuery source:

      The code for the RESTQuery class
      import json
      import base64
      if sys.version > '3':
          from urllib.parse import urlparse, parse_qs
      else:
          from urlparse import urlparse, parse_qs
      
      class RESTQuery():
      
          def __init__(self, query):
      
              self.modified_since = query.get('HTTP_IF_MODIFIED_SINCE') # cache control query
              self.none_match = query.get('HTTP_IF_NONE_MATCH')         # cache control query
              self.server_protocol = query.get('SERVER_PROTOCOL')
              self.http_host = query.get('HTTP_HOST')
              self.instance_info = {}
              self.Cookie = None
              self.Queries = {}
              self.Page = None
              self.Credentials = None
              self.parse_query_string(query)
              self.Token = self.instance_info.get('token')
              self.ID = self.instance_info.get('application_instance_id', '')
              self.Log = self.instance_info.get('log_filename', '')
              self.ThisCall = self.instance_info.get('this_call', {})
              self.ActionResult = self.instance_info.get('action_result', {})
              self.ErrorResult = self.instance_info.get('error_result', {})
              self.DroppedCalls = self.instance_info.get('dropped_calls', {})
              self.Progress = self.instance_info.get('action_progress', {})
      
          def parse_query_string(self, query):
              try:
                  data = None
      
                  method = query['REQUEST_METHOD']
                  page_url = query['PATH_INFO'].strip('/')
      
                  parse_result = urlparse(page_url)
                  self.Page = parse_result.path.strip('/')
      
                  self.Cookie = query.get('HTTP_COOKIE')
                  credentials = query.get('HTTP_AUTHORIZATION')
                  if credentials:
                      if sys.version > '3':
                          self.Credentials = base64.decodestring(bytes(credentials.lstrip('Basic '), 'utf-8'))
                      else:
                          self.Credentials = base64.decodestring(credentials.lstrip('Basic '))
      
                  q = parse_qs(query['QUERY_STRING'])
                  if sys.version > '3':
                      qiterator = q.items()
                  else:
                      qiterator = q.iteritems()
                  for k, v in qiterator:
                      if k == 'instance_info':
                          data = v[0]
                      else:
                          self.Queries[k] = v
      
                  if method.lower() == 'post':
                      content_length = int(query['CONTENT_LENGTH'])
                      body_source = query['wsgi.input']
                      if sys.version > '3':
                          data = body_source.read(content_length).decode('utf-8')
                      else:
                          data = body_source.read(content_length)
      
                  if data:
                      self.instance_info = json.loads(data)
      
              except Exception as exc:
                   print("parse_query_string: Exception: {0}".format(exc))
      
  • The InstanceInfo class

    Class synopsis

    class InstanceInfo {
    
        /* methods */
        public static InstanceInfo getInstanceInfo()
        public string getToken()
        public CallInfo getThisCallInfo()
        public string getApplicationInstanceId()
        public string getLogFilename()
        public mixed getActionResult() // returns an object
        public ErrorResult getErrorResult()
        public mixed getActionProgress() // returns an object
        public array getDroppedCallInfo() // returns an array of CallInfo objects
    }
    

    Description

    Represents the application instance information passed in the HTTP request.
    MethodDescription
    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, GetNumberResult, RunMenuResult, ConnectResult, ConnectToConferenceResult, ReceiveFaxResult, SendFaxResult or GetInputResult 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.

    The CallInfo class

    Class synopsis

    class CallInfo {
    
        /* methods */
        public string getCallId()
        public string getCallDirection()
        public string getCallFrom()
        public string getCallTo()
        public string getCallTarget()
        public float getSecondsCallDuration()
        public string getCallState()
        public string getCallCause()
        public string getApplicationParameters()
        public string getOutboundParameters()
        public string getFarEndType()
        public string getCallRecordingFilename()
    }
    

    Description

    Represents information about a call.
    Functions that return strings will return an empty string if the corresponding information was not specified in the request. getSecondsCallDuration() will return zero if no duration was specified in the request.
    The ActionResult class

    Class synopsis


    class ActionResult {
    
        /* methods */
        public string getAction()
        public boolean getInterrupted()
    }
    

    Description

    Represents the result of an action.
    MethodDescription
    getAction() will return the name of the action.
    getInterrupted() returns true if the last action was interrupted.

    The ErrorResult class

    Class synopsis


    class ErrorResult {
    
        /* methods */
        public string getResult()
        public mixed getAction() // returns null or string
        public mixed getActionIndex() // returns null or int
    }
    

    Description

    Represents information about an error.
    MethodDescription
    getResult() will return an empty string if no result string was specified in the request.
    getAction() will return null if no action was specified in the request.
    getActionIndex() will return null if no action index was specified in the request.

    Examples:

    • Get the token and the current call direction:

      $info = InstanceInfo::getInstanceInfo();
      $token = $info->getToken();
      $thisCallInfo = $info->getThisCallInfo();
      $direction = $thisCallInfo->getCallDirection();