Sending fax using Twilio and Node.js

Varsha Ladha -

In my previous blog I gave information about how to send messages using twilio and node. For brief information about twilio service you can refer my previous blog.

This blog I will give information as to how to send programmable fax using Twilio service and Node.js.

A fax (short for facsimile and sometimes called telecopying) is the telephonic transmission of scanned-in printed material (text or images), usually to a telephone number associated with a printer or other output device. The receiving fax machine reconverts the coded image and prints a paper copy of the document.

Following are the things required for starting to send messages with twilio:
1. Verified account on Twilio (can create one by visiting https://www.twilio.com/try-twilio)
2. Fax-enabled Twilio phone number:
- An Incoming Phone Number (or)
- An Outgoing Caller ID (Optional for SIP destinations.)
3. Auth token and Account Sid (auto generated for every new project we create)

While purchasing a number for sending fax we need to select fax as a service for sending fax

Buy a number from the list by clicking the "Buy" button.

Steps for sending programmable messages in node.js:

  1. Install the twilio package

     > npm install twilio

  2. Get your credentials and store them in environment file (accountSid, authToken, and fromPhoneNumber purchased on twilio or trial phoneNumber)

  3. Get twilio client by requiring twilio package along with passing accountSid and authToken from environment variable

Note: You should pass your phone numbers to the API in the E.164 format.
E.164 is the international telephone numbering plan that ensures each device on the PSTN has globally unique number.

This number allows phone calls and text messages can be correctly routed to individual phones in different countries. E.164 numbers are formatted [+] [country code] [subscriber number including area code] and can have a maximum of fifteen digits

Following is the sample code for sending simple message through twilio:

const accountSid = 'ACXXXXXXXXXXXXXXXXXXXXX';
const authToken = 'your_auth_token';
const client = require('twilio')(accountSid, authToken);
const fromPhoneNumber = TWILIO_FROM_PHONE_NUMBER;
const TO_NUMBER = 'NUMBER_ON_WHICH_FAX_IS_TO_BE_SENT';
const fileUrl = 'DOCUMENT_URL_YOU_WANT_TO_SEND'

client.fax.faxes
  .create({
     from: fromPhoneNumber,
     to: TO_NUMBER,
     mediaUrl: fileUrl
   })
  .then(fax => 
      console.log(fax.sid)
  ).catch(error => 
      console.log(error)
  );

We can send only .pdf files in mediaUrl for fax.

Fax Quality and Resolution
When sending a fax, a quality value can also be provided: if not, quality defaults to fine. Note some destination fax hardware may not support higher quality levels and you may need to specify a lower quality to ensure delivery. Lower quality faxes also generally take less time to send.

The Fax Quality value that describes the fax quality. Can be: standard, fine, or superfine.

If fax was sent successfully we will get response as follows

{
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "api_version": "v1",
  "date_created": "2015-07-30T20:00:00Z",
  "date_updated": "2015-07-30T20:00:00Z",
  "direction": "outbound",
  "from": "+15017122661",
  "media_url": null,
  "media_sid": null,
  "num_pages": null,
  "price": null,
  "price_unit": null,
  "quality": "superfine",
  "sid": "FXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "status": "queued",
  "to": "+15555555555",
  "duration": null,
  "links": {
    "media": "https://fax.twilio.com/v1/Faxes/FXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media"
  },
  "url": "https://fax.twilio.com/v1/Faxes/FXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

The status of the fax. Can be: queued, processing, sending, delivered, receiving, received, no-answer, busy, failed or canceled.

Helpful Links: