Asterisk manager API

Business SIP Providers
Provider Plan Details Monthly Rate *
Broadvoice SIP BroadVoice SIP
  • 5 lines for $55, additional lines only $2
  • Unlimited Inbound
  • month long trial period
$11.00
Details
8x8 8x8 IP Trunking
  • Unlimited calls to US and Canada
  • Softphone and mobile app available
  • 2012 Market Leader Award
$29.99
Details
Business PBX Solutions
Provider Solution Details
3CX Software PBX for Windows
  • Windows Software Solution
  • Easy to Install and Manage
  • Auto Configures Phones & Trunks
  • Android, iOS, Windows & Mac clients
Details
Bicom VoIP Become an ITSP Now!
  • Become a serious competitor in VoIP Immediately
  • FULL Consultancy, Installation, Training & Support
  • Sell Hosted IP PBXs, Biz Lines, Call Centre
  • Turnkey Provisioning at your data center
Details
Contact Center 4PSA's VoipNow Cloud Communications Platform
  • Enjoy your custom licensing plan - Pay-As-You-Grow!
  • Your fastest go-to-market solution - from deployment to billing.
  • Professional support, training and knowledge base to help you grow your business
  • On your infrastructure or cloud-based, it's up to you.
Details
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)
  • 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)
  • 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)
  • Setvar: Set Channel Variable (Priv: call,all)
  • 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)
  • 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 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

  • AMIConnector .NET Library A library for fast development of Asterisk Applications under Visual Basic & Visual NET
  • AMIgo for .NET AMIgo offers an extensive set of visual controls which supports drag and drop and offers context menus to display and interact with extensions / trunks, active channels, active calls, queues, queues members, queues calls, agents, conferences and conferences users. Build a full featured Asterisk Control Panel with drag and drop support in no time, using Visual Studio and C# or Visual Basic. Also include .config and dialplan editor, command panel, site manager and more.
  • AMIflex C++ source code allows you to specify one or multiple AMI servers, installing event handlers on to these servers - currently comes with event handlers to build a device and channel list. This is purposely a minimal design, to allow others to build upon it and save time in their custom applications.
  • Asterisk auto-dial out
  • Asterisk Channels Live is a windows Programm, which we can see all Asterisk channels On RealTime with windows Forms,written in C# .
  • Asterisk cmd UserEvent: Send a user-defined event to the manager API
  • Asterisk config manager.conf
  • asterisk manager events
  • Asterisk manager Examples
  • Asterisk manager experience by mattf
  • FOP2 - The first switchboard for Asterisk just getting better! Free for 15 buttons.
  • PAGI and PAMI (for PHP, clean, modular, easy, OOP compatible interfaces and clients for asterisk manager and agi): http://github.com/marcelog/PAMI - http://github.com/marcelog/PAGI
  • Asterisk Manager Proxy: With SSL and HTTPS support for securing manager API communication
  • Asterisk PHP API (PEAR proposed) by Straw Dogs
  • Asterisk-java
  • CPAN: Asterisk::AMI - Simple interface for accessing the asterisk manager API. It has built in functions for common tasks (such as retrieving the asterisk db) as well as a powerful Event and Action callback implementation that supports several event loops.
  • CrossCTI* A CTI solution that allows you to integrate a .NET DLL into your own application to control Asterisk and listen to it's events.
  • DialApplet, Windows, Mac & Linux Desktop
  • French Speaking Manager examples with PHP Jeremy Salmon
  • LibgAMI Cross-platform library for connections to the asterisk manager interface. Fast Access to AMI using a framework valid for multiple languages and systems.
  • 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.
  • Phone Genie for Asterisk Web-Based Controller for Asterisk Manager API. Works fine with Asterisk 1.2.x.
  • PHP Code for web-based streaming of call audio from a regular call or a conference call.
  • Python AMI library Starpy Starpy, whats new
  • ScopDEV The ScopServ Developer Kit is a package of libraries and samples to allow developper to add ScopServ Telephony system (ScopTel) integration into their software using Asterisk Manager Interface.
  • Shift8 PHP Library. Supports almost all manager commands, command queuing, SOAP and more
  • node-Shift8 A javascript implementation of Shift8 PHP library in Node.js (Asynchronous interface). Still work in progress but functional
  • Simple but powerful AMI processing script in Perl. Quickstart for AMI logging and callbacks may be found here.
  • The free Asterisk IAX2 and Manager API and AGI ActiveX control(know as IAXOCX and MVBCTI OCX)
  • SQL wrapper for some AMI commands, postgresql based
  • WombatDialer can be used to hide away the complexities of dealing with AGI calls directly when creating dialplan-scripted solutions


Created by: oej, Last modification: Wed 31 of Oct, 2012 (09:32 UTC) by lenz


Please update this page with new information, just login and click on the "Edit" or "Discussion" tab. Get a free login here: Register Thanks! - Find us on Google+

Page Changes | Comments