Asterisk AMI event delivery, filters and WaitEvent

Model event delivery as a layered contract

An AMI event reaches a client only after the manager user is allowed to read its class, the current session enables that event class, configured and dynamic filters retain it, the selected transport delivers it, and the client parses and stores it. A quiet consumer does not identify which layer removed or delayed the event.

AMI actions, responses and unsolicited events also remain different message types. The Manager TCP/IP API warns that headers are local to each message rather than standardized across messages, so correlate only fields whose specific action or event contract supports that use.

Set the session event mask deliberately

The Login action can set Events to on, off or selected classes such as system,call,log. The later Events action controls event flow for the current manager client with the same mask choices and returns its ActionID. Manager-user read permissions still bound which event classes the client is allowed to receive.

Record the authenticated user, login mask, every later Events action and its response on the same connection. An accepted action that writes or queries state does not prove that the session is subscribed to the corresponding event class.

Apply configured filters in their documented order

The recommended advanced manager.conf filters can match event name, header and content. With no filters, all otherwise-authorized events are reported. Include-only configurations report an event that matches any include filter; exclude-only configurations block an event matching any exclude filter; when both exist, includes run first and excludes refine that result.

Event names are case-sensitive. Prefer exact event-name and targeted-header criteria over scanning every payload with a legacy regular expression. Preserve the effective user section and filter order with the incident record.

Keep static and dynamic filter syntax distinct

Configured advanced filters use criteria such as method(starts_with), while the generated dynamic Filter action publishes match methods including startsWith and endsWith. Do not copy tokens between the configuration and action interfaces without checking the installed reference.

The Filter action adds a filter only to the current manager session; closing the connection removes it. It requires the system permission because a session filter may bypass filters defined in manager.conf. Record every dynamic addition and rebuild intended session state after reconnect.

Use WaitEvent only for its HTTP-session queue

WaitEvent is documented for an HTTP manager session: after it is called, manager events are generated and queued for that session. Timeout is a maximum wait in seconds and -1 means forever. The action returns ActionID, but a Success response or timeout boundary is transport evidence rather than proof that a particular business event occurred.

Do not impose WaitEvent polling semantics on an ordinary persistent TCP reader. For HTTP polling, serialize the loop, bound the wait operationally and record request start, response completion, returned events and reconnects.

Separate liveness, completeness and call outcome

A Ping action elicits Pong and can show that the manager connection still answers. It does not prove the session mask, filters, WaitEvent loop, downstream parser or storage accepts a target event. Validate delivery with a deliberately generated, permitted event and a raw message capture before changing call logic.

Events can describe state transitions, but their receipt is not proof of remote answer, complete chronology, two-way media or a successful business workflow. No PBX, AMI session, manager user, permission, configuration file, socket, HTTP session, event queue, channel, bridge, packet, media stream or live call was inspected or tested for this guide.

Apply the delivery pipeline to custom USER-class events

The UserEvent diagnostic checks USER permission, masks, filters and raw messages before changing the producer.

Preserve device-state list completion through AMI delivery controls

The AMI device-state diagnostic checks list rows, the completion event, permissions, masks and filters as one bounded transaction.

Preserve presence list completion and event scope

The AMI presence-state diagnostic separates list rows, completion, live provider events and hint-scoped events through AMI delivery controls.

Preserve extension-list completion and live-event scope

The AMI extension-state diagnostic traces list rows, completion and unsolicited ExtensionStatus through AMI delivery controls.

Do not infer dialplan state from event delivery

The AMI runtime dialplan guide uses scoped inspection for loaded state and keeps manager events as a separate delivery surface.

Separate action authorization from event delivery

The AMI command-inventory guide keeps manager write classes, read classes, masks, filters and related-event completion as distinct evidence.

Preserve the login-time event mask

The AMI session-authentication guide separates Login Events selection from account read classes, later masks, filters and parsing.

Keep HTTP AMI behind both web and manager enablement

Asterisk’s base HTTP listener is only one boundary. The HTTP service guide keeps manager enablement, web enablement, session authentication and event delivery separate.

Do not filter away a list completion event

The ConfBridge list diagnostic requires the matching Complete event before publishing an empty or final snapshot.

Keep ConfBridge lifecycle names in the approved filter set

The ConfBridge event diagnostic checks class authorization, include and exclude filters, reconnects and parser state before interpreting absence.

Preserve parking list frames and lifecycle reasons

The AMI parking guide keeps ActionID, event filters and version-specific list termination separate from parking outcomes.

Include AGENT-class queue-member events deliberately

The AMI queue-member control guide explains why event filters can hide a successful mutation.

Correlate queue caller lifecycle without invented ActionID

The AMI queue caller-control guide uses queue, channel, Uniqueid and time for unsolicited events whose published schemas omit ActionID.

Do not invent ActionID on QueueMemberRinginuse

The ring-in-use control guide correlates the AGENT-class event by node, queue, interface and time.

Do not expect an undocumented QueueLog row event

The AMI QueueLog guide treats the AMI response and observed queue-log row as separate evidence.

Keep VarSet delivery separate from the write response

The AMI variable guide distinguishes Setvar response, VarSet filtering and a fresh read.

Correlate maintenance status events with a fresh snapshot

The maintenance-mode diagnostic distinguishes filtered telemetry from runtime state.

Do not mistake a filtered subscription list for an empty one

The subscription-list diagnostic requires the matching completion event before comparing inventories.

Preserve terminal events through AMI filters

The AMI list diagnostic treats a filtered or timed-out completion event as an incomplete snapshot.

Do not infer timer failure from filtered hangup events

The AbsoluteTimeout diagnostic distinguishes response, request, dialplan and final Hangup evidence under the active event filter.

Do not wait for an undocumented MuteAudio state event

The AMI MuteAudio guide preserves the response, live identities and downstream media evidence separately.

Do not infer a playback event that the action page does not document

The AMI ControlPlayback guide keeps the response, completion variables and media result as separate observations.

Keep action acceptance, request events and final Hangup distinct

The AMI Hangup diagnostic checks CALL-event visibility before any destructive retry.

Do not invent a delivery event for SendText

The AMI SendText guide keeps action response, protocol evidence and endpoint presentation independent.

Do not invent a MessageSend delivery event

The AMI MessageSend guide requires independent action, protocol and recipient evidence.

Preserve AOC-S, AOC-D and AOC-E as phase-specific events

The AMI AOCMessage guide keeps action response, event and remote presentation separate.

Keep agent list and lifecycle events inside one delivery contract

The AMI agent diagnostic preserves list completion, AGENT-class authorization, filters and reconnect gaps.

Retain the fax list completion marker

The AMI fax-session diagnostic requires matching entry and completion events before accepting a zero-session snapshot.

Allow resource-list detail and completion events

The AMI resource-list diagnostic requires both row events and ResourceListDetailComplete for a bounded result.

Retain DAHDI channel and span-alarm transitions

The AMI DAHDI diagnostic requires explicit filters for DAHDIChannel, SpanAlarm and SpanAlarmClear.

Retain PRI-related span alarm transitions

The AMI PRI diagnostic correlates filtered alarm transitions with separate status and debug evidence.

Retain bridge-technology list completion events

The AMI bridge-technology guide requires the matching item stream and terminal count rather than a quiet interval.