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