How to: Getting started with FaxTools

,

WestFax is proud to present FaxTools.

Requirements: Windows 7,8,10, Server
Disk Space: At least 50mb t0 install tools
Account: Any active WestFax Fax to Email Account may use this feature.

(You may need your network admin to set this up if you are in a managed environment)

What is FaxTools?

AutoPrint: Anytime a fax comes in to your fax line it will print the fax automatically to a selected printer.
FaxDrive: Automatically download all incoming faxes to a local or network drive. We also have a secondary backup location to ensure you have redundancy.


Here is how to set this tool up:

  1. You may need you IT administrator to install this. Please coordinate with your IT team before using this tool.
  2. Download the FaxTools application and save it to your computer.
  3. Unzip the files to any directory and click setup.exe to start the installer.
  4. Choose a location to install the faxtools. Make sure you have at least 5omb of space available.
  5. After setup completes the application will launch.Note: You may get the “Microsoft Defender Blue box Alert” on install.
    Just click “More Info” and select “Run Anyway“. 

Let’s get started.

This is the home screen. You will be prompted to login using your WestFax Fax to Email credentials. If you have forgotten them click here to reset them.

After logging in you will see a popup that asks you to select the fax line you want to manage. If you only have one fax line just click continue. Otherwise, if you have more than one pick the line you want to start with. You can toggle fax lines anytime inside the application.

Now you are shown the landing page. This is where you will configure your AutoPrint and FaxDrive. Let’s start first with the AutoPrint. The first thing you need to have is a printer available on your computer. It can be a network printer or a local printer but you must have at least one printer installed.

Just select the printer you want to automatically print faxes and click the Enable button. That’s it! You are done! Any fax coming in after you click enable will be printed automatically. Want to check on your printer status? Just click “View Print Queue” and you can see what’s in the queue. Sometimes print jobs may be stuck because of paper jam or no paper. This is where you can see what’s printing.

Let’s setup the FaxDrive now. The first thing to select is the File Format. PDF or TIFF. If you aren’t sure just choose PDF. Next, choose a primary location for the faxes to be saved. Make sure you have plenty of space if you have a lot of faxes. Most faxes average 20-150kb in size but it really depends on how many pages you are receiving. You can also select a secondary location in case you need to have a redundant file store. This ensures your faxes are secure in case your computer crashes and you need a backup location. You don’t have to set a secondary location but we offer it just in case.

Once you have the location set click the Enable Toggle. The faxes will start downloading in the background automatically. You can click the “View” button to see the folder and watch them download.

 

You can also click a checkbox that says “Delete Remote after download”. This is for customers that do not want faxes to remain on the fax server for HIPAA reasons or security reasons. This option will mark a fax as deleted and as soon as it downloads it will be removed. Caution: If you select this option faxes will be removed from the inbox on your home.westfax.com portal.

The last option “Resync” is useful if you need to start the sync process over because you changed the backup location.

Let’s talk about the settings page. We offer the ability to set a lockscreen. This prevents anyone from viewing your fax settings unintentionally. Just click the Gear Icon on the top right. Then you can choose to enable the Lock screen by clicking “Lock App screen after” and then choose how long you want to wait before the lock screen kicks in. Then set a pin code (numeric only).

You’ll see the lock screen after the set timeout and  it will prompt you to enter your pin to unlock the interface.

That’s it! You are setup. If you close the window it will still be in your tray. Just click it and it will relaunch the control panel.

If that’s all you need to do you are good.

Advanced users read on:

If you have multiple fax numbers you can select additional fax lines under the product drop down. This will allow you to setup AutoPrint and FaxDrive for several fax lines at the same time so you can manage multiple fax lines independently.

Just toggle the fax lines to change or verify settings.


HIPAA Compliance and FaxDrive

Extra care must be taken when handling PHI. We’ve talked about Fax and HIPAA compliance before and it’s important that your organization takes HIPAA guidelines into account. If you are printing faxes using AutoPrint that contain PHI then be sure the printer is in a secure location where the public doesn’t have access. Think of your printer as a physical fax machine and treat it accordingly.

