send_fax | SignalWire

Send a fax document on the call. The document must be accessible via URL. Returns a FaxAction that you can use to stop the fax or wait for it to complete.

This method emits calling.call.fax events. See Call Events for payload details.

Parameters

document

strRequired

URL of the document to fax (PDF or TIFF format).

identity

str | NoneDefaults to None

Caller identity string (TSI) transmitted with the fax.

header_info

str | NoneDefaults to None

Header text printed at the top of each fax page.

control_id

str | NoneDefaults to None

Custom control ID. Auto-generated if not provided.

on_completed

Callable[[RelayEvent], Any] | NoneDefaults to None

Callback invoked when the fax operation completes.

Returns

FaxAction — An action handle with stop() and wait() methods.

Example

from signalwire.relay import RelayClient
client = RelayClient(
    project="your-project-id",
    token="your-api-token",
    contexts=["default"],
)
@client.on_call
async def handle_call(call):
    await call.answer()
    action = await call.send_fax(
        document="https://example.com/invoice.pdf",
        identity="+15559876543",
        header_info="Invoice #12345",
    )
    event = await action.wait()
    fax_result = event.params.get("fax", {})
    print(f"Fax sent: {fax_result.get('pages', 0)} pages")
    await call.hangup()
client.run()