Asterisk 12 introduces the Asterisk REST Interface, a set of RESTful APIs for building Asterisk based applications. This article will walk you though getting ARI up and running.
There are three main components to building an ARI application.
The first, obviously, is the RESTful API itself. The API is documented using Swagger, a lightweight specification for documenting RESTful APIs. The Swagger API docs are used to generate validations and boilerplate in Asterisk itself, along with static wiki documentation, and interactive documentation usingSwagger-UI.
Then, Asterisk needs to send asynchronous events to the application (new channel, channel left a bridge, channel hung up, etc). This is done using a WebSocket on /ari/events. Events are sent as JSON messages, and are documented on the REST Data Models page. (See the list of subtypes for the Message data model.)
Finally, connecting the dialplan to your application is the Stasis() dialplan application. From within the dialplan, you can send a channel to Stasis(), specifying the name of the external application, along with optional arguments to pass along to the application.
Installing Asterisk. We'll assume you have Asterisk 12 or later installed and running.
Configuring a SIP device in Asterisk. For the purposes of this example, we are going to assume you have a SIP softphone or hardphone registered to Asterisk, using either chan_sip or chan_pjsip.
ARI needs a WebSocket connection to receive events. For the sake of this example, we're going to use wscat, an incredibly handy command line utility similar to netcat but based on a node.js websocket library. If you don't have wscat:
If you don't have it already, install npm
$ apt-get installnpm
Install the ws node package:
$ npm install-g wscat
Some distributions repos (e.g. Ubuntu) may have older versions of nodejs and npm that will throw a wrench in your install of the ws package. You'll have to install a newer version from another repo or via source.
The response to our HTTP request will tell us whether or not the request succeeded or failed (in our case, a success will queue the playback onto the channel), as well as return in JSON the Playback resource that was created for the operation:
* About to connect() to localhost port 8088 (#0)
* Trying 127.0.0.1... connected
* Server auth using Basic with user 'asterisk'
> POST /ari/channels/1400609726.3/play?media=sound:hello-world HTTP/1.1