With FaxDrive you should be sure that the fax documents are being saved in a location that is secure, encrypted and not available to anyone who shouldn’t have access to PHI. Saving files to network shares is fine as long as your network is secure and proper permissions are in place.

Four ways to send a fax

,

Most people aren’t aware of it, but the humble fax continues to play a significant role in business, healthcare, and government institutions.  Today’s fax technology has matured considerably, though. Users can send and receive documents securely, from a desktop computer or mobile phone; and they can access document history and confirmations through a secure online portal.

Banks, healthcare providers needing HIPAA compliance, and government offices continue to use fax routinely. Nearly every member of Congress has an inbound fax number so that constituents can send them messages. A foundational rule of marketing says that you should make it easy for customers to communicate with you; so it only makes sense to add electronic fax to your business communication toolbox.

Let’s look at a few of the ways WestFax makes the process simple and painless.

Web Portal

The WestFax web portal allows you to send virtually any document or image file as a fax. Step one is to log onto your dashboard at WestFax.com, then enter the recipient’s fax number.  If you want to send the same fax to several people at the same time, it’s as simple as adding a few additional fax numbers to the list.  Then browse to a PDF, word processing document, or image file such as a JPG, TIF, or PNG. Type in some optional header information (similar to the subject line of an e-mail), and click the “Send Fax” button.  It’s that simple.

Fax to Email

With fax to e-mail, you don’t even need to be signed in to the web portal. Sending a fax is as simple as attaching a document or image file to an e-mail, and addressing that e-mail using the phone number that the recipient has provided to you. To send a fax to (888) 555-1212, for example, simply send the document as an attachment to 8885551212@westfax.com.  WestFax will automatically identify it as a fax from your account (based on the e-mail address that you are using to send it), and it will be sent as an outbound fax from your account.

Print To Fax

A third method is to print directly to fax.  WestFax provides a print driver for Windows that installs in less than a minute. When you print a document, the WestFax print driver shows up as another printer available to your computer.  Simply choose WestFax as your printer, add a phone number, and click “Send Fax”.

Using the WestFax API

For software developers, or for companies using customizable enterprise applications, WestFax provides an application programming interface (API).  Using the API, a software developer can add some simple, straightforward code that will enable fax functionality to be embedded directly into the software you use every day.

Imagine, for example, that you use a customizable software package to send customer invoices and track receivables. Some of your largest customers routinely call to ask for a monthly statement via fax. By adding a “Fax Statement” button to the customer screen, you can reduce the process of faxing a statement to a single mouse-click.  With a small amount of programming, a developer can retrieve a fax number from the customer record, run a customer statement report, and pass it to the WestFax API. The API does the rest, sending the document along using secure electronic fax technology and delivering it to your customer.

WestFax Even Manages Your Paper Trail

One of the nice benefits of using WestFax is that you have a permanent record of all of your inbound and outbound faxes, easily accessible through the web portal. If a recipient claims that they never received your fax, you can easily go back to the portal and verify that date and time that it was sent, and confirm that it was received.  Inbound faxes, too, are available to view, print, and download.  You can forward a fax that you have sent or received, or even e-mail a PDF.

If you are currently using a multifunction machine with a shared phone line, you’re missing an opportunity to operate more efficiently. There are very good reasons why cloud fax technology continues to be widely used. WestFax makes the process painless.

 

ANI and CSID Decoded and why it’s important.

,

The ANI is Automatic Number Identification. It is used by the phone carriers to determine the originating fax or telephone number for any call. ANI is different, conceptually and technically, from caller ID service. A caller’s telephone number and line type are captured by ANI service even if caller ID blocking is activated.

When you set your ANI in an API call please set the number to your fax number with no spaces or punctuation.

Example: 3335551212

If you set it to an invalid number, the receiver may block it as invalid or spam. If you are testing your API, and you can’t get the receiving fax line to accept the call, it could be because their carrier is blocking invalid ANI.

CSID is Called Subscriber Identification (abbreviated CSID), and is a fax number that identifies the specific fax machine sending the fax. A CSID is not required in all cases, but it is a good practice to set so that your fax machine will not get blocked for being spam or unknown.

