asterisk/doc/manager.txt

The Asterisk Manager TCP/IP API - AMI
=====================================

The manager is a client/server model over TCP. With the manager interface,
you'll be able to control the PBX, originate calls, check mailbox status,
monitor channels and queues as well as execute Asterisk commands.

AMI is the standard management interface into your Asterisk server.
You configure AMI in manager.conf. By default, AMI is available on
TCP port 5038 if you enable it in manager.conf.

AMI receive commands, called "actions". These generate a "response"
from Asterisk. Asterisk will also send "Events" containing various
information messages about changes within Asterisk. Some actions
generate an initial response and data in the form list of events.
This format is created to make sure that extensive reports do not
block the manager interface fully.

Management users are configured in the configuration file manager.conf and are 
given permissions for read and write, where write represents their ability 
to perform this class of "action", and read represents their ability to 
receive this class of "event".

The Asterisk manager interface in version 1.0.x of Asterisk is
not very well standardized. Work is under way to change this 
to Asterisk 1.2. If you develop AMI applications, treat the headers
in Actions, Events and Responses as local to that particular
message. There is no cross-message standardization of headers.

If you develop applications, please try to reuse existing manager
headers and their interpretation. If you are unsure, discuss on
the asterisk-dev mailing list.

Device status reports
---------------------
Manager subscribes to extension status reports from all channels,
to be able to generate events when an extension or device changes
state. The level of details in these events may depend on the channel
and device configuration. Please check each channel configuration
file for more information. (in sip.conf, check the section on
subscriptions and call limits)


Command Syntax
--------------
Management communication consists of tags of the form "header: value", 
terminated with an empty newline (\r\n) in the style of SMTP, HTTP, and
other headers.


The first tag MUST be one of the following:

    * Action: An action requested by the CLIENT to the Asterisk SERVER. Only one "Action" may be outstanding at any time.
    * Response: A response to an action from the Asterisk SERVER to the CLIENT.
    * Event: An event reported by the Asterisk SERVER to the CLIENT 


Manager commands
----------------
Output from the CLI command 'show manager' command:

    * Ping: Ping
    * Logoff: Logoff Manager
    * Hangup: Hangup Channel
    * Status: Status
    * Redirect: Redirect
    * Originate: Originate Call
    * MailboxStatus: Check Mailbox
    * Command: Execute Command
    * ExtensionState: Check Extension Status
    * AbsoluteTimeout: Set Absolute Timeout
    * MailboxCount: Check Mailbox Message Count
    * Monitor: Monitor a channel
    * StopMonitor: Stop monitoring a channel
    * ChangeMonitor: Change monitoring filename of a channel
    * IAXpeers: List IAX Peers (Defaults to IAX2)
    * SIPpeers: List SIP peers
    * SIPshowpeer: Show data about one SIP peer
    * Queues: Queues
    * QueueStatus: Queue Status 

This list depends on the version of Asterisk you are using, as
well as which modules that are loaded.

Command Summary
--------------

Command: Command
Parameters: Command

Command: ExtensionState
Parameters: Exten, Context, ActionID

Command: Hangup
Parameters: Channel

Command: Logoff
Parameters: None

Command: MailboxCount
Parameters: Mailbox, ActionID

Command: MailboxStatus
Parameters: Mailbox, ActionID

Command: Originate
Parameters: Channel, Exten, Context, Priority, Timeout, 
   CallerID, Variable, Account, Application, Data, Async

Command: Ping
Parameters: None

Command: PlayDTMF
Parameters: Channel, Digit

Command: Redirect
Parameters: Channel, ExtraChannel, Exten, Context, Priority

Command: Timeout
Parameters: Channel, Timeout

You can always get more information about a manager command
with the "show manager command <command>" CLI command in Asterisk.

Examples
--------
Login - Log a user into the manager interface.

   Action: Login
   Username: testuser
   Secret: testsecret

Originate - Originate a call from a channel to an extension.

   Action: Originate
   Channel: sip/12345
   Exten: 1234
   Context: default

Originate - Originate a call from a channel to an extension without waiting
for call to complete.

   Action: Originate
   Channel: sip/12345
   Exten: 1234
   Context: default
   Async: yes


