Asterisk 13: The Asterisk REST Interface (ARI)

By Matt Jordan
Share this:Share on Facebook0Tweet about this on TwitterShare on LinkedIn0Pin on Pinterest0

In the last two blog posts, we discussed changes to the Asterisk core that were made to facilitate new and better APIs in Asterisk. In this blog post, we’ll begin to look at the new API that those core changes allowed — the Asterisk REST Interface (ARI).

A Brief History of Asterisk APIs

When Asterisk was first created back in 1999, its design was focused on being a stand-alone Private Branch eXchange (PBX) that you could configure via static configuration files. While this level of configuration is sufficient for many applications, for some domains, it is far more preferable to manipulate Asterisk via an external system. So, not long into the project, two APIs were added to Asterisk: the Asterisk Gateway Interface (AGI) and the Asterisk Manager Interface (AMI). These two interfaces have distinct purposes:

  1. AGI is analogous to CGI in Apache. AGI provides an interface between the Asterisk dialplan and an external program that wants to manipulate a channel in the dialplan. The interface is synchronous — actions taken on a channel from an AGI block and do not return until the action is completed.
  2. AMI provides a mechanism to control where channels execute in the dialplan. Unlike AGI, AMI is an asynchronous, event-driven interface. For the most part, AMI does not provide mechanisms to control channel execution — rather, it provides information about the state of the channels and where the channels are executing.

Both of these interfaces are powerful and opened up a wide range of integration possibilities. Using AGI, remote dialplan execution could be enabled, which allowed developers to control channels in Asterisk using PHP, Python, Java, and other languages. Using AMI, the state of Asterisk could be displayed, calls initiated, and the location of channels controlled. Using both APIs together, complex applications using Asterisk as the engine could be developed.

However, while AMI is good at call control and AGI is good at allowing a remote process to execute dialplan applications, neither of these APIs were designed to let a developer build their own custom communications application. Fundamentally, neither API exposes the kinds of communications primitives that exist in Asterisk needed to easily build such an application. That wasn’t their intended purpose.

So, the Asterisk Developer Community set out to build a better API that would make it easier to build custom communications applications. ARI was the result of this effort.

ARI: An API for Building Communications Applications

ARI allows application developers to build rich, custom communications applications in the language of their choice. ARI exposes the raw primitive objects in Asterisk normally reserved for C modules — channels, bridges, endpoints, media, etc. — through an intuitive REST interface. As an asynchronous interface, ARI conveys the state of the objects being controlled by the user via JSON events over a WebSocket.

By handing control of the fundamental building blocks in Asterisk over to all developers — regardless of their language choice — Asterisk becomes an engine of communication, with the business logic of how things should communicate deferred to the application using Asterisk.

ARI is not a replacement for AMI or AGI. Rather, it is a complementary API:

  • AGI allows you to control dialplan execution of a channel
  • AMI allows you to manage calls at a high level
  • ARI allows you to replace dialplan applications with your own custom communications application

ARI is not about telling a channel to execute the VoiceMail dialplan application or redirecting a channel in the dialplan to a VoiceMail extension.

It is about letting you build your own VoiceMail application.


In the next blog post, we’ll show how easy it can be to build a simple communications application using ARI.

There Are 6 Comments

  • Ahmad says:

    Which interface is better to interact with synchronous jobs.
    for example I need call an external API in middle of call.

    So ARI is synchronous what happen if it wait for an external api

  • Arend says:

    ARI is not synchronous but asynchronous. If you need to manipulate a call/channel/bridge this is the api to use.

  • Sue Singh says:

    Would ARI be sutiable to upgrade an existing Predictive Dialer app (written in C++) which currently utilises Dialogic Hardware to a complete VOIP solution for a 500 seat call centre?
    If so, do you know if it has been done on this scale before?

    Thank you!

  • One couldn’t say whether it’s suitable or not without having detailed knowledge of the full capabilities of your existing solution. If you’re the developer, have a look at the ARI documentation from the Asterisk Wiki at and see if it meets your needs.

  • I’ts possible a Agent in queue do login, logout and pause using ARI??

  • app_queue isn’t controlled by ARI. ARI is an API for building applications. You could build a queueing application. You could create your own versions of login, logout, and pause.

Add to the Discussion

Your email address will not be published. Required fields are marked *

About the Author

Matt Jordan

Matt Jordan is an Engineering Manager for the Open Source Software team at Digium, working on Asterisk. Matt joined the team in 2011, and since then has been involved in the development of both Asterisk and the Asterisk Test Suite. His background in software development can best be described as "eclectic", having worked in a variety of industries. Uniting the various experiences, however, is a firm belief in good software development practices and methodologies and the effect they have on producing quality software (and keeping software developers from going insane).

See All of Matt's Articles