receive fax Action

Starts a fax session on an inbound call and receives a tif file to the Aculab media file store.

Received tif files are available immediately to play within an application, but generally take a few seconds to become available elsewhere. See Media File Availability for more details.

language wrappers and examples

The receive fax properties are:

Property	Required/Optional	Default	Description
next page	required		A web page request object that defines the web page to be requested once the fax session has finished. If `null` or no page is specified then the subsequent action in the action array will be executed.
id from API V2.0	optional	""	A user-defined string that can be used to uniquely identify each fax received.
progress page	optional	-	A web page request object that defines where fax progress reports are to be sent.
encryption cipher	optional	-	A cipher object to be used to encrypt the received fax.
fax available page from API V2.0	optional	-	A web page request object that defines a web page that is notified once the received fax is fully available to all applications and can be downloaded. The request to this page happens asynchronously and is not restricted to the lifetime of the application that received the fax. Its response is not considered part of the application flow.

Progress

The progress page is called after initial negotiation and then after each page that is received. It contains updated information regarding the inbound fax. The progress page will receive instance information containing an action progress object that contains details for the fax as follows:

Property	Availability	Description
id from API V2.0	always	The user-defined id specified in the action.
negotiated settings	always	A negotiated fax settings object containing the fax negotiation details, e.g., the modem and data rate.
pages received	always	The number of pages that have been received.

Note that progress notifications are not returned to the application directly, but to the progress page. A page that receives a progress notification should respond with a 204 response code indicating no content.

Returns

As soon as the fax reception is complete the fax file can be accessed by the same application (see Received Fax Available Notification for wider availability). The filename of the received fax is generated automatically and returned to the application via the subsequent HTTP Request to the next page in the action result along with final termination details of the fax session:

Property	Availability	Description
description	always	A string describing whether the fax was received successfully. The string will be one of 'fax received', 'partial reception', 'not received' or 'not a fax machine'.
id from API V2.0	always	The user-defined id specified in the action.
seconds duration	always	A floating point value to one decimal place. The number of seconds for which the fax session was active.
pages received	always	An integer. The number of pages that were received.
fax filename	always	A string. The name of the fax tif file in the media file store.
file available from API V2.0	always	true or false. Indicates whether the received file is available from the Aculab media file store outside of this application.

Received Fax Available Notification

The received fax can be accessed by the same application once next page has been called. However, more general access may not be available for several seconds (see Media File Availability).
The page supplied in fax available page will be requested when the file is available for general access (download etc.). An action result is included which is exactly the same as that in the next page request above, but with the file available property set to true.

Note that requests to this page are for notification only and should respond with a 204 response code indicating no content.

Examples:

Receive a fax and specify a next page to access the received fax filename:

"receive_fax":
{
    "next_page":
    {
        "url": "my_fax_handler_page"
    }
}

The following may be returned to the next page once the fax session has terminated:

"action_result":
{
    "action": "receive_fax",
    "result":
    {
        "id": "",
        "description": "fax received",
        "seconds_duration": 21.5,
        "pages_received": 2,
        "fax_filename": "rest_api/received_faxes/2018/04/21/12_48_11_075ef40a36c312db.4622.tif",
        "fax_available": false
    }
}

Receive a fax and save it to an encrypted file, specifying a next page to access the received fax filename. Supply a cipher to encrypt the received fax:

"receive_fax":
{
    "encryption_cipher": 
    {
        "type" : "aescbc",
        "key" : "1F2DEB2E502A4C8CBA58AB5018BD1506419EEA86DF595D3A431F43FAF57534C9",
        "initialisation_vector" : "9B85FAED9AB17570D5A82A31F846443B"
    },
    "next_page":
    {
        "url": "my_fax_handler_page"
    },
	"id": "168"
}

The following may be returned to the next page once the fax session has terminated:

"action_result":
{
    "action": "receive_fax",
    "result":
    {
        "id": "168",
        "description": "fax received",
        "seconds_duration": 21.5,
        "pages_received": 2,
        "fax_filename": "rest_api/received_faxes/2018/04/21/12_48_11_075ef40a36c312db.4622.tif",
        "fax_available": false
    }
}

Receive a fax and specify a next page and a progress page:

"receive_fax":
{
    "next_page":
    {
        "url": "my_fax_handler_page"
    },
    "progress_page": 
    {
        "url": "my_progress_handler_page"
    },
	"id": "274"
}

The following may be returned to the progress page after the first page has been received:

"action_progress":
{
    "action": "receive_fax",
    "progress": 
    {
        "id": "274",
        "negotiated_settings": 
        {
            "data_rate": 9600,
            "modem": "V17",
            "remote_subscriber_id": "12345"
        },
        "pages_received": 1
    }
}

The following may be returned to the next page once the fax session has terminated:

"action_result":
{
    "action": "receive_fax",
    "result":
    {
        "id": "274",
        "description": "fax received",
        "seconds_duration": 21.5,
        "pages_received": 2,
        "fax_filename": "rest_api/received_faxes/2018/04/21/12_48_11_075ef40a36c312db.4622.tif",
        "fax_available": false
    }
}

Receive a fax and specify a next page, a progress page and a fax available page:

"receive_fax":
{
    "next_page":
    {
        "url": "my_fax_handler_page"
    },
    "progress_page": 
    {
        "url": "my_progress_handler_page"
    },
    "fax_available_page": 
    {
        "url": "my_fax_available_handler_page"
    },
	"id": "218"
}

The following may be returned to the progress page after the first page has been received:

"action_progress":
{
    "action": "receive_fax",
    "progress": 
    {
        "id": "218",
        "negotiated_settings": 
        {
            "data_rate": 9600,
            "modem": "V17",
            "remote_subscriber_id": "12345"
        },
        "pages_received": 1
    }
}

The following may be returned to the next page once the fax session has terminated:

"action_result":
{
    "action": "receive_fax",
    "result":
    {
        "id": "218",
        "description": "fax received",
        "seconds_duration": 21.5,
        "pages_received": 2,
        "fax_filename": "rest_api/received_faxes/2018/04/21/12_48_11_075ef40a36c312db.4622.tif",
        "fax_available": false
    }
}

The following may be returned to the fax available page once the fax is fully available for download:

