ari: Add events for playback and recording.
[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                         }
158                 },
159                 "ApplicationReplaced": {
160                         "id": "ApplicationReplaced",
161                         "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.",
162                         "properties": {}
163                 },
164                 "BridgeCreated": {
165                         "id": "BridgeCreated",
166                         "description": "Notification that a bridge has been created.",
167                         "properties": {
168                                 "bridge": {
169                                         "required": true,
170                                         "type": "Bridge"
171                                 }
172                         }
173                 },
174                 "BridgeDestroyed": {
175                         "id": "BridgeDestroyed",
176                         "description": "Notification that a bridge has been destroyed.",
177                         "properties": {
178                                 "bridge": {
179                                         "required": true,
180                                         "type": "Bridge"
181                                 }
182                         }
183                 },
184                 "BridgeMerged": {
185                         "id": "BridgeMerged",
186                         "description": "Notification that one bridge has merged into another.",
187                         "properties": {
188                                 "bridge": {
189                                         "required": true,
190                                         "type": "Bridge"
191                                 },
192                                 "bridge_from": {
193                                         "required": true,
194                                         "type": "Bridge"
195                                 }
196                         }
197                 },
198                 "ChannelCreated": {
199                         "id": "ChannelCreated",
200                         "description": "Notification that a channel has been created.",
201                         "properties": {
202                                 "channel": {
203                                         "required": true,
204                                         "type": "Channel"
205                                 }
206                         }
207                 },
208                 "ChannelDestroyed": {
209                         "id": "ChannelDestroyed",
210                         "description": "Notification that a channel has been destroyed.",
211                         "properties": {
212                                 "cause": {
213                                         "required": true,
214                                         "description": "Integer representation of the cause of the hangup",
215                                         "type": "int"
216                                 },
217                                 "cause_txt": {
218                                         "required": true,
219                                         "description": "Text representation of the cause of the hangup",
220                                         "type": "string"
221                                 },
222                                 "channel": {
223                                         "required": true,
224                                         "type": "Channel"
225                                 }
226                         }
227                 },
228                 "ChannelEnteredBridge": {
229                         "id": "ChannelEnteredBridge",
230                         "description": "Notification that a channel has entered a bridge.",
231                         "properties": {
232                                 "bridge": {
233                                         "required": true,
234                                         "type": "Bridge"
235                                 },
236                                 "channel": {
237                                         "type": "Channel"
238                                 }
239                         }
240                 },
241                 "ChannelLeftBridge": {
242                         "id": "ChannelLeftBridge",
243                         "description": "Notification that a channel has left a bridge.",
244                         "properties": {
245                                 "bridge": {
246                                         "required": true,
247                                         "type": "Bridge"
248                                 },
249                                 "channel": {
250                                         "required": true,
251                                         "type": "Channel"
252                                 }
253                         }
254                 },
255                 "ChannelStateChange": {
256                         "id": "ChannelStateChange",
257                         "description": "Notification of a channel's state change.",
258                         "properties": {
259                                 "channel": {
260                                         "required": true,
261                                         "type": "Channel"
262                                 }
263                         }
264                 },
265                 "ChannelDtmfReceived": {
266                         "id": "ChannelDtmfReceived",
267                         "description": "DTMF received on a channel.\n\nThis event is sent when the DTMF ends. There is no notification about the start of DTMF",
268                         "properties": {
269                                 "digit": {
270                                         "required": true,
271                                         "type": "string",
272                                         "description": "DTMF digit received (0-9, A-E, # or *)"
273                                 },
274                                 "duration_ms": {
275                                         "required": true,
276                                         "type": "int",
277                                         "description": "Number of milliseconds DTMF was received"
278                                 },
279                                 "channel": {
280                                         "required": true,
281                                         "type": "Channel",
282                                         "description": "The channel on which DTMF was received"
283                                 }
284                         }
285                 },
286                 "ChannelDialplan": {
287                         "id": "ChannelDialplan",
288                         "description": "Channel changed location in the dialplan.",
289                         "properties": {
290                                 "channel": {
291                                         "required": true,
292                                         "type": "Channel",
293                                         "description": "The channel that changed dialplan location."
294                                 },
295                                 "dialplan_app": {
296                                         "required": true,
297                                         "type": "string",
298                                         "description": "The application about to be executed."
299                                 },
300                                 "dialplan_app_data": {
301                                         "required": true,
302                                         "type": "string",
303                                         "description": "The data to be passed to the application."
304                                 }
305                         }
306                 },
307                 "ChannelCallerId": {
308                         "id": "ChannelCallerId",
309                         "description": "Channel changed Caller ID.",
310                         "properties": {
311                                 "caller_presentation": {
312                                         "required": true,
313                                         "type": "int",
314                                         "description": "The integer representation of the Caller Presentation value."
315                                 },
316                                 "caller_presentation_txt": {
317                                         "required": true,
318                                         "type": "string",
319                                         "description": "The text representation of the Caller Presentation value."
320                                 },
321                                 "channel": {
322                                         "required": true,
323                                         "type": "Channel",
324                                         "description": "The channel that changed Caller ID."
325                                 }
326                         }
327                 },
328                 "ChannelUserevent": {
329                         "id": "ChannelUserevent",
330                         "description": "User-generated event with additional user-defined fields in the object.",
331                         "properties": {
332                                 "eventname": {
333                                         "required": true,
334                                         "type": "string",
335                                         "description": "The name of the user event."
336                                 },
337                                 "channel": {
338                                         "required": true,
339                                         "type": "Channel",
340                                         "description": "The channel that signaled the user event."
341                                 },
342                                 "userevent": {
343                                         "required": true,
344                                         "type": "object",
345                                         "description": "Custom Userevent data"
346                                 }
347                         }
348                 },
349                 "ChannelHangupRequest": {
350                         "id": "ChannelHangupRequest",
351                         "description": "A hangup was requested on the channel.",
352                         "properties": {
353                                 "cause": {
354                                         "type": "int",
355                                         "description": "Integer representation of the cause of the hangup."
356                                 },
357                                 "soft": {
358                                         "type": "boolean",
359                                         "description": "Whether the hangup request was a soft hangup request."
360                                 },
361                                 "channel": {
362                                         "required": true,
363                                         "type": "Channel",
364                                         "description": "The channel on which the hangup was requested."
365                                 }
366                         }
367                 },
368                 "ChannelVarset": {
369                         "id": "ChannelVarset",
370                         "description": "Channel variable changed.",
371                         "properties": {
372                                 "variable": {
373                                         "required": true,
374                                         "type": "string",
375                                         "description": "The variable that changed."
376                                 },
377                                 "value": {
378                                         "required": true,
379                                         "type": "string",
380                                         "description": "The new value of the variable."
381                                 },
382                                 "channel": {
383                                         "required": false,
384                                         "type": "Channel",
385                                         "description": "The channel on which the variable was set.\n\nIf missing, the variable is a global variable."
386                                 }
387                         }
388                 },
389                 "EndpointStateChange": {
390                         "id": "EndpointStateChange",
391                         "description": "Endpoint state changed.",
392                         "properties": {
393                                 "endpoint": {
394                                         "required": true,
395                                         "type": "Endpoint"
396                                 }
397                         }
398                 },
399                 "StasisEnd": {
400                         "id": "StasisEnd",
401                         "description": "Notification that a channel has left a Stasis application.",
402                         "properties": {
403                                 "channel": {
404                                         "required": true,
405                                         "type": "Channel"
406                                 }
407                         }
408                 },
409                 "StasisStart": {
410                         "id": "StasisStart",
411                         "description": "Notification that a channel has entered a Stasis application.",
412                         "properties": {
413                                 "args": {
414                                         "required": true,
415                                         "type": "List[string]",
416                                         "description": "Arguments to the application"
417                                 },
418                                 "channel": {
419                                         "required": true,
420                                         "type": "Channel"
421                                 }
422                         }
423                 }
424         }
425 }