The Asterisk Manager Interface (AMI) is a powerful programmatic interface. It allows external programs to both control and monitor an Asterisk system.[125] This interface is often used to integrate Asterisk with existing business processes and systems, CRM (Customer Relationship Management) software. It can also be used for a wide variety of applications, such as automated dialers and click-to-call systems.
The Asterisk Manager Interface listens for connections on a network port. A client program can then connect to the Asterisk Manager Interface on that port, authenticate itself, and send commands to Asterisk. Asterisk will then respond to the request, as well as update the client program with the status of the system.
To use the Manager, you must define an account in the file /etc/asterisk/manager.conf. This file will look something like this:
[general] enabled = yes port = 5038 bindaddr = 0.0.0.0 [oreilly] secret = notvery ;deny=0.0.0.0/0.0.0.0 ;permit=209.16.236.73/255.255.255.0 read = system,call,log,verbose,command,agent,user write = system,call,log,verbose,command,agent,user
In the [general] section,
you have to enable the service by setting the parameter
enabled = yes. You will need to reload
the Manager in order to have this change take effect (module reload manager from the Asterisk
console). The TCP port defaults to 5038.
Next, you create a section for each user that will authenticate to
the system. For each user, you will specify the username in square
brackets ([ ]), followed by the password for that user (secret), any IP addresses you wish to deny access to, any IP addresses you wish to
permit access to, and the read and write permissions for that user.
It is very important to understand that other than a clear text password and the ability to restrict IP addresses, there is no security of any kind on the Manager interface. If you are running Manager on an untrusted network (or have any other complex needs), you should consider using David Troy’s excellent AstManProxy to handle all of your connections to the manager API.
It is important to keep in mind that the Manager interface is designed to be used by programs, not fingers. That’s not to say that you can’t issue commands to it directly—just don’t expect a typical console interface, because that’s not what Manager is for.
Commands to Manager are delivered in packages with the following syntax (lines are terminated with CR+LF):[126]
Action: <action type>Key 1:Value 1Key 2:Value 2etc ...Variable:ValueVariable:Valueetc...
For example, to authenticate with Manager (which is required if you expect to have any interaction whatsoever), you would send the following:
Action: login Username: oreilly Secret: notvery <CR+LF>
An extra CR+LF on a blank line will submit the entire package to Manager.
Once authenticated, you will be able to initiate actions, as well as see events generated by Asterisk. On a busy system, this can get quite complicated and become totally impossible to keep track of with the unaided eye. To turn keep Asterisk from sending events, you can add the Events parameter to your login command, like this:
Action: login Username: oreilly Secret: notvery Events: off <CR+LF>
If you’re worried about sending your secret across the wire in
plain text (which you should be), you can also
authenticate using an MD5 challenge-response system, which works very
similar to HTTP digest authentication. To do this, you first call the
Challenge
action, which will present you with a challenge token:
Action: Challenge
AuthType: MD5
Response: Success
Challenge: 840415273
You can then take that challenge token, concatenate the plaintext secret onto the end of it, and calculate the MD5 checksum of the resulting string. The result can then be used to login without passing your secret in plain text.
Action: Login
AuthType: MD5
Username: Admin
Key: e7a056e1488882c6c509bbe71a049978
Response: Success
Message: Authentication accepted
Once you’ve successfully logged into the AMI system, you can send commands to Asterisk by using the other actions. We'll show a few commands here so that you can get a feel for how they work.
The Redirect action can be used to transfer a
call. After logging in, you should send an action like the one
below:
Action: Redirect Channel: SIP/John-ae201e78 Context: Lab Exten: 6001 Priority: 1 ActionID: 2340981650981
For each action you sent over the manager interface, you can send along an arbitrary ActionID value. This will allow you to recognize the responses from Asterisk as being related to your actions. It is strongly recommended that you send a unique ActionID with each of your AMI commands.
This URL transfers the specified channel to another extension and priority in the dialplan. The response to this action is:
Response: Success ActionID: 2340981650981 Message: Redirect Successful
To read an Asterisk configuration file via the Manger interface,
we can use the the GetConfig action. The
GetConfig action returns the contents of a
configuration file, or portion thereof. The following command
retrieves the contents of the file
users.conf.
Action: GetConfig Filename: users.conf ActionID: 9873497149817
Asterisk then returns the contents of the
users.conf file. The response looks like:
Response: Success ActionID: 987397149817 Category-000000: general Line-000000-000000: fullname=New User Line-000000-000001: userbase=6000 Line-000000-000002: hasvoicemail=yes Line-000000-000003: hassip=yes Line-000000-000004: hasiax=yes Line-000000-000005: hasmanager=no Line-000000-000006: callwaiting=yes Line-000000-000007: threewaycalling=yes Line-000000-000008: callwaitingcallerid=yes Line-000000-000009: transfer=yes Line-000000-000010: canpark=yes Line-000000-000011: cancallforward=yes Line-000000-000012: callreturn=yes Line-000000-000013: callgroup=1 Line-000000-000014: pickupgroup=1 Line-000000-000015: host=dynamic
It is often useful to be able to update an Asterisk
configuration file via the Asterisk Manager interface. The
UpdateConfig action is used to update one or more
settings in a configuration file. For example, to delete a user named
6003 from users.conf you could issue the
following command:
Action: UpdateConfig Filename: users.conf Reload: yes SrcFilename: users.conf DstFilename: users.conf Action-00000: delcat Cat-00000: 6003 ActionID: 5298795987243
Obviously, we've only scratched the surface of the many different actions available as part of the Asterisk Manager Interface. For a more detailed listing of the available commands, see Appendix F.
[125] Contrast this with the Asterisk Gateway Interface (AGI), which allows Asterisk to launch an external program from the dialplan. The AGI and AMI interfaces are very much complimentary to each other.
[126] Carriage Return followed by Line Feed. This is popularly achieved by pressing the Enter key on the keyboard, but there are differences across various OS platforms and programming languages, so if you are having trouble with commands to the interface, it may be worth noting the exact character combination that is required. At the time of writing, Wikipedia had a respectable writeup on this concept (http://en.wikipedia.org/wiki/Newline).