"action_result":
{
    "action": "receive_fax",
    "result":
    {
        "id": "218",
        "description": "fax received",
        "seconds_duration": 21.5,
        "pages_received": 2,
        "fax_filename": "rest_api/received_faxes/2018/04/21/12_48_11_075ef40a36c312db.4622.tif",
        "fax_available": true
    }
}

ReceiveFax Class
Namespace: Aculab.Cloud.RestAPIWrapper
Assembly: Aculab.Cloud.RestAPIWrapper.dll

An action to start a fax session on an inbound call and receive a tif file, writing it to the Aculab media file store.

public class ReceiveFax : TelephonyAction
{
    // Constructors
    public ReceiveFax(WebPageRequest nextPage, WebPageRequest progressPage = null);

    // Members
    public Cipher EncryptionCipher;
    public WebPageRequest NextPage;
    public WebPageRequest ProgressPage;
    public WebPageRequest FaxAvailablePage;
    public string Id;
}

Examples:

Receive a fax and specify a next page to access the received fax filename:

List<TelephonyAction> actions = new List<TelephonyAction>();

var receiveFax = new ReceiveFax(new WebPageRequest("MyFaxHandlerPage.aspx"));
actions.Add(receiveFax);

Get the filename of the received fax from the action's next page request:

// Unpack the request
var telephonyRequest = new TelephonyRequest(Request);

var receiveFaxResult = (ReceiveFaxResult)telephonyRequest.InstanceInfo.ActionResult;
var receiveFaxFilename = receiveFaxResult.FaxFilename;

Receive a fax and save it to an encrypted file, specifying a next page to access the received fax filename. Supply a cipher to encrypt the received fax:

List<TelephonyAction> actions = new List<TelephonyAction>();

byte[] key = new byte[] {
    0x1F, 0x2D, 0xEB, 0x2E, 0x50, 0x2A, 0x4C, 0x8C,
    0xBA, 0x58, 0xAB, 0x50, 0x18, 0xBD, 0x15, 0x06,
    0x41, 0x9E, 0xEA, 0xB6, 0xDF, 0x59, 0x5D, 0x3A,
0x43, 0x1F, 0x43, 0xFA, 0xF5, 0x75, 0x34, 0xC9 };

byte[] initialisationVector = new byte[] {
    0x9B, 0x85, 0xFA, 0xED, 0x9A, 0xB1, 0x75, 0x70,
0xD5, 0xA8, 0x2A, 0x31, 0xF8, 0x46, 0x44, 0x3B };

var receiveFax = new ReceiveFax(new WebPageRequest("MyFaxHandlerPage.aspx"));
receiveFax.EncryptionCipher = new AesCbcCipher(key, initialisationVector);
actions.Add(receiveFax);

Get the filename of the received fax from the action's next page request:

// Unpack the request
var telephonyRequest = new TelephonyRequest(Request);

var receiveFaxResult = (ReceiveFaxResult)telephonyRequest.InstanceInfo.ActionResult;
var receiveFaxFilename = receiveFaxResult.FaxFilename;

Receive a fax and specify a next page and a progress page:

List<TelephonyAction> actions = new List<TelephonyAction>();

var receiveFax = new ReceiveFax(new WebPageRequest("MyFaxHandlerPage.aspx"));
receiveFax.ProgressPage = new WebPageRequest("MyProgressHandlerPage.aspx");
receiveFax.Id = "274";
actions.Add(receiveFax);

Get the negotiated data rate from the action's progress page request:

// Unpack the request
var telRequest = new TelephonyRequest(Request);

var receiveFaxProgress = (ReceiveFaxProgress)telRequest.InstanceInfo.ActionProgress;
var negotiatedFaxSettings = receiveFaxProgress.NegotiatedSettings;
var dataRate = negotiatedFaxSettings.DataRate;

Get the filename of the received fax from the action's next page request:

// Unpack the request
var telephonyRequest = new TelephonyRequest(Request);

var receiveFaxResult = (ReceiveFaxResult)telephonyRequest.InstanceInfo.ActionResult;
var receiveFaxFilename = receiveFaxResult.FaxFilename;

Receive a fax and specify a next page, a progress page and a fax available page:

List<TelephonyAction> actions = new List<TelephonyAction>();

var receiveFax = new ReceiveFax(new WebPageRequest("MyFaxHandlerPage.aspx"));
receiveFax.ProgressPage = new WebPageRequest("MyProgressHandlerPage.aspx");
receiveFax.FaxAvailablePage = new WebPageRequest("MyFaxAvailableHandlerPage.aspx");
receiveFax.Id = "218";
actions.Add(receiveFax);

Get the negotiated data rate from the action's progress page request:

// Unpack the request
var telRequest = new TelephonyRequest(Request);

var receiveFaxProgress = (ReceiveFaxProgress)telRequest.InstanceInfo.ActionProgress;
var negotiatedFaxSettings = receiveFaxProgress.NegotiatedSettings;
var dataRate = negotiatedFaxSettings.DataRate;

Get the number of pages in the received fax from the action's next page request:

// Unpack the request
var telephonyRequest = new TelephonyRequest(Request);

var receiveFaxResult = (ReceiveFaxResult)telephonyRequest.InstanceInfo.ActionResult;
var pagesReceived = receiveFaxResult.PagesReceived;

Get the filename of the received fax from the action's fax available page request:

// Unpack the request
var availRequest = new TelephonyRequest(Request);

var recFaxResult = (ReceiveFaxResult)availRequest.InstanceInfo.ActionResult;
if (recFaxResult.FileAvailable)
{
    var faxFilename = recFaxResult.FaxFilename;
    // Can now notify user the fax is available
}

public class ReceiveFax : TelephonyAction
{
    // Constructors
    public ReceiveFax(WebPageRequest nextPage, WebPageRequest progressPage = null);

    // Members
    public Cipher EncryptionCipher;
    public WebPageRequest NextPage;
    public WebPageRequest ProgressPage;
    public WebPageRequest FaxAvailablePage;
    public string Id;
}

Examples:

Receive a fax and specify a next page to access the received fax filename:

List<TelephonyAction> actions = new List<TelephonyAction>();

var receiveFax = new ReceiveFax(new WebPageRequest("MyFaxHandlerPage.aspx"));
actions.Add(receiveFax);

