In-Queue Options

A caller on hold shouldn’t be stuck. In-queue options let a waiting caller press a DTMF key to do something other than keep waiting: route out to voicemail, request a callback via a webhook, or hang up, all without losing their place until they choose to.

Each option is a row in in_queue_option, keyed by queue and digit:

{
  "queue_id": "q_01j160r23gw5zkpfjme3fwzs5k",
  "digit": "1",
  "action": "webhook",
  "webhook_url": "https://api.example.com/hooks/callback",
  "webhook_secret_ref": "kv:hook:callback:bearer",
  "stay_in_queue": 1,
  "prompt_media_id": "media_01j22nwntmjd633gxwfhk8zya1",
  "label": "Request a callback"
}

Field	Purpose
digit	The key that triggers it: 0–9, *, # (one row per digit per queue).
action	What pressing it does; see below.
dest_kind / dest_id	For action: "route", the route target to send the caller to.
webhook_url	For webhook / deflect, the URL that receives the keypress.
webhook_secret_ref	Optional bearer token for the webhook (a key-value secret reference, never the secret itself).
stay_in_queue	1 keeps the caller holding after the action (a “deflect”); 0 removes them.
prompt_media_id	Optional confirmation played after the press (e.g. “You’ll get a text shortly.”).
label	A human label for your own UI.

Actions

action	What happens
route	The caller leaves the queue (counted as handled, not abandoned) and continues into the target flow/queue/voicemail synthesized from dest_kind/dest_id.
webhook	A POST is fired off the call path; what the caller hears next is governed by stay_in_queue.
deflect	A webhook that keeps the caller holding (stay_in_queue: 1): fire the request, play the optional confirmation, resume hold music.
callback	Virtual queue / courtesy callback: the caller hangs up but keeps their place, and is called back when an agent frees up.
hangup	Disconnect the caller.

Virtual queue (callback)

The callback action turns waiting into a courtesy callback: the caller presses a key, hangs up, and holds their position in the queue. When an agent reaches the front of that caller’s place, the platform calls the caller back and bridges them to the agent, with no more hold music and no lost position.

• The waiting record is marked virtual and kept in place; the queue reaper leaves it alone.
• When an agent frees, the brain reserves the agent (the same reserve→confirm fence as inbound) and originates the callback to the caller’s number.
• If the caller answers, they’re bridged to the held agent; if the reservation has gone stale, the caller’s place returns to waiting for the next agent.

This reuses the outbound dialer originate path. The control-plane logic is built; the media-edge originate is shared with the dialer’s Phase-1 wiring.

When the caller presses a key the queue distributor never offered them to an agent, so choosing an option is clean: route dequeues with a bridged disposition (not an abandon), keeping your abandon rate honest.

The webhook

For webhook / deflect, SIP.IO POSTs the call context to your webhook_url:

{
  "event": "in_queue_option",
  "call_id": "…",
  "account_id": "acc_01jf18ah3jeb5w6dfp27sgjsbt",
  "queue_id": "q_01j160r23gw5zkpfjme3fwzs5k",
  "digit": "1",
  "caller": "12025550123",
  "ts": 1782627351000
}

If webhook_secret_ref is set, the request carries Authorization: Bearer <secret> (resolved from the encrypted secret store). The webhook is fire-and-forget: your endpoint records the request (e.g. enqueues a callback) and the caller’s experience is decided locally by stay_in_queue, not by the webhook’s response.

• stay_in_queue: 1 (deflect) → optional prompt_media_id plays, then the caller returns to hold in their original position.
• stay_in_queue: 0 → the caller is dequeued and the call ends after the webhook fires.

Status & roadmap

The control-plane side is live: the in_queue_option model, the route / webhook / deflect / hangup actions, the webhook with optional bearer, and stay_in_queue handling. The enqueue command advertises the configured digits to the media edge, which binds them during hold and reports a digit: outcome.

The route / webhook / deflect / hangup actions and the virtual-queue callback are built. On the roadmap:

• Media-edge DTMF binding + an options announcement (“press 1 for a callback…”) played over hold music.
• Estimated-wait-time announcements and scheduled callbacks.