Redirect with ExtraChannel:
  Attempted goal:
  Have a 'robot' program Redirect both ends of an already-connected call
  to a meetme room using the ExtraChannel feature through the management interface.

  Action: Redirect
  Channel: Zap/1-1
  ExtraChannel: SIP/3064-7e00 (varies)
  Exten: 680
  Priority: 1

Where 680 is an extension that sends you to a MeetMe room.

There are a number of GUI tools that use the manager interface, please search
the mailing list archives and the documentation page on the 
http://www.asterisk.org web site for more information.


Some standard AMI headers:
--------------------------

 Account: 			-- Account Code (Status)
 AccountCode:			-- Account Code (cdr_manager)
 ACL: <Y | N>			-- Does ACL exist for object ?
 Action: <action>		-- request or notification of a particular action
 Address-IP:			-- IPaddress 
 Address-Port:			-- IP port number
 Agent: <string>		-- Agent name
 AMAflags:			-- AMA flag (cdr_manager, sippeers)
 AnswerTime:			-- Time of answer (cdr_manager)
 Append: <bool>			-- CDR userfield Append flag
 Application:			-- Application to use
 Async:				-- Whether or not to use fast setup
 AuthType: 			-- Authentication type (for login or challenge)
					"md5"
 BillableSeconds:		-- Billable seconds for call (cdr_manager)
 CallerID:			-- Caller id (name and number in Originate & cdr_manager)
 CallerID:			-- CallerID number
				   Number or "<unknown>" or "unknown" 
					(should change to "<unknown>" in app_queue)
 CallerID1:                     -- Channel 1 CallerID (Link event)
 CallerID2:                     -- Channel 2 CallerID (Link event)
 CallerIDName:			-- CallerID name
				   Name or "<unknown>" or "unknown" 
					(should change to "<unknown>" in app_queue)
 Callgroup:			-- Call group for peer/user
 CallsTaken: <num>		-- Queue status variable
 Cause: <value>			-- Event change cause - "Expired"
 Cause: <value>			-- Hangupcause (channel.c)
 CID-CallingPres:		-- Caller ID calling presentation
 Channel: <channel>		-- Channel specifier
 Channel: <dialstring>		-- Dialstring in Originate
 Channel: <tech/[peer/username]> -- Channel in Registry events (SIP, IAX2)
 Channel: <tech>		-- Technology (SIP/IAX2 etc) in Registry events
 ChannelType:			-- Tech: SIP, IAX2, ZAP, MGCP etc
 Channel1:			-- Link channel 1
 Channel2:			-- Link channel 2
 ChanObjectType:		-- "peer", "user"
 Codecs:			-- Codec list
 CodecOrder:			-- Codec order, separated with comma ","
 Command:			-- Cli command to run
 Context:			-- Context
 Count: <num>			-- Number of callers in queue
 Data:				-- Application data
 Default-addr-IP:		-- IP address to use before registration
 Default-Username:		-- Username part of URI to use before registration
 Destination:			-- Destination for call (Dialstring ) (dial, cdr_manager)
 DestinationContext:		-- Destination context (cdr_manager)
 DestinationChannel:		-- Destination channel (cdr_manager)
 DestUniqueID:			-- UniqueID of destination (dial event)
 Disposition:			-- Call disposition (CDR manager)
 Domain: <domain>		-- DNS domain
 Duration: <secs>		-- Duration of call (cdr_manager)
 Dynamic: <Y |  N>		-- Device registration supported?
 Endtime:			-- End time stamp of call (cdr_manager)
 EventList: <flag>		-- Flag being "Start", "End", "Cancelled" or "ListObject"
 Events: <eventmask>		-- Eventmask filter ("on", "off", "system", "call", "log")
 Exten:				-- Extension (Redirect command)
 Extension:			-- Extension (Status)
 Family: <string>		-- ASTdb key family
 File: <filename>		-- Filename (monitor)
 Format: <format>		-- Format of sound file (monitor)
 From: <time>			--  Parking time (ParkedCall event)
 Hint:				-- Extension hint
 Incominglimit:			-- SIP Peer incoming limit
 Key:
 Key:				-- ASTdb Database key
 LastApplication:		-- Last application executed (cdr_manager)
 LastCall: <num>		-- Last call in queue
 LastData:			-- Data for last application (cdr_manager)
 Link:				-- (Status)
 ListItems: <number>		-- Number of items in Eventlist (Optionally sent in "end" packet)
 Location:			-- Interface (whatever that is -maybe tech/name in app_queue )
 Loginchan:			-- Login channel for agent
 Logintime: <number>		-- Login time for agent
 Mailbox:			-- VM Mailbox (id@vmcontext) (mailboxstatus, mailboxcount)
 MD5SecretExist: <Y | N>	-- Whether secret exists in MD5 format 
 Membership: <string>		-- "Dynamic" or "static" member in queue
 Message: <text>		-- Text message in ACKs, errors (explanation)
 Mix: <bool> 			-- Boolean parameter (monitor) 
 NewMessages: <count>	 	-- Count of new Mailbox messages (mailboxcount)
 Newname:		
 ObjectName:			-- Name of object in list
 OldName:			-- Something in Rename (channel.c)
 OldMessages: <count>		-- Count of old mailbox messages (mailboxcount)	
 Outgoinglimit:			-- SIP Peer outgoing limit
 Paused: <num>			-- Queue member paused status
 Peer: <tech/name>		-- "channel" specifier :-)
 PeerStatus: <tech/name>	-- Peer status code 
					"Unregistered", "Registered", "Lagged", "Reachable"
 Penalty: <num>			-- Queue penalty
 Priority:			-- Extension priority
 Privilege: <privilege>		-- AMI authorization class (system, call, log, verbose, command, agent, user)
 Pickupgroup:			-- Pickup group for peer
 Position: <num>		-- Position in Queue
 Queue:				-- Queue name
 Reason:			-- "Autologoff"
 Reason:			-- "Chanunavail"
 Response: <response>		-- response code, like "200 OK"
					"Success", "Error", "Follows"
 Restart:			-- "True", "False"
 RegExpire:			-- SIP registry expire
 RegExpiry:			-- SIP registry expiry
 Reason:			-- Originate reason code
 Seconds:			-- Seconds (Status)
 Secret: <password>		-- Authentication secret (for login)
 SecretExist: <Y | N>		-- Whether secret exists 
 Shutdown:			-- "Uncleanly", "Cleanly" 
 SIP-AuthInsecure:
 SIP-FromDomain:		-- Peer FromDomain
 SIP-FromUser:			-- Peer FromUser
 SIP-NatSupport:
 SIPLastMsg:
 Source:			-- Source of call (dial event, cdr_manager)
 SrcUniqueID:			-- UniqueID of source (dial event)
 StartTime: 			-- Start time of call (cdr_manager)
 State:				-- Channel state
 Status:			-- Registration status (Registry events SIP)
 Status:			-- Extension status (Extensionstate)
 Status:			-- Peer status (if monitored)  ** Will change name **
					"unknown", "lagged", "ok"
 Status: <num>			-- Queue Status
 Status:			-- DND status (DNDState)
 Time: <sec>			-- Roundtrip time (latency)
 Timeout:			-- Parking timeout time
 Timeout:			-- Timeout for call setup (Originate)
 Timeout: <seconds>		-- Timeout for call
 Uniqueid:			-- Channel Unique ID
 Uniqueid1:			-- Channel 1 Unique ID (Link event)
 Uniqueid2:			-- Channel 2 Unique ID (Link event)
 User:				-- Username (SIP registry)
 UserField:			-- CDR userfield (cdr_manager)
 Val:				-- Value to set/read in ASTdb
 Variable:			-- Variable AND value to set (multiple separated with | in Originate)
 Variable: <name>		-- For channel variables
 Value: <value>			-- Value to set
 VoiceMailbox:			-- VM Mailbox in SIPpeers
 Waiting:			-- Count of mailbox messages (mailboxstatus)

 ** Please try to re-use existing headers to simplify manager message parsing in clients.

Read the CODING-GUIDELINES if you develop new manager commands or events.