What you'll learn

How to configure Asterisk ARI (Asterisk REST Interface) as a telephony provider in zoxaAI for self-hosted PBX systems, including Asterisk server configuration, Stasis application setup, and ExternalMedia for audio bridging.

Asterisk ARI

Asterisk ARI (Asterisk REST Interface) lets you connect a self-hosted Asterisk PBX to zoxaAI. This is ideal for on-premise deployments or organizations that already run Asterisk infrastructure.

Unlike cloud-based providers that use HTTP webhooks, ARI uses a persistent WebSocket connection between zoxaAI and your Asterisk server for real-time event notification and call control.

Agents don't run on Asterisk ARI

Calls placed or received through an Asterisk ARI configuration are not connected to agents. Agent test calls, API calls, campaigns, and inbound routing to an agent need a cloud provider such as Twilio or Vobiz.

Provider Details

Feature	Value
Provider name	`ari`
Audio format	mulaw
Sample rate	8,000 Hz
Call transfer	Yes (via bridge manipulation)
Auto-create application	No
Webhook signature verification	N/A (persistent WebSocket)
Account ID field	-- (no account ID concept)

Prerequisites

An Asterisk server (version 13+ recommended) with ARI enabled
A Stasis application registered in your Asterisk configuration
Network connectivity between your Asterisk server and zoxaAI (the ARI HTTP port must be reachable)
The websocket_client.conf configured for ExternalMedia (if using ExternalMedia channels for audio bridging)

Credentials

Field	Where to Find It	Sensitive	Required	Description
ARI Endpoint	Your Asterisk server URL	No	Yes	Base URL of the ARI interface (e.g., `http://asterisk.example.com:8088`)
App Name	Asterisk `stasis` application config	No	Yes	The Stasis application name registered in your Asterisk dialplan
App Password	Asterisk ARI user config (`ari.conf`)	Yes	Yes	Password for the ARI user
WS Client Name	`websocket_client.conf`	No	No	Connection name for ExternalMedia (e.g., `zoxa_staging`). Only needed if using ExternalMedia channels.

Setup

Open the Telephony Page

Navigate to Telephony in the zoxaAI sidebar.

Add a New Configuration

Click Add Configuration. Select Asterisk ARI from the provider dropdown.

Enter Your Credentials

Fill in:

ARI Endpoint: The HTTP base URL of your Asterisk ARI interface (e.g., http://192.168.1.100:8088 or http://asterisk.example.com:8088).
App Name: The Stasis application name registered in your Asterisk dialplan.
App Password: The password for the ARI user configured in ari.conf.
WS Client Name (optional): The websocket_client.conf connection name for ExternalMedia.

Name and Save

Give the configuration a name (e.g., "Asterisk Office PBX") and click Save.

Add SIP Extensions (optional)

Click into the configuration and add SIP extensions or numbers used for outbound calls. These serve as caller IDs when placing outbound calls through Asterisk. Asterisk has no API that lists its numbers (they live in your dialplan), so they are always added by hand.

Asterisk Server Configuration

Your Asterisk server needs three configuration files set up correctly.

Enabling ARI (`ari.conf`)

Enable ARI and create a user with read-write access:

; /etc/asterisk/ari.conf
[general]
enabled = yes
pretty = yes

[zoxa]
type = user
read_only = no
password = your-secret-password

The username (zoxa in this example) and password must match what you use when connecting from zoxaAI.

Stasis Application (Dialplan)

; /etc/asterisk/extensions.conf
[inbound-context]
exten => _X.,1,Stasis(your-app-name)

Replace your-app-name with the App Name you entered in your zoxaAI configuration.

ExternalMedia (Optional)

If you use ExternalMedia for audio bridging between Asterisk and zoxaAI, configure websocket_client.conf:

; /etc/asterisk/websocket_client.conf
[zoxa_staging]
type = websocket
uri = wss://your-domain.com/ws/ari-audio

Replace zoxa_staging with the WS Client Name you entered in your zoxaAI configuration, and your-domain.com with your zoxaAI deployment URL.

How ARI Differs from Other Providers

Aspect	Cloud Providers (Twilio, etc.)	Asterisk ARI
Communication	HTTP webhooks + WebSocket for audio	Persistent ARI WebSocket for events + ExternalMedia for audio
Infrastructure	Provider-hosted in the cloud	Self-hosted on your own servers
Call control	Provider-specific XML/API (TwiML, NCCO, etc.)	Asterisk Stasis application + ARI REST API
Phone numbers	Purchased from the cloud provider	SIP trunks and extensions managed in Asterisk
Scaling	Managed by the cloud provider	Your responsibility (clustering, load balancing)
Inbound routing	HTTP webhook to zoxaAI	ARI WebSocket event to zoxaAI

Outbound Calls

Outbound calls are initiated via the ARI channel origination API. zoxaAI creates a channel on your Asterisk server directed to the destination number, and audio is exchanged through ExternalMedia channels connected to the voice pipeline.

Inbound Calls

Inbound calls are handled through Asterisk's Stasis application. When a call arrives at the configured extension:

Asterisk routes the call to the Stasis application defined in the dialplan.
The ARI WebSocket notifies zoxaAI of the new call event.

No HTTP webhook configuration is needed -- the persistent ARI WebSocket connection handles all event delivery.

Call Transfer

Asterisk ARI supports call transfers via bridge manipulation: zoxaAI uses ARI's bridge and channel APIs to connect the caller to the destination number.

Troubleshooting

Issue	Cause	Solution
Cannot connect to ARI	Network connectivity or firewall	Ensure port 8088 (or your configured ARI port) is open between zoxaAI and your Asterisk server
Stasis app not receiving calls	Dialplan misconfiguration	Verify the Stasis application name in `extensions.conf` matches your zoxaAI configuration
No audio	ExternalMedia not configured	Set up `websocket_client.conf` and ensure the WebSocket URL points to your zoxaAI deployment
Authentication failed	Wrong ARI user/password	Verify the App Password matches the user configured in `ari.conf`
"Provider ari not supported for agent-stream"	ARI does not support external agent streaming	Use cloud providers for external agent API calls; ARI is for PBX-integrated deployments

Asterisk ARI

On this page