Skip to main content

First steps with fax

Learn how to send and receive your first fax using SignalWire. You'll configure a phone number, create SWML or cXML scripts to handle faxes, and use SWML or our APIs to send faxes programmatically.

Prerequisites​

Before you begin, you'll need:

Receiving your first fax​

To receive faxes, you'll configure a phone number to handle incoming faxes using either a SWML or cXML script that defines what happens when a fax arrives.

Obtain a phone number​

First, you need a SignalWire phone number capable of receiving faxes.

Log in to your SignalWire Space. If you don't have a number yet, navigate to the Phone Numbers section and buy a new phone number.

Create a script​

From your SignalWire Dashboard, create a new Resource by navigating to the resources tab, then select the "New Script" option and choose "New SWML application".

The new resource dialog showing cXML script creation.

Navigating to and creating a new SWML resource for handling faxes.

Paste the following code into your script:

version: 1.0.0
sections:
  main:
    - receive_fax: {}

Save the script. It should now be located in your Resources tab on the left sidebar, under Scripts.

Follow the above guide with these changes:

Create a SWML Script

Navigate to the "Relay/SWML" section of your Dashboard and create a new SWML Script.

Assign a phone number

Open the settings for your phone number. Under "Voice and Fax Settings":

  • Set "Accept Incoming Calls As" to "Fax"
  • Set "Handle Faxes Using" to "SWML Script"
  • Select your SWML Script from the dropdown for "When a Fax Comes In"

Identify your Dashboard and select between Legacy and New UIs using the tabs below.

The main sidebar menu of the new SignalWire Space Dashboard UI.

The redesigned main menu.

The selection menu when a new Resource is created.

The new SignalWire Dashboard features a streamlined sidebar menu. Many items are now located in the unified My Resources menu.

Resources that were previously accessible in the sidebar of the legacy UI are now located in the unified My Resources menu.

Configure phone number​

Navigate to the "Phone Numbers" tab on the left sidebar. From this tab, click on your newly purchased phone number, then on the "edit settings" option. In the settings page that appears, select "Assign Resource" for "Inbound Call Settings".

Phone number settings page showing the Assign Resource button for inbound calls.

Assign the script to your phone number's inbound call settings.

Select the newly created script, then click "Save" to apply the configuration.

Test your setup​

Send a test fax to your configured phone number and then open the respective call log found in the Logs section on your left sidebar.

Copy the link found in the Document parameter and paste it into your browser to view your fax.

The logs page showing voice logs where inbound faxes will be received

View your received faxes in the dashboard logs.

Alternative: Using webhooks or SDKs

If you prefer to host the fax handling logic yourself, you have two options:

You'll need to make your code accessible to SignalWire through a webhook. We have a guide on testing webhooks with ngrok to help you get started.

Sending your first fax​

SWML can be used to send a fax through the send_fax method. The below example script sends a fax, then posts the result to a predetermined webhook.

version: 1.0.0
sections:
  main:
    - send_fax:
        document: https://example.com/fax_to_send.pdf
    - execute:
        dest: 'https://example.com/handle_outgoing_fax_result'

Next steps​

Common fax errors

Troubleshoot and understand common fax transmission errors

List faxes to CSV

Export your fax history to CSV format for reporting

Filter faxes by number, status, and date

Query and filter your fax records