8692400a43dd4c4c2841529b3bcabe10f2ae46f4
[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": "0.0.1",
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                                 "PlaybackStarted",
80                                 "PlaybackFinished",
81                                 "ApplicationReplaced",
82                                 "BridgeCreated",
83                                 "BridgeDestroyed",
84                                 "BridgeMerged",
85                                 "ChannelCreated",
86                                 "ChannelDestroyed",
87                                 "ChannelEnteredBridge",
88                                 "ChannelLeftBridge",
89                                 "ChannelStateChange",
90                                 "ChannelDtmfReceived",
91                                 "ChannelDialplan",
92                                 "ChannelCallerId",
93                                 "ChannelUserevent",
94                                 "ChannelHangupRequest",
95                                 "ChannelVarset",
96                                 "EndpointStateChange",
97                                 "StasisEnd",
98                                 "StasisStart"
99                         ]
100                 },
101                 "PlaybackStarted": {
102                         "id": "PlaybackStarted",
103                         "description": "Event showing the start of a media playback operation.",
104                         "properties": {
105                                 "playback": {
106                                         "type": "Playback",
107                                         "description": "Playback control object",
108                                         "required": true
109                                 }
110                         }
111                 },
112                 "PlaybackFinished": {
113                         "id": "PlaybackFinished",
114                         "description": "Event showing the completion of a media playback operation.",
115                         "properties": {
116                                 "playback": {
117                                         "type": "Playback",
118                                         "description": "Playback control object",
119                                         "required": true
120                                 }
121                         }
122                 },
123                 "RecordingStarted": {
124                         "id": "RecordingStarted",
125                         "extends": "Event",
126                         "description": "Event showing the start of a recording operation.",
127                         "properties": {
128                                 "recording": {
129                                         "type": "LiveRecording",
130                                         "description": "Recording control object",
131                                         "required": true
132                                 }
133                         }
134                 },
135                 "RecordingFinished": {
136                         "id": "RecordingFinished",
137                         "extends": "Event",
138                         "description": "Event showing the completion of a recording operation.",
139                         "properties": {
140                                 "recording": {
141                                         "type": "LiveRecording",
142                                         "description": "Recording control object",
143                                         "required": true
144                                 }
145                         }
146                 },
147                 "RecordingFailed": {
148                         "id": "RecordingFailed",
149                         "extends": "Event",
150                         "description": "Event showing failure of a recording operation.",
151                         "properties": {
152                                 "recording": {
153                                         "type": "LiveRecording",
154                                         "description": "Recording control object",
155                                         "required": true
156                                 },
157                                 "cause": {
158                                         "type": "string",
159                                         "description": "Cause for the recording failure",
160                                         "required": true
161                                 }
162                         }
163                 },
164                 "ApplicationReplaced": {
165                         "id": "ApplicationReplaced",
166                         "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.",
167                         "properties": {}
168                 },
169                 "BridgeCreated": {
170                         "id": "BridgeCreated",
171                         "description": "Notification that a bridge has been created.",
172                         "properties": {
173                                 "bridge": {
174                                         "required": true,
175                                         "type": "Bridge"
176                                 }
177                         }
178                 },
179                 "BridgeDestroyed": {
180                         "id": "BridgeDestroyed",
181                         "description": "Notification that a bridge has been destroyed.",
182                         "properties": {
183                                 "bridge": {
184                                         "required": true,
185                                         "type": "Bridge"
186                                 }
187                         }
188                 },
189                 "BridgeMerged": {
190                         "id": "BridgeMerged",
191                         "description": "Notification that one bridge has merged into another.",
192                         "properties": {
193                                 "bridge": {
194                                         "required": true,
195                                         "type": "Bridge"
196                                 },
197                                 "bridge_from": {
198                                         "required": true,
199                                         "type": "Bridge"
200                                 }
201                         }
202                 },
203                 "ChannelCreated": {
204                         "id": "ChannelCreated",
205                         "description": "Notification that a channel has been created.",
206                         "properties": {
207                                 "channel": {
208                                         "required": true,
209                                         "type": "Channel"
210                                 }
211                         }
212                 },
213                 "ChannelDestroyed": {
214                         "id": "ChannelDestroyed",
215                         "description": "Notification that a channel has been destroyed.",
216                         "properties": {
217                                 "cause": {
218                                         "required": true,
219                                         "description": "Integer representation of the cause of the hangup",
220                                         "type": "int"
221                                 },
222                                 "cause_txt": {
223                                         "required": true,
224                                         "description": "Text representation of the cause of the hangup",
225                                         "type": "string"
226                                 },
227                                 "channel": {
228                                         "required": true,
229                                         "type": "Channel"
230                                 }
231                         }
232                 },
233                 "ChannelEnteredBridge": {
234                         "id": "ChannelEnteredBridge",
235                         "description": "Notification that a channel has entered a bridge.",
236                         "properties": {
237                                 "bridge": {
238                                         "required": true,
239                                         "type": "Bridge"
240                                 },
241                                 "channel": {
242                                         "type": "Channel"
243                                 }
244                         }
245                 },
246                 "ChannelLeftBridge": {
247                         "id": "ChannelLeftBridge",
248                         "description": "Notification that a channel has left a bridge.",
249                         "properties": {
250                                 "bridge": {
251                                         "required": true,
252                                         "type": "Bridge"
253                                 },
254                                 "channel": {
255                                         "required": true,
256                                         "type": "Channel"
257                                 }
258                         }
259                 },
260                 "ChannelStateChange": {
261                         "id": "ChannelStateChange",
262                         "description": "Notification of a channel's state change.",
263                         "properties": {
264                                 "channel": {
265                                         "required": true,
266                                         "type": "Channel"
267                                 }
268                         }
269                 },
270                 "ChannelDtmfReceived": {
271                         "id": "ChannelDtmfReceived",
272                         "description": "DTMF received on a channel.\n\nThis event is sent when the DTMF ends. There is no notification about the start of DTMF",
273                         "properties": {
274                                 "digit": {
275                                         "required": true,
276                                         "type": "string",
277                                         "description": "DTMF digit received (0-9, A-E, # or *)"
278                                 },
279                                 "duration_ms": {
280                                         "required": true,
281                                         "type": "int",
282                                         "description": "Number of milliseconds DTMF was received"
283                                 },
284                                 "channel": {
285                                         "required": true,
286                                         "type": "Channel",
287                                         "description": "The channel on which DTMF was received"
288                                 }
289                         }
290                 },
291                 "ChannelDialplan": {
292                         "id": "ChannelDialplan",
293                         "description": "Channel changed location in the dialplan.",
294                         "properties": {
295                                 "channel": {
296                                         "required": true,
297                                         "type": "Channel",
298                                         "description": "The channel that changed dialplan location."
299                                 },
300                                 "dialplan_app": {
301                                         "required": true,
302                                         "type": "string",
303                                         "description": "The application about to be executed."
304                                 },
305                                 "dialplan_app_data": {
306                                         "required": true,
307                                         "type": "string",
308                                         "description": "The data to be passed to the application."
309                                 }
310                         }
311                 },
312                 "ChannelCallerId": {
313                         "id": "ChannelCallerId",
314                         "description": "Channel changed Caller ID.",
315                         "properties": {
316                                 "caller_presentation": {
317                                         "required": true,
318                                         "type": "int",
319                                         "description": "The integer representation of the Caller Presentation value."
320                                 },
321                                 "caller_presentation_txt": {
322                                         "required": true,
323                                         "type": "string",
324                                         "description": "The text representation of the Caller Presentation value."
325                                 },
326                                 "channel": {
327                                         "required": true,
328                                         "type": "Channel",
329                                         "description": "The channel that changed Caller ID."
330                                 }
331                         }
332                 },
333                 "ChannelUserevent": {
334                         "id": "ChannelUserevent",
335                         "description": "User-generated event with additional user-defined fields in the object.",
336                         "properties": {
337                                 "eventname": {
338                                         "required": true,
339                                         "type": "string",
340                                         "description": "The name of the user event."
341                                 },
342                                 "channel": {
343                                         "required": true,
344                                         "type": "Channel",
345                                         "description": "The channel that signaled the user event."
346                                 },
347                                 "userevent": {
348                                         "required": true,
349                                         "type": "object",
350                                         "description": "Custom Userevent data"
351                                 }
352                         }
353                 },
354                 "ChannelHangupRequest": {
355                         "id": "ChannelHangupRequest",
356                         "description": "A hangup was requested on the channel.",
357                         "properties": {
358                                 "cause": {
359                                         "type": "int",
360                                         "description": "Integer representation of the cause of the hangup."
361                                 },
362                                 "soft": {
363                                         "type": "boolean",
364                                         "description": "Whether the hangup request was a soft hangup request."
365                                 },
366                                 "channel": {
367                                         "required": true,
368                                         "type": "Channel",
369                                         "description": "The channel on which the hangup was requested."
370                                 }
371                         }
372                 },
373                 "ChannelVarset": {
374                         "id": "ChannelVarset",
375                         "description": "Channel variable changed.",
376                         "properties": {
377                                 "variable": {
378                                         "required": true,
379                                         "type": "string",
380                                         "description": "The variable that changed."
381                                 },
382                                 "value": {
383                                         "required": true,
384                                         "type": "string",
385                                         "description": "The new value of the variable."
386                                 },
387                                 "channel": {
388                                         "required": false,
389                                         "type": "Channel",
390                                         "description": "The channel on which the variable was set.\n\nIf missing, the variable is a global variable."
391                                 }
392                         }
393                 },
394                 "EndpointStateChange": {
395                         "id": "EndpointStateChange",
396                         "description": "Endpoint state changed.",
397                         "properties": {
398                                 "endpoint": {
399                                         "required": true,
400                                         "type": "Endpoint"
401                                 }
402                         }
403                 },
404                 "StasisEnd": {
405                         "id": "StasisEnd",
406                         "description": "Notification that a channel has left a Stasis appliction.",
407                         "properties": {
408                                 "channel": {
409                                         "required": true,
410                                         "type": "Channel"
411                                 }
412                         }
413                 },
414                 "StasisStart": {
415                         "id": "StasisStart",
416                         "description": "Notification that a channel has entered a Stasis appliction.",
417                         "properties": {
418                                 "args": {
419                                         "required": true,
420                                         "type": "List[string]",
421                                         "description": "Arguments to the application"
422                                 },
423                                 "channel": {
424                                         "required": true,
425                                         "type": "Channel"
426                                 }
427                         }
428                 }
429         }
430 }