ARI Setup and Stasis Application

ARI exposes Asterisk primitives, channels, bridges, endpoints, media, over a REST interface, with real-time state delivered via WebSockets. It is the modern way to build custom communications applications on top of Asterisk.

Requirements

• res_ari.so and related ARI modules loaded
• res_http_websocket.so for WebSocket support
• Asterisk built-in HTTP server enabled

ARI User Configuration (ari.conf)

[general]
enabled = yes
pretty = yes
allowed_origins = *

[asterisk]
type = user
read_only = no
password = change_me_to_a_strong_password
password_format = plain
allowed_origins = *

HTTP Server (http.conf)

[general]
servername = Asterisk
enabled = yes
bindaddr = 0.0.0.0
bindport = 8088
; TLS for production use:
; tlsenable = yes
; tlsbindaddr = 0.0.0.0:8089
; tlscertfile = /etc/asterisk/keys/asterisk.pem
; tlsprivatekey = /etc/asterisk/keys/asterisk.key

Dialplan: Handing a Channel to Stasis

[from-trunk]
exten => 1000,1,NoOp(Sending channel to ARI application)
 same =>      n,Answer()
 same =>      n,Stasis(hello-world)
 same =>      n,Hangup()

Verify ARI is Running

*CLI> ari show status
ARI Status:
Enabled: Yes
Output format: pretty
Auth realm: Asterisk REST Interface
Allowed Origins: *
User count: 1

*CLI> http show status
HTTP Server Status:
Server Enabled and Bound to 0.0.0.0:8088

Enabled URI's:
/ari/... => Asterisk RESTful API
/ws => Asterisk HTTP WebSocket

How it works

1. ARI users: Each ARI user in ari.conf defines credentials and permissions. read_only = no allows the user to create and manipulate resources (channels, bridges, recordings). Use a strong password in production.
2. Stasis() application: Stasis(app-name) in the dialplan hands the channel to ARI. The channel enters a "Stasis" state where it can only be controlled by the external application via REST calls. When Stasis exits, the channel returns to dialplan execution.
3. WebSocket events: ARI pushes channel state, DTMF, and bridge events over a WebSocket connection at ws://host:8088/ari/events?api_key=user:password&app=app-name. Your application listens here for real-time notifications.
4. HTTP server: The built-in HTTP server serves both the REST API (/ari/...) and WebSocket endpoint (/ws). For production, enable TLS via tlsenable=yes in http.conf.
5. allowed_origins: Controls CORS. Use * for development only. In production, restrict to your application's domain to prevent cross-site request abuse.

Tips

• Test from the command line: curl -u asterisk:password http://localhost:8088/ari/channels to list active channels.
• The ARI API is fully documented at http://localhost:8088/ari/api-docs/resources.json when the server is running.
• Use allowed_origins = https://your-app.example.com in production instead of *.
• If you get CORS errors from a browser-based client, serve the client over HTTP (not file://) and ensure allowed_origins matches the client's origin.
• For Node.js clients, use the ari-client npm package. For Python, use ari-py.
• Reload ARI config without restarting: module reload res_ari.so on the CLI.