receive_fax
receive_fax
Receive a fax being delivered to this call.
Properties
receive_fax
An object that accepts the following properties.
receive_fax.status_url
HTTP or HTTPS URL to deliver receive fax status events. Learn more about status callbacks.
Also accepts a SWML variable reference (string), substituted when the method runs. The resolved value must be an HTTP or HTTPS URL.
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
Status callbacks are asynchronous, best-effort HTTP notifications: delivery can be delayed or fail silently — if your server is unreachable, the callback simply never arrives. Don’t gate time-critical or business-critical actions solely on receiving one. Confirm state via the REST API before acting, or use a transport with visible failure modes — see Status callback reliability.
A POST request will be sent to status_url with a JSON payload like the following, for the calling.call.fax page and finished events:
event_type
The type of event. calling.call.fax for the fax events described here. When the fax operation can’t be executed, an error event with event type calling.error may be sent instead; see error events.
event_channel
The channel for the event, includes the SWML session ID.
timestamp
Unix timestamp (float) when the event was generated.
project_id
The project ID associated with the call.
space_id
The Space ID associated with the call.
params
An object containing fax-specific parameters.
params.call_id
The call ID.
params.node_id
The node handling the call.
params.control_id
The control ID for this fax operation.
params.fax
Fax result details.
params.fax.type
The type of fax operation. Always finished.
params.fax.params
Details of the fax operation.
params.fax.params.direction
The direction of the fax (receive).
params.fax.params.identity
The identity of this fax station.
params.fax.params.remote_identity
The identity of the sending fax station.
params.fax.params.document
URL of the received fax document. Use the value from the event rather than constructing the URL yourself.
params.fax.params.pages
Number of pages received.
params.fax.params.success
Whether the fax was received successfully.
params.fax.params.result
The numeric result code of the fax operation (e.g., 0 for success).
params.fax.params.result_text
A description of the fax result (e.g., OK).
params.fax.params.format
The format of the fax document. Always "pdf".
Page progress events
A separate callback is sent for each page as the fax progresses:
params.fax.type
Always "page" for page progress events.
params.fax.params.direction
The direction of the fax.
params.fax.params.number
The page number that was just processed.
Raw JSON example
The document value above is illustrative. Use the URL returned in the event.
Error events
When the fax operation can’t be executed, SignalWire may send an event with event_type set to calling.error to status_url instead of a calling.call.fax event. Its params object has no fax object. It carries the call identifiers and these fields:
params.error.code
The error code.
params.error.message
A description of the error.
params.request
A copy of the request that failed, included for diagnostics only. Its shape isn’t a stable contract.
Check event_type before reading the rest of the payload. Not every failure produces an error event.
Examples
Receive a fax and post a result to a webhook
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.