Asterisk AMI presence-state queries, lists and hint events

Start with the read surface and its modules

AMI PresenceState queries one named provider and returns the state plus any subtype and custom message. PresenceStateList, supplied by res_manager_presencestate, lists the currently known states. The single query dates from Asterisk 11 and the list transaction from Asterisk 13; confirm the installed branch, loaded modules, action response and exact provider string before building a consumer.

The generated AMI actions do not document a dedicated presence-state write action. Asterisk instead documents the PRESENCE_STATE() dialplan function and the presencestate CLI for CustomPresence: writes, plus generic AMI variable actions for functions. Keep read, list, event and write authority separate.

Treat a presence value as application-owned input

Presence describes a user condition rather than the inferred state of a physical device. The documented values are not_set, unavailable, available, away, xa, chat and dnd, with optional subtype and message. Asterisk says presence changes must be enacted manually, does not aggregate several presence providers and does not automatically use presence when deciding device availability.

Define the writer, allowed transitions, expiry or reset policy and consumer before turning a label into routing. available does not prove a registered or reachable phone; away does not automatically pause a queue member or reject a call.

Bound PresenceStateList by its completion

Send a distinct ActionID with PresenceStateList. The documented sequence is zero or more PresenceStateChange events followed by PresenceStateListComplete, whose EventList and ListItems fields close the transaction. Buffer the rows and publish only after the completion boundary; an absent completion is an incomplete list, not an authoritative empty inventory.

The row and completion event schemas do not list ActionID even though the action says its identifier is returned. Preserve raw frames and establish the behavior of the installed release and AMI library. If correlation cannot be demonstrated, serialize list requests on that manager session instead of guessing which interleaved row belongs to which request.

Do not merge PresenceStateChange with PresenceStatus

PresenceStateChange is raised for all presence-state changes and identifies the Presentity, status, subtype and message. PresenceStatus is raised only when a dialplan hint changes due to presence; it identifies extension, context and hint as well as the presence fields. The latter event has later maintenance-release markers, including Asterisk 22.1.0, while the former dates from Asterisk 13.

A provider can therefore change without a corresponding hint-scoped event. Conversely, a hint event adds mapping context but remains distinct from SIP SUBSCRIBE delivery, the NOTIFY body and endpoint rendering.

Keep CustomPresence writes inside their boundary

PRESENCE_STATE() can read any installed presence provider but can write only a CustomPresence: identifier. Its value, subtype and message fields form one application-owned record; its encoding option changes how subtype or message data is passed, not who owns the state. A hint may map a presence provider after its device-state portion, or may contain presence without a device.

Do not use a manual custom value to conceal a provider, hint, subscription or display defect. Record how the value is initialized and restored, and minimize personal or operational detail in subtype and message because those fields can flow through AMI events and subscriber notifications.

Verify every downstream claim separately

AMI read success, list completeness, a provider transition, a hint-scoped event, SIP NOTIFY delivery and a displayed presence indicator are different outcomes. Registration, OPTIONS qualification, INVITE acceptance, queue selection, device state, extension state, two-way media and business availability remain separate observations.

Apply manager read permissions, event masks and filters deliberately, retain the exact presentity and timestamps, and validate the consumer at its owner. No PBX, module, manager session, presence provider, dialplan, hint, subscription, endpoint, packet, media stream or live call was inspected or tested for this guide.

Keep device-driven ExtensionStatus separate from presence events

The AMI extension-state guide distinguishes device aggregation from presence mapping even when a hint carries both.