Connect a PBX with a Domain Application

VoiceSIP trunking for a PBX

An IP-authenticated Domain Application takes inbound SIP from your PBX and a SIP Gateway carries calls back to it.

Also called SIP trunk, FreePBX, 3CX, Asterisk, FusionPBX

sipbyoc

The claim

Bring-your-own-PBX is two resources, both created over REST. *Inbound (PBX → SignalWire): a Domain Application is a SIP domain, <identifier>.dapp.signalwire.com. It accepts INVITEs from the IP addresses you list and runs a SWML document for each call. Outbound (SignalWire → PBX): a SIP Gateway* is a Fabric resource with an address (/private/<name>) that any SWML can connect to. SignalWire delivers the call to the PBX’s SIP URI. Neither side needs SIP registration or credentials: the PBX trusts by IP, SignalWire trusts by IP.

How it works

client._http.post("/api/relay/rest/domain_applications", body={
    "name": "Acme PBX inbound", "identifier": "acme-pbx",
    "ip_auth_enabled": True, "ip_auth": ["203.0.113.10", "203.0.113.11"],
    "call_handler": "relay_script", "call_request_url": f"{PUBLIC_URL}/from-pbx",
    "encryption": "optional", "codecs": ["PCMU", "PCMA", "OPUS"]})

client.fabric.sip_gateways.create(name="acme-pbx-gateway", uri="sip:pbx.example.com:5060",
                                  encryption="optional", ciphers=[...], codecs=[...])

The Domain Application bridges the incoming call with connect, using ${call.to} as the destination. That value is the PSTN number the PBX dialled. In the other direction, the SWML a PSTN number runs to reach the PBX is connect: { to: "/private/acme-pbx-gateway" }. Put an ai verb in either document and the PBX has an AI agent behind an extension.

The typed RestClient wraps SIP Gateways but not Domain Applications, so that one call goes through the client’s authenticated HTTP layer by path. Registering individual SIP phones instead of a trunk is register-a-sip-endpoint-and-receive-calls; a FreeSWITCH box has its own connector resource (connect-freeswitch-to-signalwire).

What to change first

Replace connect: { to: "${call.to}" } in the inbound document with an ai verb: every extension on the PBX can now dial an AI agent by number.

Where this sits

Before this

Transfer a call

Route a call to an AI agent

Build an IVR menu

python/app.py

"""Connect a PBX with a Domain Application.

Inbound from the PBX: a Domain Application is a SIP domain on SignalWire that
accepts INVITEs from your PBX's IP addresses (IP auth) and hands each call to
a SWML document. Outbound to the PBX: a SIP Gateway resource is an address your
SWML can `connect` to, which SignalWire delivers to your PBX's SIP URI.

Written against signalwire-sdk 3.0.1. The typed RestClient wraps SIP Gateways
(fabric.sip_gateways) but not Domain Applications, so that call goes through
the same authenticated HTTP layer by path.

    python app.py setup   # create both resources; print the SIP domain and gateway
"""
import os
import sys

from dotenv import load_dotenv
from signalwire import SWMLService
from signalwire.rest import RestClient

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

client = RestClient()

PBX_IPS = os.getenv("PBX_IPS", "203.0.113.10,203.0.113.11").split(",")
PBX_SIP_URI = os.getenv("PBX_SIP_URI", "sip:pbx.example.com:5060")
PUBLIC_URL = os.getenv("PUBLIC_URL", "https://your-host.example.com")
# the SIP domain becomes <IDENTIFIER>.dapp.signalwire.com
IDENTIFIER = os.getenv("DOMAIN_IDENTIFIER", "acme-pbx")
GATEWAY_NAME = os.getenv("GATEWAY_NAME", "acme-pbx-gateway")


