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:

• A SignalWire account
• At least one phone number capable of receiving faxes
• Your API credentials (Space URL, Project ID, and API token)

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.

Below are examples of how to set up your fax handler with SWML or cXML.

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 SWML 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".

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

Paste the following code into your script:

YAML

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

JSON

{
  "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.

Configure phone number for SWML

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".

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

Select the newly created SWML 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.

View your received faxes in the dashboard logs.

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 cXML script

From your SignalWire Dashboard, create a new Resource by selecting the Script option, then choose "cXML script".

Creating a new cXML script resource for handling faxes.

In the pane that appears, select the "Script Will Be Used For" dropdown, then select Faxing.

cXML script configuration with Faxing selected.

Paste the following XML into your script:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Receive></Receive>
</Response>

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

Configure phone number for cXML

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".

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

Select the newly created cXML 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.

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:

• For SWML: Configure a webhook endpoint that returns SWML. See our SWML receive_fax documentation for more details.
• For cXML: Use our Compatibility SDKs. See our <Receive> verb documentation for code examples.

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

A fax can be sent by utilizing SWML, the Compatibility REST API, or the Compatibility SDK.

Using SWML

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.

YAML

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'

JSON

{
  "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"
        }
      }
    ]
  }
}

Using the SignalWire REST API

You can also utilize SWML to send faxes via the SignalWire REST API's Create a Call endpoint

POST https://{Your_Space_Name}.signalwire.com/api/calling/calls

example body including required parameters:

Using URL parameter

{
  "command": "dial",
  "params": {
    "from": "sip:from-sip@example-112233445566.sip.signalwire.com",
    "to": "sip:from-sip@example-112233445567.sip.signalwire.com",
    "url": "https://example.com/swml-for-faxing"
  }
}

Using inline SWML

{
  "command": "dial",
  "params": {
    "from": "sip:from-sip@example-112233445566.sip.signalwire.com",
    "to": "sip:from-sip@example-112233445567.sip.signalwire.com",
    "swml": "{"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"}}]}}"
  }
}

Using the Compatibility REST API

Send a fax by making a POST request to the Compatibility API's Send Fax endpoint:

POST https://<YOUR_SPACE_URL>.signalwire.com/api/laml/2010-04-01/Accounts/<YOUR_PROJECT_ID>/Faxes

Required parameters:

• From - Your SignalWire phone number
• To - The destination fax number
• MediaUrl - URL to the document you want to send

Using the Compatibility SDK

You can also send faxes using our Compatibility SDK's Send a Fax function:

JavaScript

const { RestClient } = require("@signalwire/compatibility-api");
const client = RestClient("YourProjectID", "YourAuthToken", {
  signalwireSpaceUrl: "example.signalwire.com",
});

client.fax.faxes
  .create({
    from: "+13103383454",
    to: "+13104456789",
    mediaUrl: "https://example.com/fax.pdf",
  })
  .then((fax) => console.log(fax.sid))
  .done();

Python

from signalwire.rest import Client as signalwire_client

client = signalwire_client("YourProjectID", "YourAuthToken", signalwire_space_url = 'example.signalwire.com')

fax = client.fax.faxes \
    .create(
        from_='+13103383454',
        to='+13104456789',
        media_url='https://example.com/fax.pdf'
    )

print(fax.sid)

.NET

using System;
using System.Collections.Generic;
using Twilio;
using Twilio.Rest.Fax.V1;

class Program
{
    static void Main(string[] args)
{
    TwilioClient.Init("YourProjectID", "YourAuthToken", new Dictionary<string, object> { ["signalwireSpaceUrl"] = "<your-domain>.signalwire.com" });

    var fax = FaxResource.Create(
        from: "+13103383454",
        to: "+13104456789",
        mediaUrl: new Uri("https://example.com/fax.pdf")
    );

    Console.WriteLine(fax.Sid);
}
}

PHP

<?php
use SignalWire\Rest\Client;

  $client = new Client('YourProjectID', 'YourAuthToken', array("signalwireSpaceUrl" => "example.signalwire.com"));

  $fax = $client->fax->v1->faxes
                         ->create("+13104456789", // to
                                  "https://example.com/fax.pdf", // mediaUrl
                                  array("from" => "+13103383454")
                         );

  print($fax->sid);
?>

Ruby

require 'signalwire/sdk'

@client = Signalwire::REST::Client.new 'YourProjectID', 'YourAuthToken', signalwire_space_url: "example.signalwire.com"

fax = @client.fax.faxes
.create(
    from: '+13103383454',
    to: '+13104456789',
    media_url: 'https://example.com/fax.pdf'
)
puts fax.sid

---

In the Legacy Dashboard

No Resources tab? Your SignalWire Space is on the Legacy Dashboard.

Expand the section below to view this guide's Legacy instructions.

The New Dashboard migration

Learn about changes to the SignalWire Dashboard, what version your Space is on, and how to migrate.

Follow the above guide with these changes:

Create a cXML Script

Navigate to the "LaML/cXML" section of your Dashboard and create a new cXML bin.

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 "LaML Webhooks"
• Select your cXML script from the dropdown for "When a Fax Comes In"

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

New Dashboard

The redesigned main menu.

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.

Legacy Dashboard

The legacy main menu.

In the Legacy Dashboard, there is no My Resources tab.

Instead, Resources are accessible as individual tabs in the main navigational sidebar.

To upgrade your Space to the New UI, contact Support.

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