Asterisk AMI actions, events and permissions
Treat AMI as a management interface with a specific application identity and job. Describe the actions the application may request and the events it must receive before granting access to a live phone system.
Source-reviewed, 19 October 2026. Prepared from the cited documentation. No AMI integration has been independently tested by Phone Guides. Scope: Asterisk 22; action availability, event fields and permission requirements need their matching references.
Build an action/event contract
| Requirement | Example question |
|---|---|
| Action | Does the application need status, origination or a configuration-changing operation? |
| Event | Which event establishes the next lifecycle stage? |
| Correlation | How does the application associate responses and later events with its request? |
| Identity | Which dedicated account and network sources may connect? |
| Recovery | What current state must be rediscovered after a disconnect? |
The official AMI overview leads to the protocol documentation. Use the branch-22 action reference and event reference for the exact operations your application uses.
Grant the required permissions
Configure a separate account in the installation's supported manager configuration, with a generated secret and the necessary read/write classes. Restrict network access and protect the connection. Keep broad configuration or command authority away from an application that only displays status.
Check the matching release's manager configuration sample instead of copying an all-permissions tutorial. An account's event access and action access answer different questions; document both. Use a protected secret reference in the runbook rather than the password itself.
Distinguish acknowledgement from outcome
Receiving a response to an action does not necessarily mean the full operation has finished. For origination, for example, reaching the requested destination and being answered are lifecycle observations beyond merely submitting a request. Check the specific action's synchronous/asynchronous behaviour and relevant later events.
Use identifiers as correlation data, not as proof that two business interactions are duplicates. Transfers and application-created channels can extend the call beyond a simple incoming/outgoing pair. Preserve the interpretation alongside CDR/CEL reporting.
Read a channel-list transaction
Begin an integration review with an observation rather than a call-origination request. On an already authenticated, appropriately authorised AMI connection, this original request asks for current channels:
Action: CoreShowChannels
ActionID: pg-channel-list-001
Use actual CRLF line endings and a final empty line when encoding an AMI message. The blank line terminates the message; reading one network packet is not a reliable message parser. The AMI v2 specification defines framing and field semantics. Authentication and transport setup are intentionally outside this request, so no real credential belongs in the example or its trace.
The CoreShowChannels action reference defines the action and returned transaction identifier. Track the action response and the list's events separately. A response accepting the request does not mean the application has received all list items.
For the documented Asterisk 22.1.0-and-later event, an illustrative empty-list completion has this shape:
Event: CoreShowChannelsComplete
ActionID: pg-channel-list-001
EventList: Complete
ListItems: 0
This is an explanation of fields, not a recorded PBX response. The branch-22 completion-event reference identifies its version boundary and fields. Verify the installed patch release rather than assuming every branch-22 API event existed in 22.0.0.
Keep a per-request identifier and completion deadline. Collect matching list items until matching completion, rejection or timeout; do not finish the list on an unrelated event. Use a fresh identifier for a new request. A zero-item completed list is a different outcome from receiving no completion at all.
An event stream can contain unrelated messages while the transaction is in progress. Preserve list order where relevant, tolerate permitted repeated fields, and avoid storing the whole protocol in a dictionary that silently discards duplicate names. Select an AMI parser that follows the specification instead of splitting arbitrary incoming packets at colons.
The resulting list is an observation made during live activity, not a lock on channels. A channel can end before a later action uses it. Compare current state and handle missing resources rather than assuming that successful listing reserves a call for your application.
Reconnect and reconcile
Define how the application authenticates again, restores its event selection and reconciles current channels/state with what it last knew. Do not blindly replay resource-creating actions after a network error: the first request may already have succeeded.
Keep a bounded retry policy with an operation identifier and an explicit decision about duplicate handling. A reconnect message is not evidence that every event missed during the gap was delivered again.
Reader checks
On your own system, verify the intended allowed action, a deliberately disallowed action, required events and a controlled disconnect/reconnect. Check a request followed by caller hangup and a response arriving later than expected. Confirm the account cannot change unrelated configuration.
Log the event/action type, time and correlation identifiers needed for diagnosis without publishing subscriber data or authentication material. Compare AGI, AMI and ARI if the desired application needs a different kind of call ownership.
Return to Asterisk documentation.