FreePBX queue agent does not ring: prove eligibility before changing strategy

Prove that the call entered the intended queue

Record the queue number, caller identity, agent extension, exact timestamp and timezone, and whether the caller heard queue audio, an announcement, immediate failover or another destination. Confirm the inbound route, time condition, IVR or internal dialplan delivered this call to the intended queue. A caller hearing music does not prove that a particular agent was eligible, and an unanswered direct extension call is not a queue result.

Capture one failed example and one nearby working example if available. Avoid changing strategy, timeouts, agents and endpoint settings together; those changes erase the state that explains the incident.

Read the active queue and member state

Use a read-only Asterisk console observation such as queue show <queue> during an approved diagnostic window, and save the output with the incident. Match the exact member interface and state interface that Asterisk loaded. Look for membership type, logged-in state, paused state and reason, device status, penalty, calls taken, wrap-up and ring-in-use behavior. UI membership alone is not proof that the running queue has the expected member.

Sangoma distinguishes static agents, which are configured as persistent members, from dynamic agents, which must log in. Its queue-agent controls also distinguish logged out, logged in, static and paused states. Confirm the state in the intended queue: an all-queues login or pause action can affect more than the operator expected.

Separate pause and wrap-up from endpoint reachability

A member can be logged in yet paused, in wrap-up, busy, unavailable or excluded by ring-in-use policy. FreePBX can auto-pause after a no-answer, busy or unavailable attempt, depending on the installed version and queue settings. Preserve the pause reason and last state change before unpausing; otherwise a device or staffing fault can recur without evidence.

Then place an authorized direct internal test call to the agent and inspect the exact endpoint's current state. Registration, device state and successful ringing are different observations. If the direct call fails, follow the endpoint registration or reachability branch. If it succeeds while the queue still skips the member, keep the investigation on queue membership and policy.

Check eligibility controls in the order they act

Review the loaded member identity and penalty, then the queue's strategy, skip-busy or ring-in-use behavior, agent timeout, retry, wrap-up time and auto-pause policy. Check join-empty and leave-empty behavior, maximum callers, maximum wait and failover destination separately. A queue can accept a caller and later leave or fail over without ever offering that call to a member who was ineligible at the relevant instant.

Penalty is not simply a priority label. Lower-penalty eligible members and penalty rules can delay or prevent an offer to another tier. Do not flatten penalties, enable ring-in-use or disable auto-pause until the captured state shows that control caused the missed offer and the operational owner accepts the changed behavior.

Reconstruct the call from the queue log

Asterisk documents a dedicated queue log, stored by default at /var/log/asterisk/queue_log, for queued-call setup and teardown detail. Use the caller or unique identifier and timestamp to follow entry, member offers, no-answer or abandonment, connection and exit for the single failed example. Pair it with the channel log, CDR or CEL only where needed; those records have different purposes and may not share the same level of queue detail.

Logs can contain telephone numbers, agent identities and call metadata. Limit the time window, protect the extract and remove temporary verbose logging after the incident. Do not reset queue statistics or rewrite log data during diagnosis.

Apply one bounded correction and verify both sides

Correct the specific cause: log the authorized dynamic member into the intended queue, clear a justified pause after recording its cause, repair the endpoint, or change one approved queue control. Submit and Apply Config where configuration changed, then confirm the active queue state again. Do not edit generated queue files or use broad database, ownership, restart or module-reinstall actions as a substitute for a matched cause.

Repeat the original queued call and confirm that the intended member rings, answers, receives two-way audio and returns to the expected post-call state. Also test another member, busy and no-answer behavior, caller wait audio and failover. No queue, member state, endpoint, strategy, reporting, staffing, capacity, availability or live-call behavior was tested for this guide.

Keep caller priority separate from agent eligibility

A high QUEUE_PRIO cannot make a paused, unavailable or ineligible member ring. Use the Queue Priorities guide to preserve that caller-side boundary.

Use queue status only for its observed runtime boundary

The AMI queue-snapshot diagnostic does not promote member presence or state into proof that the target phone rang or answered.

Check AMI member state before changing queue strategy

The AMI queue-member diagnostic isolates exact membership, pause, penalty, device state, wrap-up and ring-in-use boundaries.

Verify policy only after the member and state source

The ring-in-use diagnostic follows exact queue membership, StateInterface, eligibility and the actual offer path.