AMI Configuration and Event Classes
AMI Configuration and Event Classes
The Asterisk Manager Interface (AMIAsterisk Manager Interface. A TCP socket API for monitoring events and issuing actions in Asterisk, commonly used by click-to-dial integrations and dashboards.) is a TCP client/server protocol on port 5038 for controlling the PBXPrivate Branch Exchange, a private telephone switch. Asterisk is a software PBX that routes calls between internal extensions and the outside world., originating calls, checking mailbox status, monitoring channels and queues, and executing CLI commands. It predates ARIAsterisk REST Interface. A modern asynchronous API exposing channels, bridges, and endpoints over HTTP and WebSocket for building custom call applications. and remains widely used for monitoring and simple automation.
Requirements
manager.confconfigured and loaded- TCP port 5038 accessible from the management host
- Firewall rules restricting access to trusted IPs
Manager Configuration (manager.conf)
[general]
enabled = yes
webenabled = yes
port = 5038
bindaddr = 127.0.0.1
[admin]
secret = change_me_to_a_strong_password
deny = 0.0.0.0/0.0.0.0
permit = 127.0.0.1/255.255.255.255
permit = 10.0.0.0/255.0.0.0
read = system,call,log,verbose,agent,user,config,dtmf,reporting,cdr,dialplan
write = system,call,agent,user,config,command,reporting,originate
Authorization Classes
AMI uses separate read and write permissions across these event classes:
| Class | Read (receive events) | Write (send actions) |
|---|---|---|
| system | System events (reload, shutdown) | Shutdown, Restart, Reload |
| call | ChannelA single call leg passing through Asterisk. Channels represent connections to endpoints and are what dialplan applications act on. info and state changes | Set channel variables |
| log | Log output | -- |
| verbose | Verbose output | -- |
| agent | QueueAn Asterisk call queue (app_queue) that parks incoming calls and distributes them to logged-in agents according to a chosen ring strategy./agent events | Add/remove queue members |
| user | UserEvent send/receive | UserEvent send/receive |
| config | -- | Read/write config files |
| command | -- | Execute CLI commands |
| dtmfDual-Tone Multi-Frequency, the touch-tone signals phones send for digit input during a call, used by IVRs and feature codes. | DTMF events | -- |
| reporting | System info queries | System info queries |
| cdrCall Detail Record. The per-call accounting data Asterisk writes (start, answer, and end times, duration, disposition) to files or databases. | CDR events (cdr_manager) | -- |
| dialplanThe core call-routing configuration of Asterisk, written mostly in extensions.conf as contexts, extensions, and priorities that decide how every call is handled. Full definition → | NewExten, VarSet events | -- |
| originate | -- | Originate new calls |
| agiAsterisk Gateway Interface. Lets external scripts (PHP, Python, and others) control a call by communicating with Asterisk over stdin/stdout or TCP. | AGI command output | Execute AGI commands |
| security | Security events | -- |
Common AMI Actions
Action: Login
Username: admin
Secret: your_password
Action: Originate
Channel: PJSIP/1001
Context: internal
Exten: 1002
Priority: 1
CallerID: PBX <1000>
Action: Command
Command: pjsip show endpoints
Action: QueueStatus
Queue: sales
Action: Hangup
Channel: PJSIP/1001-00000042
How it works
- TCP protocol: AMI listens on port 5038. Clients connect via TCP, send
Action: Login, and receive events as they occur. Each action is a set ofKey: Valuelines terminated by a blank line. - Read vs Write:
readpermissions control which asynchronous events the user receives.writepermissions control which actions the user can execute. Use the principle of least privilege. - bindaddr: Setting
bindaddr = 127.0.0.1restricts AMI to localhost only. For remote access, use0.0.0.0with strictpermit/denyACLs. - webenabled: When
yes, AMI is also accessible via HTTP athttp://host:8088/manager. Useful for simple web-based integrations but should be TLS-protected in production. - Originate: The most commonly used AMI action. It creates a new outbound call and connects it to a dialplanThe core call-routing configuration of Asterisk, written mostly in extensions.conf as contexts, extensions, and priorities that decide how every call is handled. Full definition → contextA named section of the dialplan that groups extensions. Calls enter a specific context and can only reach extensions visible from it, making contexts the basic unit of call routing and security./extensionA dialplan entry that matches a dialed number or pattern within a context and triggers a sequence of prioritized steps. or an application. This is how click-to-call and automated dialing systems work.
Tips
- Test with netcat:
echo -e "Action: Login\nUsername: admin\nSecret: password\n\nAction: CoreStatus\n\n" | nc localhost 5038. - For monitoring, create a read-only user with
read = system,calland nowritepermissions. - Use
Action: EventswithEventMask: offto disable event streaming if you only need to send commands. - Most programming languages have AMI libraries:
panoramisk(Python),asterisk-manager(Node.js),Adhearsion(Ruby). - Always set
deny = 0.0.0.0/0.0.0.0first, then add specificpermitlines. AMI has no built-in rate limiting, so exposure to the internet is dangerous. - Combine AMI with fail2ban: Asterisk logs failed AMI authentication attempts to the security log.
User Notes
Know a tip or gotcha for this topic? Share it below and help others.
Contribute a note
Share a tip, gotcha, or practical example. Keep it under 2000 characters. No questions (use the Asterisk community forums for support). Wrap code in backticks.