In some cases, one would want to set the CSID to another number if you want to have the receiver send responses to another number. Think of it as a REPLY TO field on email.  If one has many outbound fax lines, but one wants people to fax back to a specific return fax number, one could set the CSID to the primary inbound line so it appears the fax came from that number.

CSID is a string that identifies a sending fax machine.  This data is transmitted as part of the fax protocol when the fax transmission is negotiated.  This identifier can contain numbers, letters and punctuation.  Often it will contain the sending fax number along with a company name.  “Acme Inc.  (303) 555-1212” for instance.  Again this is part of the fax protocol and is completely separate from ANI.

In summary, when sending faxes with the API it is important to set these values correctly and not just mash numbers in or use placeholders. Many failed test faxes fail because of invalid ANIs.

Cloud Fax API use case by example

We’ve seen every use-case one could imagine. With each new customer we learn new ways to use the API. Below are several of the very common use-cases we see all the time and the API calls involved with each. We’ll use pseudo-code in our examples to describe workflow.


Outbound heavy

In this use-case the user sends large numbers of outbound faxes with no need for inbound. For each fax they need to reconcile delivery. If something fails they need to determine the reason why and act accordingly. (Number of API Calls: 2)

  1. Get faxes ready for send:
    -Generate Content to be faxed (PDF,DOC, HTML, etc…)
    -Generate the API Requests with the Outbound CallbackUrl set (learn more)
  2. Fax send loop:
    -Send requests in a Loop (API Call: Fax_SendFax)
  3. Wait for Callback:
    -Callback fires and we read the fax identifier from the callback request.
    -Get status using: (API Call: Fax_GetFaxDescriptionsUsingIds) using the fax identifier
    –[Ok] -> Write to database and mark as complete.
    –[Failed] -> Write to database for later review or retry.

Inbound heavy

In this use-case the user receives large numbers of inbound faxes with no need for outbound. They use the inbound webhook to receive notification of new inbound fax. For each fax they receive they will save the fax to a network drive and send an internal email to their users. (Number of API calls: 2)

  1. Webhook call received with fax identifier.
  2. Get inbound fax information and file.
    -Get information about the fax: (API Call: Fax_GetFaxDocuments) using fax identifier.
  3. Save fax file
    -Decode file using any BASE64 Decode function and save as the selected filetype.
    -Save file to network location
    -Mark fax as “retrieved”: (API Call: Fax_ChangeFaxFilterValue)
  4. Notify users of new fax arriving using internal email

 

How-to: Multiple numbers and files in a Fax_SendFax Call

This article assumes you:

  1. Have an API developer account.
  2. Know how to send a fax using Fax_SendFax.

By the end of this how-to you will know how to:

  1. Send a fax with multiple fax documents.
  2. Send a fax with multiple recipients.

Let’s examine the vanilla fax job below and in the next example block we’ll add additional numbers and pages.

This is a javascript example but you’ll be able to adapt the changes to your code once you understand what we are doing.

 

var data = new FormData();
data.append("Username", "test@test.com");
data.append("Password", "test9999");
data.append("Cookies", "false");
data.append("ProductId", "00000000-0000-0000-0000-0000000000");
data.append("JobName", "Test Job");
data.append("Header", "Test Header");
data.append("BillingCode", "Customer Code 1234");
data.append("Numbers0", "99922233333");
data.append("Files0", fileInput.files[0], "TEST FAX.doc");
 data.append("CSID", "5554442222");
data.append("ANI", "5554442222");
data.append("StartDate", "1/1/2019");
data.append("FaxQuality", "Fine");
data.append("FeedbackEmail", "test@test.com");

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api2.westfax.com/REST/Fax_SendFax/json");
xhr.setRequestHeader("ContentType", "multipart/form-data");

xhr.send(data);

Above you can see the Number0 and the Files0 field. This is a single document fax going to one number which is probably a vast majority of the jobs you’ll submit. In some cases though you will want to send multiple document or send to many fax numbers.

To add additional numbers all one has to do is add more Numbers fields. The same thing in regards to Files field. You can add additional files by iterating the values:

 

