Queue a call until an agent is free

Voicecall queuing

Callers wait in a named queue with hold audio and are bridged in order as agents connect to it.

Also called call queue with hold music, hold music, ACD queue

queue

The claim

Queues are native. A caller enters a named queue with enter_queue; an agent takes the next waiting caller with connect: { to: "queue:<name>" }. The platform keeps the order, plays the hold document, and bounds the wait. No queue service of your own, no polling.

How it works

Three small documents:

main:                                  # what a caller runs
  - answer: {}
  - enter_queue:
      queue_name: support
      wait_url: "https://<your-host>/wait"   # re-run while the caller waits
      wait_time: 600                         # seconds before giving up
      transfer_after_bridge: "false"
  - play: { url: "say:Sorry, no one could take your call. Goodbye." }   # fall-through
wait:                                  # served at wait_url
  - play: { url: "https://.../hold-music.mp3" }
agent:                                 # what an agent dials
  - answer: {}
  - connect: { to: "queue:support" }

The verbs after enter_queue run only if wait_time expires with nobody answering, and that is where you offer a callback instead (offer-a-callback-instead-of-a-hold). Queue depth and the next member are also readable over REST (/api/relay/rest/queues), and the Compatibility API has the same shape as <Enqueue> / <Dial><Queue>.

What to change first

Lower wait_time and put an offer-a-callback-instead-of-a-hold flow in the fall-through, so nobody waits more than a few minutes without being offered a way out.

Where this sits

Before this

Answer an inbound call

Offer a callback instead of a hold Hand off from AI to a human agent

Transfer a call

swml/agent.yaml

# Queue a call until an agent is free.
# Two documents in one file: `main` is what a caller runs; `agent` is what an
# agent runs to take the next caller. The platform re-runs wait_url while the
# caller waits, so wait_url points at a document that plays hold audio.
version: "1.0.0"
sections:
  main:
    - answer: {}
    - play: { url: "say:All of our agents are busy. Please stay on the line." }
    - enter_queue:
        queue_name: support
        wait_url: "https://your-host.example.com/wait"
        wait_time: 600
        transfer_after_bridge: "false"
    - play: { url: "say:Sorry, no one could take your call. Goodbye." }
    - hangup: {}
  # Serve this section at wait_url. It plays once; the platform loops it.
  wait:
    - play: { url: "https://cdn.signalwire.com/default-music/welcome.mp3" }
  # An agent dials a number pointed at this section and gets the next caller.
  agent:
    - answer: {}
    - connect: { to: "queue:support" }
    - hangup: {}

"""Queue a call until an agent is free.

Three small documents served from one Flask app:

  /caller  answer, then enter_queue("support") with a wait_url for hold audio.
           If nobody takes the call within wait_time, execution continues and
           the caller hears an apology.
  /wait    the hold document; the platform re-runs it while the caller waits.
  /agent   what an agent dials: connect to "queue:support" takes the next
           waiting caller.

Written against signalwire-sdk 3.0.1 (SWMLService) 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()

PUBLIC_URL = os.getenv("PUBLIC_URL", "https://your-host.example.com")
QUEUE = os.getenv("QUEUE_NAME", "support")
HOLD_MUSIC = os.getenv("HOLD_MUSIC_URL",
                       "https://cdn.signalwire.com/default-music/welcome.mp3")
MAX_WAIT_SECONDS = int(os.getenv("MAX_WAIT_SECONDS", "600"))

app = Flask(__name__)


def build_caller(service=None):
    service = service or SWMLService(name="queue-caller", route="/caller")
    service.reset_document()
    service.add_verb("answer", {})
    service.add_verb("play", {
        "url": "say:All of our agents are busy. Please stay on the line."})
    service.add_verb("enter_queue", {
        "queue_name": QUEUE,
        "wait_url": f"{PUBLIC_URL}/wait",
        "wait_time": MAX_WAIT_SECONDS,
        "transfer_after_bridge": "false",
    })
    # Reached only if the wait ran out.
    service.add_verb("play", {"url": "say:Sorry, no one could take your call. Goodbye."})
    service.add_verb("hangup", {})
    return service


def build_wait(service=None):
    service = service or SWMLService(name="queue-wait", route="/wait")
    service.reset_document()
    service.add_verb("play", {"url": HOLD_MUSIC})
    return service


def build_agent(service=None):
    service = service or SWMLService(name="queue-agent", route="/agent")
    service.reset_document()
    service.add_verb("answer", {})
    service.add_verb("connect", {"to": f"queue:{QUEUE}"})
    service.add_verb("hangup", {})
    return service


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


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


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


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

Run it

Markup only: paste swml/agent.yaml into a SWML Script. Assign one number to the main section (callers) and another to the agent section (agents); host the wait section at wait_url.

Python:

cd python
pip install -r requirements.txt
PUBLIC_URL=https://<your-host> QUEUE_NAME=support python app.py

Point the callers’ number at https://<your-host>/caller and the agents’ number at https://<your-host>/agent.

Verify it

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

All three documents validate against the SWML schema. The verifier asserts the queue name, a wait_url, a bounded wait_time, the fall-through after enter_queue, and that the agent document connects to queue:support.

Report an issue