The Asterisk Manager API

The Asterisk Manager allows a client program to connect to an Asterisk instance and issue commands or read PBX events over a TCP/IP stream. Integrators will find this particularly useful when trying to track the state of a telephony client inside Asterisk, and directing that client based on custom (and possibly dynamic) rules.

A simple "key: value" line-based protocol is utilized for communication between the connecting client and the Asterisk PBX. Lines are terminated using CRLF. For the sake of discussion below, we will use the term "packet" to describe a set of "key: value" lines that are terminated by an extra carriage return.

New in Asterisk 1.4: AJAM is a new JavaScript-based technology which allows web browsers or other HTTP enabled applications and web pages to directly access the Asterisk Manager Interface (AMI) via HTTP.

Protocol Behavior

The protocol has the following characteristics:

• Before issuing commands to Asterisk, you must establish a manager session (see below).
• Packets may be transmitted in either direction at any time after authentication.
• The first line of a packet will have a key of "Action" when sent from the client, but "Event" or "Response" when sent from Asterisk to the client.
• The order of lines within a packet is insignificant, so you may use your favorite programming language's native unordered dictionary type to efficiently store a single packet.
• CRLF is used to delimit each line and a blank line (two CRLF in a row) indicates the end of the command which Asterisk is now expected to process.

Packet Types

The type of a packet is determined by the existence of one of the following keys:

• Action: A packet sent by the connected client to Asterisk, requesting a particular Action be performed. There are a finite (but extendable) set of actions available to the client, determined by the modules presently loaded in the Asterisk engine. Only one action may be outstanding at a time. The Action packet contains the name of the operation to be performed as well as all required parameters.
• Response: the response sent by Asterisk to the last action sent by the client.
• Event: data pertaining to an event generated from within the Asterisk core or an extension module.

Generally the client sends Action packets to the Asterisk server, the Asterisk server perfoms the requested operation and returns the result (often only success or failure) in a Response packet. As there is no guarantee regarding the order of Response packets the client usually includes an ActionID parameter in every Action packet that is sent back by Asterisk in the corresponding Response packet. That way the client can easily match Action and Response packets while sending Actions at any desired rate without having to wait for outstanding Response packets before sending the next action.

Event packets are used in two different contexts: On the one hand they inform clients about state changes in Asterisk (like new channels being created and hung up or agents being logged in and out) on the other hand they are used to transport the response payload for actions that return a list of data (event generating actions). When a client sends an event generating action Asterisk sends a Response packed indicating success and containing a "Response: Follows" line. Then it sends zero or more events that contain the actual payload and finally an action complete event indicating that all data has been sent. The events sent in response to an event generating action and the action complete event contain the ActionID of the Action packet that triggered them, so you can easily match them the same way as Response packets. An example of an event generating action is the Status action that triggers Status events for each active channel. When all Status events have been sent a terminating a StatusComplete event is sent.

Opening a Manager Session and Authenticating as a User

In order to access the Asterisk Manager functionality a user needs to establish a session by opening a TCP/IP connection to the listening port (usually 5038) of the Asterisk instance and logging into the manager using the 'Login' action. This requires a previously established user account on the Asterisk server. User accounts are configured in /etc/asterisk/manager.conf. A user account consists of a set of permitted IP hosts, an authentication secret (password), and a list of granted permissions.

There is a finite set of permissions, each may be granted with either "read", "write", or "read/write" granularity. If a client is granted the ability to read a given class, Asterisk will send it events of that class. If a client is granted the ability to write a given class, it may send actions of that class.

To login and authenticate to the manager, you must send a "Login" action, with your user name and secret (password) as parameters. Here is an example:

  Action: login
  Username: admin
  Secret: god


If you do not need to subscribe to events being generated by Asterisk, you may also include the "Events: off" parameter, which will prevent event packets being sent to your connection. This is the equivalent of calling the "Events" action. Example:

  Action: login
  Username: admin
  Secret: god
  Events: off

Action Packets

When sending Asterisk an action, extra keys may be provided to further direct execution, for example, you may wish to specify a number to call, a channel to disconnect. Additionally, if your action causes Asterisk to execute an entry in the dialplan, you may wish to pass variables to the dialplan (available as of bug 1268). This is done exactly the same way you would send keys.

