Build an IVR without a server

Voiceserverless IVR

Create and assign a serverless IVR call flow through REST, without hosting a webhook server.

serverless

The claim

The vendored REST spec’s POST /api/fabric/resources/call_flows requires one field, title, and takes relayml, “The calling SWML document this Call Flow should execute”. That sentence is the serverless part: the flow executes the document, and nothing of yours serves it. POST /api/fabric/resources/{id}/phone_routes requires phone_route_id and handler, an enum of calling and messaging. Its prose says “incoming calls or messages”; the enum is what the API accepts. The document has four top-level verbs. They are answer, a prompt whose schema requires play and collects one digit, a switch whose schema requires variable and case, and hangup. You reach the REST calls as client.fabric.call_flows.create and client.fabric.resources.assign_phone_route.

How it works

service.add_verb("prompt", {"play": f"say:{MENU}", "max_digits": 1, "initial_timeout": 8})
service.add_verb("switch", {
    "variable": "prompt_value",
    "case": {digit: [{"connect": {"to": number, "timeout": 25}}]
             for digit, number in DESKS.items()},
    "default": [{"play": {"url": f"say:{FALLBACK}"}}],
})

FLOW_DATA = {"generated_by": "signalwire-recipes",
             "recipe": "build-an-ivr-without-a-server"}

def deploy(title="Ridgeline Cycles IVR"):
    return client.fabric.call_flows.create(
        title=title, relayml=build().get_document(), flow_data=FLOW_DATA)

def point_number(resource_id, e164):
    return client.fabric.resources.assign_phone_route(
        resource_id, phone_route_id=number_id(e164), handler="calling")

What the platform receives:

POST /api/fabric/resources/call_flows
{"title": "Ridgeline Cycles IVR",
 "relayml": {"version": "1.0.0", "sections": {"main": [
   {"answer": {}},
   {"prompt": {"play": "say:Thanks for calling ...", "max_digits": 1, "initial_timeout": 8}},
   {"switch": {"variable": "prompt_value",
               "case": {"1": [{"connect": {"to": "+1555...", "timeout": 25}}],
                        "2": [{"connect": {"to": "+1555...", "timeout": 25}}]},
               "default": [{"play": {"url": "say:Sorry, that was not an option. Goodbye."}}]}},
   {"hangup": {}}]},
 "flow_data": {"generated_by": "signalwire-recipes", "recipe": "build-an-ivr-without-a-server"}}

POST /api/fabric/resources/<resource_id>/phone_routes
{"phone_route_id": "<id of your number>", "handler": "calling"}

The SWML prompt reference documents prompt_value as the variable that holds what the prompt collected, so switch reads it by name. SWMLService.add_verb raises SchemaValidationError for a verb the bundled schema rejects, so a wrong field fails on your machine, not after deployment. number_id looks the number up with the spec’s filter_number and compares exactly.

Limitations

You prove the document and the requests. What the caller hears, and whether a desk answers, are the platform’s side of a live call.

The spec describes flow_data as “Call Flow Builder state, stored as an opaque JSON object”, and says to send it with relayml or send neither. The script sends a small descriptor beside the document; the document is the source.

What to change first

Add a third desk to DESKS under "3" and run the verifier. The switch assertion fails, because the verifier pins two cases. Add the case there too. The same document then deploys with three.

Where this sits

Before this

Answer an inbound call

Collect speech input and branch on it Route calls by dialed number or time

python/app.py

"""Build an IVR without a server.

A call flow is a SWML document you hand to the platform. The vendored REST
spec describes `relayml` as "The calling SWML document this Call Flow should
execute", so no server of yours serves it. `POST /api/fabric/resources/call_flows`
requires a `title`. The response is a Fabric resource with an `id`.
`POST /api/fabric/resources/{id}/phone_routes` then points a number at it; the
spec requires `phone_route_id` and `handler`, and `calling` is the handler for
voice.

You build the document with `SWMLService`, whose `add_verb` raises
`SchemaValidationError` on a verb the bundled schema rejects. The verbs are
answer, a `prompt` for one digit, a `switch` on `prompt_value` with a `connect`
per desk, and a spoken fallback.

Written against signalwire-sdk 3.0.1 (SWMLService, RestClient.fabric).
"""
import os

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

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

# RestClient() reads SIGNALWIRE_PROJECT_ID / SIGNALWIRE_API_TOKEN /
# SIGNALWIRE_SPACE from the environment (signalwire/rest/client.py).
client = RestClient()

DESKS = {"1": os.getenv("SALES_NUMBER", "+15550100001"),
         "2": os.getenv("WORKSHOP_NUMBER", "+15550100002")}
MENU = "Thanks for calling Ridgeline Cycles. Press 1 for sales, or 2 for the workshop."
FALLBACK = "Sorry, that was not an option. Goodbye."


def build(service=None):
    """The IVR as a SWML document, validated verb by verb."""
    service = service or SWMLService(name="ivr", route="/ivr")
    service.reset_document()
    service.add_verb("answer", {})
    service.add_verb("prompt", {"play": f"say:{MENU}", "max_digits": 1,
                                "initial_timeout": 8})
    service.add_verb("switch", {
        "variable": "prompt_value",
        "case": {digit: [{"connect": {"to": number, "timeout": 25}}]
                 for digit, number in DESKS.items()},
        "default": [{"play": {"url": f"say:{FALLBACK}"}}],
    })
    service.add_verb("hangup", {})
    return service


# The spec pairs relayml with flow_data: provide both or omit both. flow_data is
# the Call Flow Builder's canvas state and is opaque to the API, so a flow
# authored in code sends a small descriptor rather than a canvas.
FLOW_DATA = {"generated_by": "signalwire-recipes",
             "recipe": "build-an-ivr-without-a-server"}


def deploy(title="Ridgeline Cycles IVR"):
    """Create the call flow from the document. Returns the resource."""
    return client.fabric.call_flows.create(
        title=title, relayml=build().get_document(), flow_data=FLOW_DATA)


def number_id(e164):
    """The resource id of a number on your project, by exact match."""
    for item in client.phone_numbers.list(filter_number=e164).get("data", []):
        if item.get("number") == e164:
            return item["id"]
    raise LookupError(f"{e164} is not a number on this project")


def point_number(resource_id, e164):
    """Route a number's calls to the call flow."""
    return client.fabric.resources.assign_phone_route(
        resource_id, phone_route_id=number_id(e164), handler="calling")


if __name__ == "__main__":
    import json
    import sys

    if len(sys.argv) == 2 and sys.argv[1] == "document":
        print(json.dumps(build().get_document(), indent=2))
    elif len(sys.argv) == 2 and sys.argv[1] == "deploy":
        print(deploy())
    elif len(sys.argv) == 4 and sys.argv[1] == "point":
        print(point_number(sys.argv[2], sys.argv[3]))
    else:
        raise SystemExit("usage: python app.py document | deploy | "
                         "point <resource_id> <+1number>")

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # then edit .env: credentials and the two desk numbers
python app.py document           # the SWML, to read
python app.py deploy             # prints the resource, including its id
python app.py point <resource_id> +1XXXXXXXXXX

There is no server to expose or keep running; the script speaks to the REST API and exits, and the platform runs the document. Call the number and press 1.

Verify it

No network, no account.

cd ..                     # back to the recipe folder
python verify.py

The verifier validates the document and swaps the SDK’s HTTP layer for a recorder. It asserts the following.

the document validates and its verbs are answer, prompt, switch, hangup
the prompt is exactly the menu, one digit and an eight-second initial timeout
the switch reads prompt_value, connects 1 and 2 to their desks with a 25-second timeout, and defaults to the fallback
add_verb raises SchemaValidationError for a prompt with no play, and the document keeps its four verbs
deploy makes one POST to the documented call flows path with exactly title, that document as relayml, and the flow_data descriptor
point_number makes one GET of the phone numbers list with exactly filter_number and picks the exact match over a near miss
it then makes one POST to the documented phone routes path with exactly phone_route_id and handler: calling, and asserts calling is in the spec’s enum
the spec requires exactly title on the flow and exactly phone_route_id and handler on the route
the spec says relayml and flow_data travel together or not at all
the spec describes relayml as the SWML document the flow should execute
the bundled schema requires play on prompt, and variable and case on switch

Report an issue