Get the filename of the received fax from the action's next page request:

// Unpack the request
var telephonyRequest = new TelephonyRequest(Request);

var receiveFaxResult = (ReceiveFaxResult)telephonyRequest.InstanceInfo.ActionResult;
var receiveFaxFilename = receiveFaxResult.FaxFilename;

Receive a fax and save it to an encrypted file, specifying a next page to access the received fax filename. Supply a cipher to encrypt the received fax:

List<TelephonyAction> actions = new List<TelephonyAction>();

byte[] key = new byte[] {
    0x1F, 0x2D, 0xEB, 0x2E, 0x50, 0x2A, 0x4C, 0x8C,
    0xBA, 0x58, 0xAB, 0x50, 0x18, 0xBD, 0x15, 0x06,
    0x41, 0x9E, 0xEA, 0xB6, 0xDF, 0x59, 0x5D, 0x3A,
0x43, 0x1F, 0x43, 0xFA, 0xF5, 0x75, 0x34, 0xC9 };

byte[] initialisationVector = new byte[] {
    0x9B, 0x85, 0xFA, 0xED, 0x9A, 0xB1, 0x75, 0x70,
0xD5, 0xA8, 0x2A, 0x31, 0xF8, 0x46, 0x44, 0x3B };

var receiveFax = new ReceiveFax(new WebPageRequest("MyFaxHandlerPage.aspx"));
receiveFax.EncryptionCipher = new AesCbcCipher(key, initialisationVector);
actions.Add(receiveFax);

Get the filename of the received fax from the action's next page request:

// Unpack the request
var telephonyRequest = new TelephonyRequest(Request);

var receiveFaxResult = (ReceiveFaxResult)telephonyRequest.InstanceInfo.ActionResult;
var receiveFaxFilename = receiveFaxResult.FaxFilename;

Receive a fax and specify a next page and a progress page:

List<TelephonyAction> actions = new List<TelephonyAction>();

var receiveFax = new ReceiveFax(new WebPageRequest("MyFaxHandlerPage.aspx"));
receiveFax.ProgressPage = new WebPageRequest("MyProgressHandlerPage.aspx");
receiveFax.Id = "274";
actions.Add(receiveFax);

Get the negotiated data rate from the action's progress page request:

// Unpack the request
var telRequest = new TelephonyRequest(Request);

var receiveFaxProgress = (ReceiveFaxProgress)telRequest.InstanceInfo.ActionProgress;
var negotiatedFaxSettings = receiveFaxProgress.NegotiatedSettings;
var dataRate = negotiatedFaxSettings.DataRate;

Get the filename of the received fax from the action's next page request:

// Unpack the request
var telephonyRequest = new TelephonyRequest(Request);

var receiveFaxResult = (ReceiveFaxResult)telephonyRequest.InstanceInfo.ActionResult;
var receiveFaxFilename = receiveFaxResult.FaxFilename;

Receive a fax and specify a next page, a progress page and a fax available page:

List<TelephonyAction> actions = new List<TelephonyAction>();

var receiveFax = new ReceiveFax(new WebPageRequest("MyFaxHandlerPage.aspx"));
receiveFax.ProgressPage = new WebPageRequest("MyProgressHandlerPage.aspx");
receiveFax.FaxAvailablePage = new WebPageRequest("MyFaxAvailableHandlerPage.aspx");
receiveFax.Id = "218";
actions.Add(receiveFax);

Get the negotiated data rate from the action's progress page request:

// Unpack the request
var telRequest = new TelephonyRequest(Request);

var receiveFaxProgress = (ReceiveFaxProgress)telRequest.InstanceInfo.ActionProgress;
var negotiatedFaxSettings = receiveFaxProgress.NegotiatedSettings;
var dataRate = negotiatedFaxSettings.DataRate;

Get the number of pages in the received fax from the action's next page request:

// Unpack the request
var telephonyRequest = new TelephonyRequest(Request);

var receiveFaxResult = (ReceiveFaxResult)telephonyRequest.InstanceInfo.ActionResult;
var pagesReceived = receiveFaxResult.PagesReceived;

Get the filename of the received fax from the action's fax available page request:

// Unpack the request
var availRequest = new TelephonyRequest(Request);

var recFaxResult = (ReceiveFaxResult)availRequest.InstanceInfo.ActionResult;
if (recFaxResult.FileAvailable)
{
    var faxFilename = recFaxResult.FaxFilename;
    // Can now notify user the fax is available
}

public class ReceiveFax : TelephonyAction
{
    // Constructors
    public ReceiveFax(WebPageRequest nextPage, WebPageRequest progressPage = null);

    // Members
    public Cipher EncryptionCipher;
    public WebPageRequest NextPage;
    public WebPageRequest ProgressPage;
    public WebPageRequest FaxAvailablePage;
    public string Id;
}

Examples:

Receive a fax and specify a next page to access the received fax filename:

List<TelephonyAction> actions = new List<TelephonyAction>();

var receiveFax = new ReceiveFax(new WebPageRequest("MyFaxHandlerPage.aspx"));
actions.Add(receiveFax);

Get the filename of the received fax from the action's next page request:

// Unpack the request
var telephonyRequest = await TelephonyRequest.UnpackRequestAsync(Request);

var receiveFaxResult = (ReceiveFaxResult)telephonyRequest.InstanceInfo.ActionResult;
var receiveFaxFilename = receiveFaxResult.FaxFilename;

Receive a fax and save it to an encrypted file, specifying a next page to access the received fax filename. Supply a cipher to encrypt the received fax:

List<TelephonyAction> actions = new List<TelephonyAction>();

byte[] key = new byte[] {
    0x1F, 0x2D, 0xEB, 0x2E, 0x50, 0x2A, 0x4C, 0x8C,
    0xBA, 0x58, 0xAB, 0x50, 0x18, 0xBD, 0x15, 0x06,
    0x41, 0x9E, 0xEA, 0xB6, 0xDF, 0x59, 0x5D, 0x3A,
0x43, 0x1F, 0x43, 0xFA, 0xF5, 0x75, 0x34, 0xC9 };

byte[] initialisationVector = new byte[] {
    0x9B, 0x85, 0xFA, 0xED, 0x9A, 0xB1, 0x75, 0x70,
0xD5, 0xA8, 0x2A, 0x31, 0xF8, 0x46, 0x44, 0x3B };

