VoIP.infoThe independent guide to business communications.
VoIP.info Guide

FreePBX Queue Priorities: caller weight, channel scope and queue order

Assign a documented queue priority to the intended caller path, preserve it across the configured destination chain and distinguish caller ordering from agent penalty, staffing, service level and answer outcome.

Reviewed 2026-10-12Sangoma Queue Priorities overview and PBX GUI 13 user guide, FreePBX Queue Priorities release/17.0 repository metadata and Queueprio.class.php dialplan source, and current Asterisk QUEUE_PRIO and Queue application documentation reviewed October 12, 2026; the Sangoma screen guide is explicitly version 13, repository state does not prove an installed module or loaded channel state, and no PBX, module, priority object, route, queue, caller, member, channel variable, queue log, SLA result or call was inspected or testedAdvancedDocumentation based · not lab tested

Define the policy before choosing a number

Sangoma documents a default caller priority of zero and a Queue Priorities range from 0 through 20, with higher values placed ahead of lower-priority callers. Record the business class, eligible source paths, value, effective period, destination, owner, review date and rollback before saving an object.

The number is a relative queue-order input, not a promised wait time or service-level result. Document how calls of the same priority are ordered and how the policy treats callers already waiting when a higher-priority call arrives.

Keep caller priority distinct from agent penalty

Queue priority weights callers waiting for service. Queue member penalty controls which agents are eligible or preferred. They operate on different sides of queue matching and should not be merged into one “priority” label.

Likewise, queue weight across queues, service-level thresholds, wrap-up time, member availability and ring strategy are different controls. A high caller priority cannot create an available agent, repair a paused member or override a queue capacity or timeout.

Trace the release/17.0 channel variable

The FreePBX release/17.0 class source generates an app-queueprio target that sets inherited _QUEUE_PRIO to the configured value and then goes to the selected destination. Asterisk documents QUEUE_PRIO as the queue-priority channel variable. Verify the installed module, generated target, loaded dialplan and live channel value rather than treating repository code as runtime proof.

The leading underscore in the generated assignment is a channel-inheritance choice. Follow Local channels, transfers and other created legs explicitly; shared call identifiers do not prove that every leg owns the expected value.

Preserve the value until the queue actually admits the caller

Sangoma states that the priority can persist even when the immediate destination is not a queue, so map each IVR, time condition, announcement, language or other handoff between the priority object and Queue entry. Record any step that replaces, clears or fails to inherit the variable.

A caller reaching the queue context is not yet proof of admission. Queue limits, join-empty policy, timeouts, destination branches and application errors can prevent or end waiting before ordering affects an answer.

Measure ordering with comparable evidence

For an authorized test, use calls that enter the same queue under controlled member availability. Capture arrival time, channel identity, effective QUEUE_PRIO, queue-entry event, position changes, member offers, answer or exit and queue-log records. Compare calls only where queue, availability and policy conditions are materially equivalent.

Do not infer priority from one short wait or an anecdotal answer order. A later high-priority arrival may move ahead of lower priorities, while ringing, member acceptance, abandoned calls and simultaneous events can still affect what observers see.

Govern priority as an auditable service policy

Review who can route callers through each priority object, especially public IVRs, inbound numbers and customer-controlled inputs. Avoid an unprotected route that lets any caller claim a privileged class. Monitor distribution by priority, queue, wait, abandonment and answer without presenting the configured number as a guaranteed SLA.

Change one policy value or source path at a time, apply configuration through supported controls and retest lower, equal and higher classes plus an unauthorized boundary. This workflow is documentation-derived and was not reproduced on an installed or laboratory FreePBX system.

Sources & applicability

Primary references for the technical details above. Operational examples and planning checklists are VoIP.info editorial guidance.

Examples require adaptation to your topology. No live PBX or hardware testing is claimed.

Continue your research

Hub

FreePBX

Plan and administer a FreePBX 17 system on Debian 12 using the supported project installation path.

Explore topic →
Guide · FreePBX 17 operational guidance using Sangoma's version-13-scoped field reference plus current Asterisk 23 Queue, queue-variable and queue-log documentation reviewed October 10, 2026; no PBX, module, queue, route, caller, member, endpoint, prompt, music, report, destination, staffing level, capacity or call was inspected or tested

FreePBX queues and agent operations

Design and verify caller admission, agent eligibility, offer strategy, overflow and queue evidence as separate controls.

Read guide →
Guide · FreePBX 17 on Debian 12; route semantics cross-checked against Sangoma PBX GUI 13 guides and current FreePBX Blacklist 17.0.1.2 release/17.0 source on October 11, 2026; exact installed modules, generated or loaded route hooks and calls were not tested

FreePBX inbound and outbound routes

Follow the incoming number and outgoing dial pattern as two separate routing decisions.

Read guide →
Guide · Current Sangoma IVR guide and FreePBX 17 IVR module metadata plus current Asterisk Background, WaitExten and special-extension documentation reviewed September 28, 2026; no PBX, module, generated dialplan, prompt, destination, DTMF digit or live call was tested

FreePBX IVRs

Create a short voice menu that handles invalid digits, silence and unavailable destinations.

Read guide →
Guide · Asterisk 22 GotoIfTime, ExecIfTime, IFTIME, TESTTIME and STRFTIME documentation plus current public Sangoma Time Conditions and Time Groups guidance and FreePBX release/17.0 Time Conditions metadata version 17.0.1.19 reviewed October 15, 2026; Sangoma interface guidance is explicitly labelled for PBX GUI version 13 and is used for object and override semantics rather than as an exact FreePBX 17 screen map; installed modules, generated dialplan, host and explicit timezones, clock state, schedule, overrides, targets and calls remain deployment specific; no PBX, module, clock, timezone, dialplan, condition, override, destination or live call was inspected or tested

FreePBX time conditions and time groups

Route open hours, holidays and authorized overrides by keeping the time group, condition, destination chain, scheduled state and override state independently observable.

Read guide →
Guide · FreePBX CDR Reports and CDR user guidance plus current Asterisk CDR specification and Asterisk 22 CDR and CEL references reviewed October 11, 2026; installed module, schema, backends, report roles, timezone, retention and call behavior require system-specific evidence, and no FreePBX host, report, call, channel, CDR, CEL event, log, database, export, billing rule, backup or retention workflow was inspected or tested

FreePBX CDR Reports: query, record lifecycle and evidence boundaries

Use FreePBX CDR Reports without turning one filtered row into a complete conversation, billing record or channel-event history.

Read guide →
Troubleshooting · Sangoma Queue Priorities overview and PBX GUI 13 user guide, FreePBX Queue Priorities release/17.0 repository metadata and Queueprio.class.php dialplan source, and current Asterisk QUEUE_PRIO and Queue application documentation reviewed October 12, 2026; the Sangoma screen guide is explicitly version 13, repository state does not prove an installed module or loaded channel state, and no PBX, module, priority object, route, queue, caller, member, channel variable, queue log, SLA result or call was inspected or tested

FreePBX queue priority is not applied or callers answer in the wrong order

Trace one caller from its selecting route through the generated priority target, inherited QUEUE_PRIO value, queue admission, comparable waiters, member offers and queue outcome before changing weights or penalties.

Read guide →