var data = new FormData(); 
data.append("Username", "test@test.com"); 
data.append("Password", "test9999"); 
data.append("Cookies", "false"); 
data.append("ProductId", "00000000-0000-0000-0000-0000000000"); 
data.append("JobName", "Test Job"); 
data.append("Header", "Test Header"); 
data.append("BillingCode", "Customer Code 1234"); 
data.append("Numbers0", "9992223333"); 
data.append("Numbers1", "3335556666"); 
data.append("Numbers2", "8881114333"); 
data.append("Files0", fileInput.files[0], "CoverPage.doc"); 
data.append("Files1", fileInput.files[1], "TEST FAX.doc"); 
data.append("CSID", "5554442222"); data.append("ANI", "5554442222"); 
data.append("StartDate", "1/1/2019"); 
data.append("FaxQuality", "Fine"); data.append("FeedbackEmail", "test@test.com"); 

var xhr = new XMLHttpRequest(); 
xhr.withCredentials = true; 
xhr.addEventListener("readystatechange", function() { if(this.readyState === 4) { console.log(this.responseText); } }); 

xhr.open("POST", "https://api2.westfax.com/REST/Fax_SendFax/json"); 
xhr.setRequestHeader("ContentType", "multipart/form-data"); 
xhr.send(data);

The documents will be merged from lowest to highest (Files0 first and then Files1). In this case the cover page will be the first document and the next document is the main page. The fax will be sent to all the numbers in the Numbers[0…3] fields.

Additional notes:

Having multiple numbers can increase the length of the fax send process. If we dial 4 numbers and one of them is busy we will retry the number based on the dialing strategies we employ. A webhook callback may be delayed in this case. We will return the webhook after all calls are done. At that point you will want to query Fax_GetFaxDescriptions or Fax_GetFaxIdentifiers to get the status of the job and each individual call.

If you have any questions please reach out to develop@westfax.com or call us at 303-299-9329.

How-to: Call Status and Job Status in the API Primer

This article assumes you:

  1. Have an API developer account.
  2. Sent a Fax via the API.

After we send the fax we are going to query the API for the status.

Here is a PHP Curl request to the Fax_GetFaxDescriptionsUsingIds API function. We are passing in the standard account information as well as a nested array of the FaxIds1 field which is the job id we got back from our Fax_SendFax call.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api2.westfax.com/REST/Fax_GetFaxDescriptionsUsingIds/json",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => array('Username' => 'test@test.com','Password' => 'fakepass','Cookies' => 'false',
  'ProductId' => '00000000-0000-0000-0000-000000000',
  'FaxIds1' => '{"Id":"111111-1111-1111-1111-111111111111","Direction":"Outbound"}'),
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/x-www-form-urlencoded"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

 

Here is the result. Notice the output is broken down into two calls in the FaxCallInfoList. You have the Individual CallId for each call in the job and the individual status. Here it is Waiting to dial. This means we just received the fax and it’s in the pre-processing phase where it is converted to TIFF and being prepared for faxing. Also, note the Id field on the main Result object. That is the JobID and the Status is currently Submitted.

{
    "Success": true,
    "Result": [
        {
            "FaxCallInfoList": [
                {
                    "CallId": "00000000-0000-0000-0000-11111",
                    "CompletedUTC": "2020-02-24T17:02:45Z",
                    "TermNumber": "1112223333",
                    "OrigNumber": "2223334444",
                    "OrigCSID": "2223334444",
                    "Result": "Waiting to dial"
                },
                {
                    "CallId": "00000000-0000-0000-0000-22222",
                    "CompletedUTC": "2020-02-24T17:02:45Z",
                    "TermNumber": "5556667777",
                    "OrigNumber": "2223334444",
                    "OrigCSID": "2223334444",
                    "Result": "Waiting to dial"
                }
            ],
            "Id": "1111111-1111-1111-1111-111111111",
            "Date": "2020-02-24T17:02:45Z",
            "Direction": "Outbound",
            "Tag": "Retrieved",
            "PageCount": 1,
            "FaxQuality": "Normal",
            "Status": "Submitted",
            "Reference": "Test Job 1",
            "JobName": "Test Job"
        }
    ]
}