var receiveFax = new ReceiveFax(new WebPageRequest("MyFaxHandlerPage.aspx"));
receiveFax.EncryptionCipher = new AesCbcCipher(key, initialisationVector);
actions.Add(receiveFax);

Get the filename of the received fax from the action's next page request:

// Unpack the request
var telephonyRequest = await TelephonyRequest.UnpackRequestAsync(Request);

var receiveFaxResult = (ReceiveFaxResult)telephonyRequest.InstanceInfo.ActionResult;
var receiveFaxFilename = receiveFaxResult.FaxFilename;

Receive a fax and specify a next page and a progress page:

List<TelephonyAction> actions = new List<TelephonyAction>();

var receiveFax = new ReceiveFax(new WebPageRequest("MyFaxHandlerPage.aspx"));
receiveFax.ProgressPage = new WebPageRequest("MyProgressHandlerPage.aspx");
receiveFax.Id = "274";
actions.Add(receiveFax);

Get the negotiated data rate from the action's progress page request:

// Unpack the request
var telephonyRequest = await TelephonyRequest.UnpackRequestAsync(Request);

var receiveFaxProgress = (ReceiveFaxProgress)telRequest.InstanceInfo.ActionProgress;
var negotiatedFaxSettings = receiveFaxProgress.NegotiatedSettings;
var dataRate = negotiatedFaxSettings.DataRate;

Get the filename of the received fax from the action's next page request:

// Unpack the request
var telephonyRequest = await TelephonyRequest.UnpackRequestAsync(Request);

var receiveFaxResult = (ReceiveFaxResult)telephonyRequest.InstanceInfo.ActionResult;
var receiveFaxFilename = receiveFaxResult.FaxFilename;

Receive a fax and specify a next page, a progress page and a fax available page:

List<TelephonyAction> actions = new List<TelephonyAction>();

var receiveFax = new ReceiveFax(new WebPageRequest("MyFaxHandlerPage.aspx"));
receiveFax.ProgressPage = new WebPageRequest("MyProgressHandlerPage.aspx");
receiveFax.FaxAvailablePage = new WebPageRequest("MyFaxAvailableHandlerPage.aspx");
receiveFax.Id = "218";
actions.Add(receiveFax);

Get the negotiated data rate from the action's progress page request:

// Unpack the request
var telephonyRequest = await TelephonyRequest.UnpackRequestAsync(Request);

var receiveFaxProgress = (ReceiveFaxProgress)telRequest.InstanceInfo.ActionProgress;
var negotiatedFaxSettings = receiveFaxProgress.NegotiatedSettings;
var dataRate = negotiatedFaxSettings.DataRate;

Get the number of pages in the received fax from the action's next page request:

// Unpack the request
var telephonyRequest = await TelephonyRequest.UnpackRequestAsync(Request);

var receiveFaxResult = (ReceiveFaxResult)telephonyRequest.InstanceInfo.ActionResult;
var pagesReceived = receiveFaxResult.PagesReceived;

Get the filename of the received fax from the action's fax available page request:

// Unpack the request
var telephonyRequest = await TelephonyRequest.UnpackRequestAsync(Request);

var recFaxResult = (ReceiveFaxResult)availRequest.InstanceInfo.ActionResult;
if (recFaxResult.FileAvailable)
{
    var faxFilename = recFaxResult.FaxFilename;
    // Can now notify user the fax is available
}

ReceiveFax Class
Namespace: Aculab.Cloud.RestAPIWrapper
Assembly: Aculab.Cloud.RestAPIWrapper.dll

An action to start a fax session on an inbound call and receive a tif file, writing it to the Aculab media file store.

.Net Framework
.Net Standard

Public Class ReceiveFax
    Inherits TelephonyAction

    ' Constructors
    Public Sub New (nextPage As Webpagerequest, Optional progressPage As Webpagerequest = Nothing)

    ' Members
    Public Property EncryptionCipher As Cipher
    Public Property NextPage As Webpagerequest
    Public Property ProgressPage As Webpagerequest
    Public Property FaxAvailablePage As Webpagerequest
    Public Property Id As String
End Class

Examples:

Receive a fax and specify a next page to access the received fax filename:

Dim actions = New List(Of TelephonyAction)

Dim ReceiveFax = New ReceiveFax(New WebPageRequest("MyFaxHandlerPage.aspx"))
actions.Add(ReceiveFax)

Get the filename of the received fax from the action's next page request:

' Unpack the request
Dim TelephonyRequest = New TelephonyRequest(Request)

Dim ReceiveFaxResult As ReceiveFaxResult = TelephonyRequest.InstanceInfo.ActionResult
Dim receiveFaxFilename = ReceiveFaxResult.FaxFilename

Receive a fax and save it to an encrypted file, specifying a next page to access the received fax filename. Supply a cipher to encrypt the received fax:

Dim actions = New List(Of TelephonyAction)

Dim key As Byte() = { _
    &H1F, &H2D, &HEB, &H2E, &H50, &H2A, &H4C, &H8C, _
    &HBA, &H58, &HAB, &H50, &H18, &HBD, &H15, &H6, _
    &H41, &H9E, &HEA, &HB6, &HDF, &H59, &H5D, &H3A, _
&H43, &H1F, &H43, &HFA, &HF5, &H75, &H34, &HC9}

Dim initialisationVector As Byte() = { _
    &H9B, &H85, &HFA, &HED, &H9A, &HB1, &H75, &H70, _
&HD5, &HA8, &H2A, &H31, &HF8, &H46, &H44, &H3B}

Dim ReceiveFax = New ReceiveFax(New WebPageRequest("MyFaxHandlerPage.aspx"))
ReceiveFax.EncryptionCipher = New AesCbcCipher(key, initialisationVector)
actions.Add(ReceiveFax)

Get the filename of the received fax from the action's next page request:

' Unpack the request
Dim TelephonyRequest = New TelephonyRequest(Request)

Dim ReceiveFaxResult As ReceiveFaxResult = TelephonyRequest.InstanceInfo.ActionResult
Dim receiveFaxFilename = ReceiveFaxResult.FaxFilename

