Asterisk ari-request

Overview

Asterisk ARI(Asterisk REST Interface) 내용 정리.

Basic

Asterisk-12 버전부터는 ARI(Asterisk REST Interface) 를 지원한다.

기본 사용포트 및 base uri 은 다음과 같다.

http://localhost:8088/ari

Applications

/applications GET

List all applications. Request

GET /applications

Return List[Application]

GET

/applications/{applicationName}

Application

Get details of an application.

POST

/applications/{applicationName}/subscription

Application

Subscribe an application to a event source.

DELETE

/applications/{applicationName}/subscription

Application

Unsubscribe an application from an event source.

Channels

/channels POST

Create a new channel(originate). The new channel is created immediately and a snapshot of it returned. If a Stasis application is provided it will be automatically subscribed to the originated for further events and updates.

Query parameters

• endpoint: string - (required) Endpoint to call.
• extension: string - The extension to dial after the endpoint answers. Mutually exclusive with 'app'.
• context: string - The context to dial after the endpoint answers. If omitted, uses 'default'. Mutually exclusive with 'app'.
• priority: long - The priority to dial after the endpoint answers. If omitted, uses 1. Mutually exclusive with 'app'.
• label: string - The label to dial after the endpoint answers. Will supersede 'priority' if provided. Mutually exclusive with 'app'.
• app: string - The application that is subscribed to the originated channel. When the channel is answered, it will be passed to this Stasis application. Mutually exclusive with 'context', 'extension', 'priority' and 'label'.
• appArgs: string - The application arguments to pass to the Stasis application provided by 'app'. Mutually exclusive with 'context', 'extension', 'priority', and 'label'.
• callerid: string - CallerID to use when dialing the endpoint or extension.
• timeout: int - Timeout(in seconds) before giving up dialing, or -1 for no timeout.

Default: 30

• channelId: string - The unique id to assign the channel on creation.
• otherChannelId: string - The unique id to assign the second channel when using local channels.
• originator: string - The unique id of the channel which is originating this one.
• formats: string - The format name capability list to use if originator is not specified. Ex. "ulaw, slin16". Format names can be found with "core show codecs".

Body parameter

• variables: containers - The "variables" key in the body object holds variable key/value pairs to set on the channel on creation. Other keys in the body object are interpreted as query parameters. Ex. { "endpoint": "SIP/Alice", "variables": {"CALLERID(name)": "Alice"}}

Error response

• 400 : Invalid parameters for originating a channel.
• 409 : Channel with given unique ID already exists.

Example

$ curl -X POST http://192.168.200.20:8088/ari/channels\?api_key=asterisk:asterisk\&endpoint=pjsip/test@sippuas\&app=test

{
	"id": "1543782963.26",
	"name": "PJSIP/sippuas-0000000d",
	"state": "Down",
	"caller": {
		"name": "",
		"number": ""
	},
	"connected": {
		"name": "",
		"number": ""
	},
	"accountcode": "",
	"dialplan": {
		"context": "sippuas",
		"exten": "s",
		"priority": 1
	},
	"creationtime": "2018-12-02T21:36:03.239+0100",
	"language": "en"
}

/channels/{channelId}/continue POST

Exit application; continue execution in the dialplan.

Path parameters(Parameters are case-sensitive)

• channelId: string - Channel's Id

Query parameters

• context: string - The context to continue to.
• extension: string - The extension to continue to.
• priority: int - The priority to continue to.
• label: string - The label to continue to - will supersede 'priority' if both are provided.

Error responses

• 404: Channel not found
• 409: Channel not in a Stasis application.
• 412: Channel in invalid state.

Example

Normal

$ curl -X POST http://192.168.200.20:8088/ari/channels/1543782963.26/continue\?api_key=asterisk:asterisk

No channel info

~$ curl -X POST http://192.168.200.20:8088/ari/channels/1543782963.26/continue\?api_key=asterisk:asterisk

{"message":"Channel not in Stasis application"}

/channells/{channelId}/record POST

Start a recording. 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.

Path parameters(Parameters are case-sensitive)

• chanelId: string: Channel's Id.

Query parameters

• name: string: (required)Recording's filename.
• format: string: (required)Format to encode audio in.
• maxDurationSeconds: int: Maximum duration of the recording, in seconds. 0 for no limit.

Allowed range: Min: 0, Max: None

• maxSilenceSeconds: int: Maximum duration of silence, in seconds, 0 for no limit

Allowed range: Min: 0, Max: None

• ifExists: string: Action to take if a recording with the same name already exists.

Default: fail

Allowed values: fail, overwrite, append

• beep: boolean: Play beep when recording begins.
• terminateOn: string: DTMF input to terminate recording.

Default: none

Allowed value: non, any, *, #

Error responses

• 400: Invalid parameters.
• 404: Channel not found.
• 409: Channel is not in a Stasis application; the channel is currently bridged with other channels; A recording with the same name already exists on the system and can not be overwritten because it is in progess or ifExists=fail.
• 422: The format specified is unknown on this system.

Events

/events GET

Websocket connection for events.

Query parameters

• app: string - (required) Applications to subscribe to.

Allows comma separated values.

• subscribeAll: boolean - Subscribe to all Asterisk events. If provided, the applications listed will be subscribed to all events, effectively disabling the application specific subscriptions.

Default: false

Example

ws://192.168.200.20:8088/ari/events?api_key=asterisk:asterisk&app=test

ws://192.168.200.20:8088/ari/events?api_key=asterisk:asterisk&app=test&subscribeAll=true

Recordings

/recordings/stored GET

List recordings that are complete.

Examples

$ curl -X GET -u asterisk:asterisk http://localhost:8088/ari/recordings/stored

[
    {
        "format": "wav",
        "name": "test_call"
    }
]

/recordings/stored/{recordingName} DELETE

Delete a stored recording.

Path parameters

• recordingName: string: The name of the recording.

Error responses

• 404: Recording not found.

Examples

Normal

$ curl -X DELETE -u asterisk:asterisk http://localhost:8088/ari/recordings/stored/test_call

Not found

$ curl -X DELETE -u asterisk:asterisk http://localhost:8088/ari/recordings/stored/test_call
{"message":"Recording not found"}

/recordings/stored/{recording name} GET

Get a stored recording's details.

Path parameters

• recording name: string: The name of the recording.

Error response

• 404: Recording not found

Examples

$ curl -X GET -u asterisk:asterisk http://localhost:8088/ari/recordings/stored/test_call

{
    "format": "wav",
    "name": "test_call"
}

See also

• https://wiki.asterisk.org/wiki/display/AST/Asterisk+13+ARI - Asterisk 13 ARI