Asterisk manager API

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.

Generalmente el cliente envia un paquete Action al server Asterisk, quien procesa la operacion requerida y retorna el resultado (devuelve solo success o failure) en un paquete Response. Como no hay garantia del orden de respuesta el cliente usualmente incluye un parametro ActionID en cada Action packet que es enviado de vuelta por el Asterisk en el correspondiente paquete Response. De esta manera el cliente puede facilmente hacer match con la Accion y Respuesta mientras envia Actions en la tasa deseada sin tener que esperar por paquetes de respuesta de salida antes de enviar la proxima acción.
cada paquete son usados en 2 diferentes contextos: en el primero informan a clientes acerca del estado de cambios en Asterisk (Como nuevos canales que se inician creados y colgados o agentes que se loguean y desloguean) en la otra manera ellos son usados para transportar el response payload para acciones que devuelven una lista de datos. on the other hand they are used to transport the response payload for actions that return a list of data (actions que generan eventos). Cuando el cliente envia una accion generando eventos, Asterisk envia un paquete respuesta indicando sucesos y conteniendo una linea: "Response: Follows". Entonces se envia zero o mas eventos que contienen el actual payload y finalmente un evento de accion completa conteniendo el ActionID de el Action packet que disparó esto. 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