Simple Receive Fax

A simple inbound application that starts a fax session on an inbound call and receives a fax to a tif file.

A progress page is set so that the application can present the negotiated fax settings and a page count after each page has been received. A next page is set so that the application can present the fax termination result and the name of the tif file.

Uses actions:

Receive Fax

JSONC#VBJavaPythonPHP

First pageError pageFinal page

{
    "actions" :
    [
        {
            "receive_fax" :
            {
                "next_page"  :
                {
                    "url"    : "ReceiveFaxComplete",
                    "method" : "Post"
                }
                "progress_page":
                {
                    "url"    : "FaxProgress",
                    "method" : "Post"
                }
            }
        }
    ],
    "token" : "my instance id"
}

{
    [
    ],
    "token" : "Error for Action: xxxx  ActionIndex: xxxx  Result: xxxx"
}

{
}

Implemented as ASP.Net Web Forms:

First pageReceiveFaxProgress pageReceiveFaxComplete pageError pageFinal page

using System;
using System.Collections.Generic;
using RestAPIWrapper;

public partial class SimpleReceiveFax : System.Web.UI.Page
{
    protected void Page_Load(object sender, EventArgs e)
    {
        // Unpack the request
        TelephonyRequest ourRequest = new TelephonyRequest(Request);
        if (!ourRequest.IsValid)
        {
            return;
        }

        // Setup the actions
        List<TelephonyAction> actions = new List<TelephonyAction>();
        actions.Add(new ReceiveFax(new WebPageRequest("ReceiveFaxComplete.aspx"), new WebPageRequest("ReceiveFaxProgress.aspx")));

        // Respond
        TelephonyResponse ourResponse = new TelephonyResponse(actions, "my receive fax instance id");
        ourResponse.ToHttpResponse(Response);
    }
}

using System;
using System.Collections.Generic;
using RestAPIWrapper;

public partial class ReceiveFaxProgress : System.Web.UI.Page
{
    protected void Page_Load(object sender, EventArgs e)
    {
        // Unpack the request
        TelephonyRequest ourRequest = new TelephonyRequest(Request);
        if (!ourRequest.IsValid)
        {
            return;
        }
        String token = ourRequest.InstanceInfo.Token;
        ReceiveFaxProgress progress = (ReceiveFaxProgress)ourRequest.InstanceInfo.ActionProgress;

        // Add your own code here to use the progress information.
        // e.g. update a database, write to a log...
        int pagesReceived = progress.PagesReceived;

        // Respond
        TelephonyResponse ourResponse = new TelephonyResponse(token);
        ourResponse.ToHttpResponse(Response);
    }
}

using System;
using System.Collections.Generic;
using RestAPIWrapper;

public partial class ReceiveFaxComplete : System.Web.UI.Page
{
    protected void Page_Load(object sender, EventArgs e)
    {
        // Unpack the request
        TelephonyRequest ourRequest = new TelephonyRequest(Request);
        if (!ourRequest.IsValid)
        {
            return;
        }
        String token = ourRequest.InstanceInfo.Token;
        ReceiveFaxResult result = (ReceiveFaxResult)ourRequest.InstanceInfo.ActionResult;

        // Add your own code here to use the result information.
        // e.g. update a database, write to a log...
        int pagesReceived = result.PagesReceived;
        String faxFilename = result.FaxFilename;

        // Respond
        TelephonyResponse ourResponse = new TelephonyResponse(token);
        ourResponse.ToHttpResponse(Response);
    }
}

using System;
using System.Collections.Generic;
using RestAPIWrapper;

public partial class ErrorPage : System.Web.UI.Page
{
    protected void Page_Load(object sender, EventArgs e)
    {
        // Unpack the request
        TelephonyRequest ourRequest = new TelephonyRequest(Request);
        if (!ourRequest.IsValid)
        {
            return;
        }
        ErrorResult result = ourRequest.InstanceInfo.ErrorResult;

        String token = String.Format("Action: {0}\nActionIndex: {1}\nResult: {2}",
            result.Action, result.ActionIndex, result.Result);

        // Respond
        TelephonyResponse ourResponse = new TelephonyResponse(null, token);
        ourResponse.ToHttpResponse(Response);
    }
}

