SignalWire Docs

Appearance

Fax ​

Fresh

First steps with fax ​

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Prototype, build, and deploy fax applications quickly and at competitive rates using our APIs and SDKs as well as the lightweight SignalWire Markup Language (“SWML”).

Security first ​

SignalWire Fax is certified SOC 2 Type II compliant, and is built from the ground up for seamless HIPAA compliance.

Learn how to send and receive your first fax using SignalWire. You’ll configure a phone number, create SWML 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 a SWML script that defines what happens when a fax arrives.

1

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.

2

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

Legacy dashboard instructions ​

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”
Which Dashboard version am I using? ​

New Dashboard: You have a Resources tab in the left sidebar.

Legacy Dashboard: You have separate tabs for SIP, LaML, RELAY, etc.

3

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.

4

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.

If you prefer to host the fax handling logic yourself, configure a webhook endpoint that returns SWML. See our SWML receive_fax documentation for more details.

You’ll need to make your code accessible to SignalWire through a webhook. In development environments, use a tunneling service like ngrok to expose your local server.

Sending your first fax ​

SWML ​
SignalWire REST API ​

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

Common fax errors ​

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

This page lists the most common fax error messages along with the likely reason and troubleshooting steps for resolution. If these steps don’t resolve your issue, open a support request and include the Fax SID with the error.

Per our carrier peers’ requirements, these SIDs MUST be from the last 24 hours. SIDs older than 24 hours cannot be investigated.

Common errors ​

Connection Failed ​

Meaning: There was no receiver on the other end of the call to connect to.

Reason: The destination is not confirmed to receive facsimile transactions.

Troubleshooting steps:

  • Retry.
  • Contact the owner of the destination number to confirm compatibility and connectivity.

Disconnected after permitted retries ​

Meaning: The fax service attempted to send the same message multiple times unsuccessfully. This may be due to a call clarity issue.

Reason: Poor network conditions.

Troubleshooting steps:

  • Retry.
  • If network conditions persist, contact SignalWire Support to reach out to our carrier peer.

Document generation error ​

Meaning: There was an error while generating the document. This could be due to the file being deleted before sending.

Reason: Internal Service Error.

Troubleshooting steps:

  • Retry.
  • If the issue persists, contact SignalWire support.

Document loading error ​

Meaning: The fax service attempted to generate the message to send but a document was missing.

Reason: Internal Service Error.

Troubleshooting steps:

  • Retry.
  • If the issue persists, contact SignalWire support.

Failed to train with any of the compatible modems ​

Meaning: A remote fax machine was detected, but the sending and receiving modems could not establish communication.

Reason: Connectivity issues.

Troubleshooting steps:

  • Retry.
  • If the issue persists, contact SignalWire support.

Far end cannot receive at the resolution of the image ​

Meaning: The remote fax machine does not support receiving faxes sent by our service.

Reason: Quality is too high.

Troubleshooting steps:

  • Try lowering quality (resolution is known as “quality” in Programmable Fax).

Fax transmission not established ​

Meaning: We could not detect a remote fax machine. This could be due to there being no fax machine on the receiving end or a lack of call clarity.

Reason: Connectivity issues, carrier issues, T.38 incompatibility issue.

Troubleshooting steps:

  • Retry.
  • Determine whether the remote side was configured.

Invalid ECM response received from receiver ​

Meaning: The “Invalid ECM (Error Correction Mode) response received from receiver” error indicates that there’s an issue with the error correction process, where the receiving fax machine’s response to a request for error correction didn’t match expected parameters or was not understood by the sending machine.

Reason: Network or incompatibility issues.

Troubleshooting steps:

  • Retry.
  • If failures only occur with one number, there’s a chance that the remote fax machine is incompatible with our infrastructure.

Log entry lost ​

Meaning: The call started but the log entry for the call was lost or incomplete. In practice, this is rare and may indicate a system problem.

Reason: Internal Service Error.

