Twilio's Programmable Fax lets you send, receive, and manage faxes in your web applications with just a few lines of code.
This Python SMS Quickstart will teach you the basics of fax using our Communications REST API and either cURL or your choice of language helper library. This quickstart includes detailed instructions for those helper libraries in your choice of Python, PHP, C#, Node.js, Java, and Ruby.
In this Quickstart, you will learn how to:
- Sign up for Twilio and get your first Fax-enabled Twilio phone number
- Set up your development environment to send and receive faxes
- Send your first fax
- Receive an incoming fax
Let's get started!
Before you can commence world domination via facsimile, you'll need to own a Twilio phone number capable of sending and receiving faxes. In the Twilio Console (sign up for a Twilio account if you haven't already), you can search for phone numbers capable of sending and receiving faxes.
Buy a number from the list by clicking the "Buy" button.
Now that you have a fax-capable number, let's look at how we can send faxes using the REST API.
Sending a fax requires a Twilio Account SID and Auth Token. You can find your credentials on the Console dashboard. Your API request will use these credentials for HTTP basic authentication. There are three parameters that you must also pass along with your request.
From- the Twilio number the fax will be sent from. Use the one you bought in the console before.
To- the number you'd like to send the fax to.
MediaUrl- a fully qualified URL to a PDF document you'd like to send as the content for a fax.
Note: You should pass your phone numbers to the API in the E.164 format. For our cURL example we manually encoded the "+" sign at the beginning of each phone number to its encoded value, "%2B".
Another Note: Please make sure you are using the latest version of your favorite language's Twilio helper library.
Within moments of running the above code, your fax should be happily on its way to a lucky recipient. To get updated on the status of the fax (including when sending failed), you can specify a
StatusCallback parameter in your request to provide a URL which will be requested when the status of an outbound fax changes.
When your Twilio number receives an incoming fax, Twilio will send an HTTP request to a server you control. This callback mechanism is known as a webhook. When Twilio sends your application a request, it expects a response in the TwiML XML format telling it how to respond to the message.
Here's an example of a simple web application set up to receive a fax demonstrating our helper libraries in a variety of web languages.
There are two routes you'll probably need in your application:
- One to return TwiML when the fax is initially sent to your number
- A second when the fax has completed sending
Before we can start directing Twilio how to handle our faxes,
Chances are that during development, you'll be running this code on localhost. Unfortunately, Twilio can't directly call a server running on your computer - you'll either need to deploy this code to a public server, or run a tunnel such as ngrok that provides an externally accessible URL. We'll show you how to set that up next.
If you haven't already, install ngrok and ensure the
ngrok command is on your system path (or runnable on your Windows machine).
The following command would use ngrok to expose port
3000 to the public Internet from the command line in Mac OSX or a *NIX flavor. Replace
3000 with whatever port number you're using to run your web application.
ngrok http 3000
Next, you'll see a screen similar to the following:
Now we have a new external URL, visibly on the public internet.
Configure this address as the webhook for one of your phone numbers in the console. Select your phone number of choice then change the "A FAX COMES IN" field to the external URL to your service. For example in this case:
Now, you're all wired up - time to try it out...
Send a fax to your Twilio phone number – if you're watching ngrok, you should see a pair of HTTP requests in the ngrok console. If everything worked, you should have printed the URL of a PDF containing your inbound fax to the console.