using System;
using System.Collections.Generic;
using RestAPIWrapper;

public partial class FinalPage : System.Web.UI.Page
{
    protected void Page_Load(object sender, EventArgs e)
    {
        // Unpack the request
        TelephonyRequest ourRequest = new TelephonyRequest(Request);
        if (!ourRequest.IsValid)
        {
            return;
        }
    }
}

Implemented as ASP.Net Web Forms:

First pageReceiveFaxProgress pageReceiveFaxComplete pageError pageFinal page

Imports System
Imports System.Collections.Generic
Imports RestAPIWrapper

Partial Class SimpleReceiveFax
    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

        ' Setup the actions
        Dim actions As List(Of TelephonyAction) = New List(Of TelephonyAction)
        actions.Add(New ReceiveFax(New WebPageRequest("ReceiveFaxComplete.aspx"), New WebPageRequest("ReceiveFaxProgress.aspx")))

        ' Respond
        Dim ourResponse As TelephonyResponse = New TelephonyResponse(actions, "my receive fax instance id")
        ourResponse.ToHttpResponse(Response)
    End Sub
End Class

Imports System
Imports System.Collections.Generic
Imports RestAPIWrapper

Partial Class ReceiveFaxProgress
    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
        Dim token As String = ourRequest.InstanceInfo.Token
        Dim progress As RestAPIWrapper.ReceiveFaxProgress = ourRequest.InstanceInfo.ActionProgress

        ' Add your own code here to use the progress information.
        ' e.g. update a database, write to a log...
        Dim pagesReceived As Integer = progress.PagesReceived

        ' Respond
        Dim ourResponse As TelephonyResponse = New TelephonyResponse(token)
        ourResponse.ToHttpResponse(Response)
    End Sub
End Class

Imports System
Imports System.Collections.Generic
Imports RestAPIWrapper

Partial Class ReceiveFaxComplete
    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
        Dim token As String = ourRequest.InstanceInfo.Token
        Dim result As ReceiveFaxResult = ourRequest.InstanceInfo.ActionResult

        ' Add your own code here to use the result information.
        ' e.g. update a database, write to a log...
        Dim pagesReceived As Integer = result.PagesReceived
        Dim faxFilename As String = result.FaxFilename

        ' Respond
        Dim ourResponse As TelephonyResponse = New TelephonyResponse(token)
        ourResponse.ToHttpResponse(Response)
    End Sub
End Class

Imports System
Imports System.Collections.Generic
Imports RestAPIWrapper

Partial Class ErrorPage
    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
        Dim result As ErrorResult = ourRequest.InstanceInfo.ErrorResult

        Dim token As String = String.Format("Action: {0}\nActionIndex: {1}\nResult: {2}", _
            result.Action, result.ActionIndex, result.Result)

        ' Respond
        Dim ourResponse As TelephonyResponse = New TelephonyResponse(token)
        ourResponse.ToHttpResponse(Response)
    End Sub
End Class

Imports System
Imports System.Collections.Generic
Imports RestAPIWrapper

Partial Class FinalPage
    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
    End Sub
End Class

Implemented as Java Servlets:

First pageReceiveFaxProgress pageReceiveFaxComplete pageError pageFinal page

package com.aculab.telephonyrestapi.samples;

import javax.servlet.http.*;
import javax.servlet.ServletException;
import java.io.IOException;
import com.aculab.telephonyrestapi.*;

public class SimpleReceiveFax extends HttpServlet
{
    @Override
    public void doPost(HttpServletRequest request,
                       HttpServletResponse response) throws IOException, ServletException
    {
        handleRequest(request, response);
    }

    @Override
    public void doGet(HttpServletRequest request,
                      HttpServletResponse response) throws IOException, ServletException
    {
        handleRequest(request, response);
    }

