Update API versions and UPGRADE/CHANGES for 12.2.0
[asterisk/asterisk.git] / rest-api / api-docs / events.json
1 {
2         "_copyright": "Copyright (C) 2012 - 2013, Digium, Inc.",
3         "_author": "David M. Lee, II <dlee@digium.com>",
4         "_svn_revision": "$Revision$",
5         "apiVersion": "1.2.0",
6         "swaggerVersion": "1.2",
7         "basePath": "http://localhost:8088/stasis",
8         "resourcePath": "/api-docs/events.{format}",
9         "apis": [
10                 {
11                         "path": "/events",
12                         "description": "Events from Asterisk to applications",
13                         "operations": [
14                                 {
15                                         "httpMethod": "GET",
16                                         "upgrade": "websocket",
17                                         "websocketProtocol": "ari",
18                                         "summary": "WebSocket connection for events.",
19                                         "nickname": "eventWebsocket",
20                                         "responseClass": "Message",
21                                         "parameters": [
22                                                 {
23                                                         "name": "app",
24                                                         "description": "Applications to subscribe to.",
25                                                         "paramType": "query",
26                                                         "required": true,
27                                                         "allowMultiple": true,
28                                                         "dataType": "string"
29                                                 }
30                                         ]
31                                 }
32                         ]
33                 }
34         ],
35         "models": {
36                 "Message": {
37                         "id": "Message",
38                         "description": "Base type for errors and events",
39                         "discriminator": "type",
40                         "properties": {
41                                 "type": {
42                                         "type": "string",
43                                         "required": true,
44                                         "description": "Indicates the type of this message."
45                                 }
46                         },
47                         "subTypes": [
48                                 "MissingParams",
49                                 "Event"
50                         ]
51                 },
52                 "MissingParams": {
53                         "id": "MissingParams",
54                         "description": "Error event sent when required params are missing.",
55                         "properties": {
56                                 "params": {
57                                         "required": true,
58                                         "type": "List[string]",
59                                         "description": "A list of the missing parameters"
60                                 }
61                         }
62                 },
63                 "Event": {
64                         "id": "Event",
65                         "description": "Base type for asynchronous events from Asterisk.",
66                         "properties": {
67                                 "application": {
68                                         "type": "string",
69                                         "description": "Name of the application receiving the event.",
70                                         "required": true
71                                 },
72                                 "timestamp": {
73                                         "type": "Date",
74                                         "description": "Time at which this event was created.",
75                                         "required": false
76                                 }
77                         },
78                         "subTypes": [
79                                 "DeviceStateChanged",
80                                 "PlaybackStarted",
81                                 "PlaybackFinished",
82                                 "RecordingStarted",
83                                 "RecordingFinished",
84                                 "RecordingFailed",
85                                 "ApplicationReplaced",
86                                 "BridgeCreated",
87                                 "BridgeDestroyed",
88                                 "BridgeMerged",
89                                 "BridgeBlindTransfer",
90                                 "BridgeAttendedTransfer",
91                                 "ChannelCreated",
92                                 "ChannelDestroyed",
93                                 "ChannelEnteredBridge",
94                                 "ChannelLeftBridge",
95                                 "ChannelStateChange",
96                                 "ChannelDtmfReceived",
97                                 "ChannelDialplan",
98                                 "ChannelCallerId",
99                                 "ChannelUserevent",
100                                 "ChannelHangupRequest",
101                                 "ChannelVarset",
102                                 "EndpointStateChange",
103                                 "Dial",
104                                 "StasisEnd",
105                                 "StasisStart"
106                         ]
107                 },
108                 "DeviceStateChanged": {
109                         "id": "DeviceStateChanged",
110                         "description": "Notification that a device state has changed.",
111                         "properties": {
112                                 "device_state": {
113                                         "type": "DeviceState",
114                                         "description": "Device state object",
115                                         "required": true
116                                 }
117                         }
118                 },
119                 "PlaybackStarted": {
120                         "id": "PlaybackStarted",
121                         "description": "Event showing the start of a media playback operation.",
122                         "properties": {
123                                 "playback": {
124                                         "type": "Playback",
125                                         "description": "Playback control object",
126                                         "required": true
127                                 }
128                         }
129                 },
130                 "PlaybackFinished": {
131                         "id": "PlaybackFinished",
132                         "description": "Event showing the completion of a media playback operation.",
133                         "properties": {
134                                 "playback": {
135                                         "type": "Playback",
136                                         "description": "Playback control object",
137                                         "required": true
138                                 }
139                         }
140                 },
141                 "RecordingStarted": {
142                         "id": "RecordingStarted",
143                         "extends": "Event",
144                         "description": "Event showing the start of a recording operation.",
145                         "properties": {
146                                 "recording": {
147                                         "type": "LiveRecording",
148                                         "description": "Recording control object",
149                                         "required": true
150                                 }
151                         }
152                 },
153                 "RecordingFinished": {
154                         "id": "RecordingFinished",
155                         "extends": "Event",
156                         "description": "Event showing the completion of a recording operation.",
157                         "properties": {
158                                 "recording": {
159                                         "type": "LiveRecording",
160                                         "description": "Recording control object",
161                                         "required": true
162                                 }
163                         }
164                 },
165                 "RecordingFailed": {
166                         "id": "RecordingFailed",
167                         "extends": "Event",
168                         "description": "Event showing failure of a recording operation.",
169                         "properties": {
170                                 "recording": {
171                                         "type": "LiveRecording",
172                                         "description": "Recording control object",
173                                         "required": true
174                                 }
175                         }
176                 },
177                 "ApplicationReplaced": {
178                         "id": "ApplicationReplaced",
179                         "description": "Notification that another WebSocket has taken over for an application.\n\nAn application may only be subscribed to by a single WebSocket at a time. If multiple WebSockets attempt to subscribe to the same application, the newer WebSocket wins, and the older one receives this event.",
180                         "properties": {}
181                 },
182                 "BridgeCreated": {
183                         "id": "BridgeCreated",
184                         "description": "Notification that a bridge has been created.",
185                         "properties": {
186                                 "bridge": {
187                                         "required": true,
188                                         "type": "Bridge"
189                                 }
190                         }
191                 },
192                 "BridgeDestroyed": {
193                         "id": "BridgeDestroyed",
194                         "description": "Notification that a bridge has been destroyed.",
195                         "properties": {
196                                 "bridge": {
197                                         "required": true,
198                                         "type": "Bridge"
199                                 }
200                         }
201                 },
202                 "BridgeMerged": {
203                         "id": "BridgeMerged",
204                         "description": "Notification that one bridge has merged into another.",
205                         "properties": {
206                                 "bridge": {
207                                         "required": true,
208                                         "type": "Bridge"
209                                 },
210                                 "bridge_from": {
211                                         "required": true,
212                                         "type": "Bridge"
213                                 }
214                         }
215                 },
216                 "BridgeBlindTransfer": {
217                         "id": "BridgeBlindTransfer",
218                         "description": "Notification that a blind transfer has occurred.",
219                         "properties": {
220                                 "channel": {
221                                         "description": "The channel performing the blind transfer",
222                                         "required": true,
223                                         "type": "Channel"
224                                 },
225                                 "exten": {
226                                         "description": "The extension transferred to",
227                                         "required": true,
228                                         "type": "string"
229                                 },
230                                 "context": {
231                                         "description": "The context transferred to",
232                                         "required": true,
233                                         "type": "string"
234                                 },
235                                 "result": {
236                                         "description": "The result of the transfer attempt",
237                                         "required": true,
238                                         "type": "string"
239                                 },
240                                 "is_external": {
241                                         "description": "Whether the transfer was externally initiated or not",
242                                         "required": true,
243                                         "type": "boolean"
244                                 },
245                                 "bridge": {
246                                         "description": "The bridge being transferred",
247                                         "type": "Bridge"
248                                 }
249                         }
250                 },
251                 "BridgeAttendedTransfer": {
252                         "id": "BridgeAttendedTransfer",
253                         "description": "Notification that an attended transfer has occurred.",
254                         "properties": {
255                                 "transferer_first_leg": {
256                                         "description": "First leg of the transferer",
257                                         "required": true,
258                                         "type": "Channel"
259                                 },
260                                 "transferer_second_leg": {
261                                         "description": "Second leg of the transferer",
262                                         "required": true,
263                                         "type": "Channel"
264                                 },
265                                 "result": {
266                                         "description": "The result of the transfer attempt",
267                                         "required": true,
268                                         "type": "string"
269                                 },
270                                 "is_external": {
271                                         "description": "Whether the transfer was externally initiated or not",
272                                         "required": true,
273                                         "type": "boolean"
274                                 },
275                                 "transferer_first_leg_bridge": {
276                                         "description": "Bridge the transferer first leg is in",
277                                         "type": "Bridge"
278                                 },
279                                 "transferer_second_leg_bridge": {
280                                         "description": "Bridge the transferer second leg is in",
281                                         "type": "Bridge"
282                                 },
283                                 "destination_type": {
284                                         "description": "How the transfer was accomplished",
285                                         "required": true,
286                                         "type": "string"
287                                 },
288                                 "destination_bridge": {
289                                         "description": "Bridge that survived the merge result",
290                                         "type": "string"
291                                 },
292                                 "destination_application": {
293                                         "description": "Application that has been transferred into",
294                                         "type": "string"
295                                 },
296                                 "destination_link_first_leg": {
297                                         "description": "First leg of a link transfer result",
298                                         "type": "Channel"
299                                 },
300                                 "destination_link_second_leg": {
301                                         "description": "Second leg of a link transfer result",
302                                         "type": "Channel"
303                                 },
304                                 "destination_threeway_channel": {
305                                         "description": "Transferer channel that survived the threeway result",
306                                         "type": "Channel"
307                                 },
308                                 "destination_threeway_bridge": {
309                                         "description": "Bridge that survived the threeway result",
310                                         "type": "Bridge"
311                                 }
312                         }
313                 },
314                 "ChannelCreated": {
315                         "id": "ChannelCreated",
316                         "description": "Notification that a channel has been created.",
317                         "properties": {
318                                 "channel": {
319                                         "required": true,
320                                         "type": "Channel"
321                                 }
322                         }
323                 },
324                 "ChannelDestroyed": {
325                         "id": "ChannelDestroyed",
326                         "description": "Notification that a channel has been destroyed.",
327                         "properties": {
328                                 "cause": {
329                                         "required": true,
330                                         "description": "Integer representation of the cause of the hangup",
331                                         "type": "int"
332                                 },
333                                 "cause_txt": {
334                                         "required": true,
335                                         "description": "Text representation of the cause of the hangup",
336                                         "type": "string"
337                                 },
338                                 "channel": {
339                                         "required": true,
340                                         "type": "Channel"
341                                 }
342                         }
343                 },
344                 "ChannelEnteredBridge": {
345                         "id": "ChannelEnteredBridge",
346                         "description": "Notification that a channel has entered a bridge.",
347                         "properties": {
348                                 "bridge": {
349                                         "required": true,
350                                         "type": "Bridge"
351                                 },
352                                 "channel": {
353                                         "type": "Channel"
354                                 }
355                         }
356                 },
357                 "ChannelLeftBridge": {
358                         "id": "ChannelLeftBridge",
359                         "description": "Notification that a channel has left a bridge.",
360                         "properties": {
361                                 "bridge": {
362                                         "required": true,
363                                         "type": "Bridge"
364                                 },
365                                 "channel": {
366                                         "required": true,
367                                         "type": "Channel"
368                                 }
369                         }
370                 },
371                 "ChannelStateChange": {
372                         "id": "ChannelStateChange",
373                         "description": "Notification of a channel's state change.",
374                         "properties": {
375                                 "channel": {
376                                         "required": true,
377                                         "type": "Channel"
378                                 }
379                         }
380                 },
381                 "ChannelDtmfReceived": {
382                         "id": "ChannelDtmfReceived",
383                         "description": "DTMF received on a channel.\n\nThis event is sent when the DTMF ends. There is no notification about the start of DTMF",
384                         "properties": {
385                                 "digit": {
386                                         "required": true,
387                                         "type": "string",
388                                         "description": "DTMF digit received (0-9, A-E, # or *)"
389                                 },
390                                 "duration_ms": {
391                                         "required": true,
392                                         "type": "int",
393                                         "description": "Number of milliseconds DTMF was received"
394                                 },
395                                 "channel": {
396                                         "required": true,
397                                         "type": "Channel",
398                                         "description": "The channel on which DTMF was received"
399                                 }
400                         }
401                 },
402                 "ChannelDialplan": {
403                         "id": "ChannelDialplan",
404                         "description": "Channel changed location in the dialplan.",
405                         "properties": {
406                                 "channel": {
407                                         "required": true,
408                                         "type": "Channel",
409                                         "description": "The channel that changed dialplan location."
410                                 },
411                                 "dialplan_app": {
412                                         "required": true,
413                                         "type": "string",
414                                         "description": "The application about to be executed."
415                                 },
416                                 "dialplan_app_data": {
417                                         "required": true,
418                                         "type": "string",
419                                         "description": "The data to be passed to the application."
420                                 }
421                         }
422                 },
423                 "ChannelCallerId": {
424                         "id": "ChannelCallerId",
425                         "description": "Channel changed Caller ID.",
426                         "properties": {
427                                 "caller_presentation": {
428                                         "required": true,
429                                         "type": "int",
430                                         "description": "The integer representation of the Caller Presentation value."
431                                 },
432                                 "caller_presentation_txt": {
433                                         "required": true,
434                                         "type": "string",
435                                         "description": "The text representation of the Caller Presentation value."
436                                 },
437                                 "channel": {
438                                         "required": true,
439                                         "type": "Channel",
440                                         "description": "The channel that changed Caller ID."
441                                 }
442                         }
443                 },
444                 "ChannelUserevent": {
445                         "id": "ChannelUserevent",
446                         "description": "User-generated event with additional user-defined fields in the object.",
447                         "properties": {
448                                 "eventname": {
449                                         "required": true,
450                                         "type": "string",
451                                         "description": "The name of the user event."
452                                 },
453                                 "channel": {
454                                         "required": true,
455                                         "type": "Channel",
456                                         "description": "The channel that signaled the user event."
457                                 },
458                                 "userevent": {
459                                         "required": true,
460                                         "type": "object",
461                                         "description": "Custom Userevent data"
462                                 }
463                         }
464                 },
465                 "ChannelHangupRequest": {
466                         "id": "ChannelHangupRequest",
467                         "description": "A hangup was requested on the channel.",
468                         "properties": {
469                                 "cause": {
470                                         "type": "int",
471                                         "description": "Integer representation of the cause of the hangup."
472                                 },
473                                 "soft": {
474                                         "type": "boolean",
475                                         "description": "Whether the hangup request was a soft hangup request."
476                                 },
477                                 "channel": {
478                                         "required": true,
479                                         "type": "Channel",
480                                         "description": "The channel on which the hangup was requested."
481                                 }
482                         }
483                 },
484                 "ChannelVarset": {
485                         "id": "ChannelVarset",
486                         "description": "Channel variable changed.",
487                         "properties": {
488                                 "variable": {
489                                         "required": true,
490                                         "type": "string",
491                                         "description": "The variable that changed."
492                                 },
493                                 "value": {
494                                         "required": true,
495                                         "type": "string",
496                                         "description": "The new value of the variable."
497                                 },
498                                 "channel": {
499                                         "required": false,
500                                         "type": "Channel",
501                                         "description": "The channel on which the variable was set.\n\nIf missing, the variable is a global variable."
502                                 }
503                         }
504                 },
505                 "EndpointStateChange": {
506                         "id": "EndpointStateChange",
507                         "description": "Endpoint state changed.",
508                         "properties": {
509                                 "endpoint": {
510                                         "required": true,
511                                         "type": "Endpoint"
512                                 }
513                         }
514                 },
515                 "Dial": {
516                         "id": "Dial",
517                         "description": "Dialing state has changed.",
518                         "properties": {
519                                 "caller": {
520                                         "required": false,
521                                         "type": "Channel",
522                                         "description": "The calling channel."
523                                 },
524                                 "peer": {
525                                         "required": true,
526                                         "type": "Channel",
527                                         "description": "The dialed channel."
528                                 },
529                                 "forward": {
530                                         "required": false,
531                                         "type": "string",
532                                         "description": "Forwarding target requested by the original dialed channel."
533                                 },
534                                 "forwarded": {
535                                         "required": false,
536                                         "type": "Channel",
537                                         "description": "Channel that the caller has been forwarded to."
538                                 },
539                                 "dialstring": {
540                                         "required": false,
541                                         "type": "string",
542                                         "description": "The dial string for calling the peer channel."
543                                 },
544                                 "dialstatus": {
545                                         "required": true,
546                                         "type": "string",
547                                         "description": "Current status of the dialing attempt to the peer."
548                                 }
549                         }
550                 },
551                 "StasisEnd": {
552                         "id": "StasisEnd",
553                         "description": "Notification that a channel has left a Stasis application.",
554                         "properties": {
555                                 "channel": {
556                                         "required": true,
557                                         "type": "Channel"
558                                 }
559                         }
560                 },
561                 "StasisStart": {
562                         "id": "StasisStart",
563                         "description": "Notification that a channel has entered a Stasis application.",
564                         "properties": {
565                                 "args": {
566                                         "required": true,
567                                         "type": "List[string]",
568                                         "description": "Arguments to the application"
569                                 },
570                                 "channel": {
571                                         "required": true,
572                                         "type": "Channel"
573                                 }
574                         }
575                 }
576         }
577 }