Now that some time has passed let’s run the call again. This result below is the same job but it is now Complete. You will see one of the jobs is marked as “Sent” and the other one is “Failed” and the overall job has the Status of “Complete“. You need to look at the Result of the FaxCallInfoList to determine the true status of a fax job. Complete just means that we are done with this fax. It does not mean success. You will want to either resend the fax to the failed call or handle it manually by figuring out what is wrong with the number and updating it. 

 

{
    "Success": true,
    "Result": [
        {
            "FaxCallInfoList": [
                {
                    "CallId": "00000000-0000-0000-0000-11111",
                    "CompletedUTC": "2020-02-24T17:04:55Z",
                    "TermNumber": "1112223333",
                    "OrigNumber": "2223334444",
                    "TermCSID": "(222) 333-4444",
                    "OrigCSID": "2223334444,
                    "Result": "Sent"
                },
                {
                    "CallId": "00000000-0000-0000-0000-22222",
                    "CompletedUTC": "2020-02-24T17:04:52Z",
                    "TermNumber": "5556667777",
                    "OrigNumber": "2223334444",
                    "TermCSID": "(222) 333-4444",
                    "OrigCSID": "2223334444",
                    "Result": "Failed"
                }
            ],
            "Id": "1111111-1111-1111-1111-111111111",
            "Date": "2020-02-24T17:05:28Z",
            "Direction": "Outbound",
            "Tag": "Retrieved",
            "PageCount": 1,
            "FaxQuality": "Normal",
            "Status": "Complete",
            "Reference": "Test Job 1",
            "JobName": "Test Job"
        }
    ]
}

In summary:

The job Status is representative of whether we are still processing a fax job. The individual Result code on the FaxCallInfoList is the authoritative location for the status. Complete means that we are done and will not work on the calls anymore and it is final.

This confuses some using the API and usually results in 2 kinds of mistakes:

  • The developer sends multiple calls per job, and does not realize that there is a job Result, AND a call Status. The developer interprets the job Status as the final result, and therefore does not get the real result of the job.
  • The developer ignores the job result and uses the call result that is retrieved and assumes that the result is the final result. Unless the job Status is marked as Complete we are still processing the calls. One should wait for Status = Complete before you read the individual Result.

WestFax can also customize your retry strategy. We typically retry 5 times before failing. If you wish to have us only try once and then fail let us know and we can adjust your retry settings.

 

All possible values of the Call Result (Bold are common Result codes)

Sent, //Fax was sent
Waiting to dial, //We are preparing the fax.
Dialing, // We are dialing the number.
Busy, //The line is busy
NoAnswer,
NoFaxDevice,
Cancelled,
Failed, //We retried several times and it never sent.
InvalidNumber // Bad number i.e. 22930-3940-399430A

All possible values of Job Status (Some you will never see. Bold are common Status codes):

Complete,  //Job is done. Check call Result for individual fax status.
Submitted, //This means it’s still processing.
Production,
UnSubmitted,
UnAssigned,
Failed, //None of the calls went through. See Call Result for status.
Cancelled,
Paused

 

How to port your hard line fax number to digital cloud fax

You keep meaning to do it, but it seems like a hassle. Yes, getting rid of the old fax machine.

You are paying for a dedicated phone line, fax machine upkeep and the paper and ink supplies. Plus dealing with having to resend when the receiving machine is busy or missing faxes because your machine is busy.

There is no better time to go to Digital Cloud Fax.

But you want to keep your fax number, and the process (you think) is a pain. Just know that it isn’t hard at all and here is how to do it quickly and easily.

Pre-requisites:

  1. You must be current with your phone / fax line provider.
  2. You must have a copy of the latest bill handy.

The first thing you want to do is sign up for online fax. WestFax offers a basic fax plan for $8.99 a month with a 10-day free trial. So, go ahead and sign up.

You will pick a new fax number but let’s not get hung up on that. We will port your number next so that new number you pick will just be a placeholder.

Now, let’s test if your number is portable. Some providers make it difficult to port out your number. Using our quick check tool allows you to get an instant answer. Click here to check your fax number’s portability.

Ok, Let’s assume it’s portable. Now all you need to do is fill out the  porting form.