    private void handleRequest(HttpServletRequest request,
                               HttpServletResponse response) throws IOException
    {
        // Unpack the request
        TelephonyRequest ourRequest = new TelephonyRequest(request);
        if (!ourRequest.isValid())
        {
            return;
        }

        // Setup the actions
        List<TelephonyAction> actions = new ArrayList<TelephonyAction>();
        actions.add(new ReceiveFax(new WebPageRequest("ReceiveFaxComplete"), new WebPageRequest("ReceiveFaxProgress")));

        // Respond
        TelephonyResponse ourResponse = new TelephonyResponse(actions, "my receive fax instance id");
        ourResponse.setHttpServletResponse(response);
    }
}

package com.aculab.telephonyrestapi.samples;

import javax.servlet.http.*;
import javax.servlet.ServletException;
import java.io.IOException;
import com.aculab.telephonyrestapi.*;

public class ReceiveFaxProgress extends HttpServlet
{
    @Override
    public void doPost(HttpServletRequest request,
                       HttpServletResponse response) throws IOException, ServletException
    {
        handleRequest(request, response);
    }

    @Override
    public void doGet(HttpServletRequest request,
                      HttpServletResponse response) throws IOException, ServletException
    {
        handleRequest(request, response);
    }

    private void handleRequest(HttpServletRequest request,
                               HttpServletResponse response) throws IOException
    {
        // Unpack the request
        TelephonyRequest ourRequest = new TelephonyRequest(request);
        if (!ourRequest.isValid())
        {
            return;
        }
        String token = ourRequest.getInstanceInfo().getToken();
        ReceiveFaxProgress result = (ReceiveFaxProgress)ourRequest.getInstanceInfo().getActionProgress();

        // Add your own code here to use the progress information.
        // e.g. update a database, write to a log...
        int pagesReceived = progress.getPagesReceived();

        // Respond
        TelephonyResponse ourResponse = new TelephonyResponse(token);
        ourResponse.setHttpServletResponse(response);
    }
}

package com.aculab.telephonyrestapi.samples;

import javax.servlet.http.*;
import javax.servlet.ServletException;
import java.io.IOException;
import com.aculab.telephonyrestapi.*;

public class ReceiveFaxComplete extends HttpServlet
{
    @Override
    public void doPost(HttpServletRequest request,
                       HttpServletResponse response) throws IOException, ServletException
    {
        handleRequest(request, response);
    }

    @Override
    public void doGet(HttpServletRequest request,
                      HttpServletResponse response) throws IOException, ServletException
    {
        handleRequest(request, response);
    }

    private void handleRequest(HttpServletRequest request,
                               HttpServletResponse response) throws IOException
    {
        // Unpack the request
        TelephonyRequest ourRequest = new TelephonyRequest(request);
        if (!ourRequest.isValid())
        {
            return;
        }
        String token = ourRequest.getInstanceInfo().getToken();
        ReceiveFaxResult result = (ReceiveFaxResult)ourRequest.getInstanceInfo().getActionResult();

        // Add your own code here to use the result information.
        // e.g. update a database, write to a log...
        int pagesReceived = result.getPagesReceived();
        String faxFilename = result.getFaxFilename();

        // Respond
        TelephonyResponse ourResponse = new TelephonyResponse(token);
        ourResponse.setHttpServletResponse(response);
    }
}

package com.aculab.telephonyrestapi.samples;

import javax.servlet.http.*;
import javax.servlet.ServletException;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;

import com.aculab.telephonyrestapi.*;

public class ErrorPage extends HttpServlet
{
    private static final long serialVersionUID = -4842873371047361437L;

    @Override
    public void doGet(HttpServletRequest request,
                      HttpServletResponse response)
        throws IOException, ServletException
    {
        handleRequest(request, response);
    }

    @Override
    public void doPost(HttpServletRequest request,
            HttpServletResponse response)
                    throws IOException, ServletException
    {
        handleRequest(request, response);
    }

