Change ARI originate to also allow dialing an exten/context/priority.
[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                                         "errorResponses": [
189                                                 {
190                                                         "code": 404,
191                                                         "reason": "Channel not found"
192                                                 },
193                                                 {
194                                                         "code": 409,
195                                                         "reason": "Channel not in a Stasis application"
196                                                 }
197                                         ]
198                                 }
199                         ]
200                 },
201                 {
202                         "path": "/channels/{channelId}/continue",
203                         "description": "Exit application; continue execution in the dialplan",
204                         "operations": [
205                                 {
206                                         "httpMethod": "POST",
207                                         "summary": "Exit application; continue execution in the dialplan.",
208                                         "nickname": "continueInDialplan",
209                                         "responseClass": "void",
210                                         "parameters": [
211                                                 {
212                                                         "name": "channelId",
213                                                         "description": "Channel's id",
214                                                         "paramType": "path",
215                                                         "required": true,
216                                                         "allowMultiple": false,
217                                                         "dataType": "string"
218                                                 },
219                                                 {
220                                                         "name": "context",
221                                                         "description": "The context to continue to.",
222                                                         "paramType": "query",
223                                                         "required": false,
224                                                         "allowMultiple": false,
225                                                         "dataType": "string"
226                                                 },
227                                                 {
228                                                         "name": "extension",
229                                                         "description": "The extension to continue to.",
230                                                         "paramType": "query",
231                                                         "required": false,
232                                                         "allowMultiple": false,
233                                                         "dataType": "string"
234                                                 },
235                                                 {
236                                                         "name": "priority",
237                                                         "description": "The priority to continue to.",
238                                                         "paramType": "query",
239                                                         "required": false,
240                                                         "allowMultiple": false,
241                                                         "dataType": "int"
242                                                 }
243                                         ],
244                                         "errorResponses": [
245                                                 {
246                                                         "code": 404,
247                                                         "reason": "Channel not found"
248                                                 },
249                                                 {
250                                                         "code": 409,
251                                                         "reason": "Channel not in a Stasis application"
252                                                 }
253                                         ]
254                                 }
255                         ]
256                 },
257                 {
258                         "path": "/channels/{channelId}/answer",
259                         "description": "Answer a channel",
260                         "operations": [
261                                 {
262                                         "httpMethod": "POST",
263                                         "summary": "Answer a channel.",
264                                         "nickname": "answerChannel",
265                                         "responseClass": "void",
266                                         "parameters": [
267                                                 {
268                                                         "name": "channelId",
269                                                         "description": "Channel's id",
270                                                         "paramType": "path",
271                                                         "required": true,
272                                                         "allowMultiple": false,
273                                                         "dataType": "string"
274                                                 }
275                                         ],
276                                         "errorResponses": [
277                                                 {
278                                                         "code": 404,
279                                                         "reason": "Channel not found"
280                                                 }
281                                         ]
282                                 }
283                         ]
284                 },
285                 {
286                         "path": "/channels/{channelId}/mute",
287                         "description": "Mute a channel",
288                         "operations": [
289                                 {
290                                         "httpMethod": "POST",
291                                         "summary": "Mute a channel.",
292                                         "nickname": "muteChannel",
293                                         "responseClass": "void",
294                                         "parameters": [
295                                                 {
296                                                         "name": "channelId",
297                                                         "description": "Channel's id",
298                                                         "paramType": "path",
299                                                         "required": true,
300                                                         "allowMultiple": false,
301                                                         "dataType": "string"
302                                                 },
303                                                 {
304                                                         "name": "direction",
305                                                         "description": "Direction in which to mute audio",
306                                                         "paramType": "query",
307                                                         "required": false,
308                                                         "allowMultiple": false,
309                                                         "dataType": "string",
310                                                         "defaultValue": "both",
311                                                         "allowableValues": {
312                                                                 "valueType": "LIST",
313                                                                 "values": [
314                                                                         "both",
315                                                                         "in",
316                                                                         "out"
317                                                                 ]
318                                                         }
319                                                 }
320                                         ],
321                                         "errorResponses": [
322                                                 {
323                                                         "code": 404,
324                                                         "reason": "Channel not found"
325                                                 },
326                                                 {
327                                                         "code": 409,
328                                                         "reason": "Channel not in a Stasis application"
329                                                 }
330                                         ]
331                                 }
332                         ]
333                 },
334                 {
335                         "path": "/channels/{channelId}/unmute",
336                         "description": "Unmute a channel",
337                         "operations": [
338                                 {
339                                         "httpMethod": "POST",
340                                         "summary": "Unmute a channel.",
341                                         "nickname": "unmuteChannel",
342                                         "responseClass": "void",
343                                         "parameters": [
344                                                 {
345                                                         "name": "channelId",
346                                                         "description": "Channel's id",
347                                                         "paramType": "path",
348                                                         "required": true,
349                                                         "allowMultiple": false,
350                                                         "dataType": "string"
351                                                 },
352                                                 {
353                                                         "name": "direction",
354                                                         "description": "Direction in which to unmute audio",
355                                                         "paramType": "query",
356                                                         "required": false,
357                                                         "allowMultiple": false,
358                                                         "dataType": "string",
359                                                         "defaultValue": "both",
360                                                         "allowableValues": {
361                                                                 "valueType": "LIST",
362                                                                 "values": [
363                                                                         "both",
364                                                                         "in",
365                                                                         "out"
366                                                                 ]
367                                                         }
368                                                 }
369                                         ],
370                                         "errorResponses": [
371                                                 {
372                                                         "code": 404,
373                                                         "reason": "Channel not found"
374                                                 },
375                                                 {
376                                                         "code": 409,
377                                                         "reason": "Channel not in a Stasis application"
378                                                 }
379                                         ]
380                                 }
381                         ]
382                 },
383                 {
384                         "path": "/channels/{channelId}/hold",
385                         "description": "Put a channel on hold",
386                         "operations": [
387                                 {
388                                         "httpMethod": "POST",
389                                         "summary": "Hold a channel.",
390                                         "nickname": "holdChannel",
391                                         "responseClass": "void",
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                                         "errorResponses": [
403                                                 {
404                                                         "code": 404,
405                                                         "reason": "Channel not found"
406                                                 },
407                                                 {
408                                                         "code": 409,
409                                                         "reason": "Channel not in a Stasis application"
410                                                 }
411                                         ]
412                                 }
413                         ]
414                 },
415                 {
416                         "path": "/channels/{channelId}/unhold",
417                         "description": "Remove a channel from hold",
418                         "operations": [
419                                 {
420                                         "httpMethod": "POST",
421                                         "summary": "Remove a channel from hold.",
422                                         "nickname": "unholdChannel",
423                                         "responseClass": "void",
424                                         "parameters": [
425                                                 {
426                                                         "name": "channelId",
427                                                         "description": "Channel's id",
428                                                         "paramType": "path",
429                                                         "required": true,
430                                                         "allowMultiple": false,
431                                                         "dataType": "string"
432                                                 }
433                                         ],
434                                         "errorResponses": [
435                                                 {
436                                                         "code": 404,
437                                                         "reason": "Channel not found"
438                                                 },
439                                                 {
440                                                         "code": 409,
441                                                         "reason": "Channel not in a Stasis application"
442                                                 }
443                                         ]
444                                 }
445                         ]
446                 },
447                 {
448                         "path": "/channels/{channelId}/play",
449                         "description": "Play media to a channel",
450                         "operations": [
451                                 {
452                                         "httpMethod": "POST",
453                                         "summary": "Start playback of media.",
454                                         "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.)",
455                                         "nickname": "playOnChannel",
456                                         "responseClass": "Playback",
457                                         "parameters": [
458                                                 {
459                                                         "name": "channelId",
460                                                         "description": "Channel's id",
461                                                         "paramType": "path",
462                                                         "required": true,
463                                                         "allowMultiple": false,
464                                                         "dataType": "string"
465                                                 },
466                                                 {
467                                                         "name": "media",
468                                                         "description": "Media's URI to play.",
469                                                         "paramType": "query",
470                                                         "required": true,
471                                                         "allowMultiple": false,
472                                                         "dataType": "string"
473                                                 },
474                                                 {
475                                                         "name": "lang",
476                                                         "description": "For sounds, selects language for sound.",
477                                                         "paramType": "query",
478                                                         "required": false,
479                                                         "allowMultiple": false,
480                                                         "dataType": "string"
481                                                 },
482                                                 {
483                                                         "name": "offsetms",
484                                                         "description": "Number of media to skip before playing.",
485                                                         "paramType": "query",
486                                                         "required": false,
487                                                         "allowMultiple": false,
488                                                         "dataType": "int"
489                                                 },
490                                                 {
491                                                         "name": "skipms",
492                                                         "description": "Number of milliseconds to skip for forward/reverse operations.",
493                                                         "paramType": "query",
494                                                         "required": false,
495                                                         "allowMultiple": false,
496                                                         "dataType": "int",
497                                                         "defaultValue": 3000
498                                                 }
499                                         ],
500                                         "errorResponses": [
501                                                 {
502                                                         "code": 404,
503                                                         "reason": "Channel not found"
504                                                 },
505                                                 {
506                                                         "code": 409,
507                                                         "reason": "Channel not in a Stasis application"
508                                                 }
509                                         ]
510                                 }
511                         ]
512                 },
513                 {
514                         "path": "/channels/{channelId}/record",
515                         "description": "Record audio from a channel",
516                         "operations": [
517                                 {
518                                         "httpMethod": "POST",
519                                         "summary": "Start a recording.",
520                                         "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.",
521                                         "nickname": "recordChannel",
522                                         "responseClass": "void",
523                                         "parameters": [
524                                                 {
525                                                         "name": "channelId",
526                                                         "description": "Channel's id",
527                                                         "paramType": "path",
528                                                         "required": true,
529                                                         "allowMultiple": false,
530                                                         "dataType": "string"
531                                                 },
532                                                 {
533                                                         "name": "name",
534                                                         "description": "Recording's filename",
535                                                         "paramType": "query",
536                                                         "required": true,
537                                                         "allowMultiple": false,
538                                                         "dataType": "string"
539                                                 },
540                                                 {
541                                                         "name": "format",
542                                                         "description": "Format to encode audio in",
543                                                         "paramType": "query",
544                                                         "required": true,
545                                                         "allowMultiple": true,
546                                                         "dataType": "string"
547                                                 },
548                                                 {
549                                                         "name": "maxDurationSeconds",
550                                                         "description": "Maximum duration of the recording, in seconds. 0 for no limit",
551                                                         "paramType": "query",
552                                                         "required": false,
553                                                         "allowMultiple": false,
554                                                         "dataType": "int",
555                                                         "defaultValue": 0
556                                                 },
557                                                 {
558                                                         "name": "maxSilenceSeconds",
559                                                         "description": "Maximum duration of silence, 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": "append",
568                                                         "description": "If true, and recording already exists, append to recording",
569                                                         "paramType": "query",
570                                                         "required": false,
571                                                         "allowMultiple": false,
572                                                         "dataType": "boolean",
573                                                         "defaultValue": false
574                                                 },
575                                                 {
576                                                         "name": "beep",
577                                                         "description": "Play beep when recording begins",
578                                                         "paramType": "query",
579                                                         "required": false,
580                                                         "allowMultiple": false,
581                                                         "dataType": "boolean",
582                                                         "defaultValue": false
583                                                 },
584                                                 {
585                                                         "name": "terminateOn",
586                                                         "description": "DTMF input to terminate recording",
587                                                         "paramType": "query",
588                                                         "required": false,
589                                                         "allowMultiple": false,
590                                                         "dataType": "string",
591                                                         "defaultValue": "none",
592                                                         "allowableValues": {
593                                                                 "valueType": "LIST",
594                                                                 "values": [
595                                                                         "none",
596                                                                         "any",
597                                                                         "*",
598                                                                         "#"
599                                                                 ]
600                                                         }
601                                                 }
602                                         ],
603                                         "errorResponses": [
604                                                 {
605                                                         "code": 404,
606                                                         "reason": "Channel not found"
607                                                 },
608                                                 {
609                                                         "code": 409,
610                                                         "reason": "Channel is not in a Stasis application."
611                                                 },
612                                                 {
613                                                         "code": 409,
614                                                         "reason": "The channel is currently bridged with other channels."
615                                                 }
616                                         ]
617                                 }
618                         ]
619                 }
620         ],
621         "models": {
622                 "Dialed": {
623                         "id": "Dialed",
624                         "properties": {}
625                 },
626                 "DialplanCEP": {
627                         "id": "DialplanCEP",
628                         "properties": {
629                                 "context": {
630                                         "required": true,
631                                         "type": "string",
632                                         "description": "Context in the dialplan"
633                                 },
634                                 "exten": {
635                                         "required": true,
636                                         "type": "string",
637                                         "description": "Extension in the dialplan"
638                                 },
639                                 "priority": {
640                                         "required": true,
641                                         "type": "long",
642                                         "description": "Priority in the dialplan"
643                                 }
644                         }
645                 },
646                 "CallerID": {
647                         "id": "CallerID",
648                         "properties": {
649                                 "name": {
650                                         "required": true,
651                                         "type": "string"
652                                 },
653                                 "number": {
654                                         "required": true,
655                                         "type": "string"
656                                 }
657                         }
658                 },
659                 "Channel": {
660                         "id": "Channel",
661                         "properties": {
662                                 "uniqueid": {
663                                         "required": true,
664                                         "type": "string",
665                                         "description": "Unique identifier of the channel"
666                                 },
667                                 "name": {
668                                         "required": true,
669                                         "type": "string",
670                                         "description": "Name of the channel (i.e. SIP/foo-0000a7e3)"
671                                 },
672                                 "state": {
673                                         "required": true,
674                                         "type": "string"
675                                 },
676                                 "accountcode": {
677                                         "required": true,
678                                         "type": "string"
679                                 },
680                                 "peeraccount": {
681                                         "required": true,
682                                         "type": "string"
683                                 },
684                                 "userfield": {
685                                         "required": true,
686                                         "type": "string"
687                                 },
688                                 "linkedid": {
689                                         "required": true,
690                                         "type": "string"
691                                 },
692                                 "parkinglot": {
693                                         "required": true,
694                                         "type": "string"
695                                 },
696                                 "hangupsource": {
697                                         "required": true,
698                                         "type": "string"
699                                 },
700                                 "appl": {
701                                         "required": true,
702                                         "type": "string",
703                                         "description": "Currently executing dialplan application"
704                                 },
705                                 "data": {
706                                         "required": true,
707                                         "type": "string",
708                                         "description": "Arguments passed to appl"
709                                 },
710                                 "dialplan": {
711                                         "required": true,
712                                         "type": "DialplanCEP",
713                                         "description": "Current location in the dialplan"
714                                 },
715                                 "caller": {
716                                         "required": true,
717                                         "type": "CallerID"
718                                 },
719                                 "connected": {
720                                         "required": true,
721                                         "type": "CallerID"
722                                 },
723                                 "creationtime": {
724                                         "required": true,
725                                         "type": "Date",
726                                         "description": "Timestamp when channel was created"
727                                 }
728                         }
729                 },
730                 "Playback": {
731                         "id": "Playback",
732                         "description": "Object representing the playback of media to a channel",
733                         "properties": {
734                                 "id": {
735                                         "type": "string",
736                                         "description": "ID for this playback operation",
737                                         "required": true
738                                 },
739                                 "media_uri": {
740                                         "type": "string",
741                                         "description": "URI for the media to play back.",
742                                         "required": true
743                                 },
744                                 "target_uri": {
745                                         "type": "string",
746                                         "description": "URI for the channel or bridge to play the media on",
747                                         "required": true
748                                 },
749                                 "language": {
750                                         "type": "string",
751                                         "description": "For media types that support multiple languages, the language requested for playback."
752                                 },
753                                 "state": {
754                                         "type": "string",
755                                         "description": "Current state of the playback operation.",
756                                         "required": true,
757                                         "allowableValues": {
758                                                 "valueType": "LIST",
759                                                 "values": [
760                                                         "queued",
761                                                         "playing",
762                                                         "complete"
763                                                 ]
764                                         }
765                                 }
766                         }
767                 }
768         }
769 }