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 using Swagger-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.
Example: ARI Hello World!
In this example, we will:
- Configure Asterisk to enable ARI
- Send a channel into Stasis
- And playback "Hello World" to the channel
This example will not cover:
- 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
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
In order to control a channel in the Stasis dialplan application through ARI, we also need an HTTP client. For the sake of this example, we'll use curl:
Enable the Asterisk HTTP service in
Configure an ARI user in
Create a dialplan extension for your Stasis application. Here, we're choosing extension
default- if your SIP phone is configured for a different context, adjust accordingly.
Connect to Asterisk using
In Asterisk, we should see a new WebSocket connection and a message telling us that our Stasis application has been created:
From your SIP device, dial extension 1000:
In wscat, we should see the
StasisStartevent, indicating that a channel has entered into our Stasis application:
curl, tell Asterisk to playback
hello-world. Note that the identifier of the channel in the
channelsresource must match the channel
idpassed back in the
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:
In Asterisk, the sound file will be played back to the channel:
And in our
wscatWebSocket connection, we'll be informed of the start of the playback, as well as it finishing:
Hang up the phone! This will cause the channel in Asterisk to be hung up, and the channel will leave the Stasis application, notifying the client via a