Search:
     
3CX Phone System for Windows Download the Free Edition

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 discussion below, we will use the term "packet" to describe a set of "key: value" lines that are terminated by an extra CR/LF.

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 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 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 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) 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 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)
  • Asterisk Manager API Action AgentLogoff: Sets an agent as no longer logged in (Priv: agent,all)
  • Asterisk Manager API Action Agents: Lists agents and their status (Priv: agent,all)
  • Asterisk Manager API Action AGI: Add an AGI command to execute by Async AGI (Priv: call,all)
  • Asterisk Manager API Action Bridge: Bridge two channels already in the PBX (Priv: call,all)
  • Asterisk Manager API Action 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)
  • Asterisk Manager API Action CoreSettings: Show PBX core settings (version etc) (Priv: system,reporting,all)
  • Asterisk Manager API Action CoreShowChannels: List currently active channels (Priv: system,reporting,all)
  • Asterisk Manager API Action CoreStatus: Show PBX core status variables (Priv: system,reporting,all)
  • Asterisk Manager API Action CreateConfig: Creates an empty file in the configuration directory (Priv: config,all)
  • Asterisk Manager API Action DAHDIDialOffhook: Dial over DAHDI channel while offhook (Priv: <none>)
  • Asterisk Manager API Action DAHDIDNDoff: Toggle DAHDI channel Do Not Disturb status OFF (Priv: <none>)
  • Asterisk Manager API Action DAHDIDNDon: Toggle DAHDI channel Do Not Disturb status ON (Priv: <none>)
  • Asterisk Manager API Action DAHDIHangup: Hangup DAHDI Channel (Priv: <none>)
  • Asterisk Manager API Action DAHDIRestart: Fully Restart DAHDI channels (terminates calls) (Priv: <none>)
  • Asterisk Manager API Action DAHDIShowChannels: Show status dahdi channels (Priv: <none>)
  • Asterisk Manager API Action DAHDITransfer: Transfer DAHDI Channel (Priv: <none>)
  • Asterisk Manager API Action DBDel: Delete DB Entry (Priv: system,all)
  • Asterisk Manager API Action 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)
  • Asterisk Manager API Action GetConfigJSON: Retrieve configuration (JSON format) (Priv: system,config,all)
  • GetConfig: Retrieve configuration (Priv: system,config,all)
  • Getvar: Gets a Channel Variable (Priv: call,reporting,all)
  • Hangup: Hangup Channel (Priv: system,call,all)
  • Asterisk Manager API Action IAXnetstats: Show IAX Netstats (Priv: system,reporting,all)
  • Asterisk Manager API Action IAXpeerlist: List IAX Peers (Priv: system,reporting,all)
  • IAXpeers: List IAX Peers (Priv: system,reporting,all)
  • Asterisk Manager API Action 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)
  • Asterisk Manager API Action MeetmeMute: Mute a Meetme user (Priv: call,all)
  • Asterisk Manager API Action MeetmeUnmute: Unmute a Meetme user (Priv: call,all)
  • Asterisk Manager API Action ModuleCheck: Check if module is loaded (Priv: system,all)
  • Asterisk Manager API Action 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>)
  • Asterisk Manager API Action Park: Park a channel (Priv: call,all)
  • Asterisk Manager API Action 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)
  • Asterisk Manager API Action QueueLog: Adds custom entry in queue_log (Priv: agent,all)
  • QueuePause: Makes a queue member temporarily unavailable (Priv: agent,all)
  • Asterisk Manager API Action QueuePenalty: Set the penalty for a queue member (Priv: agent,all)
  • QueueRemove: Remove interface from queue. (Priv: agent,all)
  • Asterisk Manager API Action QueueRule: Queue Rules (Priv: <none>)
  • Queues: Queues (Priv: <none>)
  • QueueStatus: Queue Status (Priv: <none>)
  • Asterisk Manager API Action QueueSummary: Queue Summary (Priv: <none>)
  • Redirect: Redirect (transfer) a call (Priv: call,all)
  • Asterisk Manager API Action Reload: Send a reload event (Priv: system,config,all)
  • Asterisk Manager API Action SendText: Send text message to channel (Priv: call,all)
  • Setvar: Set Channel Variable (Priv: call,all)
  • Asterisk Manager API Action ShowDialPlan: List dialplan (Priv: config,reporting,all)
  • SIPpeers: List SIP peers (text format) (Priv: system,reporting,all)
  • SIPshowpeer: Show SIP peer (text format) (Priv: system,reporting,all)
  • Asterisk Manager API Action 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)
  • Asterisk Manager API Action UnpauseMonitor: Unpause monitoring of a channel (Priv: call,all)
  • UpdateConfig: Update basic configuration (Priv: config,all)
  • Asterisk Manager API Action UserEvent: Send an arbitrary event (Priv: user,all)
  • Asterisk Manager API Action VoicemailUsersList: List All Voicemail User Information (Priv: call,reporting,all)
  • Asterisk Manager API Action 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 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 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

Created by: oej,Last modification on Wed 04 of Aug, 2010 [09:09 UTC] by jalonljc


Please update this page with new information, just login and click on the "Edit" or "Discussion" tab. Get a free login here: Register Thanks! - support@voip-info.org

Page Changes | Comments

 
Sponsored by:





Search: