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, sharing the same media-edge origination logic.

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.

Virtual hold: offered automatically at join

The callback option above is reactive: a caller presses a key while already holding. Virtual hold is proactive: the queue itself offers a callback the moment a caller joins, if their estimated wait is already long, before they ever hear hold music.

{
  "id": "q_01j160r23gw5zkpfjme3fwzs5k",
  "virtual_hold": 1,
  "virtual_hold_threshold_sec": 300,
  "virtual_hold_digit": "1",
  "virtual_hold_prompt": "media_01j22nwntmjd633gxwfhk8zya1"
}

Field	Purpose
virtual_hold	1 to enable the proactive offer on this queue.
virtual_hold_threshold_sec	Offer it only when the estimated wait exceeds this; 0/unset offers it on every join.
virtual_hold_digit	The key to press to accept (default 1).
virtual_hold_prompt	The prompt played at join (e.g. “Your wait is about 5 minutes, press 1 for a callback and keep your place.”).

Accepting converts the caller to the same courtesy-callback mechanism as the manual callback option above: they keep their place, hang up, and get called back when an agent frees. Declining (or not pressing anything) just continues into the normal hold experience.

Status & roadmap

The control-plane side is live: the in_queue_option model, the route / webhook / deflect / hangup actions, the webhook with optional bearer, stay_in_queue handling, and virtual hold’s proactive join-time offer. The enqueue command advertises the configured digits to the media edge, which binds them during hold (or plays the virtual-hold offer prompt at join) and reports a digit: outcome.

On the roadmap: scheduled callbacks (pick a specific time rather than “next available”).

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.