Once we get your form, we’ll begin porting your number. You can still use the new number you just signed up with to test it but once the port is complete, you will get all your hard faxes in digital PDF format delivered to your inbox. No more paper jams, paper expense or missed faxes. No more busy signals.

Porting is not as hard are you might think. You just need to have your billing information handy and fill out a basic form. It’s easy and it will save you hundreds of dollars in telephone line costs a year.

So cut the cord and sign up with digital fax today!

API Parameters and Return values [decoded]

Unless you are deep diving into the SDK you may miss some of the enum values that are useful for implementing the API. What are Enums? Basically they are a list of values that can be used as an input value for a web service or they are presented as output values. If you need to trap a particular output or status these values are key for proper error trapping and flow in your application.

We’ll look at the most frequently used API calls and break down the values allowed and returned. Is there another API call you want documentation for or need to know more? Let us know.

Note: We aren’t showing all the input and output parameters. Just the ones that have set values that must be set or can be counted on as a set return value.

 

Webservice Call

Input Parameters

Output Values

Fax_SendFax

FaxQuality:
Fine or Normal
Success: true or false
Result: 0000000-0000-0000-0000 {JobId} or
if failed it will return an ErrorString and InfoString which will have detailed failure information.

Fax_GetFaxDescriptionsUsingIds

FaxIds1..3

Use a json object for this:
{
"Id": "28887ac4-424d-4164-9def-ca5e926342d8",
"Direction": "Outbound"
}


Include the jobId and the Direction which can be Inbound or Outbound
Success: true or false
Result: Returns a json object:

{
"Success": true,
"Result": [
{
"FaxCallInfoList": [
{
"CallId": "00000-00000-000000-0000",
"CompletedUTC": "2019-12-05T15:11:06Z",
"TermNumber": "000000000",
"OrigNumber": "2225551212",
"OrigCSID": "(222) 555-1212",
"Result": "NoAnswer"
}
],
"Id": "00000-00000-000000-0000",
"Date": "2019-12-05T15:11:33Z",
"Direction": "Outbound",
"Tag": "Retrieved",
"PageCount": 1,
"FaxQuality": "Normal",
"Status": "Complete"
}
]
}

Result can be:

{
Success,
Dialing,
Removed,
BadNumber,
Busy,
NoAnswer,
NoFaxDevice,
Cancelled,
Failed,
InvalidNumber,
Unknown
}

Fax_GetFaxIdentifiers

FaxDirection:
Inbound or Outbound
"Success": true,
"Result": [
{
"Id": "000000-00000-00000-000000",
"Direction": "Inbound",
"Date": "2020-01-23T21:24:50Z",
"Tag": "None"
},{
"Id": "000000-00000-00000-000000",
"Direction": "Inbound",
"Date": "2020-01-23T21:24:50Z",
"Tag": "None"
}
]

Fax_GetFaxDocuments

FaxIds1..3

Use a json object for this:
{
"Id": "28887ac4-424d-4164-9def-ca5e926342d8",
"Direction": "Outbound"
}


Include the jobId and the Direction which can be Inbound or Outbound

{"Success":true,"Result":
[
{
"FaxFiles":[
{"ContentType":"application/pdf",
"ContentLength":35586,
"FileContents":"JVBERi0xLjINCgolJUVPRg0K..."}],
"Id":"0000000-0000-0000-0000000000",
"Direction":"Inbound",
"Date":"2020-01-23T21:24:50Z",
"Status":"Ok",
"Format":"pdf",
"PageCount":1
}
]
}
}
]
}

FaxDirection:
Inbound or Outbound

Fax_ChangeFaxFilterValue

FaxIds1..3

Must be in json:
{
"Id": "0000000-00000-000000-000000000"
}


Filter is what we are changing the specified fax status to:
None (reset - marked as unread),
Retrieved (Marked as Read),
Removed (Deleted)
{
"Success": true,
"Result": true
}

Fax_GetProductsWithInboundFaxes

Filter:
None,
Retrieved,
Removed.

 

 

:

 

WestFax API HowTo: Checking for new inbound faxes with new function.

,

