Receive a fax being delivered to this call.

Properties

receive_fax

objectRequired

An object that accepts the following properties.

receive_fax.status_url

string

HTTP or HTTPS URL to deliver receive fax status events. Learn more about status callbacks.

Variables

Set by the method:

• receive_fax_document: (out) URL of received document.
• receive_fax_identity: (out) identity of this fax station.
• receive_fax_remote_identity: (out) identity of the sending fax station.
• receive_fax_pages: (out) number of pages received.
• receive_fax_result_code: (out) fax status code.
• receive_fax_result_text: (out) description of fax status code.
• receive_fax_result: (out) success | failed.

StatusCallbacks

A POST request will be sent to status_url with a JSON payload like the following:

event_type

string

The type of event. Always calling.call.fax for this method.

event_channel

string

The channel for the event, includes the SWML session ID.

timestamp

number

Unix timestamp (float) when the event was generated.

project_id

string

The project ID associated with the call.

space_id

string

The Space ID associated with the call.

params

object

An object containing fax-specific parameters.

params.call_id

string

The call ID.

params.node_id

string

The node handling the call.

params.control_id

string

The control ID for this fax operation.

params.fax

object

Fax result details.

fax.type

string

The type of fax operation. Always finished.

fax.params.direction

string

The direction of the fax (receive).

fax.params.identity

string

The identity of this fax station.

fax.params.remote_identity

string

The identity of the sending fax station.

fax.params.document

string

URL of the received fax document.

fax.params.pages

number

Number of pages received.

fax.params.success

boolean

Whether the fax was received successfully.

fax.params.result

number

The numeric result code of the fax operation (e.g., 0 for success).

fax.params.result_text

string

A description of the fax result (e.g., OK).

fax.params.format

string

The format of the fax document. Always "pdf".

Page progress events

A separate callback is sent for each page as the fax progresses:

fax.type

string

Always "page" for page progress events.

fax.params.direction

string

The direction of the fax.

fax.params.number

number

The page number that was just processed.

Raw JSON example

{
  "event_type": "calling.call.fax",
  "event_channel": "swml:xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "timestamp": 1640000000.123,
  "project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "params": {
    "call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "node_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "control_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "fax": {
      "type": "finished",
      "params": {
        "direction": "receive",
        "identity": "+15551231234",
        "remote_identity": "+15553214321",
        "document": "https://your-space.signalwire.com/api/v1/faxes/fax-uuid/download",
        "pages": 3,
        "success": true,
        "result": 0,
        "result_text": "OK",
        "format": "pdf"
      }
    }
  }
}

---

Examples

Receive a fax and post a result to a webhook

YAMLJSON

version: 1.0.0
sections:
  main:
    - receive_fax: {}
    - execute:
        dest: 'https://<NGROK UUID>.ngrok-free.app'

In this example, when a fax is received, a POST request will be sent to the URL with all the fax related variables (like receive_fax_document) already set. Refer to the execute statement’s documentation for more details on this behavior.