Receive a fax and specify a next page and a progress page:

Dim actions = New List(Of TelephonyAction)

Dim receiveFax = New ReceiveFax(New WebPageRequest("MyFaxHandlerPage.aspx"))
receiveFax.ProgressPage = New WebPageRequest("MyProgressHandlerPage.aspx")
actions.Add(receiveFax)

Get the negotiated data rate from the action's progress page request:

' Unpack the request
Dim telRequest = New TelephonyRequest(Request)

Dim receiveFaxProgress As ReceiveFaxProgress = telRequest.InstanceInfo.ActionProgress
Dim negotiatedFaxSettings = receiveFaxProgress.NegotiatedSettings
Dim dataRate = negotiatedFaxSettings.DataRate

Get the filename of the received fax from the action's next page request:

' Unpack the request
Dim telephonyRequest = New TelephonyRequest(Request)

Dim receiveFaxResult As ReceiveFaxResult = telephonyRequest.InstanceInfo.ActionResult
Dim receiveFaxFilename = receiveFaxResult.FaxFilename

Receive a fax and specify a next page, a progress page and a fax available page:

Dim actions = New List(Of TelephonyAction)

Dim receiveFax = New ReceiveFax(New WebPageRequest("MyFaxHandlerPage.aspx"))
receiveFax.ProgressPage = New WebPageRequest("MyProgressHandlerPage.aspx")
receiveFax.FaxAvailablePage = New WebPageRequest("MyFaxAvailableHandlerPage.aspx")
receiveFax.Id = "218"
actions.Add(receiveFax)

Get the negotiated data rate from the action's progress page request:

' Unpack the request
Dim telRequest = New TelephonyRequest(Request)

Dim receiveFaxProgress As ReceiveFaxProgress = telRequest.InstanceInfo.ActionProgress
Dim negotiatedFaxSettings = receiveFaxProgress.NegotiatedSettings
Dim dataRate = negotiatedFaxSettings.DataRate

Get the filename of the received fax from the action's next page request:

' Unpack the request
Dim telephonyRequest = New TelephonyRequest(Request)

Dim receiveFaxResult As ReceiveFaxResult = telephonyRequest.InstanceInfo.ActionResult
Dim pagesReceived = receiveFaxResult.PagesReceived

Get the filename of the received fax from the action's fax available page request:

' Unpack the request
Dim availRequest = New TelephonyRequest(Request)

Dim recFaxResult As ReceiveFaxResult = availRequest.InstanceInfo.ActionResult
If recFaxResult.FileAvailable Then
    Dim faxFilename = recFaxResult.FaxFilename
    ' Can now notify user the fax Is available
End If

Public Class ReceiveFax
    Inherits TelephonyAction

    ' Constructors
    Public Sub New (nextPage As Webpagerequest, Optional progressPage As Webpagerequest = Nothing)

    ' Members
    Public Property EncryptionCipher As Cipher
    Public Property NextPage As Webpagerequest
    Public Property ProgressPage As Webpagerequest
    Public Property FaxAvailablePage As Webpagerequest
    Public Property Id As String
End Class

Examples:

Receive a fax and specify a next page to access the received fax filename:

Dim actions = New List(Of TelephonyAction)

Dim ReceiveFax = New ReceiveFax(New WebPageRequest("MyFaxHandlerPage.aspx"))
actions.Add(ReceiveFax)

Get the filename of the received fax from the action's next page request:

' Unpack the request
Dim TelephonyRequest = New TelephonyRequest(Request)

Dim ReceiveFaxResult As ReceiveFaxResult = TelephonyRequest.InstanceInfo.ActionResult
Dim receiveFaxFilename = ReceiveFaxResult.FaxFilename

Receive a fax and save it to an encrypted file, specifying a next page to access the received fax filename. Supply a cipher to encrypt the received fax:

Dim actions = New List(Of TelephonyAction)

Dim key As Byte() = { _
    &H1F, &H2D, &HEB, &H2E, &H50, &H2A, &H4C, &H8C, _
    &HBA, &H58, &HAB, &H50, &H18, &HBD, &H15, &H6, _
    &H41, &H9E, &HEA, &HB6, &HDF, &H59, &H5D, &H3A, _
&H43, &H1F, &H43, &HFA, &HF5, &H75, &H34, &HC9}

Dim initialisationVector As Byte() = { _
    &H9B, &H85, &HFA, &HED, &H9A, &HB1, &H75, &H70, _
&HD5, &HA8, &H2A, &H31, &HF8, &H46, &H44, &H3B}

Dim ReceiveFax = New ReceiveFax(New WebPageRequest("MyFaxHandlerPage.aspx"))
ReceiveFax.EncryptionCipher = New AesCbcCipher(key, initialisationVector)
actions.Add(ReceiveFax)

Get the filename of the received fax from the action's next page request:

' Unpack the request
Dim TelephonyRequest = New TelephonyRequest(Request)

Dim ReceiveFaxResult As ReceiveFaxResult = TelephonyRequest.InstanceInfo.ActionResult
Dim receiveFaxFilename = ReceiveFaxResult.FaxFilename

Receive a fax and specify a next page and a progress page:

Dim actions = New List(Of TelephonyAction)

Dim receiveFax = New ReceiveFax(New WebPageRequest("MyFaxHandlerPage.aspx"))
receiveFax.ProgressPage = New WebPageRequest("MyProgressHandlerPage.aspx")
actions.Add(receiveFax)

Get the negotiated data rate from the action's progress page request:

' Unpack the request
Dim telRequest = New TelephonyRequest(Request)

Dim receiveFaxProgress As ReceiveFaxProgress = telRequest.InstanceInfo.ActionProgress
Dim negotiatedFaxSettings = receiveFaxProgress.NegotiatedSettings
Dim dataRate = negotiatedFaxSettings.DataRate

Get the filename of the received fax from the action's next page request:

' Unpack the request
Dim telephonyRequest = New TelephonyRequest(Request)

Dim receiveFaxResult As ReceiveFaxResult = telephonyRequest.InstanceInfo.ActionResult
Dim receiveFaxFilename = receiveFaxResult.FaxFilename

Receive a fax and specify a next page, a progress page and a fax available page:

Dim actions = New List(Of TelephonyAction)

