Push Notifications

The EtherFax.Client (3.0.14 and later) now provides real-time push notifications to etherFAX developers. Instead of periodically polling for fax status or if new fax has arrived, the EtherFax.Client interface now provides event handlers that will signal the application when a changed or new condition exists.

To start the push notification services, set the FaxStatusEvent and FaxReceiveEvent handlers and invoke the StartPushListener method. Similarly, when the EtherFaxClient is no longer in use, the application should stop listening for push notifications by invoking the StopPushListener method.

📘

Network Communications

When using Push Notifications, the EtherFaxClient will subscribe to the etherFAX services using a very lightweight TCP socket secured using TLS. This connection consumes little resources and is established outbound over port 443.

Though push notifications are extremely reliable, it is good practice for applications to build periodic outbound/inbound status checking in the event an event is missed due to poor internet communications, etc.

// create client with api-key
var client = new EtherFaxClient("api_key...");

// start push notifications
client.FaxStatusEvent += OnFaxStatusEvent;
client.FaxReceiveEvent += OnFaxReceiveEvent;
client.StartPushListener();

//
// Send faxes, perform other work, etc.
//

// stop push notifications
client.StopPushListener();

Example Receive Handler

In this example, the OnFaxReceiveEvent function is called whenever a new fax document arrives that is associated with the credentials provided. The sender object contains the originating EtherFaxClient instance that may be used to perform other functions (such as mark the fax as received in this example).

private void OnFaxReceiveEvent(object sender, FaxReceiveEventArgs e)
{
    var client = sender as EtherFaxClient;
  
    // save fax, etc.
  
    // mark received
    client.SetFaxReceived(e.Receive.JobId);
}

Example Status Handler

In this example, the fax status activity is simply logged. Applications should observe the FaxResult value to determine if the fax transmission has completed.

private void OnFaxStatusEvent(object sender, FaxStatusEventArgs e)
{
    // let's display some JSON!
    Console.WriteLine("Status: " + JsonConvert.SerializeObject(e.Status) + "\n");

    if (e.Status.FaxResult != FaxResult.InProgress)
    {
      // fax completed
      // ...
    }
}