Send a fax.

Properties

send_fax

objectRequired

An object that accepts the following properties.

send_fax.document

stringRequired

URL to the PDF document to fax

send_fax.header_info

string

Text to add to the fax header

send_fax.identity

stringDefaults to Calling party's caller ID number

Station identity to report

send_fax.status_url

string

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

Variables

Set by the method:

• send_fax_document: (out) URL of sent document.
• send_fax_identity: (out) identity of this fax station.
• send_fax_remote_identity: (out) identity of the receiving fax station.
• send_fax_pages: (out) number of pages sent.
• send_fax_result_code: (out) fax status code.
• send_fax_result_text: (out) description of fax status code.
• send_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 (send).

fax.params.identity

string

The identity of this fax station.

fax.params.remote_identity

string

The identity of the receiving fax station.

fax.params.document

string

URL of the sent fax document.

fax.params.pages

number

Number of pages sent.

fax.params.success

boolean

Whether the fax was sent 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": "send",
        "identity": "+15551231234",
        "remote_identity": "+15553214321",
        "document": "https://example.com/fax_to_send.pdf",
        "pages": 3,
        "success": true,
        "result": 0,
        "result_text": "OK",
        "format": "pdf"
      }
    }
  }
}

---

Examples

Send a fax and post a result to a webhook

YAMLJSON

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'