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.extensions.conf
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
In the section on getting wscat it would be helpful to know which versions of npm and nodejs are required. Then people would know whether they can use the versions that come with their distro or if they should install by hand.
Wscat is just an example of a websocket client. You can use any existing ws client to connect to asterisk, and version doesn't matter.
In that case the box which begins "Some distributions repos (e.g. Ubuntu) may have older versions ..." should be removed.
Well, that line is accurate. Some distros do have older versions, which do cause issues. Unfortunately, I abandoned Ubuntu for other reasons, so I'm not sure what the version was any longer. If a current Ubuntu user can look to see if it still has the same issues with npm/nodejs, that'd be great.