Cxml Fax

Fresh

Fax Overview

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.

Fax cXML is a set of actions defined in an XML document you can use to tell SignalWire what to do when you receive an incoming fax.

Overview

When a fax is sent to one of your SignalWire phone numbers, SignalWire looks up the Fax cXML document from the URL you configured, and reads the instructions you provided to determine what to do.

Fax cXML allows you to control what SignalWire will do when you receive an incoming fax.

Request

SignalWire makes an HTTP request to your configured endpoint just like a regular web form submission (POST) or page load (GET). The request includes contextual information about the fax, allowing you to respond dynamically and fluidly to the fax to meet the needs of your application.

You can configure the endpoint URL and HTTP Method in your phone number settings panel on your SignalWire Dashboard, or via the REST API.

Request parameters

SignalWire sends the following parameters, as either URL query parameters or POST parameters, to your endpoint when it receives a fax:

AccountSid

string

The account that the fax was sent from.

ApiVersion

string

The version of the SignalWire API.

FaxSid

string

A unique identifier for the fax.

From

string

The number or SIP URI the fax was sent from.

To

string

The number or SIP URI the fax will be sent to.

Responding to SignalWire

An example of a cXML document that receives an incoming fax:

XMLNode.jsC#PythonRuby

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

When a fax comes into one of your SignalWire phone numbers, SignalWire makes an HTTP request to the URL endpoint you configured for that number. Your response to that request instructs SignalWire on what to do next.

Responses to the HTTP request are in SignalWire cXML. SignalWire starts at the top of your XML document and executes your commands in order, from top to bottom.

cXML verbs and their attributes are case-sensitive, so using <receive> instead of <Receive> will result in an error.

StatusCallback when sending a fax

When sending a fax you can specify a StatusCallback URL. If you do so, your specified URL will receive POST requests with the following parameters:

ErrorCode

string

The error code provides more information on a failed fax.

ErrorMessage

string

The message explaining the reason for fax failure.

FaxStatus

string

The status of the fax.

MediaSid

string

The SID that uniquely identifies the fax media.

MediaUrl

string

The media URL to request to retrieve incoming media.

NumPages

integer

The number of pages received from a successful fax.

OriginalMediaUrl

string

The original URL passed when a fax is sent.

RemoteStationId

string

The transmitting subscriber identification (TSID) reported by the fax machine that sent in the fax.

Instructions

The following instructions are used to manage faxes:

Receive\ \ Receive an incoming fax. Reject\ \ Reject an incoming fax.

---

*Twilio and TwiML are trademarks of Twilio, Inc. SignalWire, Inc. and its products are not affiliated with or endorsed by Twilio, Inc.

---

Receive

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.

The <Receive> verb tells SignalWire to receive an incoming fax, which results in the creation of a new Fax instance resource.

Faxes remain stored indefinitely. To delete a fax, use the appropriate API call from the Compatibility API.

Verb attributes

action

string

The URL to request when a fax has failed or has been received.

mediaType

stringDefaults to application/pdf

The type of media used to store fax media. Valid values are application/pdf or image/tiff.

method

stringDefaults to POST

The method attribute specifies whether the request to action is a GET or a POST. Valid values are GET or POST.

pageSize

stringDefaults to letter

The size to interpret incoming pages as. Valid values are letter, legal, or a4.

Action callback

If the verb attribute action is specified, the action callback will include the Standard Fax Request Parameters plus the following optional parameters:

ErrorCode

string

The error code provides more information on a failed fax.

ErrorMessage

string

The message explaining the reason for fax failure.

FaxStatus

string

The status of the fax.

MediaUrl

string

The media URL to request to retrieve incoming media.

NumPages

integer

The number of pages received from a successful fax.

RemoteStationId

string

The transmitting subscriber identification (TSID) reported by the fax machine that sent in the fax.

Examples

Receive a fax

XMLNode.jsC#PythonRuby

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

SignalWire will receive the incoming fax and provide a URL endpoint.

Store fax image

XMLNode.jsC#PythonRuby

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

This example shows that the media from the incoming fax will be stored on SignalWire’s server in TIFF format.

---

*Twilio and TwiML are trademarks of Twilio, Inc. SignalWire, Inc. and its products are not affiliated with or endorsed by Twilio, Inc.

---

Reject

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.

The <Reject> verb tells SignalWire to reject an incoming fax, which results in a status of canceled.

Verb attributes

The <Reject> verb does not have any attributes that modify its behavior.

Examples

Fax reject

XMLNode.jsC#PythonRuby

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

SignalWire will reject the incoming fax.

---

*Twilio and TwiML are trademarks of Twilio, Inc. SignalWire, Inc. and its products are not affiliated with or endorsed by Twilio, Inc.