send fax Action

Starts a fax session on an outbound call and sends a tif file. This can be the name of a file in the Aculab media file store or the URL of a remote file.


The send fax properties are:

PropertyRequired/OptionalDefaultDescription
fax to send required - The tif file to send. This can be the file name or a web page request. If a file name is given the file must be present in the Aculab media file store.
progress page optional null A web page request object that defines the web page to be requested for fax progress reports.
next page optional null 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.
decryption cipher optional null The cipher object to be used to decrypt the tif file to send, if it is encrypted. Cannot be used if fax to send is a web page request.

web page request defines how a specific web page is requested:

PropertyRequired/OptionalDefaultDescription
url required - The address of the web page to request.
method optional POST One of "GET" or "POST". The HTTP request method to use when requesting the url. Only "GET" is supported when uploading a file.

If a web page request is given for the fax to send, the URL supplied should point to a page that will upload a tif file. The URL can be a relative or full path. When the URL is accessed, Aculab Cloud will expect to receive image data. No information will be sent to the URL, i.e., instance info will NOT be sent, and no actions can be returned from the URL. Aculab Cloud implements cacheing, so HTTP cache-control headers will be honoured. The maximum size of a file to be uploaded is five megabytes, which is at least thirty fax pages. If your file has been cached and you need it to be refreshed immediately you can force a refresh by changing the url. An easy way to do this is to add a version number to your url.

For example, if your URL is http://Badger.set.com:80/my_tif_page?filename=my_fax.tif&version=1 it will be easy to change version to 2 and force a refresh.

Progress

The progress page is called after initial negotiation and then after each page that is sent. It contains updated information regarding the outbound fax. The progress page will receive instance information containing the property action progress which has details for the fax as follows:

PropertyDescription
action A string. The name of the action for which progress information is being supplied.
progress An object containing the progress information supplied for the current action.

The progress property will have the following properties:

PropertyDescription
negotiated settings An object containing fax negotiation details, e.g., the modem and data rate. See below.
pages sent The number of pages that have been sent.
reconnects An integer. The number of times the outbound fax session has had to place a new call (normally 0). For longer faxes, the outbound call can disconnect if the line experiences a glitch or noise. The outbound fax session will automatically call again and continue the fax from where it left off.

The negotiated settings object will contain the following properties:

PropertyDescription
data rate An integer. The negotiated baud rate in bps, e.g., 9600 or 4800.
modem A string. The modem being used, e.g., V.17 or V.29.
remote subscriber id A string. The remote end ID string.

decryption cipher contains the details of a cipher used to decrypt media files:

PropertyRequired/OptionalDescription
type required The cipher type, currently only "aescbc" (AES algorithm, CBC mode) is supported.

For the aescbc cipher the following properties must be supplied in the cipher object:

PropertyRequired/OptionalDescription
key required The cipher key as a string, either 128, 192 or 256 bits represented as 16, 24 or 32 hexadecimal bytes.
initialisation vector required The initialisation vector as a string, 128 bits represented as 16 hexadecimal bytes.

Returns

The http request to the next page will provide final termination details of the fax session in action result as follows:

