a9b47def5295cfd1abc95e02210d393d06140242
[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: Transfer
318         Modules: res_features, chan_sip
319         Purpose:
320                 Inform about call transfer, linking transferer with transfer target
321                 You should be able to trace the call flow with this missing piece
322                 of information. If it works out well, the "Transfer" event should
323                 be followed by a "Bridge" event
324                 The transfermethod: header informs if this is a pbx core transfer
325                 or something done on channel driver level. For SIP, check the example:
326         Example:
327                 
328                 Event: Transfer
329                 Privilege: call,all
330                 TransferMethod: SIP
331                 TransferType: Blind
332                 Channel: SIP/device1-01849800
333                 SIP-Callid: 091386f505842c87016c4d93195ec67d@127.0.0.1
334                 TargetChannel: SIP/device2-01841200
335                 TransferExten: 100
336                 TransferContext: default
337
338 - Event: ChannelUpdate
339         Modules: chan_sip.c, chan_iax2.c
340         Purpose:
341                 Updates channel information with ID of PVT in channel driver, to
342                 be able to link events on channel driver level.
343                 * Integrated in SVN trunk as of May 4th, 2007
344
345         Example:
346
347                 Event: ChannelUpdate
348                 Privilege: system,all
349                 Uniqueid: 1177271625.27
350                 Channel: SIP/olle-01843c00
351                 Channeltype: SIP
352                 SIPcallid: NTQzYWFiOWM4NmE0MWRkZjExMzU2YzQ3OWQwNzg3ZmI.
353                 SIPfullcontact: sip:olle@127.0.0.1:49054
354
355 - Event: NewAccountCode
356         Modules: cdr.c
357         Purpose: To report a change in account code for a live channel
358         Example:
359                 Event: NewAccountCode
360                 Privilege: call,all
361                 Channel: SIP/olle-01844600
362                 Uniqueid: 1177530895.2
363                 AccountCode: Stinas account 1234848484
364                 OldAccountCode: OllesAccount 12345
365
366 - Event: ModuleLoadReport
367         Modules: loader.c
368         Purpose: To report that module loading is complete. Some aggressive
369                 clients connect very quickly to AMI and needs to know when
370                 all manager events embedded in modules are loaded
371                 Also, if this does not happen, something is seriously wrong.
372                 This could happen to chan_sip and other modules using DNS.
373         Example:
374                 Event: ModuleLoad
375                 ModuleLoadStatus: Done
376                 ModuleSelection: All
377                 ModuleCount: 24
378
379 - Event: QueueSummary
380         Modules: app_queue
381         Purpose: To report a summary of queue information. This event is generated by
382                 issuing a QueueSummary AMI action.
383         Example:
384                 Event: QueueSummary
385                 Queue: Sales
386                 LoggedIn: 12
387                 Available: 5
388                 Callers: 10
389                 HoldTime: 47
390         If an actionID was specified for the QueueSummary action, it will be appended as the
391         last line of the QueueSummary event.
392
393 - Event: AgentRingNoAnswer
394         Modules: app_queue
395         Purpose: Reports when a queue member was rung but there was no answer.
396         Example:
397                 Event: AgentRingNoAnswer
398                 Queue: Support
399                 Uniqueid: 1177530895.2
400                 Channel: SIP/1000-53aee458
401                 Member: SIP/1000
402                 MemberName: Thaddeus McClintock
403                 Ringtime: 10
404
405 - Event: RegistryEntry
406         Modules: chan_sip
407         Purpose: Reports the state of the SIP registrations. This event is generated by
408                 issuing a QueueSummary AMI action.
409                 The RegistrationTime header is expressed as epoch.
410         Example:
411                 Event: RegistryEntry
412                 Host: sip.myvoipprovider.com
413                 Port: 5060
414                 Username: guestuser
415                 Refresh: 105
416                 State: Registered
417                 RegistrationTime: 1219161830
418         If an actionID was specified for the SipShowRegistry action, it will be appended as the
419         last line of the RegistrationsComplete event.
420
421 - Event: ChanSpyStart
422         Modules: app_chanspy
423         Purpose: Reports when an active channel starts to be monitored by someone.
424         Example:
425                 Event: ChanSpyStart
426                 SpyerChannel: SIP/4321-13bba124
427                 SpyeeChannel: SIP/1234-56ecc098
428
429 - Event: ChanSpyStop
430         Modules: app_chanspy
431         Purpose: Reports when an active channel stops to be monitored by someone.
432         Example:
433                 Event: ChanSpyStop
434                 SpyeeChannel: SIP/1234-56ecc098
435
436 * TODO
437 ------
438