Asterisk.org: Developer Documentation (28 Oct 2009)

Wed Oct 28 15:49:24 2009

## Asterisk developer's documentation

# AMI - The Manager Interface

- Configuration file
- manager.c

      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.

      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: 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
      					"Unregistred", "Registred", "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"
       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>		-- Timout 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.