Informizely customer feedback surveys
By using the Aculab site, you agree with our use of cookies.

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:

PropertyRequired/OptionalDefaultDescription
next pagerequiredA 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 pageoptional-A web page request object that defines where fax progress reports are to be sent.
encryption cipheroptional-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:

PropertyAvailabilityDescription
id
from API V2.0
alwaysThe user-defined id specified in the action.
negotiated settingsalwaysA negotiated fax settings object containing the fax negotiation details, e.g., the modem and data rate.
pages receivedalwaysThe 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:

PropertyAvailabilityDescription
descriptionalwaysA 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
alwaysThe user-defined id specified in the action.
seconds durationalwaysA floating point value to one decimal place. The number of seconds for which the fax session was active.
pages receivedalwaysAn integer. The number of pages that were received.
fax filenamealwaysA string. The name of the fax tif file in the media file store.
file available
from API V2.0
alwaystrue 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.

 See also: Simple Receive Fax

  • 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 acces 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 enrypted 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
      }
      
  • 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
        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 acces 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 enrypted 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 and a progress 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:

      receive_fax_action = ReceiveFax(WebPage(url='my_fax_handler_page'))
      
      my_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:

      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)
      
      my_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:

      receive_fax_action = ReceiveFax(WebPage(url='my_fax_handler_page'))
      receive_fax_action.set_progress_page(WebPage(url='my_progress_handler_page'))
      
      my_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:

      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")
      
      my_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 */
      }