Dim receiveFax = New ReceiveFax(New WebPageRequest("MyFaxHandlerPage.aspx"))
receiveFax.ProgressPage = New WebPageRequest("MyProgressHandlerPage.aspx")
receiveFax.FaxAvailablePage = New WebPageRequest("MyFaxAvailableHandlerPage.aspx")
receiveFax.Id = "218"
actions.Add(receiveFax)

Get the negotiated data rate from the action's progress page request:

' Unpack the request
Dim telRequest = New TelephonyRequest(Request)

Dim receiveFaxProgress As ReceiveFaxProgress = telRequest.InstanceInfo.ActionProgress
Dim negotiatedFaxSettings = receiveFaxProgress.NegotiatedSettings
Dim dataRate = negotiatedFaxSettings.DataRate

Get the filename of the received fax from the action's next page request:

' Unpack the request
Dim telephonyRequest = New TelephonyRequest(Request)

Dim receiveFaxResult As ReceiveFaxResult = telephonyRequest.InstanceInfo.ActionResult
Dim pagesReceived = receiveFaxResult.PagesReceived

Get the filename of the received fax from the action's fax available page request:

' Unpack the request
Dim availRequest = New TelephonyRequest(Request)

Dim recFaxResult As ReceiveFaxResult = availRequest.InstanceInfo.ActionResult
If recFaxResult.FileAvailable Then
    Dim faxFilename = recFaxResult.FaxFilename
    ' Can now notify user the fax Is available
End If

class ReceiveFax extends TelephonyAction

Represents a receive fax action.

Class synopsis:

// Constructors:
public ReceiveFax(WebPageRequest nextPage)
public ReceiveFax(WebPageRequest nextPage, WebPageRequest progressPage)

// Members:
public void setId(String id)
public void setProgressPage(WebPageRequest progressPage)
public void setEncryptionCipher(Cipher encryptionCipher)
public void setFaxAvailablePage(WebPageRequest availablePage)

class ReceiveFaxProgress extends ActionProgress

Represents the progress of a receive fax action.

Class synopsis:

// Members:
public String getId()
public int getPagesReceived()
public NegotiatedFaxSettings getNegotiatedSettings()

class ReceiveFaxResult extends ActionResult

Represents the result of a receive fax action. This is sent in the action result for both the next page and the fax available page.

Class synopsis:

// Members:
public String getDescription()
public String getId()
public double getSecondsDuration()
public int getPagesReceived()
public String getFaxFilename()
public boolean getFileAvailable()

Examples:

Receive a fax and specify a next page to access the received fax filename:

List<TelephonyAction> actions = new ArrayList<TelephonyAction>();
            
WebPageRequest nextPage = new WebPageRequest("my_fax_handler_page");
actions.add(new ReceiveFax(nextPage));

Get details of the received fax from the action's next page request:

TelephonyRequest ourRequest = new TelephonyRequest(request);

ReceiveFaxResult receiveFaxResult = (ReceiveFaxResult)ourRequest.getInstanceInfo().getActionResult();

if (receiveFaxResult.getDescription().compareTo("fax received") == 0)
{
    String id = receiveFaxResult.getId();
    String faxFilename = receiveFaxResult.getFaxFilename();
    double duration = receiveFaxResult.getSecondsDuration();
    int pages = receiveFaxResult.getPagesReceived();

    //Your code here...
}

Receive a fax and save it to an encrypted file, specifying a next page to access the received fax filename. Supply a cipher to encrypt the received fax:

List<TelephonyAction> actions = new ArrayList<TelephonyAction>();

// Specify a 256 bit cipher to be used to encrypt the received fax
byte[] key = new byte[] {
  (byte)0x1F, (byte)0x2D, (byte)0xEB, (byte)0x2E, (byte)0x50, (byte)0x2A, (byte)0x4C, (byte)0x8C,
  (byte)0xBA, (byte)0x58, (byte)0xAB, (byte)0x50, (byte)0x18, (byte)0xBD, (byte)0x15, (byte)0x06,
  (byte)0x41, (byte)0x9E, (byte)0xEA, (byte)0x86, (byte)0xDF, (byte)0x59, (byte)0x5D, (byte)0x3A,
  (byte)0x43, (byte)0x1F, (byte)0x43, (byte)0xFA, (byte)0xF5, (byte)0x75, (byte)0x34, (byte)0xC9 };
              
byte[] initialisationVector = new byte[] {
  (byte)0x9B, (byte)0x85, (byte)0xFA, (byte)0xED, (byte)0x9A, (byte)0xB1, (byte)0x75, (byte)0x70,
  (byte)0xD5, (byte)0xA8, (byte)0x2A, (byte)0x31, (byte)0xF8, (byte)0x46, (byte)0x44, (byte)0x3B };

Cipher encryptionCipher = new AesCbcCipher(key, initialisationVector);

ReceiveFax receiveFaxAction = new ReceiveFax(new WebPageRequest("my_fax_handler_page"));
receiveFaxAction.setEncryptionCipher(encryptionCipher);
receiveFaxAction.setId("168");

actions.add(receiveFaxAction);

Get details of the received fax from the action's next page request:

TelephonyRequest ourRequest = new TelephonyRequest(request);

ReceiveFaxResult receiveFaxResult = (ReceiveFaxResult)ourRequest.getInstanceInfo().getActionResult();

if (receiveFaxResult.getDescription().compareTo("fax received") == 0)
{
    String id = receiveFaxResult.getId();
    String faxFilename = receiveFaxResult.getFaxFilename();
    double duration = receiveFaxResult.getSecondsDuration();
    int pages = receiveFaxResult.getPagesReceived();

    //Your code here...
}

Receive a fax and specify a next page and a progress page:

List<TelephonyAction> actions = new ArrayList<TelephonyAction>();

WebPageRequest nextPage = new WebPageRequest("my_fax_handler_page");
WebPageRequest progressPage = new WebPageRequest("my_progress_handler_page");

ReceiveFax receiveFaxAction = new ReceiveFax(nextPage, progressPage);
receiveFaxAction.setId("274");

actions.add(receiveFaxAction);

Get the negotiated data rate from the action's progress page request:

TelephonyRequest ourRequest = new TelephonyRequest(request);
            
