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