Receive an inbound fax

Faxinbound fax to webhook

Receive an inbound fax at a webhook URL and get a status callback when delivery completes.

fax

The claim

Receiving a fax is a three-verb SWML document on a fax-capable number: answer, receive_fax, hangup. The platform handles the tones and the page transfer; when the fax completes it POSTs the result to status_url: success, page count and the document URL. Nothing about T.30 reaches your code.

How it works

- answer: {}
- receive_fax: { status_url: "https://<your-host>/fax-received" }
- hangup: {}

The Flask route at /fax-received stores the document URL and page count when success is true and ignores a failed receive. From there the document is a normal file: OCR it, extract fields with a model, file it. The Telnyx “fax-to-structured-data” stems are this recipe plus a parser.

Fax media URLs can be protected so they require API auth to fetch (Dashboard → Media URL protection). The Compatibility API offers the same receive as <Receive action=...>, and inbound fax history is in GET /api/fax/logs.

What to change first

Feed the document URL to extract-structured-data-after-a-call’s sibling pattern, a model with a typed schema, and post the JSON to your system.

Where this sits

Before this

Buy a number and point it at your app

Send a fax

Extract structured data after a call

swml/agent.yaml

# Receive an inbound fax - assign this document to a fax-capable number.
# receive_fax answers the fax tone and takes the document; the result (pages,
# success, and the document URL) is POSTed to status_url when it completes.
version: "1.0.0"
sections:
  main:
    - answer: {}
    - receive_fax:
        status_url: "https://your-host.example.com/fax-received"
    - hangup: {}

"""Receive an inbound fax.

A fax-capable number runs this SWML: `receive_fax` answers the fax tone and
takes the document. When it completes, SignalWire POSTs the result - pages,
success, result text and the document URL - to status_url, where the Flask
route below stores it.

Written against signalwire-sdk 3.0.1 (SWMLService) and Flask.
"""
import os

from dotenv import load_dotenv
from flask import Flask, jsonify, request
from signalwire import SWMLService

# the SDK does not read .env for you
load_dotenv()

PUBLIC_URL = os.getenv("PUBLIC_URL", "https://your-host.example.com")

app = Flask(__name__)


def build(service=None):
    service = service or SWMLService(name="fax-in", route="/fax")
    service.reset_document()
    service.add_verb("answer", {})
    service.add_verb("receive_fax", {"status_url": f"{PUBLIC_URL}/fax-received"})
    service.add_verb("hangup", {})
    return service


@app.route("/fax", methods=["GET", "POST"])
def swml():
    return jsonify(build().get_document())


received = {}


@app.post("/fax-received")
def fax_received():
    p = request.get_json(silent=True) or request.form.to_dict()
    params = p.get("params", p)  # fax fields may be nested under params
    call_id = p.get("call_id", "unknown")
    if str(params.get("success")).lower() == "true" or params.get("success") is True:
        received[call_id] = {
            "pages": params.get("pages"),
            "document": params.get("document") or params.get("url"),
            "from": p.get("from") or params.get("remote_identity"),
        }
    return "", 204


if __name__ == "__main__":
    app.run(port=int(os.getenv("PORT", "8080")))

Run it

Markup only: paste swml/agent.yaml into a SWML Script, set status_url, and assign it to a fax-capable number.

Python:

cd python
pip install -r requirements.txt
PUBLIC_URL=https://<your-host> python app.py

Point the number’s SWML webhook at https://<your-host>/fax.

Verify it

python verify.py          # from the recipe folder, not python/

Both surfaces validate against the SWML schema and consist of exactly answer → receive_fax(status_url) → hangup; the status webhook stores pages and the document URL only for a successful receive.

Report an issue