ReceiveFaxProgress receiveFaxProgress = (ReceiveFaxProgress)ourRequest.getInstanceInfo().getActionProgress();
NegotiatedFaxSettings settings = receiveFaxProgress.getNegotiatedSettings();

int dataRate = settings.getDataRate();

// Your code here...

Get details of the received fax from the action's next page request:

TelephonyRequest ourRequest = new TelephonyRequest(request);

ReceiveFaxResult receiveFaxResult = (ReceiveFaxResult)ourRequest.getInstanceInfo().getActionResult();

if (receiveFaxResult.getDescription().compareTo("fax received") == 0)
{
    String id = receiveFaxResult.getId();
    String faxFilename = receiveFaxResult.getFaxFilename();
    double duration = receiveFaxResult.getSecondsDuration();
    int pages = receiveFaxResult.getPagesReceived();

    //Your code here...
}

Receive a fax and specify a next page, a progress page and a fax available page:

List<TelephonyAction> actions = new ArrayList<TelephonyAction>();

WebPageRequest nextPage = new WebPageRequest("my_fax_handler_page");
WebPageRequest progressPage = new WebPageRequest("my_progress_handler_page");
WebPageRequest availablePage = new WebPageRequest("my_fax_available_handler_page");

ReceiveFax receiveFaxAction = new ReceiveFax(nextPage, progressPage);
receiveFaxAction.setFaxAvailablePage(availablePage);
receiveFaxAction.setId("218");

actions.add(receiveFaxAction);

Get the negotiated data rate from the action's progress page request:

TelephonyRequest ourRequest = new TelephonyRequest(request);
            
ReceiveFaxProgress receiveFaxProgress = (ReceiveFaxProgress)ourRequest.getInstanceInfo().getActionProgress();
NegotiatedFaxSettings settings = receiveFaxProgress.getNegotiatedSettings();

int dataRate = settings.getDataRate();

// Your code here...

Get details of the received fax from the action's next page request:

TelephonyRequest ourRequest = new TelephonyRequest(request);

ReceiveFaxResult receiveFaxResult = (ReceiveFaxResult)ourRequest.getInstanceInfo().getActionResult();

if (receiveFaxResult.getDescription().compareTo("fax received") == 0)
{
    String id = receiveFaxResult.getId();
    String faxFilename = receiveFaxResult.getFaxFilename();
    double duration = receiveFaxResult.getSecondsDuration();
    int pages = receiveFaxResult.getPagesReceived();

    //Your code here...
}

Get details of the received fax from the action's fax available page request:

TelephonyRequest ourRequest = new TelephonyRequest(request);

ReceiveFaxResult receiveFaxResult = (ReceiveFaxResult)ourRequest.getInstanceInfo().getActionResult();

String id = receiveFaxResult.getId();
String faxFilename = receiveFaxResult.getFaxFilename();

//Your code here...

class ReceiveFax

Represents a receive fax action.

Class synopsis:

# ReceiveFax object:
ReceiveFax(next_page, progress_page=None, encryption_cipher=None)

# Instance methods:
ReceiveFax.set_id(id)
ReceiveFax.set_progress_page(progress_page)
ReceiveFax.set_encryption_cipher(encryption_cipher)
ReceiveFax.set_fax_available_page(fax_available_page)

Receive Fax Progress

The Receive Fax Progress is represented by a dictionary. It is found within the action progress for the progress page.

Obtaining the Receive Fax Progress dictionary:

my_request = TelephonyRequest(request)
action_progress = my_request.get_action_progress()
if action_progress.get("action") == "receive_fax":
    rxfax_progress =  action_progress.get("progress")

Receive Fax Result

The Receive Fax Result is represented by a dictionary. It is found within the action result for both the next page and the fax available page.

Obtaining the Receive Fax Result dictionary:

my_request = TelephonyRequest(request)
action_result = my_request.get_action_result()
if action_result.get("action") == "receive_fax":
    rxfax_result =  action_result.get("result")

Examples:

Receive a fax and specify a next page to access the received fax filename:

# Create a list of actions that will be passed to the TelephonyResponse constructor
list_of_actions = []

receive_fax_action = ReceiveFax(WebPage(url='my_fax_handler_page'))

list_of_actions.append(receive_fax_action)

Get details of the received fax from the action's next page request:

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

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

    rxfax_result =  action_result.get("result")

    id = rxfax_result.get("id")
    fax_filename = rxfax_result.get("fax_filename")
    seconds_duration = rxfax_result.get("seconds_duration")
    pages_received = rxfax_result.get("pages_received")

    # Your code here...

Receive a fax and save it to an encrypted file, specifying a next page to access the received fax filename. Supply a cipher to encrypt the received fax:

# Create a list of actions that will be passed to the TelephonyResponse constructor
list_of_actions = []

my_cipher = AESCBCCipher(key='1F2DEB2E502A4C8CBA58AB5018BD1506419EEA86DF595D3A431F43FAF57534C9', 
                         initialisation_vector='9B85FAED9AB17570D5A82A31F846443B')
                         
receive_fax_action = ReceiveFax(WebPage(url='my_fax_handler_page'))
receive_fax_action.set_encryption_cipher(my_cipher)

list_of_actions.append(receive_fax_action)

Get details of the received fax from the action's next page request:

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

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

    rxfax_result =  action_result.get("result")

    id = rxfax_result.get("id")
    fax_filename = rxfax_result.get("fax_filename")
    seconds_duration = rxfax_result.get("seconds_duration")
    pages_received = rxfax_result.get("pages_received")

    # Your code here...

Receive a fax and specify a next page and a progress page:

# Create a list of actions that will be passed to the TelephonyResponse constructor
list_of_actions = []

receive_fax_action = ReceiveFax(WebPage(url='my_fax_handler_page'))
receive_fax_action.set_progress_page(WebPage(url='my_progress_handler_page'))

list_of_actions.append(receive_fax_action)

Get the negotiated data rate from the action's progress page request:

my_request = TelephonyRequest(request)
action_progress = my_request.get_action_progress()

if action_progress.get("action") == "receive_fax":

    rxfax_progress =  action_progress.get("progress")

    id = rxfax_progress.get("id")
    negotiated_settings = rxfax_progress.get("negotiated_settings")
    data_rate = negotiated_settings.get("data_rate")

    # Your code here...

