doc/manager.txt

   1 The Asterisk Manager TCP/IP API - AMI
   2 =====================================
   3
   4 The manager is a client/server model over TCP. With the manager interface,
   5 you'll be able to control the PBX, originate calls, check mailbox status,
   6 monitor channels and queues as well as execute Asterisk commands.
   7
   8 AMI is the standard management interface into your Asterisk server.
   9 You configure AMI in manager.conf. By default, AMI is available on
  10 TCP port 5038 if you enable it in manager.conf.
  11
  12 AMI receive commands, called "actions". These generate a "response"
  13 from Asterisk. Asterisk will also send "Events" containing various
  14 information messages about changes within Asterisk. Some actions
  15 generate an initial response and data in the form list of events.
  16 This format is created to make sure that extensive reports do not
  17 block the manager interface fully.
  18
  19 Management users are configured in the configuration file manager.conf and are
  20 given permissions for read and write, where write represents their ability
  21 to perform this class of "action", and read represents their ability to
  22 receive this class of "event".
  23
  24 The Asterisk manager interface in version 1.0.x of Asterisk is
  25 not very well standardized. Work is under way to change this
  26 to Asterisk 1.2. If you develop AMI applications, treat the headers
  27 in Actions, Events and Responses as local to that particular
  28 message. There is no cross-message standardization of headers.
  29
  30 If you develop applications, please try to reuse existing manager
  31 headers and their interpretation. If you are unsure, discuss on
  32 the asterisk-dev mailing list.
  33
  34 Device status reports
  35 ---------------------
  36 Manager subscribes to extension status reports from all channels,
  37 to be able to generate events when an extension or device changes
  38 state. The level of details in these events may depend on the channel
  39 and device configuration. Please check each channel configuration
  40 file for more information. (in sip.conf, check the section on
  41 subscriptions and call limits)
  42
  43
  44 Command Syntax
  45 --------------
  46 Management communication consists of tags of the form "header: value",
  47 terminated with an empty newline (\r\n) in the style of SMTP, HTTP, and
  48 other headers.
  49
  50
  51 The first tag MUST be one of the following:
  52
  53     * Action: An action requested by the CLIENT to the Asterisk SERVER. Only one "Action" may be outstanding at any time.
  54     * Response: A response to an action from the Asterisk SERVER to the CLIENT.
  55     * Event: An event reported by the Asterisk SERVER to the CLIENT
  56
  57
  58 Manager commands
  59 ----------------
  60 Output from the CLI command 'show manager' command:
  61
  62     * Ping: Ping
  63     * Logoff: Logoff Manager
  64     * Hangup: Hangup Channel
  65     * Status: Status
  66     * Redirect: Redirect
  67     * Originate: Originate Call
  68     * MailboxStatus: Check Mailbox
  69     * Command: Execute Command
  70     * ExtensionState: Check Extension Status
  71     * AbsoluteTimeout: Set Absolute Timeout
  72     * MailboxCount: Check Mailbox Message Count
  73     * Monitor: Monitor a channel
  74     * StopMonitor: Stop monitoring a channel
  75     * ChangeMonitor: Change monitoring filename of a channel
  76     * IAXpeers: List IAX Peers (Defaults to IAX2)
  77     * SIPpeers: List SIP peers
  78     * SIPshowpeer: Show data about one SIP peer
  79     * Queues: Queues
  80     * QueueStatus: Queue Status
  81
  82 This list depends on the version of Asterisk you are using, as
  83 well as which modules that are loaded.
  84
  85 Command Summary
  86 --------------
  87
  88 Command: Command
  89 Parameters: Command
  90
  91 Command: ExtensionState
  92 Parameters: Exten, Context, ActionID
  93
  94 Command: Hangup
  95 Parameters: Channel
  96
  97 Command: Logoff
  98 Parameters: None
  99
 100 Command: MailboxCount
 101 Parameters: Mailbox, ActionID
 102
 103 Command: MailboxStatus
 104 Parameters: Mailbox, ActionID
 105
 106 Command: Originate
 107 Parameters: Channel, Exten, Context, Priority, Timeout,
 108    CallerID, Variable, Account, Application, Data, Async
 109
 110 Command: Ping
 111 Parameters: None
 112
 113 Command: PlayDTMF
 114 Parameters: Channel, Digit
 115
 116 Command: Redirect
 117 Parameters: Channel, ExtraChannel, Exten, Context, Priority
 118
 119 Command: Timeout
 120 Parameters: Channel, Timeout
 121
 122 You can always get more information about a manager command
 123 with the "show manager command <command>" CLI command in Asterisk.
 124
 125 Examples
 126 --------
 127 Login - Log a user into the manager interface.
 128
 129    Action: Login
 130    Username: testuser
 131    Secret: testsecret
 132
 133 Originate - Originate a call from a channel to an extension.
 134
 135    Action: Originate
 136    Channel: sip/12345
 137    Exten: 1234
 138    Context: default
 139
 140 Originate - Originate a call from a channel to an extension without waiting
 141 for call to complete.
 142
 143    Action: Originate
 144    Channel: sip/12345
 145    Exten: 1234
 146    Context: default
 147    Async: yes
 148
 149
 150 Redirect with ExtraChannel:
 151   Attempted goal:
 152   Have a 'robot' program Redirect both ends of an already-connected call
 153   to a meetme room using the ExtraChannel feature through the management interface.
 154
 155   Action: Redirect
 156   Channel: Zap/1-1
 157   ExtraChannel: SIP/3064-7e00 (varies)
 158   Exten: 680
 159   Priority: 1
 160
 161 Where 680 is an extension that sends you to a MeetMe room.
 162
 163 There are a number of GUI tools that use the manager interface, please search
 164 the mailing list archives and the documentation page on the
 165 http://www.asterisk.org web site for more information.
 166
 167
 168 Some standard AMI headers:
 169 --------------------------
 170
 171  Account:                       -- Account Code (Status)
 172  AccountCode:                   -- Account Code (cdr_manager)
 173  ACL: <Y | N>                   -- Does ACL exist for object ?
 174  Action: <action>               -- request or notification of a particular action
 175  Address-IP:                    -- IPaddress
 176  Address-Port:                  -- IP port number
 177  Agent: <string>                -- Agent name
 178  AMAflags:                      -- AMA flag (cdr_manager, sippeers)
 179  AnswerTime:                    -- Time of answer (cdr_manager)
 180  Append: <bool>                 -- CDR userfield Append flag
 181  Application:                   -- Application to use
 182  Async:                         -- Whether or not to use fast setup
 183  AuthType:                      -- Authentication type (for login or challenge)
 184                                         "md5"
 185  BillableSeconds:               -- Billable seconds for call (cdr_manager)
 186  CallerID:                      -- Caller id (name and number in Originate & cdr_manager)
 187  CallerID:                      -- CallerID number
 188                                    Number or "<unknown>" or "unknown"
 189                                         (should change to "<unknown>" in app_queue)
 190  CallerID1:                     -- Channel 1 CallerID (Link event)
 191  CallerID2:                     -- Channel 2 CallerID (Link event)
 192  CallerIDName:                  -- CallerID name
 193                                    Name or "<unknown>" or "unknown"
 194                                         (should change to "<unknown>" in app_queue)
 195  Callgroup:                     -- Call group for peer/user
 196  CallsTaken: <num>              -- Queue status variable
 197  Cause: <value>                 -- Event change cause - "Expired"
 198  Cause: <value>                 -- Hangupcause (channel.c)
 199  CID-CallingPres:               -- Caller ID calling presentation
 200  Channel: <channel>             -- Channel specifier
 201  Channel: <dialstring>          -- Dialstring in Originate
 202  Channel: <tech/[peer/username]> -- Channel in Registry events (SIP, IAX2)
 203  Channel: <tech>                -- Technology (SIP/IAX2 etc) in Registry events
 204  ChannelType:                   -- Tech: SIP, IAX2, ZAP, MGCP etc
 205  Channel1:                      -- Link channel 1
 206  Channel2:                      -- Link channel 2
 207  ChanObjectType:                -- "peer", "user"
 208  Codecs:                        -- Codec list
 209  CodecOrder:                    -- Codec order, separated with comma ","
 210  Command:                       -- Cli command to run
 211  Context:                       -- Context
 212  Count: <num>                   -- Number of callers in queue
 213  Data:                          -- Application data
 214  Default-addr-IP:               -- IP address to use before registration
 215  Default-Username:              -- Username part of URI to use before registration
 216  Destination:                   -- Destination for call (Dialstring ) (dial, cdr_manager)
 217  DestinationContext:            -- Destination context (cdr_manager)
 218  DestinationChannel:            -- Destination channel (cdr_manager)
 219  DestUniqueID:                  -- UniqueID of destination (dial event)
 220  Disposition:                   -- Call disposition (CDR manager)
 221  Domain: <domain>               -- DNS domain
 222  Duration: <secs>               -- Duration of call (cdr_manager)
 223  Dynamic: <Y |  N>              -- Device registration supported?
 224  Endtime:                       -- End time stamp of call (cdr_manager)
 225  EventList: <flag>              -- Flag being "Start", "End", "Cancelled" or "ListObject"
 226  Events: <eventmask>            -- Eventmask filter ("on", "off", "system", "call", "log")
 227  Exten:                         -- Extension (Redirect command)
 228  Extension:                     -- Extension (Status)
 229  Family: <string>               -- ASTdb key family
 230  File: <filename>               -- Filename (monitor)
 231  Format: <format>               -- Format of sound file (monitor)
 232  From: <time>                   --  Parking time (ParkedCall event)
 233  Hint:                          -- Extension hint
 234  Incominglimit:                 -- SIP Peer incoming limit
 235  Key:
 236  Key:                           -- ASTdb Database key
 237  LastApplication:               -- Last application executed (cdr_manager)
 238  LastCall: <num>                -- Last call in queue
 239  LastData:                      -- Data for last application (cdr_manager)
 240  Link:                          -- (Status)
 241  ListItems: <number>            -- Number of items in Eventlist (Optionally sent in "end" packet)
 242  Location:                      -- Interface (whatever that is -maybe tech/name in app_queue )
 243  Loginchan:                     -- Login channel for agent
 244  Logintime: <number>            -- Login time for agent
 245  Mailbox:                       -- VM Mailbox (id@vmcontext) (mailboxstatus, mailboxcount)
 246  MD5SecretExist: <Y | N>        -- Whether secret exists in MD5 format
 247  Membership: <string>           -- "Dynamic" or "static" member in queue
 248  Message: <text>                -- Text message in ACKs, errors (explanation)
 249  Mix: <bool>                    -- Boolean parameter (monitor)
 250  NewMessages: <count>           -- Count of new Mailbox messages (mailboxcount)
 251  Newname:
 252  ObjectName:                    -- Name of object in list
 253  OldName:                       -- Something in Rename (channel.c)
 254  OldMessages: <count>           -- Count of old mailbox messages (mailboxcount)
 255  Outgoinglimit:                 -- SIP Peer outgoing limit
 256  Paused: <num>                  -- Queue member paused status
 257  Peer: <tech/name>              -- "channel" specifier :-)
 258  PeerStatus: <tech/name>        -- Peer status code
 259                                         "Unregistered", "Registered", "Lagged", "Reachable"
 260  Penalty: <num>                 -- Queue penalty
 261  Priority:                      -- Extension priority
 262  Privilege: <privilege>         -- AMI authorization class (system, call, log, verbose, command, agent, user)
 263  Pickupgroup:                   -- Pickup group for peer
 264  Position: <num>                -- Position in Queue
 265  Queue:                         -- Queue name
 266  Reason:                        -- "Autologoff"
 267  Reason:                        -- "Chanunavail"
 268  Response: <response>           -- response code, like "200 OK"
 269                                         "Success", "Error", "Follows"
 270  Restart:                       -- "True", "False"
 271  RegExpire:                     -- SIP registry expire
 272  RegExpiry:                     -- SIP registry expiry
 273  Reason:                        -- Originate reason code
 274  Seconds:                       -- Seconds (Status)
 275  Secret: <password>             -- Authentication secret (for login)
 276  SecretExist: <Y | N>           -- Whether secret exists
 277  Shutdown:                      -- "Uncleanly", "Cleanly"
 278  SIP-AuthInsecure:
 279  SIP-FromDomain:                -- Peer FromDomain
 280  SIP-FromUser:                  -- Peer FromUser
 281  SIP-NatSupport:
 282  SIPLastMsg:
 283  Source:                        -- Source of call (dial event, cdr_manager)
 284  SrcUniqueID:                   -- UniqueID of source (dial event)
 285  StartTime:                     -- Start time of call (cdr_manager)
 286  State:                         -- Channel state
 287  Status:                        -- Registration status (Registry events SIP)
 288  Status:                        -- Extension status (Extensionstate)
 289  Status:                        -- Peer status (if monitored)  ** Will change name **
 290                                         "unknown", "lagged", "ok"
 291  Status: <num>                  -- Queue Status
 292  Status:                        -- DND status (DNDState)
 293  Time: <sec>                    -- Roundtrip time (latency)
 294  Timeout:                       -- Parking timeout time
 295  Timeout:                       -- Timeout for call setup (Originate)
 296  Timeout: <seconds>             -- Timeout for call
 297  Uniqueid:                      -- Channel Unique ID
 298  Uniqueid1:                     -- Channel 1 Unique ID (Link event)
 299  Uniqueid2:                     -- Channel 2 Unique ID (Link event)
 300  User:                          -- Username (SIP registry)
 301  UserField:                     -- CDR userfield (cdr_manager)
 302  Val:                           -- Value to set/read in ASTdb
 303  Variable:                      -- Variable AND value to set (multiple separated with | in Originate)
 304  Variable: <name>               -- For channel variables
 305  Value: <value>                 -- Value to set
 306  VoiceMailbox:                  -- VM Mailbox in SIPpeers
 307  Waiting:                       -- Count of mailbox messages (mailboxstatus)
 308
 309  ** Please try to re-use existing headers to simplify manager message parsing in clients.
 310
 311 Read the CODING-GUIDELINES if you develop new manager commands or events.