Asterisk 13: The Asterisk REST Interface (ARI)

By Matt Jordan

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.


For more information about getting started with the ARI, check out the Asterisk wiki.

Related Posts

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.

  • felipe marcos says:

    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 joined Digium in July of 2011. Since joining Digium, he has served as lead on the Asterisk open source project, as an Engineering Manager, and as Director of Technology. In June 2016, Jordan was named CTO of Digium. In this role, Jordan is responsible for technology and architectural decisions used in the Company’s product and service offerings.Jordan holds a Bachelor of Science degree in Computer Engineering from Michigan Technological University, and a Master of Science degree in Electrical Engineering from Louisiana State University and multiple patents.

See All of Matt's Articles