Get details of the received fax from the action's next page request:

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

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

    rxfax_result =  action_result.get("result")

    id = rxfax_result.get("id")
    fax_filename = rxfax_result.get("fax_filename")
    seconds_duration = rxfax_result.get("seconds_duration")
    pages_received = rxfax_result.get("pages_received")

    # Your code here...

Receive a fax and specify a next page, a progress page and a fax available page:

# Create a list of actions that will be passed to the TelephonyResponse constructor
list_of_actions = []

receive_fax_action = ReceiveFax(WebPage(url='my_fax_handler_page'))
receive_fax_action.set_progress_page(WebPage(url='my_progress_handler_page'))
receive_fax_action.set_fax_available_page(WebPage(url='my_fax_available_handler_page'))
receive_fax_action.set_id("218")

list_of_actions.append(receive_fax_action)

Get the negotiated data rate from the action's progress page request:

my_request = TelephonyRequest(request)
action_progress = my_request.get_action_progress()

if action_progress.get("action") == "receive_fax":

    rxfax_progress =  action_progress.get("progress")

    id = rxfax_progress.get("id")
    negotiated_settings = rxfax_progress.get("negotiated_settings")
    data_rate = negotiated_settings.get("data_rate")

    # Your code here...

Get details of the received fax from the action's next page request:

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

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

    rxfax_result =  action_result.get("result")

    id = rxfax_result.get("id")
    fax_filename = rxfax_result.get("fax_filename")
    seconds_duration = rxfax_result.get("seconds_duration")
    pages_received = rxfax_result.get("pages_received")

    # Your code here...

Get details of the received fax from the action's fax available page request:

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

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

    rxfax_result =  action_result.get("result")

    id = rxfax_result.get("id")
    fax_filename = rxfax_result.get("fax_filename")

    # Your code here...

The ReceiveFax class

Introduction

Represents a receive fax action.

Class synopsis

class ReceiveFax extends ActionBase {

    /* methods */
    public __construct(WebPageRequest|string $next_page, string $method = null)
    public self setID(string $id)
    public self setProgressPage(WebPageRequest|string $progress_page, string $method = null)
    public self setEncryptionCipher(Cipher $cipher)
    public self setFaxAvailablePage(WebPageRequest|string $page, string $method = null)
}

The ReceiveFaxProgress class

Introduction

Represents the progress information of a receive fax action.

Class synopsis

class ReceiveFaxProgress extends ActionProgress {

    /* methods */
    public string getID()
    public int getPagesReceived()
    public NegotiatedFaxSettings getNegotiatedFaxSettings()

    /* inherited methods */
    public string getAction()
}

The ReceiveFaxResult class

Introduction

Represents the result information of a receive fax action.

Class synopsis

class ReceiveFaxResult extends ActionResult {

    /* methods */
    public string getID()
    public string getDescription()
    public int getPagesReceived()
    public float getSecondsDuration()
    public string getFaxFilename()
    public boolean getFileAvailable()

    /* inherited methods */
    public string getAction()
    public boolean getInterrupted()
}

Examples:

Receive a fax and specify a next page to access the received fax filename:

$r = new Aculab\TelephonyRestAPI\ReceiveFax('my_fax_handler_page');
$response->addAction($r);

Get the filename of the received fax from the action's next page request:

$info = InstanceInfo::getInstanceInfo();
$receiveFaxResult = $info->getActionResult();
$receivedFaxFilename = $receiveFaxResult->getFaxFilename();

Receive a fax and save it to an encrypted file, specifying a next page to access the received fax filename. Supply a cipher to encrypt the received fax:

$r = new Aculab\TelephonyRestAPI\ReceiveFax('my_fax_handler_page');

$cipher = new Aculab\TelephonyRestAPI\AesCbcCipher(
    "1F2DEB2E502A4C8CBA58AB5018BD1506419EEA86DF595D3A431F43FAF57534C9",
    "9B85FAED9AB17570D5A82A31F846443B"
);
$r->setEncryptionCipher($cipher)
    ->setID("168");

$response->addAction($r);

Get the filename of the received fax from the action's next page request:

$info = InstanceInfo::getInstanceInfo();
$receiveFaxResult = $info->getActionResult();
$receivedFaxFilename = $receiveFaxResult->getFaxFilename();

Receive a fax and specify a next page and a progress page:

$r = new Aculab\TelephonyRestAPI\ReceiveFax('my_fax_handler_page');
$r->setProgressPage('my_progress_handler_page')
    ->setID("274");
$response->addAction($r);

Get the negotiated data rate from the action's progress page request:

$info = InstanceInfo::getInstanceInfo();
$receiveFaxProgress = $info->getActionProgress();
$negotiatedFaxSettings = $receiveFaxProgress->getNegotiatedFaxSettings();
$dataRate = $negotiatedFaxSettings->getDataRate();

Get the filename of the received fax from the action's next page request:

$info = InstanceInfo::getInstanceInfo();
$receiveFaxResult = $info->getActionResult();
$receivedFaxFilename = $receiveFaxResult->getFaxFilename();

Receive a fax and specify a next page, a progress page and a fax available page:

$r = new Aculab\TelephonyRestAPI\ReceiveFax('my_fax_handler_page');
$r->setProgressPage('my_progress_handler_page')
    ->setFaxAvailablePage('my_fax_available_handler_page')
    ->setID("218");
$response->addAction($r);

Get the negotiated data rate from the action's progress page request:

$info = InstanceInfo::getInstanceInfo();
$receiveFaxProgress = $info->getActionProgress();
$negotiatedFaxSettings = $receiveFaxProgress->getNegotiatedFaxSettings();
$dataRate = $negotiatedFaxSettings->getDataRate();

Get the number of pages in the received fax from the action's next page request:

$info = InstanceInfo::getInstanceInfo();
$receiveFaxResult = $info->getActionResult();
$pages = $receiveFaxResult->getPagesReceived();

Get the filename of the received fax from the action's fax available page request:

$info = InstanceInfo::getInstanceInfo();
$receiveFaxResult = $info->getActionResult();
if ($receiveFaxResult->getFileAvailable()) {
    $receivedFaxFilename = $receiveFaxResult->getFaxFilename();
    /* can now notify user the fax is available */
}