Troubleshooting steps:

  • Retry.
  • If the issue persists, contact SignalWire support.

No response after sending a page ​

Meaning: The remote fax machine did not acknowledge that it received a page of the fax. Depending on the remote machine’s behavior, it may still have printed the page and any preceding pages.

Reason: Connectivity issues.

Troubleshooting steps:

  • Retry.
  • Contact destination to ensure delivery.

Received a DCN from remote after sending a page ​

Meaning: The remote fax machine responded with a disconnect message after a page was sent successfully. Depending on the remote machine’s behavior, it may have still printed the sent page and any preceding pages.

Reason: Poor network conditions.

Troubleshooting steps:

  • Retry.
  • If network conditions persist, contact SignalWire Support to reach out to our carrier peer.

Received no response to DCS or TCF ​

Meaning: The bulk fax service could not successfully determine the remote machine’s fax capabilities.

Reason: Network or incompatibility issues.

Troubleshooting steps:

  • Retry.
  • Determine whether the remote side was configured for supported fax protocols (T.38/T.30).
  • Ensure the remote side’s network is stable.
  • If failures only occur with one number, there’s a chance that the remote fax machine is incompatible with our infrastructure.

The call dropped prematurely ​

Meaning: The call dropped due to a non-fax transmission error. It is likely that the receiver hung up.

Reason: Inbound to SignalWire: the destination is a voice number or not set up to receive faxes. Outbound: the destination is a voice number, or the destination returns ringing for so long that the transmission times out before the handshake can be established.

Troubleshooting steps:

  • Retry.

SignalWire Fax only supports the transmission of PDFs to fax-enabled destinations.

The HDLC carrier did not stop in a timely manner ​

Meaning: The fax service initiated a fax transmission with the receiver, but there was a synchronization (timing) error that could not be resolved.

Reason: Likely low-quality routes.

Troubleshooting steps:

  • Retry.
  • If network conditions persist, contact SignalWire Support to reach out to our carrier peer.

Timed out waiting for initial communication ​

Meaning: A call was established with the receiver, and the bulk fax service attempted to establish a fax session. However, there was no fax response from the receiver. This could be due to there being no fax machine on the receiving end or lack of call clarity.

Reason: No remote fax machine or poor quality routes.

Troubleshooting steps:

  • Retry.
  • If network conditions persist, contact SignalWire Support to reach out to our carrier peer.

Unexpected DCM after EOM or MPS sequence ​

Meaning: The remote fax machine disconnected unexpectedly after receiving a page of a multi-page fax. Depending on the remote machine’s behavior, it may have still printed the sent pages and any preceding pages.

Reason: Poor network conditions.

Troubleshooting steps:

  • Retry.
  • If network conditions persist, contact SignalWire Support to reach out to our carrier peer.

Unexpected DCN while waiting for DCS DIS ​

Meaning: “Unexpected DCN (Disconnect) while waiting for DCS (Digital Command Signal) or DIS (Digital Identification Signal)” implies that the fax machine received a disconnect signal unexpectedly during the initial negotiation phase, before the communication parameters were fully agreed upon.

Reason: Network or incompatibility issues.

Troubleshooting steps:

  • Retry.
  • Determine whether the remote side was configured for supported fax protocols (T.38/T.30).
  • Ensure the remote side’s network is stable.
  • If failures only occur with one number, there’s a chance that the remote fax machine is incompatible with our infrastructure.

Unexpected message received ​

Meaning: The fax service received a message that it did not expect given the current context.

Reason: Protocol failure.

Troubleshooting steps:

  • Determine whether the expected number of pages matches the number of successfully transmitted pages. Failure may have been in tearing down the call.

Still having issues? ​

If you’ve worked through the troubleshooting steps above and the error persists, open a ticket with SignalWire Support and include the Fax SID from the last 24 hours so our team can investigate with our carrier peers.

SignalWire Developer Documentation

Internal SOP Reference