Dial destinations in order or all at once, with a failure path

Voicesequential and simultaneous ring

Dial destinations sequentially or simultaneously, then run a failure branch if no connection succeeds.

Also called ring group, hunt group, find me follow me, failover dialing

failover

The claim

One connect verb carries the whole hunt. The connect reference describes serial as destinations “to dial in order”, each “tried sequentially”. It describes parallel as destinations “to dial simultaneously”, where “the first destination to answer is bridged and the rest are cancelled”. The to field accepts phone numbers, SIP URIs and Resource addresses; this list mixes the first two.

Why it holds

When the bridge ends, result runs against connect_result, which the reference gives as connected or failed, with connect_failed_reason carrying the “detailed reason for failure”. The failed case is the failure path, whatever the reason.

How it works

- connect:
    timeout: 15
    serial:
      - { to: "+15550100001" }
      - { to: "sip:workshop@pbx.example.com" }
      - { to: "+15550100003" }
    result:
      case:
        connected:
          - play: { url: "say:Thanks for calling Ridgeline Cycles. Goodbye." }
          - hangup: {}
        failed:
          - play: { url: "say:Nobody could take your call. Please try again later." }
          - hangup: {}

result runs “once the peer leg of the call has ended”, per the reference. For connected that is after the conversation; for failed it is after the last destination fails. The parallel section dials the two phone numbers together and keeps only a failed branch.

The schema defines connect as a oneOf over four shapes: a single to, a serial list, a parallel list, or serial_parallel. A verb carrying both to and serial fails validation, which the verifier shows.

The Python surface builds the same document with SWMLService, reading the list from DESTINATIONS. The verifier asserts the two documents are equal.

Limitations

The verifier proves the document, not the dialling. On a live call, connect_failed_reason carries the detail when the connect fails; this recipe does not read it.

A queue: destination needs transfer_after_bridge, per the reference, and is not part of this list.

What to change first

Swap the first two serial entries in both surfaces and run the verifier. The order assertion fails, which is the point: the list is the hunt order, and nothing else decides it.

Where this sits

Before this

Transfer a call

Queue a call until an agent is free

swml/agent.yaml

# Try destinations in order. `connect` takes a `serial` list of destinations
# to dial in order. When the bridge ends, `result` runs: `connect_result` is
# "connected" or "failed", and the "failed" branch is the failure path.
version: "1.0.0"
sections:
  main:
    - answer: {}
    - play: { url: "say:One moment while I find someone to help you." }
    - connect:
        timeout: 15
        serial:
          - { to: "+15550100001" }
          - { to: "sip:workshop@pbx.example.com" }
          - { to: "+15550100003" }
        result:
          case:
            connected:
              - play: { url: "say:Thanks for calling Ridgeline Cycles. Goodbye." }
              - hangup: {}
            failed:
              - play: { url: "say:Nobody could take your call. Please try again later." }
              - hangup: {}
  # Variant: dial the phone destinations at once.
  parallel:
    - answer: {}
    - connect:
        timeout: 20
        parallel:
          - { to: "+15550100001" }
          - { to: "+15550100003" }
        result:
          case:
            failed:
              - play: { url: "say:Nobody could take your call." }
              - hangup: {}
    - hangup: {}

"""Try destinations in order.

`connect` takes a `serial` list of destinations to dial in order, or a
`parallel` list to dial at once, per the connect reference. When the bridge
ends, `result` runs against `connect_result`, which is "connected" or
"failed", and `connect_failed_reason` carries the detail.

The `to` field accepts phone numbers, SIP URIs and Resource addresses; this
list mixes the first two.

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

from dotenv import load_dotenv
from signalwire import SWMLService

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

# Comma-separated, tried in this order.
DESTINATIONS = [d.strip() for d in os.getenv(
    "DESTINATIONS", "+15550100001,sip:workshop@pbx.example.com,+15550100003"
).split(",") if d.strip()]
RING_SECONDS = int(os.getenv("RING_SECONDS", "15"))

GOODBYE = "say:Thanks for calling Ridgeline Cycles. Goodbye."
NOBODY = "say:Nobody could take your call. Please try again later."


def build(service=None):
    service = service or SWMLService(name="hunt", route="/hunt")
    service.reset_document()

    service.add_verb("answer", {})
    service.add_verb("play", {"url": "say:One moment while I find someone to help you."})
    service.add_verb("connect", {
        "timeout": RING_SECONDS,
        "serial": [{"to": d} for d in DESTINATIONS],
        "result": {"case": {
            "connected": [{"play": {"url": GOODBYE}}, {"hangup": {}}],
            "failed": [{"play": {"url": NOBODY}}, {"hangup": {}}],
        }},
    })

    # Variant: dial every phone destination at once; SIP entries are left out.
    service.add_section("parallel")
    service.add_verb_to_section("parallel", "answer", {})
    service.add_verb_to_section("parallel", "connect", {
        "timeout": RING_SECONDS + 5,
        "parallel": [{"to": d} for d in DESTINATIONS if not d.startswith("sip:")],
        "result": {"case": {
            "failed": [{"play": {"url": "say:Nobody could take your call."}},
                       {"hangup": {}}],
        }},
    })
    service.add_verb_to_section("parallel", "hangup", {})
    return service


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

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # set DESTINATIONS and RING_SECONDS
python app.py

The webhook needs a public HTTPS URL. For a local run, expose port 8080 with a tunnel such as ngrok and use that hostname. Point a number’s SWML webhook at https://<user>:<password>@<your-host>/hunt/, call, and let the first destination ring out.

Verify it

No network, no account.

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

It validates both surfaces against the bundled schema and asserts the following.

the main section is answer, play, connect, and the connect has no single to
serial holds the three destinations in the configured order, with a 15 second timeout
result.case has exactly connected and failed, and each branch is a play then a hangup
the parallel section carries the two phone numbers and keeps a failed branch
the Python surface and the YAML surface render the same document
a connect carrying both to and serial fails schema validation

Report an issue