Place an outbound call

Voiceprogrammatic outbound calling

Dial a number from your own code and follow the call through to completion.

outbound

The claim

Your backend decides a call should happen, and one request makes it happen. The same request carries the SWML the call runs once someone picks up. There is no second fetch, and no URL of yours to keep online for it.

Why it holds

The reverse of answer-an-inbound-call: there the platform came to you, here you go to the platform.

How it works

client.calling.dial() posts a dial command to /api/calling/calls. It takes either url or swml, and the choice is about whether the call needs anything looked up.

client.calling.dial(**{
    "from": FROM,
    "to": to,
    "swml": reminder_document(message),
    "status_url": f"{PUBLIC_URL}/call-status",
    "status_events": ["ringing", "answered", "ended"],
    "timeout": 25,
})

url makes the platform fetch a document from you when the call connects, which is what you want when the greeting depends on who answered. swml puts the document in the request itself. A reminder has nothing to look up, so it travels inline and no server is involved after the POST returns.

from is a Python keyword, so the parameters go in through a dict rather than as keyword arguments.

timeout is the ring timeout, documented as 1 to 600 seconds. Leaving it at the default is how outbound calls end up talking to voicemail: 25 seconds stops ringing while a person could still plausibly answer.

The call’s lifecycle goes to status_url, filtered by status_events. The documented events are created, ringing, answered and ended. Receiving them is handle-call-status-callbacks.

Limitations

An inline document is fixed at dial time. Anything that depends on who picked up belongs behind url, where you answer with a document built for that call.

dial accepting the request does not mean anyone answered. Busy, no-answer and failed all arrive later on status_url, which is why the recipe sets one.

What to change first

Swap swml for url and point it at the route from answer-an-inbound-call. The call behaves the same and the document now comes from your server, which is the trade this parameter is making.

Where this sits

Seen in a build

One of 8 recipes composed by Order status desk: one omnichannel AI agent for web chat and phone.

python/app.py

"""Place an outbound call and hand it a document.

One POST originates the call. The same request carries the SWML the call runs
once someone answers, so there is no second fetch and no URL to host.

`dial` takes either `url` or `swml`. `url` makes the platform fetch a document
from you when the call connects; `swml` puts the document in the request. This
recipe uses `swml`, because a reminder call has nothing to look up.

Written against signalwire-sdk 3.0.1 (RestClient.calling).
"""
import os

from dotenv import load_dotenv
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 when not passed explicitly.
client = RestClient()

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


def reminder_document(message):
    """The document the call runs when it is answered."""
    return {
        "version": "1.0.0",
        "sections": {
            "main": [
                {"answer": {}},
                {"play": {"url": f"say:{message}"}},
                {"hangup": {}},
            ]
        },
    }


def place(to, message):
    """Originate the call. `from` is a Python keyword, so it goes in a dict."""
    return client.calling.dial(**{
        "from": FROM,
        "to": to,
        "swml": reminder_document(message),
        # where the lifecycle is reported; see handle-call-status-callbacks
        "status_url": f"{PUBLIC_URL}/call-status",
        "status_events": ["ringing", "answered", "ended"],
        # stop ringing rather than rolling to the callee's voicemail
        "timeout": 25,
    })


if __name__ == "__main__":
    import sys

    to = sys.argv[1] if len(sys.argv) > 1 else "+15552223333"
    result = place(to, "This is a reminder that your bike is ready for pickup.")
    print(result)

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # add your credentials and From number
python app.py +15552223333

Verify it

No network, no account:

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

With the HTTP layer replaced by a recorder, place() must make exactly one request. The verifier asserts:

one POST to /api/calling/calls with command: dial
every parameter is a documented property of the SWML dial variant, and its required fields are present, read from tools/openapi/rest.json
the document travels as swml, with no url alongside it
that document is itself valid SWML, so the call has something real to run
status_events uses only the four documented event names
timeout is inside the documented range

Report an issue