Here is what we are going to do:

  1. Check for new faxes using a new api call: Fax_GetProductsWithInboundFaxes
  2. Get a collection of inbound faxes for us to process.

Here is what you need:

  1. We will assume you are using a relatively modern development framework. PHP, React, .Net, etc…
  2. We recommend you use a tool like Postman (Free and available on all platforms) to test your API’s and generate the code or you can run in a sandbox at SwaggerHub.
  3. Developer API account. Easy to sign up and get started immediately.
  4. If you haven’t implemented the API before you may want to check out our quickstart how-to articles here and here.

What is this useful for:

This is useful if you have multiple inbound fax lines and you need to check them for new inbound faxes. Just calling this one procedure will alert you to new inbound faxes and you can then go and retrieve the metadata about the new faxes. If nothing is new you don’t have to make a call for each productID which saves server time and resources.

 

Phase 1: Let’s check our Fax number for new faxes.

In this case I have sent myself a test fax before I run this proc.

I am going to fire up SwaggerHub and use the Tryout function to call the procedure and get data back.

The procedure is called Fax_GetProductsWithInboundFaxes. You can see it’s spec here.
Description of the Postman call.
We are going to call the proc using the Try Out feature.

 

  1. We’ll be asked to enter the Username and Password for our WestFax API Call. Notice we are not specifying a prodid as this procedure works across all fax lines and will return a collection of fax lines if the filter field matches.
  2. Let’s talk about the filter field. If you leave it blank it will assume Unread flag. You can set it to None, Recieved & Removed. None or <blank> will show you Fax numbers that have unread faxes. Recieved will show you fax lines that have read faxes and removed will show you faxes that have deleted faxes. These are unlikely use-cases but here nevertheless.
  3. So here is the call:
    Description of the Postman call.
  4. When I execute it I get back:
    Response of a postman call
  5. You can see that it returns a ID record as well as the InboundNumber so you can now go call the Fax_GetFaxDescriptions or  Fax_GetInboundFaxDescriptions. Set your FaxDirection as Inbound and you can now update your app with the new incoming faxes.

Success! As you can see it’s not hard at all to add Faxing to your Enterprise application. If you have questions or need more help please reach out to us at 800-473-6208 or contact us via email.

 

WestFax API HowTo: How to handle inbound faxes and callbacks.

,

In this how-to we are going to talk about different implementations of callbacks and different ways to handle inbound faxes and notifications. This article assumes you hare familiar with the basics of the WestFax API. Here is a refresher article.

What are callbacks? They are asynchronous, out-of-band requests that your service will send to some other service in response to certain events. This helps you improve the workflow your app.

In layman’s term a callback is just that. Something happens (You send a fax) and we “call” you back and tell you that it sent. A callback for an incoming fax works the same way. We get a fax for you and we let you know it. The mechanism is for our server to “call” or load a URL that is specified by you. When we call your script or webpage you can configure your app to do whatever it needs to do.

You set the callback url which is a page on your website that can process data about an event. Your page is configured to receive parameters using POST or GET Method. WestFax supports both. When an event occurs (Successful fax delivery, etc…) it will call that url with the proper parameters so your application can handle the event and process your workflow without having to intermittently ping our service.

 

Here is what we are going to do:

  1. Send a fax using the API to ourselves or a test fax number.
  2. Get the callback response and call a web service that gives us the status of the fax

Here is what you need:

  1. We will assume you are using a relatively modern development framework. PHP, React, .Net, etc…
  2. We recommend you use a tool like Postman (Free and available on all platforms) to test your API’s and generate the code.
  3. Developer API account. Easy to sign up and get started immediately.

