add channel CLID info in manager Link event (bug #4548 with minor mod)
[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: Redirect
105 Parameters: Channel, ExtraChannel, Exten, Context, Priority
106
107 Command: Timeout
108 Parameters: Channel, Timeout
109
110 You can always get more information about a manager command
111 with the "show manager command <command>" CLI command in Asterisk.
112
113 Examples
114 --------
115 Login - Log a user into the manager interface.
116
117    Action: Login
118    Username: testuser
119    Secret: testsecret
120
121 Originate - Originate a call from a channel to an extension.
122
123    Action: Originate
124    Channel: sip/12345
125    Exten: 1234
126    Context: default
127
128 Originate - Originate a call from a channel to an extension without waiting
129 for call to complete.
130
131    Action: Originate
132    Channel: sip/12345
133    Exten: 1234
134    Context: default
135    Async: yes
136
137
138 Redirect with ExtraChannel:
139   Attempted goal:
140   Have a 'robot' program Redirect both ends of an already-connected call
141   to a meetme room using the ExtraChannel feature through the management interface.
142
143   Action: Redirect
144   Channel: Zap/1-1
145   ExtraChannel: SIP/3064-7e00 (varies)
146   Exten: 680
147   Priority: 1
148
149 Where 680 is an extension that sends you to a MeetMe room.
150
151 There are a number of GUI tools that use the manager interface, please search
152 the mailing list archives and the documentation page on the 
153 http://www.asterisk.org web site for more information.
154
155
156 Some standard AMI headers:
157 --------------------------
158
159  Account:                       -- Account Code (Status)
160  AccountCode:                   -- Account Code (cdr_manager)
161  ACL: <Y | N>                   -- Does ACL exist for object ?
162  Action: <action>               -- request or notification of a particular action
163  Address-IP:                    -- IPaddress 
164  Address-Port:                  -- IP port number
165  Agent: <string>                -- Agent name
166  AMAflags:                      -- AMA flag (cdr_manager, sippeers)
167  AnswerTime:                    -- Time of answer (cdr_manager)
168  Append: <bool>                 -- CDR userfield Append flag
169  Application:                   -- Application to use
170  Async:                         -- Whether or not to use fast setup
171  AuthType:                      -- Authentication type (for login or challenge)
172                                         "md5"
173  BillableSeconds:               -- Billable seconds for call (cdr_manager)
174  CallerID:                      -- Caller id (name and number in Originate & cdr_manager)
175  CallerID:                      -- CallerID number
176                                    Number or "<unknown>" or "unknown" 
177                                         (should change to "<unknown>" in app_queue)
178  CallerID1:                     -- Channel 1 CallerID (Link event)
179  CallerID2:                     -- Channel 2 CallerID (Link event)
180  CallerIDName:                  -- CallerID name
181                                    Name or "<unknown>" or "unknown" 
182                                         (should change to "<unknown>" in app_queue)
183  Callgroup:                     -- Call group for peer/user
184  CallsTaken: <num>              -- Queue status variable
185  Cause: <value>                 -- Event change cause - "Expired"
186  Cause: <value>                 -- Hangupcause (channel.c)
187  CID-CallingPres:               -- Caller ID calling presentation
188  ChanVariable:                  -- Channel variable to set - name,value (comma between name and value)
189  Channel: <channel>             -- Channel specifier
190  Channel: <dialstring>          -- Dialstring in Originate
191  Channel: <tech/[peer/username]> -- Channel in Registry events (SIP, IAX2)
192  Channel: <tech>                -- Technology (SIP/IAX2 etc) in Registry events
193  ChannelType:                   -- Tech: SIP, IAX2, ZAP, MGCP etc
194  Channel1:                      -- Link channel 1
195  Channel2:                      -- Link channel 2
196  ChanObjectType:                -- "peer", "user"
197  Codecs:                        -- Codec list
198  CodecOrder:                    -- Codec order, separated with comma ","
199  Command:                       -- Cli command to run
200  Context:                       -- Context
201  Count: <num>                   -- Number of callers in queue
202  Data:                          -- Application data
203  Default-addr-IP:               -- IP address to use before registration
204  Default-Username:              -- Username part of URI to use before registration
205  Destination:                   -- Destination for call (Dialstring ) (dial, cdr_manager)
206  DestinationContext:            -- Destination context (cdr_manager)
207  DestinationChannel:            -- Destination channel (cdr_manager)
208  DestUniqueID:                  -- UniqueID of destination (dial event)
209  Disposition:                   -- Call disposition (CDR manager)
210  Domain: <domain>               -- DNS domain
211  Duration: <secs>               -- Duration of call (cdr_manager)
212  Dynamic: <Y |  N>              -- Device registration supported?
213  Endtime:                       -- End time stamp of call (cdr_manager)
214  EventList: <flag>              -- Flag being "Start", "End", "Cancelled" or "ListObject"
215  Events: <eventmask>            -- Eventmask filter ("on", "off", "system", "call", "log")
216  Exten:                         -- Extension (Redirect command)
217  Extension:                     -- Extension (Status)
218  Family: <string>               -- ASTdb key family
219  File: <filename>               -- Filename (monitor)
220  Format: <format>               -- Format of sound file (monitor)
221  From: <time>                   --  Parking time (ParkedCall event)
222  Hint:                          -- Extension hint
223  Incominglimit:                 -- SIP Peer incoming limit
224  Key:
225  Key:                           -- ASTdb Database key
226  LastApplication:               -- Last application executed (cdr_manager)
227  LastCall: <num>                -- Last call in queue
228  LastData:                      -- Data for last application (cdr_manager)
229  Link:                          -- (Status)
230  ListItems: <number>            -- Number of items in Eventlist (Optionally sent in "end" packet)
231  Location:                      -- Interface (whatever that is -maybe tech/name in app_queue )
232  Loginchan:                     -- Login channel for agent
233  Logintime: <number>            -- Login time for agent
234  Mailbox:                       -- VM Mailbox (id@vmcontext) (mailboxstatus, mailboxcount)
235  MD5SecretExist: <Y | N>        -- Whether secret exists in MD5 format 
236  Membership: <string>           -- "Dynamic" or "static" member in queue
237  Message: <text>                -- Text message in ACKs, errors (explanation)
238  Mix: <bool>                    -- Boolean parameter (monitor) 
239  NewMessages: <count>           -- Count of new Mailbox messages (mailboxcount)
240  Newname:               
241  ObjectName:                    -- Name of object in list
242  OldName:                       -- Something in Rename (channel.c)
243  OldMessages: <count>           -- Count of old mailbox messages (mailboxcount) 
244  Outgoinglimit:                 -- SIP Peer outgoing limit
245  Paused: <num>                  -- Queue member paused status
246  Peer: <tech/name>              -- "channel" specifier :-)
247  PeerStatus: <tech/name>        -- Peer status code 
248                                         "Unregistred", "Registred", "Lagged", "Reachable"
249  Penalty: <num>                 -- Queue penalty
250  Priority:                      -- Extension priority
251  Privilege: <privilege>         -- AMI authorization class (system, call, log, verbose, command, agent, user)
252  Pickupgroup:                   -- Pickup group for peer
253  Position: <num>                -- Position in Queue
254  Queue:                         -- Queue name
255  Reason:                        -- "Autologoff"
256  Response: <response>           -- response code, like "200 OK"
257                                         "Success", "Error", "Follows"
258  Restart:                       -- "True", "False"
259  RegExpire:                     -- SIP registry expire
260  RegExpiry:                     -- SIP registry expiry
261  Reason:                        -- Originate reason code
262  Seconds:                       -- Seconds (Status)
263  Secret: <password>             -- Authentication secret (for login)
264  SecretExist: <Y | N>           -- Whether secret exists 
265  Shutdown:                      -- "Uncleanly", "Cleanly" 
266  SIP-AuthInsecure:
267  SIP-FromDomain:                -- Peer FromDomain
268  SIP-FromUser:                  -- Peer FromUser
269  SIP-NatSupport:
270  SIPLastMsg:
271  Source:                        -- Source of call (dial event, cdr_manager)
272  SrcUniqueID:                   -- UniqueID of source (dial event)
273  StartTime:                     -- Start time of call (cdr_manager)
274  State:                         -- Channel state
275  Status:                        -- Registration status (Registry events SIP)
276  Status:                        -- Extension status (Extensionstate)
277  Status:                        -- Peer status (if monitored)  ** Will change name **
278                                         "unknown", "lagged", "ok"
279  Status: <num>                  -- Queue Status
280  Status:                        -- DND status (DNDState)
281  Time: <sec>                    -- Roundtrip time (latency)
282  Timeout:                       -- Parking timeout time
283  Timeout:                       -- Timeout for call setup (Originate)
284  Timeout: <seconds>             -- Timout for call
285  Uniqueid:                      -- Channel Unique ID
286  Uniqueid1:                     -- Channel 1 Unique ID (Link event)
287  Uniqueid2:                     -- Channel 2 Unique ID (Link event)
288  User:                          -- Username (SIP registry)
289  UserField:                     -- CDR userfield (cdr_manager)
290  Val:                           -- Value to set/read in ASTdb
291  Variable:                      -- Variable AND value to set (multiple separated with | in Originate)
292  Variable: <name>               -- For channel variables
293  Value: <value>                 -- Value to set
294  VoiceMailbox:                  -- VM Mailbox in SIPpeers
295  Waiting:                       -- Count of mailbox messages (mailboxstatus)
296
297  ** Please try to re-use existing headers to simplify manager message parsing in clients.
298