The Asterisk Manager Interface (AMI) Protocol
TweetBehind the scenes of any VoIP Application for the Asterisk PBX
The Asterisk Manager Interface (AMI) protocol is a very simple protocol that allows you to communicate and manage your asterisk server, almost completely. It has support to edit/create asterisk configuration files and also manage the calls, clients, agents, dialplan, etc.
You might also be interested in PAMI. An AMI client/framework that allows you to quickly develop ami clients in an oop/event-driven fashion.
Overview of the AMI Protocol
AMI is a plain text protocol, and it works by sending and receiving packets. Each packet consists in a series
of text lines delimited by \r\n. And each packet is delimited by \r\n\r\n.
AMI uses a tcp port configured in manager.conf. As soon as the connection is established, asterisk salutes you with something like:
Asterisk Call Manager/1.1
This message indicates that the communication can begin. Packets may be transmitted in either direction at any time after authentication.
AMI Packets (Actions, Responses, Events)
AMI defines 3 kind of possible packets:
- Actions: This kind of packet is what the client sends. Only the client can generate Actions.
- Responses: Actions have at least one Response, indicating the result of the executed (or requested) action.
- Events: There are two kind of events. The ones attached to a particular response for a particular action, and the ones that asterisk generate to inform the connected client about things that are happening in the server (like call events, changes in variables values, agents and other clients that connect/disconnect to/from the server, etc).
The first line of a packet will have a key of "Action" when sent from the client to Asterisk, but "Event" or "Response" when sent from Asterisk to the client.
A typical action is the Login action, which looks like this:
Action: Login\r\n
Username: admin\r\n
Secret: mysecret\r\n
ActionId: 1a2b\r\n
\r\n
And its response is something like:
Response: Success\r\n
ActionID: 1a2b\r\n
Message: Authentication accepted\r\n
\r\n
Notice the ActionId field in the action and response packet. This field is optional, but highly recommended to send, because it tells asterisk to respond with this same actionid value so the client can easily associate the response with the action sent. If any events are attached to this response, they will also contain the same actionid value.
So the general format for an action packet is something like this:
Action: <action>\r\n
<Key1>: <value>\r\n
<Key2>: <value>\r\n
...
<KeyN>: <value>\r\n
Variable: <name>=<value>
Variable: <name>=<value>
...
Variable: <name>=<value>
Different actions require different keys and/or variables. You can find the complete list of actions in the Actions section of the Asterisk Wiki.
A response that contains a:
Response: Error
Is considered a failed action. Otherwise, should be a successfull one.
Asynchronous events
This kind of events are the ones that asterisk sends you at any given time without the need of you sending
any action. This events can be disabled via the Event action.
An example:
Event: PeerStatus\r\n
Privilege: system,all\r\n
ChannelType: SIP\r\n
Peer: SIP/marcelog\r\n
PeerStatus: Registered\r\n
\r\n
Synchronous events
These events are used by asterisk whenever a response has a long payload to send. For example, when you ask for the dialplan lines, or the connected clients, or the status of all channels, etc.
Asterisk will return a Response packet indicating that the response actually has more data that will be sent in Events packets. A little note here. AMI is kind of broken and inconsistent (at least in asterisk 1.6). This means that there exists a couple of ways (depending on the action issued) for asterisk to report a Response with events attached.
To actually know if a given response contains events attached, you should check for
any of the following conditions:
Message: Result will follow
Message: Result follows
Response: Follows
Response: Result will follow
EventList: Start
The same happens when you're trying to know when to consider a response as completed (all events received). You should check for:
Event: EventNameHereComplete
EventList: Complete
A very simple protocol for your Telephony Applications
AMI is a pretty straightforward protocol. You can even try to create a client using netcat via a shell script or whatever programming language you like, allowing you to make console operators or manage the asterisk queues, calls, agents, etc from a single controlled point of your architecture. It has it pitfalls. For example, there is no specification as to quoting the ":" (semicolon) character (which separates keys from values) and some asterisk versions have a broken implementation for some events/resposes (i.e: not even sending the "Event:" / "Response:" keys,) sending a "follows" without a "complete", sending "follow" instead of "follows", not even sending "follows", etc.. a real nightmare).
