Asterisk Manager API

The Asterisk Manager Interface (AMI) allows a client program to connect to an Asterisk instance and issue commands or read 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 CR/LF. For the sake of the discussion below, we will use the term “packet” to describe a set of “key: value” lines that are terminated by an extra CR/LF.

Page Contents

Protocol Behavior
Packet Types
Opening a Manager Session and Authenticating as a User
Action Packets
Manager Actions
Asterisk Events
Manager Examples
Authorization for various classes
Caveat
See also

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 to Asterisk, 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.
CR/LF is used to delimit each line and a blank line (two CR/LF in a row) indicates the end of the command which Asterisk is now expected to process.

Packet Types

The type of 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 performs 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 from 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 Asterisk CLI command manager show commands:
(For Asterisk 1.2 and earlier, use show manager 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) NOTE: starting from 1.6: originate,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 Asterisk 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

GetConfig: Display a configuration file, used mainly by AJAM/Asterisk-gui. (Privilege: config,all)
PlayDTMF: Play DTMF signal on a specific channel. (Privilege: call,all)
UpdateConfig: Updates a configuration file, used mainly by AJAM/Asterisk-gui. (Privilege: config,all)

Available in Asterisk 1.6.0

AbsoluteTimeout: Set Absolute Timeout (Priv: system,call,all)
AgentLogoff: Sets an agent as no longer logged in (Priv: agent,all)
Agents: Lists agents and their status (Priv: agent,all)
AGI: Add an AGI command to execute by Async AGI (Priv: call,all)
Bridge: Bridge two channels already in the PBX (Priv: call,all)
Challenge: Generate Challenge for MD5 Auth (Priv: <none>)
ChangeMonitor: Change monitoring filename of a channel (Priv: call,all)
Command: Execute Asterisk CLI Command (Priv: command,all)
CoreSettings: Show PBX core settings (version etc) (Priv: system,reporting,all)
CoreShowChannels: List currently active channels (Priv: system,reporting,all)
CoreStatus: Show PBX core status variables (Priv: system,reporting,all)
CreateConfig: Creates an empty file in the configuration directory (Priv: config,all)
DAHDIDialOffhook: Dial over DAHDI channel while offhook (Priv: <none>)
DAHDIDNDoff: Toggle DAHDI channel Do Not Disturb status OFF (Priv: <none>)
DAHDIDNDon: Toggle DAHDI channel Do Not Disturb status ON (Priv: <none>)
DAHDIHangup: Hangup DAHDI Channel (Priv: <none>)
DAHDIRestart: Fully Restart DAHDI channels (terminates calls) (Priv: <none>)
DAHDIShowChannels: Show status dahdi channels (Priv: <none>)
DAHDITransfer: Transfer DAHDI Channel (Priv: <none>)
DBDel: Delete DB Entry (Priv: system,all)
DBDelTree: Delete DB Tree (Priv: system,all)
DBGet: Get DB Entry (Priv: system,reporting,all)
DBPut: Put DB Entry (Priv: system,all)
Events: Control Event Flow (Priv: <none>)
ExtensionState: Check Extension Status (Priv: call,reporting,all)
GetConfigJSON: Retrieve configuration (JSON format) (Priv: system,config,all)
GetConfig: Retrieve configuration (Priv: system,config,all)
Asterisk Manager API Action GetVar: Gets a Channel Variable (Priv: call,reporting,all)
Hangup: Hangup Channel (Priv: system,call,all)
IAXnetstats: Show IAX Netstats (Priv: system,reporting,all)
IAXpeerlist: List IAX Peers (Priv: system,reporting,all)
IAXpeers: List IAX Peers (Priv: system,reporting,all)
ListCategories: List categories in configuration file (Priv: config,all)
ListCommands: List available manager commands (Priv: <none>)
Login: Login Manager (Priv: <none>)
Logoff: Logoff Manager (Priv: <none>)
MailboxCount: Check Mailbox Message Count (Priv: call,reporting,all)
MailboxStatus: Check Mailbox (Priv: call,reporting,all)
MeetmeMute: Mute a Meetme user (Priv: call,all)
MeetmeUnmute: Unmute a Meetme user (Priv: call,all)
ModuleCheck: Check if module is loaded (Priv: system,all)
ModuleLoad: Module management (Priv: system,all)
Monitor: Monitor a channel (Priv: call,all)
Originate: Originate Call (Priv: originate,all)
ParkedCalls: List parked calls (Priv: <none>)
Park: Park a channel (Priv: call,all)
PauseMonitor: Pause monitoring of a channel (Priv: call,all)
Ping: Keepalive command (Priv: <none>)
PlayDTMF: Play DTMF signal on a specific channel. (Priv: call,all)
QueueAdd: Add interface to queue. (Priv: agent,all)
QueueLog: Adds custom entry in queue_log (Priv: agent,all)
QueuePause: Makes a queue member temporarily unavailable (Priv: agent,all)
QueuePenalty: Set the penalty for a queue member (Priv: agent,all)
QueueRemove: Remove interface from queue. (Priv: agent,all)
QueueRule: Queue Rules (Priv: <none>)
Queues: Queues (Priv: <none>)
QueueStatus: Queue Status (Priv: <none>)
QueueSummary: Queue Status (Priv: <none>)
Redirect: Redirect (transfer) a call (Priv: call,all)
Reload: Send a reload event (Priv: system,config,all)
SendText: Send text message to channel (Priv: call,all)
Asterisk Manager API Action SetVar: Set Channel Variable (Priv: call,all)
ShowDialPlan: List dialplan (Priv: config,reporting,all)
SIPpeers: List SIP peers (text format) (Priv: system,reporting,all)
Asterisk Manager API Action SIPshowPeer: Show SIP peer (text format) (Priv: system,reporting,all)
SIPshowregistry: Show SIP registrations (text format) (Priv: system,reporting,all)
Status: Lists channel status (Priv: system,call,reporting,all)
StopMonitor: Stop monitoring a channel (Priv: call,all)
UnpauseMonitor: Unpause monitoring of a channel (Priv: call,all)
UpdateConfig: Update basic configuration (Priv: config,all)
UserEvent: Send an arbitrary event (Priv: user,all)
VoicemailUsersList: List All Voicemail User Information (Priv: call,reporting,all)
WaitEvent: Wait for an event to occur (Priv: <none>)

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.

Authorization for various classes

Read authorization permits you to receive asynchronous events, in general.
Write authorization permits you to send commands and get back responses. The
following classes exist:

system – General information about the system and ability to run system management commands, such as Shutdown, Restart, and Reload.
call – Information about channels and ability to set information in a running channel.
log – Logging information. Read-only.
verbose – Verbose information. Read-only.
agent – Information about queues and agents and the ability to add queue members to a queue.
user – Permission to send and receive UserEvent.
config – Ability to read and write configuration files.
command – Permission to run CLI commands. Write-only.
dtmf – Receive DTMF events. Read-only.
reporting – Ability to get information about the system.
cdr – Output of cdr_manager, if loaded. Read-only.
dialplan – Receive NewExten and VarSet events. Read-only.
originate – Permission to originate new calls. Write-only.

Caveat

We’re sorry, but if you do a show application 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.