docs(voice): add call queues guide

[Devon-White]

Summary

• New guide, Queue calls (/docs/platform/voice/call-queues), modeled on Detect machines (approach-first). Bayview Taxi's dispatch queue is the running example.
  • Shared sections: choose an approach, prepare, how call queues work, and create a queue with the Server SDKs or REST.
  • SWML: put a caller in a queue (enter_queue with wait_time and a busy fallback), connect an agent (REST dial with inline SWML connect to queue:dispatch), take a caller out (queue_result outcomes, calling.end), and track the queue (status_url events and the variables enter_queue sets).
  • WebSocket (Relay): the same four tasks. The app plays its own hold music and enforces the wait limit, removes callers with queue_leave(), and connects the agent with connect() and a queue device.
  • Monitor and manage queues via REST: an operation table plus three task sections, with response snippets for the queue and member objects:
    • Get a queue's size and wait time: list and get queues, and find a queue's ID from its name.
    • List the callers waiting in a queue: the member list, position 1 as the next caller, and get one member.
    • Update or delete a queue: name is required on every update, and a queue must be empty to delete.
• Adds a "Queue calls" card to the voice overview's Popular guides.
• Repoints the fern/llms.txt "Call queues" bullet from the Relay queue_enter reference to the new guide, titled "Queue calls".
• Agent rules: unverifiable facts stay out of the page and go in the PR's notes instead of a [NEEDS SOURCE] placeholder, and PR bodies don't cite internal repositories.

Notes for reviewers

Queue behavior the guide relies on, traced in the platform source:

• Relay queues: queue.enter plays no hold audio and ignores wait_time; both apply only to SWML enter_queue. That's why the Relay sample loops its own music and runs its own timer. queue.enter also doesn't answer the call.
• Agent connects: Relay calling.connect accepts a {type: "queue"} device. On an empty queue, it reports connect_state: failed, and SWML connect sets connect_result: failed and continues to the next instruction. Neither waits for a caller. Callers are taken in FIFO order.
• Shared queues: SWML, Relay and the REST Queues API share one namespace: exact name match, auto-created on first use.

Upstream issues worked around or left out:

• Python SDK builder bug: signalwire-sdk 3.4.1, and still 3.6.0, validates enter_queue against a stale schema that requires transfer_after_bridge, so every valid enter_queue is rejected. Filed as enter_queue fails schema validation: bundled schema requires transfer_after_bridge signalwire-python#112. The Python sample sets schema_validation=False on its SWMLService, with a comment linking the issue. The TypeScript builder is fine.
• "Get next queue member" not used: GET /api/relay/rest/queues/{queue_id}/members/next isn't served; the request is treated as Get queue member with an ID of next and fails. The guide finds the next caller from the member list instead (position 1). The spec needs a fix, or the API needs the route.
• Behavior the REST spec doesn't document:
  • Update requires name on every request.
  • Both list endpoints return newest first, 50 per page (max 1000).
  • List queues accepts an undocumented filter_name (partial match). The guide doesn't use it.
• max_size left undescribed: nothing appears to enforce it, so the guide doesn't say what happens to a caller who enters a full queue.
• Left out on purpose:
  • Removing a caller by redirecting their call with REST update: untested.
  • The Compatibility API "Update a Queue Member": doesn't apply to SWML/Relay callers.
  • The undocumented whisper_url parameter.
• Reference-page follow-ups (not in this PR):
  • The enter_queue reference lists queue_result values that can't occur (entering, connecting, leaving).
  • The Relay queue_enter reference mentions "position updates", but none are sent.

Verification

• Extracted every fenced block: Python py_compile and pyflakes clean; TypeScript tsc --strict against @signalwire/sdk@2.0.5; YAML and JSON parse.
• Builder output from both SDKs matches the hand-written JSON beside it. Both SWMLService samples were served locally, and the fetched document matched.
• Ran every complete sample end to end, in both SDKs, against a local TLS mock of Relay and REST that follows the platform's queue behavior:
  • REST: create queue, list members, calling.end, and agent dial with inline SWML.
  • Relay: wait limit reached, agent connects to a waiting caller, agent connects to an empty queue, caller hangs up while waiting.
• Not yet tested with live calls.
• yarn fern-md-check passes. yarn fern-check fails only on the FDR redirects check, which couldn't reach the network (403).
• Internal links checked against target slugs, and in-page anchors checked by hand.

Preview

• /docs/platform/voice/call-queues
• /docs/platform/voice (new card)

[github-actions]

🌿 Preview

https://signalwire-preview-docs-780.docs.buildwithfern.com/docs

---

View workflow run

[hey-august]

Looks great, all notes have been addressed!