Handle an incoming fax with Node.js

Now that you know how to send yourself a fax a using the Fax API, learn how to handle incoming faxes.

What you need to know before you start

Before you can get started, you need the following already set up:

• Set all Fax API configuration settings.
• NPM and a familiarity with how to install packages.
• Node.js and a familiarity with how to create a new app.
• A Sinch phone number configured for the Fax API.

Set up your Node.js application

First we'll create a Node project using npm. This creates a package.json and the core dependencies necessary to start coding.

To create the project, do the following steps:

1. Create a folder called fax-receive
2. Navigate into the folder you created and run the following command.
   Copy

   Copied

   npm init

   This command adds the node_modules folder and the package.json file. You will be prompted to provide values for the fields. For this tutorial, you can simply accept the default values and press enter at each stage.

Install your dependencies

We will be using Express to create a lightweight webserver that will listen for requests from the Sinch servers to handle incoming faxes. Because the webserver is running on your local machine, you will also need a method for making the server accessible over the internet. In this guide we'll be using ngrok to do that, but if you have another way you'd prefer to do it, feel free to use that. Additionally, we'll be using the node-fetch package to make HTTP requests.

Use the following command to install the Express, ngrok, and node-fetch packages:

npm install express ngrok node-fetch

Create your file

In your project folder, create a new file named index.js in the project and paste the provided "index.js" code into the file.

This code starts your webserver, creates an ngrok tunnel, updates your incoming webhook URL, and also contains the logic to download fax content from the Sinch servers. We'll come back to what those things are in a moment.

Before you save your file and start your server, there's a couple of values you to need to update.

Update your parameter values

Update the values of the following parameters:

Start your server

At this point, you can start your server with the following command:

node index.js

You should notice a few things.

• First, your console should show that the server has started on port 5000 of your localhost.
• Second, the ngrok tunnel has started and you should see the URL displayed in the console.
• Additionally, you should see a message in your console that the incoming webhook URL for your fax service was updated automatically. There is code in the sample that makes a request to the Fax API to update the incoming webhook URL.

Now your server is listening and your incoming webhook URL is configured, so you're almost ready to test everything and send a fax that you can receive. But before we do, let's take a closer look at webhooks. If you already know about webhooks, skip right to sending yourself a fax.

Understanding webhooks

Webhooks (also known as "callbacks" or "notifications") are the method that the Fax API uses to inform you when your Sinch number is sent a fax. Basically, a notification is a request that the Sinch servers send to your server whenever something happens (otherwise known as an "event"), such as when you send or receive a fax. There are two different kinds of events, the Fax Completed and the Incoming Fax event, but the one we're concerned about is the Incoming Fax event.

An Incoming Fax event happens whenever someone sends a fax to one of your Sinch numbers. All of the notification events the Fax API sends expect a 200 OK response in return.

And that's it! Now we can test.

Send your Sinch number a fax

Using the app we created in the previous guide, send a fax to your Sinch number. The fax should be picked up by the Sinch servers and a PDF of your fax will be downloaded to your machine. Now you know how to handle an incoming fax.

Next steps

Learn more about the Fax API:

• API specification