    private void handleRequest(HttpServletRequest request,
                               HttpServletResponse response) throws IOException
    {
        // Unpack the request
        TelephonyRequest ourRequest = new TelephonyRequest(request);
        if (!ourRequest.isValid())
        {
            return;
        }
        ErrorResult result = ourRequest.getInstanceInfo().getErrorResult();

        String token = String.format("Action: %s\nActionIndex: %d\nResult: %s", result.getAction(), result.getActionIndex(), result.getResult());

        // Respond
        List<TelephonyAction> actions = new ArrayList<TelephonyAction>();
        TelephonyResponse ourResponse = new TelephonyResponse(actions, token);
        ourResponse.setHttpServletResponse(response);
    }
}

package com.aculab.telephonyrestapi.samples;

import javax.servlet.http.*;
import javax.servlet.ServletException;
import java.io.IOException;
import com.aculab.telephonyrestapi.*;

public class FinalPage extends HttpServlet
{
    private static final long serialVersionUID = 5940620014313056844L;

    @Override
    public void doGet(HttpServletRequest request,
                      HttpServletResponse response)
        throws IOException, ServletException
    {
        handleRequest(request, response);
    }

    @Override
    public void doPost(HttpServletRequest request,
            HttpServletResponse response)
                    throws IOException, ServletException
    {
        handleRequest(request, response);
    }

    private void handleRequest(HttpServletRequest request,
                               HttpServletResponse response) throws IOException
    {
        // Unpack the request
        TelephonyRequest ourRequest = new TelephonyRequest(request);
        if (!ourRequest.isValid())
        {
            return;
        }
    }
}

Implemented using a wrapper for Python's wsgiref.simple_server.

For the purposes of this sample, the first page is first_page, the final page is final_page and the error page is error_page.

base classapplication

The application base class.

from aculab.telephony_rest_api import Play

class ApplicationBase:

    def __init__(self, exit=None):
        self.exit = exit or [self.exit]


    def exit(self):
        pass


    def error_page(self, my_actions, query_info):
        try:
            error_result = query_info.ErrorResult
            action = error_result.get('action', 'none')
            print("\nError {0} : {1}\n".format(action, error_result['result']))
            my_actions.add(Play(text_to_say='I encountered an error.'))

        except Exception as exc:
            print("Error page exception: {0}".format(exc))
        return True


    def final_page(self, my_actions, query_info):
        try:
            tcall = query_info.ThisCall
            if tcall:
                print("This call ID         : {0}".format(tcall.get('call_id')))
                print("This call duration   : {0}".format(tcall.get('seconds_call_duration')))
            self.exit[0]()
        except Exception as exc:
            print("Final page exception: {0}".format(exc))
        return True


    def unknown_page(self, my_actions, query_info):
        try:
            my_actions.add(Play(text_to_say='I find myself on an unknown page.'))
        except Exception as exc:
            print("Unknown page exception: {0}".format(exc))
        return True

The application code.

import sys, os
sys.path.append(os.path.abspath('../..'))

# import the wrappers for the REST API, these are used to create and send tasks
from aculab.telephony_rest_api import *
from aculab.simple_server import *
from aculab.base_application import ApplicationBase

