Asterisk AMI queue-member add, remove, pause and penalty controls

Resolve the queue member identity before changing it

Queue-member control starts with the responding node, installed Asterisk release, loaded app_queue module, exact case-sensitive queue name and exact Interface string. MemberName is a display name, while StateInterface can supply device-state tracking for a different identifier; neither substitutes for the member Interface used by these actions. Preserve all three when they appear.

Record the manager account, ActionID, configuration owner and pre-change QueueStatus snapshot. If FreePBX owns the queue, its stored configuration and generated Asterisk state are separate authorities. A runtime AMI change must not be represented as durable across reload, restart or a later GUI apply until that deployment is observed.

Add or remove one exact membership

QueueAdd requires Queue and Interface; it can also set Penalty, Paused, Reason, MemberName and StateInterface. A higher numeric penalty means the member is considered only after members with lower penalties have been attempted, but penalty is not a promise that this member will ring or answer. Preserve every supplied field and the later QueueMemberAdded event.

QueueRemove also targets an exact Queue and Interface. Preserve the response and QueueMemberRemoved event, then obtain a later queue snapshot. Removal is a membership transition, not proof that an endpoint unregistered, a channel hung up, a device stopped ringing or a caller reached another agent.

Scope pause and unpause deliberately

QueuePause requires Interface and Paused; Reason is optional. With an exact Queue, the change is limited to that membership. If Queue is omitted, the documented scope is every queue to which the interface belongs. An operator should make that breadth explicit before sending the request rather than assuming a current screen implies one queue.

The QueueMemberPause event carries the resulting Paused and PausedReason fields with a complete member snapshot. An action response and event are state evidence, not proof that no already-offered call exists, a wrap-up interval ended, the device is reachable or the agent will answer.

Treat penalty as ordering input, not outcome

QueuePenalty requires an exact Interface and a nonnegative Penalty. Its optional Queue has the same important scope boundary: when omitted, the change applies to all queues to which the interface belongs. The QueueMemberPenalty event reports the resulting member state, including queue, interface and penalty.

Penalty is only one input to queue selection. Queue strategy, paused state, member status, InCall, Ringinuse, wrap-up timing, concurrent calls and subsequent state changes can all affect an offer. Keep the action response, event, later snapshot, actual ring attempt, answer and caller result as distinct records.

Interpret member events and snapshots field by field

The reviewed queue-member events are in the AMI AGENT class. A manager read class, event mask or filter can therefore hide them even when the action succeeded. Membership distinguishes the reported membership type; Status is a numeric device-state value, while Paused, InCall, Ringinuse, Wrapuptime, calls taken and last-call timestamps describe other dimensions. Do not collapse them into one ready/not-ready Boolean.

Correlate exact queue and interface plus bounded time. The event schemas reviewed here do not document ActionID, so do not invent direct request correlation. Use a completed post-change QueueStatus snapshot as a separate postcondition, and preserve races where another controller or the queue application changed state again.

Validate one disposable member and negative scopes

In an approved nonproduction window, add one disposable member with explicit queue, interface, member name, state interface, penalty and pause state. Capture the response, matching member event and completed later snapshot. Then test exact-queue pause, unpause, penalty and remove, plus denied and nonexistent queue or interface cases. Test omitted-queue scope only where changing every membership is safe.

Verify registration, device state, ring attempt, bridge, answer and authorized two-way media independently if those outcomes matter. No PBX, module, queue, member, configuration, manager account, session, event stream, endpoint, packet, audio or live call was inspected or tested for this guide; documentation does not establish availability, compatibility, persistence, eligibility, ringing, answer or caller outcome.

Keep caller priority separate from member penalty

The AMI queue caller-control guide changes a waiting caller while member controls change agent eligibility or ordering inputs.

Add ring-in-use without merging other member controls

The ring-in-use control guide treats policy, pause, penalty, membership and state as separate fields.