Queues

Purpose

Describe queues: how inbound callers wait and are matched to agents, plus comfort announcements and the callback (“keep my place”) feature.

Overview

A queue (queues table) holds callers until a suitable agent is free. Each queue has an extension (the number callers reach via *86<ext>), a strategy (round_robin, least_busy, skills_based), a max_wait_secs, optional required_skills, and an overflow_target. Members are agents (queue_members, ordered by priority).

The waiting line lives in Redis (a sorted set scored by join time). The flow:

FreeSWITCH parks the caller (CHANNEL_PARK with g2d_queue_extension); the call engine resolves the queue and enqueues the caller, publishing caller_joined.
If an agent is already available, an opportunistic sweep assigns immediately; otherwise the worker waits for an agent to transition to available (via the t.<tenant>.agent.*.state subscription).
On a free agent, the worker picks a caller FIFO (with preferred-agent affinity), stamps routing channel variables, and bridges the caller to the agent’s SIP user through the local OpenSIPS. On bridge failure the caller is re-enqueued.

Configuration

Queues, members and strategy are configured in the tenant app (/api/v1/queues). Comfort announcements are tunable on the call engine:

QUEUE_ANNOUNCE_POSITION=true        # announce queue position
QUEUE_ANNOUNCE_EWT=true             # announce estimated wait
QUEUE_ANNOUNCE_INTERVAL=30s         # how often
QUEUE_ANNOUNCE_AVG_HANDLE_SECS=180  # EWT model input
QUEUE_CALLBACK_DIGIT=               # DTMF digit to request a callback (empty = off)

Examples

Callback (“keep my place”): a waiting caller presses QUEUE_CALLBACK_DIGIT; instead of holding, they’re removed from the live line and queued for callback. When an agent frees up and no live caller is waiting, the engine dials the callback number back and bridges it to the agent (up to 3 attempts). Live callers always win over callbacks.

Estimated wait is ceil(position ÷ agents) × avg_handle_secs, played via FreeSWITCH mod_say (no pre-recorded per-number audio needed).

Notes

Announcements and callbacks are best-effort comfort features — a failure never affects assignment.
The bridge pins the next hop to the local OpenSIPS (127.0.0.1:5060) because agents register there over WSS, not on FreeSWITCH directly.