30ba876ca56b85f48c147af38d9bf8c6137c4a7f
[asterisk/asterisk.git] / doc / manager_1_1.txt
1 Changes to manager version 1.1:
2 -------------------------------
3
4 * SYNTAX CLEANUPS
5 -----------------
6
7 - Response: headers are now either
8         "Success"       - Action OK, this message contains response
9         "Error"         - Action failed, reason in Message: header
10         "Follows"       - Action OK, response follows in following Events.
11
12 - Manager version changed to 1.1
13
14 * CHANGED EVENTS AND ACTIONS
15 ----------------------------
16 - The Hold/Unhold events
17         - Both are now "Hold" events
18                 For hold, there's a "Status: On" header, for unhold, status is off
19         - Modules chan_sip/chan_iax2
20
21 - The Ping Action
22         - Now use Response: success
23         - New header "Ping: pong" :-)
24
25 - The Events action
26         - Now use Response: Success
27         - The new status is reported as "Events: On" or "Events: Off"
28
29 - The JabberSend action
30         - The Response: header is now the first header in the response
31         - now sends "Response: Error" instead of "Failure"
32
33 - Newstate and Newchannel events
34         - these have changed headers
35         "State"         -> ChannelStateDesc     Text based channel state
36                         -> ChannelState         Numeric channel state
37         - The events does not send "<unknown>" for unknown caller IDs just an empty field
38
39 - Newchannel event
40         - Now includes "AccountCode"
41
42 - Newstate event
43         - Now has "CalleridNum" for numeric caller id, like Newchannel
44         - The event does not send "<unknown>" for unknown caller IDs just an empty field
45
46 - Newexten and VarSet events
47         - Now are part of the new Dialplan privilege class, instead of the Call class
48
49 - Dial event
50         - Event Dial has new headers, to comply with other events
51         - Source        -> Channel              Channel name (caller)
52         - SrcUniqueID   -> UniqueID             Uniqueid
53         (new)           -> Dialstring           Dialstring in app data
54
55 - Link and Unlink events
56         - The "Link" and "Unlink" bridge events in channel.c are now renamed to "Bridge"
57         - The link state is in the bridgestate: header as "Link" or "Unlink"
58         - For channel.c bridges, "Bridgetype: core" is added. This opens up for
59           bridge events in rtp.c 
60         - The RTP channel also reports Bridge: events with bridgetypes
61                 - rtp-native    RTP native bridge
62                 - rtp-direct    RTP peer-2-peer bridge (NAT support only)
63                 - rtp-remote    Remote (re-invite) bridge. (Not reported yet)
64
65 - The "Rename" manager event has a renamed header, to use the same
66         terminology for the current channel as other events
67         - Oldname       -> Channel              
68
69 - The "NewCallerID" manager event has a renamed header
70         - CallerID      -> CallerIDnum
71         - The event does not send "<unknown>" for unknown caller IDs just an empty field
72         
73 - Reload event
74         - The "Reload" event sent at manager reload now has a new header and is now implemented
75         in more modules than manager to alert a reload. For channels, there's a CHANNELRELOAD 
76         event to use.
77         (new)           -> Module: manager | CDR | DNSmgr | RTP | ENUM
78         (new)           -> Status: enabled | disabled
79         - To support reload events from other modules too
80                 - cdr module added
81
82 - Status action replies (Event: Status)
83         Header changes
84         - link          -> BridgedChannel
85         - Account       -> AccountCode
86         - (new)         -> BridgedUniqueid
87
88 - StatusComplete Event
89         New header
90         - (new)         -> Items                Number of channels reported
91         
92
93 - The ExtensionStatus manager command now has a "StatusDesc" field with text description of the state
94
95 - The Registry and Peerstatus events in chan_sip and chan_iax now use "ChannelType" instead of "ChannelDriver"
96
97 - The Response to Action: IAXpeers now have a Response: Success header
98
99 - The MeetmeJoin now has caller ID name and Caller ID number fields (like MeetMeLeave)
100
101 - Action DAHDIShowChannels
102         Header changes
103         - Channel:      -> DAHDIChannel
104         For active channels, the Channel: and Uniqueid: headers are added
105         You can now add a "DAHDIChannel: " argument to DAHDIshowchannels actions
106         to only get information about one channel.
107
108 - Event DAHDIShowChannelsComplete
109         New header
110         - (new)         -> Items:       Reports number of channels reported
111
112 - Action VoicemailUsersList
113         Added new headers for SayEnvelope, SayCID, AttachMessage, CanReview
114         and CallOperator voicemail configuration settings.
115
116 - Action Originate
117         Now requires the new Originate privilege.
118         If you call out to a subshell in Originate with the Application parameter,
119                 you now also need the System privilege.
120
121 - Event QueueEntry now also returns the Uniqueid field like other events from app_queue.
122
123 - Action IAXpeerlist
124         Now includes if the IAX link is a trunk or not
125
126 - Action IAXpeers
127         Now includes if the IAX link is a trunk or not
128
129 - Action Ping
130         Response now includes a timestamp
131
132 - Action SIPshowpeer
133         Response now includes the configured parkinglot
134
135 - Action SKINNYshowline
136         Response now includes the configured parkinglot
137
138 * NEW ACTIONS
139 -------------
140 - Action: DataGet
141         Modules: data.c
142         Purpose:
143                 To be able to retrieve the asterisk data tree.
144         Variables:
145           ActionID: <id>          Action ID for this transaction. Will be returned.
146           Path: <data path>       The path to the callback node to retrieve.
147           Filter: <filter>        Which nodes to retrieve.
148           Search: <search>        Search condition.
149
150 - Action: IAXregistry
151         Modules: chan_iax2
152         Purpose:
153                 To list all IAX2 peers in the IAX registry with their registration status.
154         Variables:
155           ActionID: <id>                Action ID for this transaction. Will be returned.
156
157 - Action: ModuleLoad
158         Modules: loader.c
159         Purpose:
160                 To be able to unload, reload and unload modules from AMI.
161         Variables: 
162           ActionID: <id>          Action ID for this transaction. Will be returned.
163           Module: <name>          Asterisk module name (including .so extension)
164                                   or subsystem identifier:
165                                 cdr, enum, dnsmgr, extconfig, manager, rtp, http
166           LoadType: load | unload | reload
167                           The operation to be done on module
168         If no module is specified for a reload loadtype, all modules are reloaded
169
170 - Action: ModuleCheck
171         Modules: loader.c
172         Purpose:
173                 To check version of a module - if it's loaded
174         Variables:
175           ActionID: <id>          Action ID for this transaction. Will be returned.
176           Module: <name>          Asterisk module name (not including extension)
177         Returns:
178                 If module is loaded, returns version number of the module
179                 
180                 Note: This will have to change. I don't like sending Response: failure
181                 on both command not found (trying this command in earlier versions of
182                 Asterisk) and module not found.
183                 Also, check if other manager actions behave that way.
184
185 - Action: QueueSummary
186         Modules: app_queue
187         Purpose:
188                 To request that the manager send a QueueSummary event (see the NEW EVENTS
189             section for more details).
190         Variables:
191           ActionID: <id>                Action ID for this transaction. Will be returned.
192           Queue: <name>                 Queue for which the summary is desired
193
194 - Action: QueuePenalty
195         Modules: app_queue
196         Purpose:
197                 To change the penalty of a queue member from AMI
198         Variables:
199           Interface: <tech/name>        The interface of the member whose penalty you wish to change
200           Penalty:  <number>            The new penalty for the member. Must be nonnegative.
201           Queue:  <name>                If specified, only set the penalty for the member for this queue;
202                                         Otherwise, set the penalty for the member in all queues to which
203                                         he belongs.
204
205 - Action: QueueRule
206         Modules: app_queue
207         Purpose:
208                 To list queue rules defined in queuerules.conf
209         Variables:
210           Rule: <name>                  The name of the rule whose contents you wish to list. If this variable
211                                         is not present, all rules in queuerules.conf will be listed.
212                 
213 - Action: Atxfer
214         Modules: none
215         Purpose:
216                 Initiate an attended transfer
217         Variables:
218                 Channel: The transferer channel's name
219                 Exten: The extension to transfer to
220                 Priority: The priority to transfer to
221                 Context: The context to transfer to
222
223 - Action: SipShowRegistry
224         Modules: chan_sip
225         Purpose:
226                 To request that the manager send a list of RegistryEntry events.
227         Variables:
228           ActionId: <id>                Action ID for this transaction. Will be returned.
229
230 - Action: QueueReload
231         Modules: app_queue
232         Purpose:
233                 To reload queue rules, a queue's members, a queue's parameters, or all of the aforementioned
234         Variable:
235                 Queuename: <name> The name of the queue to take action on. If no queue name is specified, then all queues are affected
236                 Rules: <yes or no> Whether to reload queue_rules.conf
237                 Members: <yes or no> Whether to reload the queue's members
238                 Parameters: <yes or no> Whether to reload the other queue options
239
240 - Action: QueueReset
241         Modules: app_queue
242         Purpose:
243                 Reset the statistics for a queue
244         Variables:
245                 Queuename: <name> The name of the queue on which to reset statistics
246
247 - Action: SKINNYdevices
248         Modules: chan_skinny
249         Purpose:
250                 To list all SKINNY devices configured.
251         Variables:
252                 ActionId: <id> Action ID for this transaction. Will be returned.
253
254 - Action: SKINNYlines
255         Modules: chan_skinny
256         Purpose:
257                 To list all SKINNY lines configured.
258         Variables:
259                 ActionId: <id> Action ID for this transaction. Will be returned.
260
261 - Action SKINNYshowdevice
262         Modules: chan_skinny
263         Purpose:
264                 To list the information about a specific SKINNY device.
265         Variables:
266                 Device: <device> Device to show information about.
267
268 - Action SKINNYshowline
269         Modules: chan_skinny
270         Purpose:
271                 To list the information about a specific SKINNY line.
272         Variables:
273                 Line: <line> Line to show information about.
274
275 - Action: CoreSettings
276         Modules: manager.c
277         Purpose: To report core settings, like AMI and Asterisk version,
278                 maxcalls and maxload settings.
279                 * Integrated in SVN trunk as of May 4th, 2007
280         Example:
281                 Response: Success
282                 ActionID: 1681692777
283                 AMIversion: 1.1
284                 AsteriskVersion: SVN-oej-moremanager-r61756M
285                 SystemName: EDVINA-node-a
286                 CoreMaxCalls: 120
287                 CoreMaxLoadAvg: 0.000000
288                 CoreRunUser: edvina
289                 CoreRunGroup: edvina
290
291 - Action: CoreStatus
292         Modules: manager.c
293         Purpose: To report current PBX core status flags, like
294                 number of concurrent calls, startup and reload time.
295                 * Integrated in SVN trunk as of May 4th, 2007
296         Example:
297                 Response: Success
298                 ActionID: 1649760492
299                 CoreStartupTime: 22:35:17
300                 CoreReloadTime: 22:35:17
301                 CoreCurrentCalls: 20
302
303 - Action: MixMonitorMute
304         Modules: app_mixmonitor.c
305         Purpose: 
306                 Mute / unMute a Mixmonitor recording.
307         Variables: 
308                 ActionId: <id> Action ID for this transaction. Will be returned.
309                 Channel: the channel MixMonitor is running on
310                 Direction: Which part of the recording to mute:  read, write or both (from
311                         channel, to channel or both channels).
312                 State: Turn mute on or off : 1 to turn on, 0 to turn off.
313
314 * NEW EVENTS
315 ------------
316
317 - Event: FullyBooted
318         Modules: loader.c
319         Purpose:
320                 It is handy to have a single event notification for when all Asterisk
321                 modules have been loaded--especially for situations like running
322                 automated tests. This event will fire 1) immediately upon all modules
323                 loading or 2) upon connection to the AMI interface if the modules have
324                 already finished loading before the connection was made. This ensures
325                 that a user will never miss getting a FullyBooted event. In vary rare
326                 circumstances, it might be possible to get two copies of the message
327                 if the AMI connection is made right as the modules finish loading.
328         Example:
329                 Event: FullyBooted
330                 Privilege: system,all
331                 Status: Fully Booted
332
333 - Event: Transfer
334         Modules: res_features, chan_sip
335         Purpose:
336                 Inform about call transfer, linking transferer with transfer target
337                 You should be able to trace the call flow with this missing piece
338                 of information. If it works out well, the "Transfer" event should
339                 be followed by a "Bridge" event
340                 The transfermethod: header informs if this is a pbx core transfer
341                 or something done on channel driver level. For SIP, check the example:
342         Example:
343                 
344                 Event: Transfer
345                 Privilege: call,all
346                 TransferMethod: SIP
347                 TransferType: Blind
348                 Channel: SIP/device1-01849800
349                 SIP-Callid: 091386f505842c87016c4d93195ec67d@127.0.0.1
350                 TargetChannel: SIP/device2-01841200
351                 TransferExten: 100
352                 TransferContext: default
353
354 - Event: ChannelUpdate
355         Modules: chan_sip.c, chan_iax2.c
356         Purpose:
357                 Updates channel information with ID of PVT in channel driver, to
358                 be able to link events on channel driver level.
359                 * Integrated in SVN trunk as of May 4th, 2007
360
361         Example:
362
363                 Event: ChannelUpdate
364                 Privilege: system,all
365                 Uniqueid: 1177271625.27
366                 Channel: SIP/olle-01843c00
367                 Channeltype: SIP
368                 SIPcallid: NTQzYWFiOWM4NmE0MWRkZjExMzU2YzQ3OWQwNzg3ZmI.
369                 SIPfullcontact: sip:olle@127.0.0.1:49054
370
371 - Event: NewAccountCode
372         Modules: cdr.c
373         Purpose: To report a change in account code for a live channel
374         Example:
375                 Event: NewAccountCode
376                 Privilege: call,all
377                 Channel: SIP/olle-01844600
378                 Uniqueid: 1177530895.2
379                 AccountCode: Stinas account 1234848484
380                 OldAccountCode: OllesAccount 12345
381
382 - Event: ModuleLoadReport
383         Modules: loader.c
384         Purpose: To report that module loading is complete. Some aggressive
385                 clients connect very quickly to AMI and needs to know when
386                 all manager events embedded in modules are loaded
387                 Also, if this does not happen, something is seriously wrong.
388                 This could happen to chan_sip and other modules using DNS.
389         Example:
390                 Event: ModuleLoad
391                 ModuleLoadStatus: Done
392                 ModuleSelection: All
393                 ModuleCount: 24
394
395 - Event: QueueSummary
396         Modules: app_queue
397         Purpose: To report a summary of queue information. This event is generated by
398                 issuing a QueueSummary AMI action.
399         Example:
400                 Event: QueueSummary
401                 Queue: Sales
402                 LoggedIn: 12
403                 Available: 5
404                 Callers: 10
405                 HoldTime: 47
406         If an actionID was specified for the QueueSummary action, it will be appended as the
407         last line of the QueueSummary event.
408
409 - Event: AgentRingNoAnswer
410         Modules: app_queue
411         Purpose: Reports when a queue member was rung but there was no answer.
412         Example:
413                 Event: AgentRingNoAnswer
414                 Queue: Support
415                 Uniqueid: 1177530895.2
416                 Channel: SIP/1000-53aee458
417                 Member: SIP/1000
418                 MemberName: Thaddeus McClintock
419                 Ringtime: 10
420
421 - Event: RegistryEntry
422         Modules: chan_sip
423         Purpose: Reports the state of the SIP registrations. This event is generated by
424                 issuing a QueueSummary AMI action.
425                 The RegistrationTime header is expressed as epoch.
426         Example:
427                 Event: RegistryEntry
428                 Host: sip.myvoipprovider.com
429                 Port: 5060
430                 Username: guestuser
431                 Refresh: 105
432                 State: Registered
433                 RegistrationTime: 1219161830
434         If an actionID was specified for the SipShowRegistry action, it will be appended as the
435         last line of the RegistrationsComplete event.
436
437 - Event: ChanSpyStart
438         Modules: app_chanspy
439         Purpose: Reports when an active channel starts to be monitored by someone.
440         Example:
441                 Event: ChanSpyStart
442                 SpyerChannel: SIP/4321-13bba124
443                 SpyeeChannel: SIP/1234-56ecc098
444
445 - Event: ChanSpyStop
446         Modules: app_chanspy
447         Purpose: Reports when an active channel stops to be monitored by someone.
448         Example:
449                 Event: ChanSpyStop
450                 SpyeeChannel: SIP/1234-56ecc098
451
452 * TODO
453 ------
454