Examples:

• Example 1
• Example 2
• Example 3
• Example 4
• Example 5

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

• Example 1

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

• Example 1

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

• Example 1
• Example 2

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

• Example 1
• Example 2

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

Method	Description
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.

Method	Description
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.

Method	Description
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:

• Example 1

• Get the token and the current call direction:

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