PropertyDescription
description A string describing whether the fax was sent successfully. The string will be one of 'fax delivered', 'partial delivery', 'not delivered' or 'not a fax machine'.
seconds duration A floating point value to one decimal place. The number of seconds for which the fax session was active.
pages sent An integer. The number of pages that were sent.
 See also: Simple send fax
  • Examples:

    • Send a fax using the defaults:

      "send_fax": 
      {
          "fax_to_send": "my_fax.tif"
      }
      
      Note that by default there is no progress page defined. Also, note that by default there is no next page defined, so no action result is returned.

      To send a remote fax using the defaults:

      "send_fax": 
      {
          "fax_to_send": { "url" : "http://Badger.set.com:80/my_tif_page?filename=my_fax.tif&version=1" }
      }
      
    • Send a fax and specify a next page to receive the result of the send:

      "send_fax":
      {
          "fax_to_send": "my_fax.tif",
          "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": "send_fax",
              "result":
              {   
                  "description": "fax delivered",
                  "seconds_duration": 120.5,
                  "pages_sent": 2
              }
          }
      }
      
    • Send a fax from an encrypted file and specify a next page to receive the result of the send. Supply the cipher to decrypt the fax:

      "send_fax":
      {
          "fax_to_send": "my_encrypted_fax.tif",
          "decryption_cipher": 
          {
              "type" : "aescbc",
              "key" : "1F2DEB2E502A4C8CBA58AB5018BD1506419EEA86DF595D3A431F43FAF57534C9",
              "initialisation_vector" : "9B85FAED9AB17570D5A82A31F846443B"
          },
          "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": "send_fax",
              "result":
              {   
                  "description": "fax delivered",
                  "seconds_duration": 120.5,
                  "pages_sent": 2
              }
          }
      }
      
    • Send a fax, specify a progress page and a next page:

      "send_fax":
      {
          "fax_to_send": "my_fax.tif",
          "progress_page": 
          {
              "url": "my_progress_handler_page"
          },
          "next_page":
          {
              "url": "my_fax_handler_page"
          }
      }
      

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

      "action_progress":
      {
          "action": "send_fax",
          "progress": 
          {
              "negotiated_settings": 
              {
                  "data_rate": 9600,
                  "modem": "V17",
                  "remote_subscriber_id": "12345"
              },
              "pages_sent": 1,
              "reconnects": 0
          }
      }
      

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

      "action_result":
      {
          {
              "action": "send_fax",
              "result":
              {   
                  "description": "fax delivered",
                  "seconds_duration": 120.5,
                  "pages_sent": 2
              }
          }
      }
      
  • API Reference:

    class SendFax : TelephonyAction

    Represents a send fax action.

    Constructors:

    SendFax(String faxToSend);
    SendFax(Uri faxToSend);
    SendFax(String faxToSend, WebPageRequest nextPage, WebPageRequest progressPage);
    SendFax(Uri faxToSend, WebPageRequest nextPage, WebPageRequest progressPage);
    

    Members:

    Cipher DecryptionCipher;
    WebPageRequest NextPage;
    WebPageRequest ProgressPage;
    
    class WebPageRequest

    Represents a request to a web page.

    Constructors:

    WebPageRequest(String url);
    WebPageRequest(String url, String method);
    

    Members:

    String Method;
    
    class Cipher

    Represents a cipher to be used for file encryption/decryption.

    Members:

    String Type;
    
    class AesCbcCipher : Cipher

    Represents the AES cipher in CBC mode.

    Constructors:

    AesCbcCipher(byte[] key, byte[] initialisationVector);
    

    Members:

    byte[] InitialisationVector;
    
    class SendFaxProgress : ActionProgress

    Represents the progress of a send fax action.

    Members:

    int PagesSent;
    int Reconnects;
    NegotiatedFaxSettings NegotiatedSettings;
    
    class NegotiatedFaxSettings

    Represents the settings negotiated during a fax send or receive.

    Members:

    int DataRate;
    String Modem;
    String RemoteSubscriberId;
    
    class SendFaxResult : ActionResult

    Represents the result of a send fax action.

    Members:

    String Description;
    double SecondsDuration;
    int PagesSent;
    

    Examples:

    • Send a fax using the defaults:

      actions.Add(new SendFax("myFax.tif"));
      
      Note that ProgressPage and NextPage are not set by default, so no ActionResult is returned.
    • Send a fax and specify a next page to receive the result of the send:

      WebPageRequest nextPage = new WebPageRequest("MySendFaxNextPage.aspx");
      actions.Add(new SendFax("myFax.tif", nextPage, null));
      

      The send fax result is obtained from the request to the next page:

      SendFaxResult sendFaxResult = (SendFaxResult)ourRequest.InstanceInfo.ActionResult;
      int pagesSent = sendFaxResult.PagesSent;
      double secondsDuration = sendFaxResult.SecondsDuration;
      if (sendFaxResult.Description.CompareTo("fax delivered") == 0)
      {
          ...
      
    • Send a fax from an encrypted file and specify a next page to receive the result of the send. Supply the cipher to decrypt the fax:

      // Specify the 256 bit cipher needed to decrypt the file to send
      byte[] key = new byte[] {
        0x1F, 0x2D, 0xEB, 0x2E, 0x50, 0x2A, 0x4C, 0x8C,
        0xBA, 0x58, 0xAB, 0x50, 0x18, 0xBD, 0x15, 0x06,
        0x41, 0x9E, 0xEA, 0x86, 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 };
      
      Cipher decryptionCipher = new AesCbcCipher(key, initialisationVector);
      
      WebPageRequest nextPage = new WebPageRequest("MySendFaxNextPage.aspx");
      
      SendFax sendFaxAction = new SendFax("myEncryptedFax.tif", nextPage, null);
      sendFaxAction.DecryptionCipher = decryptionCipher;
      
      actions.Add(sendFaxAction);
      

      The send fax result is obtained from the request to the next page:

      SendFaxResult sendFaxResult = (SendFaxResult)ourRequest.InstanceInfo.ActionResult;
      int pagesSent = sendFaxResult.PagesSent;
      double secondsDuration = sendFaxResult.SecondsDuration;
      if (sendFaxResult.Description.CompareTo("fax delivered") == 0)
      {
          ...
      
    • Send a fax specifying a next page and a progress page:

      WebPageRequest nextPage = new WebPageRequest("MySendFaxNextPage.aspx");
      WebPageRequest progressPage = new WebPageRequest("MyProgressHandlerPage.aspx");
      actions.Add(new SendFax("myFax.tif", nextPage, progressPage));
      

      The send fax progress is obtained from the request to the progress page:

      SendFaxProgress sendFaxProgress = (SendFaxProgress)ourRequest.InstanceInfo.ActionProgress;
      int pagesSent = sendFaxProgress.PagesSent;
      int reconnects = sendFaxProgress.Reconnects;
      String remoteSubscriberId = sendFaxProgress.NegotiatedSettings.RemoteSubscriberId;
      ...
      

      The send fax result is obtained from the request to the next page:

      SendFaxResult sendFaxResult = (SendFaxResult)ourRequest.InstanceInfo.ActionResult;
      int pagesSent = sendFaxResult.PagesSent;
      double secondsDuration = sendFaxResult.SecondsDuration;
      if (sendFaxResult.Description.CompareTo("fax delivered") == 0)
      {
          ...
      
  • API Reference:

    Class SendFax Inherits TelephonyAction

    Represents a send fax action.

    Constructors:

    New(faxToSend As String)
    New(faxToSend As System.Uri)
    New(faxToSend As String, nextPage As RestAPIWrapper.WebPageRequest, progressPage As RestAPIWrapper.WebPageRequest);
    New(faxToSend As System.Uri, nextPage As RestAPIWrapper.WebPageRequest, progressPage As RestAPIWrapper.WebPageRequest);
    

    Members:

    DecryptionCipher As RestAPIWrapper.Cipher
    NextPage As RestAPIWrapper.WebPageRequest
    ProgressPage As RestAPIWrapper.WebPageRequest
    
    Class WebPageRequest

    Represents a request to a web page.

    Constructors:

    New(url As String)
    New(url As String, method As String)
    

    Members:

    Method As String
    
    class Cipher Represents a cipher to be used for file encryption/decryption.

    Members:

      Type As String
    
    class AesCbcCipher : Cipher

    Represents the AES cipher in CBC mode.

    Constructors:

      AesCbcCipher(ByVal key As Byte(), ByVal initialisationVector As Byte())
    

    Members:

      InitialisationVector As Byte()
    
    Class SendFaxProgress Inherits RestAPIWrapper.ActionProgress

    Represents the progress of a send fax action.

    Members:

    PagesSent As Integer
    Reconnects As Integer
    NegotiatedSettings As RestAPIWrapper.NegotiatedFaxSettings
    
    Class NegotiatedFaxSettings

    Represents the settings negotiated during a fax send or receive.

    Members:

    DataRate As Integer
    Modem As String
    RemoteSubscriberId As String
    
    Class SendFaxResult Inherits RestAPIWrapper.ActionResult

    Represents the result of a send fax action.

    Members:

    Description As String
    SecondsDuration As Double
    PagesSent As Integer
    

    Examples:

    • Send a fax using the defaults:

      actions.Add(New SendFax("myFax.tif"))
      
      Note that ProgressPage and NextPage are not set by default, so no ActionResult is returned.
    • Send a fax and specify a next page to receive the result of the send:

      Dim nextPage As WebPageRequest = New WebPageRequest("MySendFaxNextPage.aspx")
      actions.Add(New SendFax("myFax.tif", nextPage, Nothing))
      

      The send fax result is obtained from the request to the next page:

      Dim sendFaxResult As SendFaxResult = ourRequest.InstanceInfo.ActionResult
      Dim pagesSent As Integer = sendFaxResult.PagesSent
      Dim secondsDuration As Double = sendFaxResult.SecondsDuration
      if sendFaxResult.Description.CompareTo("fax delivered") = 0 Then
          ...
      
    • Send a fax from an encrypted file and specify a next page to receive the result of the send. Supply the cipher to decrypt the fax:

      ' Specify the 256 bit cipher needed to decrypt the file to send
      Dim key As Byte() = {
        &H1F, &H2D, &HEB, &H2E, &H50, &H2A, &H4C, &H8C,
        &HBA, &H58, &HAB, &H50, &H18, &HBD, &H15, &H06,
        &H41, &H9E, &HEA, &H86, &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 decryptionCipher As Cipher = New AesCbcCipher(key, initialisationVector)
      
      Dim nextPage As WebPageRequest = New WebPageRequest("MySendFaxNextPage.aspx")
      
      Dim sendFaxAction As SendFax = New SendFax("myEncryptedFax.tif", nextPage, null)
      sendFaxAction.DecryptionCipher = decryptionCipher
      
      actions.Add(sendFaxAction)
      

      The send fax result is obtained from the request to the next page:

      Dim sendFaxResult As SendFaxResult = ourRequest.InstanceInfo.ActionResult
      Dim pagesSent As Integer = sendFaxResult.PagesSent
      Dim secondsDuration As Double = sendFaxResult.SecondsDuration
      if sendFaxResult.Description.CompareTo("fax delivered") = 0 Then
          ...
      
    • Send a fax specifying a next page and a progress page:

      Dim nextPage As WebPageRequest = New WebPageRequest("MySendFaxNextPage.aspx")
      Dim progressPage As WebPageRequest = New WebPageRequest("MyProgressHandlerPage.aspx")
      actions.Add(New SendFax("myFax.tif", nextPage, progressPage))
      

      The send fax progress is obtained from the request to the progress page:

      Dim sendFaxProgress As SendFaxProgress= ourRequest.InstanceInfo.ActionProgress
      Dim pagesSent As Integer = sendFaxProgress.PagesSent
      Dim reconnects As Integer = sendFaxProgress.Reconnects
      Dim remoteSubscriberId As String = sendFaxProgress.NegotiatedSettings.RemoteSubscriberId
      ...
      

      The send fax result is obtained from the request to the next page:

      Dim sendFaxResult As SendFaxResult = ourRequest.InstanceInfo.ActionResult
      Dim pagesSent As Integer = sendFaxResult.PagesSent
      Dim secondsDuration As Double = sendFaxResult.SecondsDuration
      if sendFaxResult.Description.CompareTo("fax delivered") = 0 Then
          ...
      
  • API Reference:

    class SendFax extends TelephonyAction

    Represents a send fax action.

    Constructors:

    SendFax(String faxToSend);
    SendFax(Uri faxToSend);
    SendFax(String faxToSend, WebPageRequest nextPage, WebPageRequest progressPage);
    SendFax(Uri faxToSend, WebPageRequest nextPage, WebPageRequest progressPage);
    

    Members:

    setDecryptionCipher(Cipher decryptionCipher);
    setNextPage(WebPageRequest nextPage);
    setProgressPage(WebPageRequest progressPage);
    
    class WebPageRequest

    Represents a request to a web page.

    Constructors:

    WebPageRequest(String url);
    WebPageRequest(String url, String method);
    

    Members:

    setMethod(String method);
    
    class Cipher

    Represents a cipher to be used for file encryption/decryption.

    Members:

    String getType();
    
    class AesCbcCipher extends Cipher

    Represents the AES cipher in CBC mode.

    Constructors:

    AesCbcCipher(byte[] key, byte[] initialisationVector);
    

    Members:

    byte[] getInitialisationVector();
    setInitialisationVector(byte[] iv);
    
    class SendFaxProgress extends ActionProgress

    Represents the progress of a send fax action.

    Members:

    int getPagesSent();
    int getReconnects();
    NegotiatedFaxSettings getNegotiatedSettings();
    
    class NegotiatedFaxSettings

    Represents the settings negotiated during a fax send or receive.

    Members:

    int getDataRate();
    String getModem();
    String getRemoteSubscriberId();
    
    class SendFaxResult extends ActionResult

    Represents the result of a send fax action.

    Members:

    String getDescription();
    double getSecondsDuration();
    int getPagesSent();
    

    Examples:

    • Send a fax using the defaults:

      actions.add(new SendFax("myFax.tif"));
      
      Note that ProgressPage and NextPage are not set by default, so no ActionResult is returned.
    • Send a fax and specify a next page to receive the result of the send:

      WebPageRequest nextPage = new WebPageRequest("MySendFaxNextPage");
      actions.add(new SendFax("myFax.tif", nextPage, null));

      The send fax result is obtained from the request to the next page:

      public void doGet(HttpServletRequest request, HttpServletResponse response) 
      {
        TelephonyRequest ourRequest = new TelephonyRequest(request);
        SendFaxResult sendFaxResult = (SendFaxResult)ourRequest.getInstanceInfo().getActionResult();
        int pagesSent = sendFaxResult.getPagesSent();
        double secondsDuration = sendFaxResult.getSecondsDuration();
        if (sendFaxResult.getDescription().CompareTo("fax delivered") == 0)
        {
          ...
      }
      
    • Send a fax from an encrypted file and specify a next page to receive the result of the send. Supply the cipher to decrypt the fax:

      // Specify the 256 bit cipher needed to decrypt the file to send
      byte[] key = new byte[] {
        0x1F, 0x2D, 0xEB, 0x2E, 0x50, 0x2A, 0x4C, 0x8C,
        0xBA, 0x58, 0xAB, 0x50, 0x18, 0xBD, 0x15, 0x06,
        0x41, 0x9E, 0xEA, 0x86, 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 };
      
      Cipher decryptionCipher = new AesCbcCipher(key, initialisationVector);
      
      WebPageRequest nextPage = new WebPageRequest("MySendFaxNextPage");
      
      SendFax sendFaxAction = new SendFax("myEncryptedFax.tif", nextPage, null);
      sendFaxAction.DecryptionCipher = decryptionCipher;
      
      actions.Add(sendFaxAction);
      

      The send fax result is obtained from the request to the next page:

      public void doGet(HttpServletRequest request, HttpServletResponse response) 
      {
        TelephonyRequest ourRequest = new TelephonyRequest(request);
        SendFaxResult sendFaxResult = (SendFaxResult)ourRequest.getInstanceInfo().getActionResult();
        int pagesSent = sendFaxResult.getPagesSent();
        double secondsDuration = sendFaxResult.getSecondsDuration();
        if (sendFaxResult.getDescription().CompareTo("fax delivered") == 0)
        {
          ...
      }
      
    • Send a fax specifying a next page and a progress page:

      WebPageRequest nextPage = new WebPageRequest("MySendFaxNextPage");
      WebPageRequest progressPage = new WebPageRequest("MyProgressHandlerPage");
      actions.add(new SendFax("myFax.tif", nextPage, progressPage));
      

      The send fax progress is obtained from the request to the progress page:

      public void doGet(HttpServletRequest request, HttpServletResponse response) 
      {
        TelephonyRequest ourRequest = new TelephonyRequest(request);
        SendFaxProgress sendFaxProgress = (SendFaxProgress)ourRequest.getInstanceInfo().getActionProgress();
        int pagesSent = sendFaxProgress.getPagesSent();
        int reconnects = sendFaxProgress.getReconnects();
        String remoteSubscriberId = sendFaxProgress.getNegotiatedSettings().getRemoteSubscriberId();
        ...
      }
      

      The send fax result is obtained from the request to the next page:

      public void doGet(HttpServletRequest request, HttpServletResponse response) 
      {
        TelephonyRequest ourRequest = new TelephonyRequest(request);
        SendFaxResult sendFaxResult = (SendFaxResult)ourRequest.getInstanceInfo().getActionResult();
        int pagesSent = sendFaxResult.getPagesSent();
        double secondsDuration = sendFaxResult.getSecondsDuration();
        if (sendFaxResult.getDescription().CompareTo("fax delivered") == 0)
        {
          ...
      }
      
  • API Reference:

    class SendFax

    Represents a send fax action.

    Constructors:

    SendFax(fax_to_send, 
            progress_page=None, # A WebPage object, see Redirect() for details
            next_page=None,     # A WebPage object, see Redirect() for details
            decryption_cipher=None)
    

    Members:

    def set_fax_to_send(fax_to_send) # File or URL
    def set_next_page(next_page)     # A WebPage object
    def set_progress_page(next_page) # A WebPage object
    def set_decryption_cipher(decryption_cipher)
    

    Examples:

    • Send a fax using the default parameters:

      from aculab.telephony_rest_api import Actions, SendFax
      
      my_actions = Actions('Usage example 1: Send fax.')
      my_actions.add(SendFax(fax_to_send='my_fax.tif'))
      
      response_body = my_actions.get_json()
      
    • Send a remote fax using the default parameters:

      from aculab.telephony_rest_api import Actions, SendFax
      
      my_actions = Actions('Usage example 1: Send fax.')
      my_actions.add(SendFax(fax_to_send=WebPage(url='http://Badger.set.com:80/my_tif_page?filename=my_fax.tif&version=1')))
      
      response_body = my_actions.get_json()
      
    • Send a fax and specify the progress page:

      from aculab.telephony_rest_api import Actions, SendFax, WebPage
      
      my_actions = Actions('Usage example 2: Send fax.')
      my_actions.add(SendFax(fax_to_send='my_fax.tif',
                             progress_page=WebPage(url='fax_progress_page', method='POST')))
      
      response_body = my_actions.get_json()
      
    • Send a fax and specify the progress page. Also specify a cipher to decrypt the fax before sending:

      from aculab.telephony_rest_api import Actions, SendFax, WebPage, AESCBCCipher
      
      my_actions = Actions('Usage example 3: Send fax.')
      my_cipher = AESCBCCipher(key='407e4cc1a732cb2ac1b84395488f3322404e414ffeba8a8d692c034d608d9cc8', 
                               initialisation_vector='3bfd048ecaad5515f1ca7b9b58302c04')
      my_actions.add(SendFax(fax_to_send='my_fax.tif',
                             progress_page=WebPage(url='fax_progress_page', method='POST'),
                             decryption_cipher=my_cipher))
      
      response_body = my_actions.get_json()
      
    • Send a fax, specify the progress page and the next page:

      from aculab.telephony_rest_api import Actions, SendFax, WebPage
      
      my_actions = Actions('Usage example 4: Send fax.')
      my_actions.add(SendFax(fax_to_send='my_fax.tif',
                             progress_page=WebPage(url='fax_progress_page', method='POST'),
                             next_page=WebPage(url='send_fax_complete', method='POST')))
      
      response_body = my_actions.get_json()
      
  • API Reference:

    The SendFax class

    Introduction

    Represents a send fax action.

    Class synopsis

    class SendFax extends ActionBase {
    
        /* methods */
        public __construct()
        public void setTiffFile(string $fax_to_send, Cipher $cipher = null)
        public void setTiffUrl(string $fax_to_send, string $method = null)
        public void setProgressPage(string $progress_page, string $method = null)
        public void setNextPage(string $next_page, string $method = null)
    }
    
    The SendFaxResult class

    Introduction

    Represents the result of a send fax action.

    Class synopsis

    class SendFaxResult extends ActionResult {
    
        /* Methods */
        public string getFaxResult()
        public int getNumberPagesSent()
        public float getSecondsFaxDuration()
        
        /* inherited methods */
        public string getAction()
        public boolean getInterrupted()
    }
    
    The SendFaxProgress class

    Introduction

    Represents the progress information of a send fax action.

    Class synopsis

    class SendFaxProgress extends ActionProgress {
    
        /* Methods */
        public int getPagesSent()
        public int getCallCount()
        public NegotiatedFaxSettings getNegotiatedFaxSettings()
        
        /* inherited methods */
        public string getAction()
    }
    
    The NegotiatedFaxSettings class

    Introduction

    Represents the negotiated fax settings.

    Class synopsis

    class NegotiatedFaxSettings {
    
        /* Methods */
        public int getDataRate()
        public string getModem()
        public string getRemoteSubscriberId()
    }
    

    The Cipher class

    Introduction

    An abstract class to represent ciphers.

    Class synopsis

    abstract class Cipher {
    
        /* methods */
        public __construct(string $type)
    }
    
    The AesCbcCipher class

    Introduction

    A class to represent a cipher using AES in CBC mode.

    Class synopsis


    $key and $initialisation_vector are strings of hexadecimal bytes.
    class AesCbcCipher extends Cipher{
    
        /* methods */
        public __construct(string $key, string $initialisation_vector)
    }
    

    Examples:

    • Send a fax using the defaults:

      $r = new Aculab\TelephonyRestAPI\SendFax();
      $r->setTiffFile('my_fax.tif');
      $actions->add($r);
      
    • Send a remote fax using the defaults:

      $r = new Aculab\TelephonyRestAPI\SendFax();
      $r->setTiffUrl('http://Badger.set.com:80/my_tif_page?filename=my_fax.tif&version=1');
      $actions->add($r);
      
    • Send a fax and specify a next page to receive the result of the send:

      $r = new Aculab\TelephonyRestAPI\SendFax();
      $r->setTiffFile('my_fax.tif');
      $r->setNextPage('my_fax_handler_page');
      $actions->add($r);
      

      Get the number of pages sent from the action's next page request:

      $info = InstanceInfo::getInstanceInfo();
      $sendFaxResult = $info->getActionResult();
      $numberPagesSent = $sendFaxResult->getNumberPagesSent();
      
    • Send a fax from an encrypted file and specify a next page to receive the result of the send. Supply the cipher to decrypt the fax:

      $cipher = new Aculab\TelephonyRestAPI\AesCbcCipher(
          "1F2DEB2E502A4C8CBA58AB5018BD1506419EEA86DF595D3A431F43FAF57534C9",
          "9B85FAED9AB17570D5A82A31F846443B"
      );
      
      $sf = new Aculab\TelephonyRestAPI\SendFax();
      $sf->setTiffFile('my_encrypted_fax.tif', $cipher);
      $sf->setNextPage('my_fax_handler_page');
      $actions->add($sf);
      

      Get the number of pages sent from the action's next page request:

      $info = InstanceInfo::getInstanceInfo();
      $sendFaxResult = $info->getActionResult();
      $numberPagesSent = $sendFaxResult->getNumberPagesSent();
      
    • Send a fax, specify a progress page and the next page:

      $r = new Aculab\TelephonyRestAPI\SendFax();
      $r->setTiffFile('my_fax.tif');
      $r->setProgressPage('my_progress_handler_page');
      $r->setNextPage('my_fax_handler_page');
      $actions->add($r);
      

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

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

      Get the number of pages sent from the action's next page request:

      $info = InstanceInfo::getInstanceInfo();
      $sendFaxResult = $info->getActionResult();
      $numberPagesSent = $sendFaxResult->getNumberPagesSent();