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

Asterisk AMI UserEvent custom telemetry

Design application-owned UserEvent names, headers and correlation keys while keeping AMI action responses, dialplan emission, event delivery and downstream outcomes independently observable.

Reviewed 2026-10-16Current Asterisk branch-23-generated AMI UserEvent action, UserEvent event and UserEvent dialplan-application references, matching branch-22 references, plus the official AMI event-filtering, command-syntax and Manager TCP/IP material reviewed October 16, 2026; installed branch, module, dialplan, manager permissions, session mask, filters, transport, parser, retry policy, schema and application outcome remain deployment specific; no PBX, module, dialplan, manager session, event stream, channel, bridge, endpoint, packet, media stream, business system or live call was inspected or testedAdvancedDocumentation based · not lab tested

Treat UserEvent as an application contract

UserEvent carries application-defined telemetry; Asterisk does not assign business meaning to the chosen event name or custom headers. Publish an owner, schema version, event-name convention, required fields, permitted values and retention boundary before consumers depend on it. Keep names stable and add fields compatibly rather than silently reusing one name for a different state.

The documented AMI event belongs to class USER. A receiving manager user therefore needs the relevant read permission, while the current session mask and event filters still control delivery. Event production and delivery remain separate results.

Distinguish the two producers

The AMI UserEvent action sends an arbitrary event to manager sessions. Its ActionID belongs to the action transaction and is returned with the response. Do not assume that value appears in the resulting event unless the application deliberately includes a separate custom correlation header.

The dialplan UserEvent(eventname,[body]) application raises an event for interested channel parties, including AMI users and relevant res_stasis applications. Its optional body is a comma-delimited list of key:value pairs; for AMI, each additional argument becomes a new event line.

Preserve documented and custom fields

The documented AMI event can include channel snapshot fields such as Channel, Uniqueid and Linkedid, plus the application-defined UserEvent name and arbitrary parameters. Those snapshot fields are context, not an immutable call record; channel state can change immediately after emission.

Use a dedicated application correlation key for a workflow or attempt, and record the producer, schema version and event time in the consumer. Do not overwrite standard AMI header names or rely on unspecified header order.

Design for delivery gaps and duplicate processing

A produced event must still pass manager read permissions, the session event mask, configured and dynamic filters, transport, parsing and storage. A reconnect is not a documented replay mechanism. When the telemetry matters, reconcile from an authoritative application state or bounded Asterisk snapshot instead of assuming missed custom events will return.

Make downstream writes idempotent with the application correlation key and event meaning. Duplicate rows can be created by retrying a producer, running two consumers, reconnect overlap or non-idempotent storage; the event alone does not identify which occurred.

Minimize and protect the payload

Custom headers can reach every authorized manager consumer whose masks and filters admit the event. Do not place passwords, tokens, payment data, recordings, unnecessary caller information or unrestricted free text in the payload. Use opaque references where possible and enforce least privilege, protected transport, bounded logs and retention.

Filtering can reduce noise but is not a substitute for authorization or data minimization. Record the effective manager user, USER read access, session mask and filters with each integration release.

Do not promote telemetry into outcome proof

An accepted UserEvent action shows that Asterisk accepted that action transaction; a received custom event shows that a permitted consumer received a message matching the application contract. Neither result by itself proves remote answer, bridge membership, transfer completion, recording persistence, two-way media or a completed business workflow.

Validate the business outcome at its owning system and retain the join keys needed to compare it with the custom event. No PBX, module, dialplan, manager session, event stream, channel, bridge, endpoint, packet, media stream, business system or live call was inspected or tested for this guide.

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

Guide · Asterisk 22 LTS

Asterisk dialplan: contexts, patterns and loaded-call evidence

Build a restricted Asterisk 22 call path, then prove its context, match, priorities and runtime behavior separately.

Read guide →
Guide · Current Asterisk interface documentation reviewed September 30, 2026; implementation must be checked against the installed branch and integration library

Asterisk AMI, ARI and AGI: choose the control boundary

Separate management events, synchronous dialplan work and application-owned call control before exposing an integration.

Read guide →
Guide · Current Asterisk branch-23-generated Events, Filter, WaitEvent, Login and Ping action references, matching branch-22 Events, Filter and WaitEvent references, the official AMI event-filtering guide and Manager TCP/IP API reviewed October 16, 2026; installed branch, manager user permissions, login mask, static and dynamic filters, connection type, event queue, client parser, reconnect behavior, action concurrency, downstream storage and call activity remain deployment specific; 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

Asterisk AMI event delivery, filters and WaitEvent

Trace event delivery through manager read permissions, login and Events masks, configured and session filters, TCP or HTTP transport, WaitEvent queueing and client processing without treating silence as a failed PBX.

Read guide →
Guide · Current Asterisk branch-23-generated CoreShowChannelMap, CoreShowChannelMapComplete, CoreShowChannels, CoreShowChannel, CoreShowChannelsComplete, Status, StatusComplete, Newchannel and Rename references plus the branch 22 map action and completion event reviewed October 16, 2026; installed branch, loaded actions and events, manager permissions, session ordering, channel names, stable identifiers, bridge membership, variables, signaling and media remain deployment specific; no PBX, AMI session, manager user, permission, channel, bridge, variable, packet, media stream or live call was inspected or tested

Asterisk AMI channel snapshots and connected maps

Choose CoreShowChannels, CoreShowChannelMap or Status deliberately, preserve list boundaries, and correlate mutable channel, linked and bridge identities without treating a snapshot as a final call result.

Read guide →
Guide · Operational guidance; Asterisk 22 / FreePBX 17 where applicable

Least privilege for PBX users and integrations

Separate the right to register, place calls, administer the PBX and read sensitive data.

Read guide →
Troubleshooting · Current Asterisk branch-23-generated AMI UserEvent action, UserEvent event and UserEvent dialplan-application references, matching branch-22 references, plus the official AMI event-filtering, command-syntax and Manager TCP/IP material reviewed October 16, 2026; installed branch, module, dialplan, manager permissions, session mask, filters, transport, parser, retry policy, schema and application outcome remain deployment specific; no PBX, module, dialplan, manager session, event stream, channel, bridge, endpoint, packet, media stream, business system or live call was inspected or tested

Asterisk AMI UserEvent is missing, duplicated or misleading

Trace one application-owned event from its AMI action or dialplan producer through event naming, USER permission, masks, filters, transport, parsing, idempotent storage and the separate business outcome.

Read guide →