AMI Configuration and Event Classes
AMI Configuration and Event Classes
The Asterisk Manager Interface (AMI) is a TCP client/server protocol on port 5038 for controlling the PBX, originating calls, checking mailbox status, monitoring channels and queues, and executing CLI commands. It predates ARI 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 | Channel info and state changes | Set channel variables |
| log | Log output | -- |
| verbose | Verbose output | -- |
| agent | Queue/agent events | Add/remove queue members |
| user | UserEvent send/receive | UserEvent send/receive |
| config | -- | Read/write config files |
| command | -- | Execute CLI commands |
| dtmf | DTMF events | -- |
| reporting | System info queries | System info queries |
| cdr | CDR events (cdr_manager) | -- |
| dialplan | NewExten, VarSet events | -- |
| originate | -- | Originate new calls |
| agi | 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 dialplan context/extension 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
No notes yet. Be the first to contribute a tip or example.
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.