This patch adds support for controlling a playback operation from the
[asterisk/asterisk.git] / rest-api / api-docs / channels.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.1",
7         "basePath": "http://localhost:8088/stasis",
8         "resourcePath": "/api-docs/channels.{format}",
9         "apis": [
10                 {
11                         "path": "/channels",
12                         "description": "Active channels",
13                         "operations": [
14                                 {
15                                         "httpMethod": "GET",
16                                         "summary": "List active channels.",
17                                         "nickname": "getChannels",
18                                         "responseClass": "List[Channel]"
19                                 },
20                                 {
21                                         "httpMethod": "POST",
22                                         "summary": "Create a new channel (originate).",
23                                         "nickname": "originate",
24                                         "responseClass": "Originated",
25                                         "parameters": [
26                                                 {
27                                                         "name": "endpoint",
28                                                         "description": "Endpoint to call. If not specified, originate is routed via dialplan",
29                                                         "paramType": "query",
30                                                         "required": false,
31                                                         "allowMultiple": false,
32                                                         "dataType": "string"
33                                                 },
34                                                 {
35                                                         "name": "extension",
36                                                         "description": "Extension to dial",
37                                                         "paramType": "query",
38                                                         "required": false,
39                                                         "allowMultiple": false,
40                                                         "dataType": "string"
41                                                 },
42                                                 {
43                                                         "name": "context",
44                                                         "description": "When routing via dialplan, the context use. If omitted, uses 'default'",
45                                                         "paramType": "query",
46                                                         "required": false,
47                                                         "allowMultiple": false,
48                                                         "dataType": "string"
49                                                 }
50                                         ]
51                                 }
52                         ]
53                 },
54                 {
55                         "path": "/channels/{channelId}",
56                         "description": "Active channel",
57                         "operations": [
58                                 {
59                                         "httpMethod": "GET",
60                                         "summary": "Channel details.",
61                                         "nickname": "getChannel",
62                                         "responseClass": "Channel",
63                                         "parameters": [
64                                                 {
65                                                         "name": "channelId",
66                                                         "description": "Channel's id",
67                                                         "paramType": "path",
68                                                         "required": true,
69                                                         "allowMultiple": false,
70                                                         "dataType": "string"
71                                                 }
72                                         ],
73                                         "errorResponses": [
74                                                 {
75                                                         "code": 404,
76                                                         "reason": "Channel not found"
77                                                 }
78                                         ]
79                                 },
80                                 {
81                                         "httpMethod": "DELETE",
82                                         "summary": "Delete (i.e. hangup) a channel.",
83                                         "nickname": "deleteChannel",
84                                         "responseClass": "void",
85                                         "parameters": [
86                                                 {
87                                                         "name": "channelId",
88                                                         "description": "Channel's id",
89                                                         "paramType": "path",
90                                                         "required": true,
91                                                         "allowMultiple": false,
92                                                         "dataType": "string"
93                                                 }
94                                         ],
95                                         "errorResponses": [
96                                                 {
97                                                         "code": 404,
98                                                         "reason": "Channel not found"
99                                                 }
100                                         ]
101                                 }
102                         ]
103                 },
104                 {
105                         "path": "/channels/{channelId}/dial",
106                         "description": "Create a new channel (originate) and bridge to this channel",
107                         "operations": [
108                                 {
109                                         "httpMethod": "POST",
110                                         "summary": "Create a new channel (originate) and bridge to this channel.",
111                                         "nickname": "dial",
112                                         "responseClass": "Dialed",
113                                         "parameters": [
114                                                 {
115                                                         "name": "channelId",
116                                                         "description": "Channel's id",
117                                                         "paramType": "path",
118                                                         "required": true,
119                                                         "allowMultiple": false,
120                                                         "dataType": "string"
121                                                 },
122                                                 {
123                                                         "name": "endpoint",
124                                                         "description": "Endpoint to call. If not specified, dial is routed via dialplan",
125                                                         "paramType": "query",
126                                                         "required": false,
127                                                         "allowMultiple": false,
128                                                         "dataType": "string"
129                                                 },
130                                                 {
131                                                         "name": "extension",
132                                                         "description": "Extension to dial",
133                                                         "paramType": "query",
134                                                         "required": false,
135                                                         "allowMultiple": false,
136                                                         "dataType": "string"
137                                                 },
138                                                 {
139                                                         "name": "context",
140                                                         "description": "When routing via dialplan, the context use. If omitted, uses 'default'",
141                                                         "paramType": "query",
142                                                         "required": false,
143                                                         "allowMultiple": false,
144                                                         "dataType": "string"
145                                                 }
146                                         ],
147                                         "errorResponses": [
148                                                 {
149                                                         "code": 404,
150                                                         "reason": "Channel not found"
151                                                 },
152                                                 {
153                                                         "code": 409,
154                                                         "reason": "Channel not in a Stasis application"
155                                                 }
156                                         ]
157                                 }
158                         ]
159                 },
160                 {
161                         "path": "/channels/{channelId}/continue",
162                         "description": "Exit application; continue execution in the dialplan",
163                         "operations": [
164                                 {
165                                         "httpMethod": "POST",
166                                         "summary": "Exit application; continue execution in the dialplan.",
167                                         "nickname": "continueInDialplan",
168                                         "responseClass": "void",
169                                         "parameters": [
170                                                 {
171                                                         "name": "channelId",
172                                                         "description": "Channel's id",
173                                                         "paramType": "path",
174                                                         "required": true,
175                                                         "allowMultiple": false,
176                                                         "dataType": "string"
177                                                 }
178                                         ],
179                                         "errorResponses": [
180                                                 {
181                                                         "code": 404,
182                                                         "reason": "Channel not found"
183                                                 },
184                                                 {
185                                                         "code": 409,
186                                                         "reason": "Channel not in a Stasis application"
187                                                 }
188                                         ]
189                                 }
190                         ]
191                 },
192                 {
193                         "path": "/channels/{channelId}/answer",
194                         "description": "Answer a channel",
195                         "operations": [
196                                 {
197                                         "httpMethod": "POST",
198                                         "summary": "Answer a channel.",
199                                         "nickname": "answerChannel",
200                                         "responseClass": "void",
201                                         "parameters": [
202                                                 {
203                                                         "name": "channelId",
204                                                         "description": "Channel's id",
205                                                         "paramType": "path",
206                                                         "required": true,
207                                                         "allowMultiple": false,
208                                                         "dataType": "string"
209                                                 }
210                                         ],
211                                         "errorResponses": [
212                                                 {
213                                                         "code": 404,
214                                                         "reason": "Channel not found"
215                                                 }
216                                         ]
217                                 }
218                         ]
219                 },
220                 {
221                         "path": "/channels/{channelId}/mute",
222                         "description": "Mute a channel",
223                         "operations": [
224                                 {
225                                         "httpMethod": "POST",
226                                         "summary": "Mute a channel.",
227                                         "nickname": "muteChannel",
228                                         "responseClass": "void",
229                                         "parameters": [
230                                                 {
231                                                         "name": "channelId",
232                                                         "description": "Channel's id",
233                                                         "paramType": "path",
234                                                         "required": true,
235                                                         "allowMultiple": false,
236                                                         "dataType": "string"
237                                                 },
238                                                 {
239                                                         "name": "direction",
240                                                         "description": "Direction in which to mute audio",
241                                                         "paramType": "query",
242                                                         "required": false,
243                                                         "allowMultiple": false,
244                                                         "dataType": "string",
245                                                         "defaultValue": "both",
246                                                         "allowableValues": {
247                                                                 "valueType": "LIST",
248                                                                 "values": [
249                                                                         "both",
250                                                                         "in",
251                                                                         "out"
252                                                                 ]
253                                                         }
254                                                 }
255                                         ],
256                                         "errorResponses": [
257                                                 {
258                                                         "code": 404,
259                                                         "reason": "Channel not found"
260                                                 },
261                                                 {
262                                                         "code": 409,
263                                                         "reason": "Channel not in a Stasis application"
264                                                 }
265                                         ]
266                                 }
267                         ]
268                 },
269                 {
270                         "path": "/channels/{channelId}/unmute",
271                         "description": "Unmute a channel",
272                         "operations": [
273                                 {
274                                         "httpMethod": "POST",
275                                         "summary": "Unmute a channel.",
276                                         "nickname": "unmuteChannel",
277                                         "responseClass": "void",
278                                         "parameters": [
279                                                 {
280                                                         "name": "channelId",
281                                                         "description": "Channel's id",
282                                                         "paramType": "path",
283                                                         "required": true,
284                                                         "allowMultiple": false,
285                                                         "dataType": "string"
286                                                 },
287                                                 {
288                                                         "name": "direction",
289                                                         "description": "Direction in which to unmute audio",
290                                                         "paramType": "query",
291                                                         "required": false,
292                                                         "allowMultiple": false,
293                                                         "dataType": "string",
294                                                         "defaultValue": "both",
295                                                         "allowableValues": {
296                                                                 "valueType": "LIST",
297                                                                 "values": [
298                                                                         "both",
299                                                                         "in",
300                                                                         "out"
301                                                                 ]
302                                                         }
303                                                 }
304                                         ],
305                                         "errorResponses": [
306                                                 {
307                                                         "code": 404,
308                                                         "reason": "Channel not found"
309                                                 },
310                                                 {
311                                                         "code": 409,
312                                                         "reason": "Channel not in a Stasis application"
313                                                 }
314                                         ]
315                                 }
316                         ]
317                 },
318                 {
319                         "path": "/channels/{channelId}/hold",
320                         "description": "Put a channel on hold",
321                         "operations": [
322                                 {
323                                         "httpMethod": "POST",
324                                         "summary": "Hold a channel.",
325                                         "nickname": "holdChannel",
326                                         "responseClass": "void",
327                                         "parameters": [
328                                                 {
329                                                         "name": "channelId",
330                                                         "description": "Channel's id",
331                                                         "paramType": "path",
332                                                         "required": true,
333                                                         "allowMultiple": false,
334                                                         "dataType": "string"
335                                                 }
336                                         ],
337                                         "errorResponses": [
338                                                 {
339                                                         "code": 404,
340                                                         "reason": "Channel not found"
341                                                 },
342                                                 {
343                                                         "code": 409,
344                                                         "reason": "Channel not in a Stasis application"
345                                                 }
346                                         ]
347                                 }
348                         ]
349                 },
350                 {
351                         "path": "/channels/{channelId}/unhold",
352                         "description": "Remove a channel from hold",
353                         "operations": [
354                                 {
355                                         "httpMethod": "POST",
356                                         "summary": "Remove a channel from hold.",
357                                         "nickname": "unholdChannel",
358                                         "responseClass": "void",
359                                         "parameters": [
360                                                 {
361                                                         "name": "channelId",
362                                                         "description": "Channel's id",
363                                                         "paramType": "path",
364                                                         "required": true,
365                                                         "allowMultiple": false,
366                                                         "dataType": "string"
367                                                 }
368                                         ],
369                                         "errorResponses": [
370                                                 {
371                                                         "code": 404,
372                                                         "reason": "Channel not found"
373                                                 },
374                                                 {
375                                                         "code": 409,
376                                                         "reason": "Channel not in a Stasis application"
377                                                 }
378                                         ]
379                                 }
380                         ]
381                 },
382                 {
383                         "path": "/channels/{channelId}/play",
384                         "description": "Play media to a channel",
385                         "operations": [
386                                 {
387                                         "httpMethod": "POST",
388                                         "summary": "Start playback of media.",
389                                         "notes": "The media URI may be any of a number of URI's. You may use http: and https: URI's, as well as sound: and recording: URI's. This operation creates a playback resource that can be used to control the playback of media (pause, rewind, fast forward, etc.)",
390                                         "nickname": "playOnChannel",
391                                         "responseClass": "Playback",
392                                         "parameters": [
393                                                 {
394                                                         "name": "channelId",
395                                                         "description": "Channel's id",
396                                                         "paramType": "path",
397                                                         "required": true,
398                                                         "allowMultiple": false,
399                                                         "dataType": "string"
400                                                 },
401                                                 {
402                                                         "name": "media",
403                                                         "description": "Media's URI to play.",
404                                                         "paramType": "query",
405                                                         "required": true,
406                                                         "allowMultiple": false,
407                                                         "dataType": "string"
408                                                 },
409                                                 {
410                                                         "name": "lang",
411                                                         "description": "For sounds, selects language for sound.",
412                                                         "paramType": "query",
413                                                         "required": false,
414                                                         "allowMultiple": false,
415                                                         "dataType": "string"
416                                                 },
417                                                 {
418                                                         "name": "offsetms",
419                                                         "description": "Number of media to skip before playing.",
420                                                         "paramType": "query",
421                                                         "required": false,
422                                                         "allowMultiple": false,
423                                                         "dataType": "int"
424                                                 },
425                                                 {
426                                                         "name": "skipms",
427                                                         "description": "Number of milliseconds to skip for forward/reverse operations.",
428                                                         "paramType": "query",
429                                                         "required": false,
430                                                         "allowMultiple": false,
431                                                         "dataType": "int",
432                                                         "defaultValue": 3000
433                                                 }
434                                         ],
435                                         "errorResponses": [
436                                                 {
437                                                         "code": 404,
438                                                         "reason": "Channel not found"
439                                                 },
440                                                 {
441                                                         "code": 409,
442                                                         "reason": "Channel not in a Stasis application"
443                                                 }
444                                         ]
445                                 }
446                         ]
447                 },
448                 {
449                         "path": "/channels/{channelId}/record",
450                         "description": "Record audio from a channel",
451                         "operations": [
452                                 {
453                                         "httpMethod": "POST",
454                                         "summary": "Start a recording.",
455                                         "notes": "Record audio from a channel. Note that this will not capture audio sent to the channel. The bridge itself has a record feature if that's what you want.",
456                                         "nickname": "recordChannel",
457                                         "responseClass": "void",
458                                         "parameters": [
459                                                 {
460                                                         "name": "channelId",
461                                                         "description": "Channel's id",
462                                                         "paramType": "path",
463                                                         "required": true,
464                                                         "allowMultiple": false,
465                                                         "dataType": "string"
466                                                 },
467                                                 {
468                                                         "name": "name",
469                                                         "description": "Recording's filename",
470                                                         "paramType": "query",
471                                                         "required": true,
472                                                         "allowMultiple": false,
473                                                         "dataType": "string"
474                                                 },
475                                                 {
476                                                         "name": "format",
477                                                         "description": "Format to encode audio in",
478                                                         "paramType": "query",
479                                                         "required": true,
480                                                         "allowMultiple": true,
481                                                         "dataType": "string"
482                                                 },
483                                                 {
484                                                         "name": "maxDurationSeconds",
485                                                         "description": "Maximum duration of the recording, in seconds. 0 for no limit",
486                                                         "paramType": "query",
487                                                         "required": false,
488                                                         "allowMultiple": false,
489                                                         "dataType": "int",
490                                                         "defaultValue": 0
491                                                 },
492                                                 {
493                                                         "name": "maxSilenceSeconds",
494                                                         "description": "Maximum duration of silence, in seconds. 0 for no limit",
495                                                         "paramType": "query",
496                                                         "required": false,
497                                                         "allowMultiple": false,
498                                                         "dataType": "int",
499                                                         "defaultValue": 0
500                                                 },
501                                                 {
502                                                         "name": "append",
503                                                         "description": "If true, and recording already exists, append to recording",
504                                                         "paramType": "query",
505                                                         "required": false,
506                                                         "allowMultiple": false,
507                                                         "dataType": "boolean",
508                                                         "defaultValue": false
509                                                 },
510                                                 {
511                                                         "name": "beep",
512                                                         "description": "Play beep when recording begins",
513                                                         "paramType": "query",
514                                                         "required": false,
515                                                         "allowMultiple": false,
516                                                         "dataType": "boolean",
517                                                         "defaultValue": false
518                                                 },
519                                                 {
520                                                         "name": "terminateOn",
521                                                         "description": "DTMF input to terminate recording",
522                                                         "paramType": "query",
523                                                         "required": false,
524                                                         "allowMultiple": false,
525                                                         "dataType": "string",
526                                                         "defaultValue": "none",
527                                                         "allowableValues": {
528                                                                 "valueType": "LIST",
529                                                                 "values": [
530                                                                         "none",
531                                                                         "any",
532                                                                         "*",
533                                                                         "#"
534                                                                 ]
535                                                         }
536                                                 }
537                                         ],
538                                         "errorResponses": [
539                                                 {
540                                                         "code": 404,
541                                                         "reason": "Channel not found"
542                                                 },
543                                                 {
544                                                         "code": 409,
545                                                         "reason": "Channel is not in a Stasis application."
546                                                 },
547                                                 {
548                                                         "code": 409,
549                                                         "reason": "The channel is currently bridges with other channels."
550                                                 }
551                                         ]
552                                 }
553                         ]
554                 }
555         ],
556         "models": {
557                 "Originated": {
558                         "id": "Originated",
559                         "properties": {}
560                 },
561                 "Dialed": {
562                         "id": "Dialed",
563                         "properties": {}
564                 },
565                 "DialplanCEP": {
566                         "id": "DialplanCEP",
567                         "properties": {
568                                 "context": {
569                                         "required": true,
570                                         "type": "string",
571                                         "description": "Context in the dialplan"
572                                 },
573                                 "exten": {
574                                         "required": true,
575                                         "type": "string",
576                                         "description": "Extension in the dialplan"
577                                 },
578                                 "priority": {
579                                         "required": true,
580                                         "type": "long",
581                                         "description": "Priority in the dialplan"
582                                 }
583                         }
584                 },
585                 "CallerID": {
586                         "id": "CallerID",
587                         "properties": {
588                                 "name": {
589                                         "required": true,
590                                         "type": "string"
591                                 },
592                                 "number": {
593                                         "required": true,
594                                         "type": "string"
595                                 }
596                         }
597                 },
598                 "Channel": {
599                         "id": "Channel",
600                         "properties": {
601                                 "uniqueid": {
602                                         "required": true,
603                                         "type": "string",
604                                         "description": "Unique identifier of the channel"
605                                 },
606                                 "name": {
607                                         "required": true,
608                                         "type": "string",
609                                         "description": "Name of the channel (i.e. SIP/foo-0000a7e3)"
610                                 },
611                                 "state": {
612                                         "required": true,
613                                         "type": "string"
614                                 },
615                                 "accountcode": {
616                                         "required": true,
617                                         "type": "string"
618                                 },
619                                 "peeraccount": {
620                                         "required": true,
621                                         "type": "string"
622                                 },
623                                 "userfield": {
624                                         "required": true,
625                                         "type": "string"
626                                 },
627                                 "linkedid": {
628                                         "required": true,
629                                         "type": "string"
630                                 },
631                                 "parkinglot": {
632                                         "required": true,
633                                         "type": "string"
634                                 },
635                                 "hangupsource": {
636                                         "required": true,
637                                         "type": "string"
638                                 },
639                                 "appl": {
640                                         "required": true,
641                                         "type": "string",
642                                         "description": "Currently executing dialplan application"
643                                 },
644                                 "data": {
645                                         "required": true,
646                                         "type": "string",
647                                         "description": "Arguments passed to appl"
648                                 },
649                                 "dialplan": {
650                                         "required": true,
651                                         "type": "DialplanCEP",
652                                         "description": "Current location in the dialplan"
653                                 },
654                                 "caller": {
655                                         "required": true,
656                                         "type": "CallerID"
657                                 },
658                                 "connected": {
659                                         "required": true,
660                                         "type": "CallerID"
661                                 },
662                                 "creationtime": {
663                                         "required": true,
664                                         "type": "Date",
665                                         "description": "Timestamp when channel was created"
666                                 }
667                         }
668                 },
669                 "Playback": {
670                         "id": "Playback",
671                         "description": "Object representing the playback of media to a channel",
672                         "properties": {
673                                 "id": {
674                                         "type": "string",
675                                         "description": "ID for this playback operation",
676                                         "required": true
677                                 },
678                                 "media_uri": {
679                                         "type": "string",
680                                         "description": "URI for the media to play back.",
681                                         "required": true
682                                 },
683                                 "target_uri": {
684                                         "type": "string",
685                                         "description": "URI for the channel or bridge to play the media on",
686                                         "required": true
687                                 },
688                                 "language": {
689                                         "type": "string",
690                                         "description": "For media types that support multiple languages, the language requested for playback."
691                                 },
692                                 "state": {
693                                         "type": "string",
694                                         "description": "Current state of the playback operation.",
695                                         "required": true,
696                                         "allowableValues": {
697                                                 "valueType": "LIST",
698                                                 "values": [
699                                                         "queued",
700                                                         "playing",
701                                                         "complete"
702                                                 ]
703                                         }
704                                 }
705                         }
706                 }
707         }
708 }