def create_domain_application():
    """Inbound: PBX -> SignalWire. IP-authenticated; calls run our SWML."""
    return client._http.post("/api/relay/rest/domain_applications", body={
        "name": "Acme PBX inbound",
        "identifier": IDENTIFIER,
        "ip_auth_enabled": True,
        "ip_auth": PBX_IPS,
        "call_handler": "relay_script",
        "call_request_url": f"{PUBLIC_URL}/from-pbx",
        "call_request_method": "POST",
        "encryption": "optional",
        "codecs": ["PCMU", "PCMA", "OPUS"],
    })


def create_sip_gateway():
    """Outbound: SignalWire -> PBX. A Fabric resource with a dialable address."""
    return client.fabric.sip_gateways.create(
        name=GATEWAY_NAME,
        uri=PBX_SIP_URI,
        encryption="optional",
        ciphers=["AEAD_AES_256_GCM_8", "AES_256_CM_HMAC_SHA1_80"],
        codecs=["PCMU", "PCMA", "OPUS"],
    )


def build_from_pbx(service=None):
    """SWML the Domain Application runs for a call arriving from the PBX:
    bridge it to the PSTN number the PBX dialled."""
    service = service or SWMLService(name="from-pbx", route="/from-pbx")
    service.reset_document()
    service.add_verb("answer", {})
    service.add_verb("connect", {"to": "${call.to}"})
    service.add_verb("hangup", {})
    return service


def build_to_pbx(service=None, gateway_address=None):
    """SWML for a PSTN number that should ring into the PBX via the gateway."""
    service = service or SWMLService(name="to-pbx", route="/to-pbx")
    service.reset_document()
    service.add_verb("answer", {})
    service.add_verb("connect", {"to": gateway_address or f"/private/{GATEWAY_NAME}"})
    service.add_verb("hangup", {})
    return service


if __name__ == "__main__":
    if sys.argv[1:] == ["setup"]:
        dapp = create_domain_application()
        gw = create_sip_gateway()
        domain = dapp.get("domain") or f"{IDENTIFIER}.dapp.signalwire.com"
        print("PBX should send INVITEs to:", domain)
        print("SWML can connect to the PBX at:", f"/private/{GATEWAY_NAME}", gw.get("id"))
    else:
        build_from_pbx().serve(port=int(os.getenv("PORT", "8080")))

# Connect a PBX - the two SWML documents that sit on either side of the SIP link.
# `main` is what the Domain Application runs when the PBX sends a call in: bridge
# it to whatever PSTN number the PBX dialled. `to_pbx` is what a PSTN number runs
# to ring into the PBX through the SIP Gateway resource created by app.py.
version: "1.0.0"
sections:
  main:
    - answer: {}
    - connect: { to: "${call.to}" }
    - hangup: {}
  to_pbx:
    - answer: {}
    - connect: { to: "/private/acme-pbx-gateway" }
    - hangup: {}

Run it

cd python
pip install -r requirements.txt
export SIGNALWIRE_SPACE=... SIGNALWIRE_PROJECT_ID=... SIGNALWIRE_API_TOKEN=...
export PBX_IPS=203.0.113.10 PBX_SIP_URI=sip:pbx.example.com:5060 PUBLIC_URL=https://<your-host>
export SWML_BASIC_AUTH_USER=signalwire SWML_BASIC_AUTH_PASSWORD=choose-something-long
python app.py setup      # prints the SIP domain for the PBX and the gateway address for SWML
python app.py            # serves the inbound SWML at /from-pbx

On the PBX, add a trunk to the printed .dapp.signalwire.com domain. Point a SignalWire number’s SWML webhook at a document that connects to the gateway address (the to_pbx section of swml/agent.yaml). The served document sits behind the basic-auth credentials above, so a webhook URL into this app carries them as https://<user>:<password>@<your-host>/from-pbx/.

Verify it

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

With the HTTP layer recorded, setup must make exactly the two documented requests, with the documented required fields checked against tools/openapi/rest.json. The verifier also asserts:

IP auth is enabled with our PBX addresses
our SWML URL is the handler
both SWML documents validate and connect in the right direction

Report an issue