Skip to main content

Retrying Failed Faxes


This is a simple guide using the SignalWire NodeJS SDK and Express to create an application that can send faxes, detected failed faxes with status callbacks, and perform one retry.

What do I need to run this code?

View the full code on our Github here.
You will also need the SignalWire NodeJS SDK here
You will also need to install the NodeJS Express Web Framework here
For demonstration and testing you may also need ngrok here

How to run this application

Run natively

By default you can run node app.js in your terminal and express and ngrok will run on port 3000.
Once ngrok spins up it should log the ngrok tunnel url to your console.
To send a test fax navigate to the ngrokurl/quicksend. This will return a fax SID that you can check in your Signalwire Dashboard.

Code Walkthrough

The code walkthrough is truncated to only include the most relevant functions. The full code can be found on our Github here.
This repository will inclue the app.js and accompanying package.json and package-lock.json files.
Additionally, this repository will include an example.env file that you can copy and save with your own credentials as .env

Environment File Setup

Save this file as .env after populating it withy our own data

# This is the full name of your SignalWire Space. e.g.:

# Your Project ID - you can find it on the `API` page in your Dashboard.

# Your API token - you can generate one on the `API` page in your Dashboard

# The phone number you'll be using for this Snippet. Must include the `+1` ex. `+11231231234`
SIGNALWIRE_TONUMBER=+1<10dlc number>

# If you have an Ngrok account you can include your auth token here.

#If hosting this app, enter the host domain here and remove the ngrok tunnel

App.JS set up

First we will need to require our Express, Ngrok, and Rest Client packages. Here we will also assign our Environment Variables.

const ngrok = require("ngrok");
const express = require("express");
const { RestClient } = require("@signalwire/compatibility-api");

let DOMAIN = "";

SendFax Function

This function will be what sends our faxes. It will accept a number that will be the number we send the fax, and a querystring.
Next the function creates our Rest Client, sends a new fax, and sets the statuscallback using our formaturl function.
Finally we will log the fax.sid to our console, and return it to the client.

async function sendFaxTo(number, querystring = "") {
signalwireSpaceUrl: SIGNALWIRE_SPACE,
const fax = await client.fax.faxes.create({
to: number,
mediaUrl: "",
statusCallback: formatUrl("callback", querystring),
console.log("Done", fax.sid);
return fax.sid;

App Route: QuickSend

This route is a very swift way of creating a test fax. It will call our sendFaxTo() function and pass our TO_NUMBER environment variable.

app.get("/quicksend", async (req, res, next) => {
sid = await sendFaxTo(TO_NUMBER);

App Route: Callback

This route handles our status callbacks. If a fax fails we will re-call our sendFaxTo this time passing a querystring. Any faxes that have already been retried once will not be retried again."/callback", async (req, res, next) => {

if (req.body.FaxStatus == 'failed') {
// retry if we haven't retried already
if (req.query.retry) {
console.log('no retry');
} else {
await sendFaxTo(req.body.To, '?retry=1')

Ngrok Function

This function starts our ngrok tunnel on port 3000, logs the url to our console, and sets our DOMAIN to the url. Comment/delete this out and set DOMAIN to your app's host DOMAIN in production.

(async function () {
const url = await ngrok.connect(3000);
DOMAIN = url;

Formaturl function

This function is how we will append actions and querystrings to our domain URLS. This is primarily used when creating a statuscallback url for our sendFaxTo() method

function formatUrl(action, querystring = "") {
return DOMAIN + "/" + action + querystring;


Points our app to port 3000, this port should match the port that we launch ngrok to.

app.listen(process.env.PORT || 3000, () => {
console.log("Server running on port 3000");

Wrap Up

This guide is a great way to get an understanding of how SignalWire's API can be used to send out faxes and properly make use of statuscallbacks to detect and retry failed faxes.


View the full code on our Github here.
You will also need the SignalWire NodeJS SDK here
You will also need to install the NodeJS Express Web Framework here
For demonstration and testing you may also need ngrok here

Sign Up Here

If you would like to test this example out, you can create a SignalWire account and space here.

Please feel free to reach out to us on our Community Slack or create a Support ticket if you need guidance!