Handle an incoming fax with Python

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

In this guide you will learn:

How to set up your your Python app
How to start your server
About webhooks
How to receive an incoming fax

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.
Python and a familiarity with how to create a new file.
PIP (package installer for Python) and a familiarity with how to install Python modules.
Flask and a familiarity with how to set up a Flask environment and app.
ngrok. You'll use ngrok to open a tunnel to your local server.

Set up your Flask Python application

Create a new folder where you want your app project and open a command prompt to that location. Create a new environment with the following command:

Copy

Copied

py -3 -m venv venv

Activate the environment using the following command:

Copy

Copied

venv/Scripts/activate

Install your dependencies

We will be using Flask 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 (and in particular the pyngrok module) 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 requests module to make HTTP requests.Use the following command to install the Flask, requests, and pyngrok modules:

Copy

Copied

pip install Flask requests pyngrok

Create your file

In your project folder, create a new file named app.py. Populate that file with the provided "app.py" code found on this page.

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:

Parameter	Your value
`YOUR_access_key`	The key found on your Sinch dashboard.
`YOUR_access_secret`	The secret found on your Sinch dashboard. Note: Access secrets are only available during initial key creation.
`YOUR_project_id`	The project ID found on your Sinch dashboard.
`YOUR_service_id`	The service ID found on your Sinch dashboard.

Start your server

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

Copy

Copied

flask run

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.

Tip:

You can also update your incoming webhook URL in the dashboard yourself. Navigate to your fax services on your dashboard. Next to your service click the Edit button. You'll see a field labeled "Incoming webhook URL." Enter your URL into that field and click Save.

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