FreePBX queues and agent operations

Model four separate queue responsibilities

A queue has at least four owners: the route that admits a caller, the membership and state that make agents eligible, the strategy that offers calls, and the destination that takes responsibility after an exit. A ring group mainly describes a set of destinations to ring; a queue also holds callers and tracks agent state. Treating the queue number as the whole service hides time conditions, IVRs, endpoint state and overflow behavior.

Write down staffed hours, queue number, static and dynamic membership, pause and wrap-up policy, caller announcements, recording policy, maximum wait, capacity limit and failover owner. Sangoma's detailed field guide is explicitly scoped to PBX GUI version 13, so preserve its semantics without assuming the current FreePBX 17 screen has identical labels, order or defaults.

Keep membership, login and endpoint state distinct

Sangoma describes static agents as persistent queue members and dynamic agents as members who log in and out. Membership does not prove login, an active login does not prove the member is unpaused, and an unpaused member does not prove the endpoint is reachable or free. Record the exact member interface, state interface, queue-specific login, pause reason, penalty, device state and most recent state transition.

Restrict dynamic-agent access according to the installed module and business policy. All-queue feature codes, single-queue actions, BLF hints and external destinations have different scope and failure modes. Do not use a handset's registration icon or a FreePBX membership row as the only evidence that the running queue can offer a call to that member.

Choose strategy and concurrency deliberately

FreePBX documents ring-all, least-recent, fewest-calls, random, round-robin-memory, ordered round robin, linear and weighted-random strategies. The strategy determines offer order; it does not create staffed capacity or guarantee fairness. Autofill, agent timeout, retry time, penalties, queue weight, Skip Busy Agents and Asterisk ringinuse controls each change a different decision.

Do not use penalties as an assumed timed escalation ladder without proving the loaded rule and eligible members. Sangoma also warns that ringinuse=no can keep a transferring agent unavailable until the transferred call ends in some configurations. Test transfers, outbound calls, call waiting and membership in multiple queues before using a busy-state setting as a capacity rule.

Design admission, waiting and exit together

Join-empty and leave-empty behavior, maximum callers, maximum wait, caller exit keys and failover destination must be designed as one caller path. Asterisk's Queue() application can return without admitting the caller when join conditions fail, and exposes different completion states such as TIMEOUT, FULL, JOINEMPTY, LEAVEEMPTY, JOINUNAVAIL and LEAVEUNAVAIL. A caller hearing music or ringing does not prove admission, agent eligibility or eventual overflow.

Asterisk also documents that Queue() does not answer automatically; answer, progress and ringing treatment belong to the surrounding dialplan. Keep announcements short and truthful. Position or expected-wait messages are estimates, not guarantees, and a generous maximum wait is not a staffing plan.

Treat pause, wrap-up and no-answer as agent lifecycle

Define who may pause an agent, which reasons are required, whether no-answer, busy or unavailable results trigger auto-pause, and who may clear that state. Wrap-up, pause, busy, unreachable and logged-out are different reasons not to offer another call. Record the transition before resetting it so a device, staffing or workflow fault is not erased.

For a bounded pilot, use one available agent and two callers, then repeat with the member busy, paused, logged out, unreachable and in wrap-up. Confirm caller treatment, agent offer, answer, two-way audio, post-call state and failover separately. When one agent is skipped, use the focused queue-agent diagnosis before changing the strategy or adding capacity.

Use queue evidence without overstating service results

Asterisk's queue log distinguishes entry, ringing without answer, connection, normal completion, abandonment, caller-selected exit, empty-queue exit and timeout. Correlate one caller's timestamp and unique identifier across ENTERQUEUE, offer events, CONNECT, completion or exit, then use CDR or CEL only where another call leg or transfer must be reconstructed. QUEUESTATUS, ABANDONED, QUEUEWAIT, ANSWEREDTIME and the logged event answer different questions.

Do not treat every abandonment as a technical failure, every long wait as a network fault, or every answered record as usable audio. Protect queue logs because they can contain caller and agent identities. No FreePBX module, Asterisk queue, route, member, endpoint, pause, strategy, recording, report, staffing level, capacity, caller experience or live call was inspected or tested for this guide.

Map the queue's waiting category and every override

Use the Music on Hold guide to preserve the queue category, inherited route category, runtime class and caller audio separately. Queue entry or an AMI start event is not proof that the intended file remained audible for the complete wait.

Diagnose caller treatment and exit separately from agent ringing

When a caller waits indefinitely, leaves early, hears the wrong treatment or reaches the wrong failover, use the caller-side queue diagnostic. It separates route arrival, Queue admission, music and announcements, live eligibility, the recorded exit reason and the downstream destination.

Treat QUEUE_PRIO as a caller-side ordering input

Use the Queue Priorities guide to distinguish caller priority from member penalty and to verify the variable on the channel that actually enters Queue.

Treat the Asterisk Info queue view as one current snapshot

The Asterisk Info report guide separates current member and caller state from queue configuration, event history, eligibility, ringing, answer and media. Compare the same queue and time through its owning runtime surface.

Do not infer queue acceptance from a system-wide dashboard card

The System Dashboard workflow requires the owning queue, member, caller and event evidence. Process and resource cards do not prove agent eligibility, ringing, answer, caller treatment or media.

Reconcile runtime AMI member changes with FreePBX ownership

The AMI queue-member diagnostic compares runtime state with generated configuration and later persistence.

Reconcile AMI queue reload with FreePBX ownership

The AMI queue reload or reset diagnostic compares GUI storage, generated files, runtime snapshots, statistics and later regeneration.

Preserve FreePBX queue ownership while controlling a live caller

The queue caller-control diagnostic uses generated dialplan as evidence and avoids treating an AMI action as a saved GUI change.

Treat runtime ring-in-use control and saved queue configuration separately

The ring-in-use diagnostic checks later FreePBX apply, Asterisk reload and the generated member record independently.

Separate Asterisk queue-log rows from FreePBX reports

The QueueLog diagnostic follows the active log, alternate backend, parser and report independently.