class Application(ApplicationBase):

    def __init__(self):
        ApplicationBase.__init__(self)


    def responder(self, query, start_response):

        query_info = RESTQuery(query)
        page = query_info.Page

        my_actions = Actions(token='receive fax sample')

        # on your inbound service, set the first page entry to point to this page
        # e.g., http://<ip address>:<port>/first_page
        if 'first_page' == page:
            fax_action = ReceiveFax(progress_page=WebPage(url='fax_progress_page', method='POST'),
                                    next_page=WebPage(url='fax_completed_page', method='POST'))
            my_actions.add(fax_action)

        elif 'fax_progress_page' == page:
            negotiated_settings = query_info.Progress['progress'].get('negotiated_settings')
            if negotiated_settings:
                modem = negotiated_settings['modem']
                datarate = negotiated_settings['data_rate']
                print("Modem {0} rate {1}".format(modem, datarate))
            pages = query_info.Progress['progress'].get('pages_received', '0')
            print("Page count {0}".format(pages))

        elif 'fax_completed_page' == page:
            fax_result = query_info.ActionResult['result']['description']
            fax_filename = query_info.ActionResult['result']['fax_filename']
            print("The fax result is {0}".format(fax_result))
            print("The fax filename is {0}".format(fax_filename))

        elif 'final_page' == page:
            if self.final_page(my_actions, query_info) is False:
                return None

        elif 'error_page' == page:
            if self.error_page(my_actions, query_info) is False:
                return None

        else:
            if self.unknown_page(my_actions, query_info) is False:
                return None

        response_body = my_actions.get_json()
        response_headers = [('Content-Type', 'application/json; charset=utf-8'), ('Content-Length', str(len(response_body)))]
        start_response('200 OK', response_headers)
        return [response_body]


if __name__ == "__main__":
    application = Application()
    # Set the host and port you want to use in the rest_simple_server.py file.
    # To use SSL also set the key and certificate file.
    ss = SimpleServer(application, simple_server_host, simple_server_port, simple_server_keyfile, simple_server_certfile)
    ss.start()
    print("Hit ctl-break to quit.")

First pageFaxProgress pageReceiveFaxComplete pageError pageFinal page

declare(encoding='UTF-8');
spl_autoload_register();
header("Content-Type: application/json; charset=UTF-8");

$fax = new Aculab\TelephonyRestAPI\ReceiveFax();
$fax->setProgressPage('FaxProgress.php', 'POST');
$fax->setNextPage('ReceiveFaxComplete.php', 'POST');

$response = new Aculab\TelephonyRestAPI\Actions();
$response->setToken('my instance id');
$response->add($fax);

print $response;

declare(encoding='UTF-8');
spl_autoload_register();
header("Content-Type: application/json; charset=UTF-8");

$info = Aculab\TelephonyRestAPI\InstanceInfo::getInstanceInfo();
$p = $info->getActionProgress();
$str = 'recv progress: ';
$str .= ' pages: ' . $p->getPagesReceived();
$ns = $p->getNegotiatedFaxSettings();
$str .= ' modem: ' . $ns->getModem() . ' at: ' . $ns->getDataRate() . ' remote: ' . $ns->getRemoteSubscriberId();
error_log($str);

print '';

declare(encoding='UTF-8');
spl_autoload_register();
header("Content-Type: application/json; charset=UTF-8");

$info = Aculab\TelephonyRestAPI\InstanceInfo::getInstanceInfo();
$result = $info->getActionResult();
$str = 'Fax file: ' . $result->getFaxFilename() . ' result: ' . $result->getDescription();
$str .= ' pages: ' . $result->getPagesReceived();
$str .= ' time: ' . $result->getSecondsDuration();
error_log($str);

print '';

declare(encoding='UTF-8');
spl_autoload_register();
header("Content-Type: application/json; charset=UTF-8");

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

$error = $info->getErrorResult();
$action = $error->getAction();
$desc = $error->getResult();
if (!is_null($action)) {
    error_log("Error from action \"$action\" with result:\n$desc\n");
} else {
    error_log("Error result:\n$desc\n");
}

$response = new \Aculab\TelephonyRestAPI\Actions();
$response->setToken('Error');

$play = new \Aculab\TelephonyRestAPI\Play();
$play->addText('An error has occurred.');
$response->add($play);

print $response;

declare(encoding='UTF-8');
spl_autoload_register();
header("Content-Type: application/json; charset=UTF-8");

$info = \Aculab\TelephonyRestAPI\InstanceInfo::getInstanceInfo();
$call = $info->getThisCallInfo();
$callid = $call->getCallId();
$duration = $call->getSecondsCallDuration();
error_log("This all id: $callid\nThis call duration: $duration\n");

print '';