The WestFax API is comprised of a large set of methods that are exposed using a RESTful interface. Data can be interchanged in a number of formats including JSON and XML. Additionally, WestFax offers SOAP and RPC bindings that are described elsewhere. For the purposes of this demo the REST interface with JSON encoding is used.

  1. Get the sample code for Postman. Link here.
  2. Click Download or Fork it to your local repo.
    Postman illustration
  3. Once you have the local files you should see two Json Files: WestFaxApi_Postman_collection.json and WestFaxApiEnvironment.postman_environment.json
  4. Open Postman and create a new Request. You can call it whatever you want to call it but we will use WestFax.
    Postman illustration
  5. Now go click the File -> Import command.
    Postman illustration
  6. Drag or select  the two Json Files from the code you downloaded earlier and click import. You should have requests in your new WestFax Collection.
  7. Now look at the top right corner of postman. You should see a drop down and an “eye” icon and a gear icon.
    Select the Dropdown to select “WestFaxApiEnvironment” and then click the Eye icon.
    Postman illustration
  8. You will now see a bunch of pre-defined variables. You will want to change these by clicking Edit.
    Postman illustration
  9. Change the default values to the ones you received when you signed up for API access.
  10. Now let’s try to send a fax. If you have an incoming number attached to your account you can use that or any other fax number. You can also use the well known HP Faxback test number at 1-888-473-2963. They will fax you back that they received your fax usually within 5 minutes.
  11. So click the Fax_SendFax method on the left and you will see this for your Body setup.
    Postman illustration
  12. The {{Orange}} values are filled in from the config you already set so you can ignore those. The values you need to set are the Numbers1, Files0 fields. The rest are optional and you can unclick them if you want. Although adding a FeedbackEmail value is useful to get confirmation of the fax sending. Once you set all these variables go ahead and click send.
  13. Set your CallbackUrl with templated values for replacement. In this case we are using: [get]http://webhook.site/bf01f09f-3255-4b46-9a9d-10a9c21fbeed/?jobid={@jobid}?prod={@prodid}&dir={@dir}. WestFax will replace the @jobid, @prodid and @dir with real values so one can process accordingly. GET is implied so you can exclude [get] from the beginning or use [post] to use that method. You can go to webhook.site and get your own callback url for free.
  14. You should see a result code of True and a hash string with the confirmation code. This Result code is the @jobid you will use in the next phase of handling the callback so copy this value somewhere.
    Postman illustration
  15. Ok, so here is a neat trick that Postman give us. You can get all your code done for you. Just click the button “Code”. It’s kind of buried near the Send button next to cookies.
    Postman illustration
  16. Now when you click code you will get formatted code for almost any programming language you may need:
    Postman illustration

 

Phase 2: Let’s check the Status of the Fax now that the pingback call has come back.

So the fax process worked and we are waiting for a callback response. Basically WestFax will ping a url that you provide.

In our case we used a website called Webhook.site. Here is the result of the Callback call:

Postman illustration

So when the callback fires your webpage should handle those input values.

Once you have the values you can call the next webservice and get the data back. Let’s get started.

  1. Let’s go back to Postman and find the webservice called Fax_GetFaxDescriptionsUsingIds. Go ahead and click it. You’ll see something like this:
    Postman illustration
  2. Ok, so let’s look at the Body of this request so we know what we need to fill out to get the fax status.
    Postman illustration
    We see that it has the username, password, cookies (we can ignore that), productID and two new fields FaxIds1 and FaxIds2. You’ll notice that these fields have template string placeholders of {{FaxIds1}} and {{FaxIds2}}. This is because these values are serialized and we’ll look at this next. The FaxIds fields are the Faxes we want to get the status of. We have the result code from the previous call so let’s go explore that.
  3. We are going to click on the Pre-request Script header and we’ll see the format of the template placeholder we talked about previously.
    Postman illustration
    So we already put this code in there for you. All you need to do is replace the Id field. The Direction, Date and Tag are optional as the ID is the key field here. So we’ll put our Id in here and you can see on Line 8 that we bind the JSON string to the Variable. You could also copy all the JSON from the variable id1 into the FaxIds1 field directly but this template allows you to append more Id’s and get the status of several faxes.
  4. Once you have the ID in there you will hit Send and get the following output.
    Postman illustration
    You can see here that we have a complete record of the fax transmission. You can parse the JSON result in whatever method you choose and you can see that we have the Date, Direction, PageCount, Quality and Status which is Complete. So the fax is completed.

 

Success! As you can see it’s not hard at all to add Faxing to your Enterprise application. If you have questions or need more help please reach out to us at 800-473-6208 or contact us via email.