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