Answer an inbound call

Voiceinbound call handling

Accept an incoming call, greet the caller, and hang up cleanly.

The claim

The smallest complete call. A number rings, SignalWire fetches a document from your URL, and the document answers the call, speaks a line and hangs up. Three verbs, no account state, no AI.

Why it holds

A queue, an agent or a transfer is this document with more verbs in it.

How it works

SignalWire fetches the document when the call arrives and runs sections.main in order.

sections:
  main:
    - answer:
        max_duration: 300
    - play:
        url: "say:Thanks for calling Ridgeline Cycles. We are open until six."
    - hangup: {}

answer decides when the call is picked up. It is not a prerequisite for audio: play carries auto_answer, true by default, so a document that opens with play answers the call on its way to speaking. Answering explicitly is worth the line because it puts the moment under your control.

play speaks its url when the value starts with say:. Any other URL is a file to fetch and play instead. That is how you swap a synthesised voice for a recorded one, without touching the rest.

hangup ends the call. Leave it out and the call stays open, silent, until max_duration expires. That is why max_duration is set at all. It is a backstop against a call nobody ended, not a feature of this greeting.

The Python surface builds the same three verbs through SWMLService. The greeting comes from the environment, and the document is validated against the SWML schema before it is served.

Limitations

The bundled schema requires play to be an object with a url. The shorter play: "say:..." form appears in the docs and will not pass local validation, so prefer the object form in anything you lint.

There is no input here. Collecting a digit or a phrase is build-an-ivr-menu and collect-speech-input-and-branch.

What to change first

Set auto_answer: false on the play and remove the answer above it. The greeting now plays as early media, before the call is answered. That is how you say something to a caller you are not yet billing for.

python/app.py

"""Answer an inbound call.

SignalWire fetches a SWML document when the number rings and runs its verbs in
order: answer the call, say something, hang up.

`SWMLService` builds the same document the YAML surface holds, with one
advantage: the greeting comes from the environment and every verb is validated
against the SWML schema before it is served.

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

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

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

GREETING = os.getenv(
    "GREETING",
    "Thanks for calling Ridgeline Cycles. We are open until six.",
)
MAX_DURATION = int(os.getenv("MAX_DURATION", "300"))

app = Flask(__name__)


def build(service=None):
    service = service or SWMLService(name="greeting", route="/greeting")
    service.reset_document()
    # until this runs the call is still ringing
    service.add_verb("answer", {"max_duration": MAX_DURATION})
    # "say:" speaks the text; a URL would play a file
    service.add_verb("play", {"url": f"say:{GREETING}"})
    # without this the call sits open until max_duration expires
    service.add_verb("hangup", {})
    return service


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


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

# Answer an inbound call, greet the caller, hang up.
#
# The smallest complete call. SignalWire fetches this document when the number
# rings and runs the verbs in order.
version: "1.0.0"
sections:
  main:
    # Until this runs the call is still ringing, and the caller is not
    # billed or connected. max_duration is a backstop against a stuck call.
    - answer:
        max_duration: 300
    # "say:" is text to speak. A real URL here would play a file instead.
    # The object form is used because the SDK's bundled schema requires it;
    # the bare `play: "say:..."` shorthand in the docs does not validate.
    - play:
        url: "say:Thanks for calling Ridgeline Cycles. We are open until six."
    # Without this the call sits open until max_duration expires.
    - hangup: {}

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env
python app.py

Point a phone number’s SWML webhook at https://<your-host>/greeting.

Verify it

No network, no account:

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

Both surfaces validate against the SDK’s bundled SWML schema. The verifier asserts:

the verbs are exactly answer, play, hangup, in that order
answer precedes play, so the call is answered explicitly
max_duration is set to a positive integer
the played URL is a say: string with something after the colon
a POST to the route, which is how SignalWire fetches it, returns the document

Report an issue