Skip to end of metadata
Go to start of metadata

Overview

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.

On This Page

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:

  1. Installing Asterisk. We'll assume you have Asterisk 12 or later installed and running.
  2. 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.

Getting wscat

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:

  1. If you don't have it already, install npm

  2. Install the ws node package:

Icon

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.

Installing Nodejs via packages

Installing npm in a variety of ways

 

Getting curl

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:

Configuring Asterisk

  1. Enable the Asterisk HTTP service in http.conf:

    http.conf

  2. Configure an ARI user in ari.conf:

    ari.conf

    This is just a demo

    Icon

    Please use a more secure account user and password for production applications. Outside of examples and demos, asterisk/asterisk is a terrible, horrible, no-good choice...

  3. Create a dialplan extension for your Stasis application. Here, we're choosing extension 1000 in context default - if your SIP phone is configured for a different context, adjust accordingly.

    extensions.conf

Hello World!

  1. Connect to Asterisk using wscat:

    In Asterisk, we should see a new WebSocket connection and a message telling us that our Stasis application has been created:

  2. From your SIP device, dial extension 1000:

    In wscat, we should see the StasisStart event, indicating that a channel has entered into our Stasis application:

  3. Using curl, tell Asterisk to playback hello-world. Note that the identifier of the channel in the channels resource must match the channel id passed back in the StasisStart event:

    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 wscat WebSocket connection, we'll be informed of the start of the playback, as well as it finishing:

  4. 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 StasisEnd event:

 

 

  • No labels

4 Comments

  1. Chris Moore

    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.

    1. Alexander Gonchiy

      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.

       

      1. Chris Moore

        In that case the box which begins "Some distributions repos (e.g. Ubuntu) may have older versions ..." should be removed.

        1. Matt Jordan

          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.