To send Asterisk an action, follow this simple format:

   Action: <action type><CRLF>
   <Key 1>: <Value 1><CRLF>
   <Key 2>: <Value 2><CRLF>
   ...
   Variable: <Variable 1>=<Value 1><CRLF>
   Variable: <Variable 2>=<Value 2><CRLF>
   ...
   <CRLF>

Manager Actions

Output from the CLI command show manager commands:
(For Asterisk 1.4 and greater, use manager show commands)

• AbsoluteTimeout: Set Absolute Timeout (privilege: call,all)
• ChangeMonitor: Change monitoring filename of a channel (privilege: call,all)
• Command: Execute Command (privilege: command,all)
• Events: Control Event Flow
• ExtensionState: Check Extension Status (privilege: call,all)
• GetVar: Gets a Channel Variable (privilege: call,all)
• Hangup: Hangup Channel __(privilege: call,all)
• IAXpeers: List IAX Peers (privilege: system,all)
• ListCommands: List available manager commands
• Logoff: Logoff Manager
• MailboxCount: Check Mailbox Message Count (privilege: call,all)
• MailboxStatus: Check Mailbox (privilege: call,all)
• Monitor: Monitor a channel (privilege: call,all)
• Originate: Originate Call (privilege: call,all)
• ParkedCalls: List parked calls
• Ping: Ping
• QueueAdd: Queues (privilege: agent,all)
• QueueRemove: Queues (privilege: agent,all)
• Queues: Queues
• QueueStatus: Queue Status
• Redirect: Redirect (privilege: call,all)
• SetCDRUserField: Set the CDR UserField (privilege: call,all)
• SetVar: Set Channel Variable (privilege: call,all)
• SIPpeers: List SIP Peers (chan_sip2 only. Not available in chan_sip as of 9/20/2004) (privilege: system,all)
• Status: Status (privilege: call,all)
• StopMonitor: Stop monitoring a channel (privilege: call,all)
• ZapDialOffhook: Dial over Zap channel while offhook
• ZapDNDoff: Toggle Zap channel Do Not Disturb status OFF
• ZapDNDon: Toggle Zap channel Do Not Disturb status ON
• ZapHangup: Hangup Zap Channel
• ZapTransfer: Transfer Zap Channel
• ZapShowChannels: Show Zap Channels

(New?) in Asterisk 1.2.1 (was "CVS HEAD") (Taken from the output of CLI command show manager commands):

• AgentCallbackLogin: Sets an agent as logged in by callback (Privilege: agent,all)
• AgentLogoff: Sets an agent as no longer logged in (Privilege: agent,all)
• Agents: Lists agents and their status (Privilege: agent,all)
• DBGet: Get DB Entry (Privilege: system,all)
• DBPut: Put DB Entry (Privilege: system,all)
• QueuePause: Makes a queue member temporarily unavailable (Privilege: agent,all)
• SIPshowPeer: Show SIP peer (text format) (Privilege: system,all)

New in Asterisk 1.4.0

• PlayDTMF: Play DTMF signal on a specific channel. (Privilege: call,all)

New in Asterisk 1.4.0

• UpdateConfig: Updates a configuration file, used mainly by AJAM/Asterisk-gui. (Privilege: config,all)
• GetConfig: Display a configuration file, used mainly by AJAM/Asterisk-gui. (Privilege: config,all)

Asterisk Events

These are listed on a separate page: asterisk manager events.

Manager Examples

These are listed on a separate page also: Asterisk manager Examples.

Caveat

We're sorry, but if you do a show applications on the console, you will see the command to view connected managers is show manager connect, but the correct command is show manager connected. Please make a note of it.

See also

• Phone Genie for Asterisk Web-Based Controller for Asterisk Manager API. Works fine with Asterisk 1.2.x.
• Asterisk manager experience by mattf
• Asterisk config manager.conf
• Asterisk cmd UserEvent: Send a user-defined event to the manager API
• Asterisk auto-dial out
• Asterisk Manager Proxy: With SSL and HTTPS support for securing manager API communication
• Asterisk-java
• OrderlyCalls (successor to JAGIServer) offers full support for FastAGI and Manager in an easy-to-use Named Service environment. Includes Web Deployer for developing integrated VOIP-HTML applications.
• Asterisk manager Examples
• asterisk manager events
• French Speaking Manager examples with PHP Jeremy Salmon
• Star Asterisk API, PHP with event examples StarAstAPI
• Asterisk PHP API (PEAR proposed) by Straw Dogs

---

• Asterisk | FAQ | Applications | Tips & Tricks