Asterisk ARI Integration

Overview#

Asterisk ARI (Asterisk REST Interface) allows you to connect Paladin AI voice agents to your existing Asterisk PBX. ARI provides a WebSocket-based event model for controlling calls via Stasis applications, giving Paladin full control over call flow and audio streaming.

This guide focuses on the Paladin-specific configuration. For general Asterisk installation and administration, refer to the official Asterisk documentation.

Prerequisites#

Before setting up the ARI integration, ensure you have:

• A running Asterisk instance (version 16 or later recommended)
• ARI module enabled in Asterisk
• chan_websocket (WebSocket channel driver) enabled in your Asterisk build
• Network connectivity between your Paladin workspace and Asterisk
• Access to your Paladin workspace

Asterisk Configuration#

The following Asterisk configuration files need to be set up to work with Paladin. These are minimal examples focused on the Paladin integration -- refer to the Asterisk documentation for full configuration details.

Enable ARI (ari.conf)#

Create an ARI user that Paladin will use to authenticate:

[general]
enabled = yes

[paladin]
type = user
read_only = no
password = your_secure_password

Enable the HTTP Server (http.conf)#

ARI requires the Asterisk HTTP server to be enabled:

[general]
enabled = yes
bindaddr = 0.0.0.0
bindport = 8088

Configure the Stasis Dialplan (extensions.conf)#

Route incoming calls to your Stasis application so Paladin can handle them:

[from-external]
exten => _X.,1,NoOp(Incoming call to ${EXTEN})
 same => n,Stasis(paladin)
 same => n,Hangup()

Replace paladin with the app name you configured in ari.conf and in Paladin.

Configure External Media Streaming (websocket_client.conf)#

Paladin uses Asterisk's external media streaming to send and receive audio over WebSocket. Configure a WebSocket client connection that points to your Paladin instance:

[paladin]
type = websocket_client
uri = ws://your-paladin-host:port/api/v1/telephony/ws/ari
protocols = audio

Refer to the Asterisk WebSocket documentation for additional websocket_client.conf options and TLS configuration.

Configuration in Paladin#

Step 1: Navigate to Telephony Settings#

1. Navigate to /telephony-configurations and click Add configuration
2. Select Asterisk ARI as your provider

Step 2: Enter Your ARI Credentials#

Configure the following fields:

Step 3: Save and Add Extensions#

1. Click Save Configuration
2. Open the configuration you just created and add each SIP extension that should be reachable as a phone number (e.g. 8000). For inbound, you'll assign a workflow to each extension separately — see Inbound Calling below.
3. Create a test workflow and initiate a test call to verify the connection.

Inbound Calling#

Unlike other telephony providers that use HTTP webhooks for inbound calls, ARI delivers inbound calls as StasisStart events on the ARI WebSocket. Paladin automatically detects these events and activates the workflow assigned to the called extension.

How It Works#

1. An external call arrives at Asterisk and the dialplan routes it to Stasis(paladin)
2. Asterisk fires a StasisStart event over the ARI WebSocket with the channel in Ring state and the dialed extension in the dialplan context
3. Paladin looks up the called extension in your telephony configuration's phone numbers, finds the assigned workflow, validates quota, and creates a workflow run
4. The call is answered, bridged to an external media channel, and your voice agent workflow begins

Workflow assignment is per extension, so different extensions on the same Asterisk can route to different agents.

Setting Up Inbound Calls#

Step 1: Configure the Asterisk dialplan

Ensure your dialplan routes the extensions you care about into the Stasis application. Either route a specific extension:

[from-external]
exten => 8000,1,NoOp(Incoming call to 8000)
 same => n,Stasis(paladin)
 same => n,Hangup()

…or use a pattern that catches every extension you'll register in Paladin:

[from-external]
exten => _X.,1,NoOp(Incoming call to ${EXTEN})
 same => n,Stasis(paladin)
 same => n,Hangup()

Replace paladin with the app name you configured in ari.conf and in Paladin.

Step 2: Add the extension as a phone number in Paladin

1. Go to /telephony-configurations and open your Asterisk ARI configuration
2. In the Phone numbers section, add a phone number whose address is the SIP extension (e.g. 8000)
3. Set its Inbound workflow to the agent that should answer
4. Save

Repeat Step 2 for each extension that should reach a voice agent.

Step 3: Test an inbound call

Place a call to one of the extensions you configured. You should see the assigned workflow activate and the voice agent respond.

Inbound Call Context#

When an inbound call activates a workflow, the following context is available to your workflow:

Troubleshooting#

Best Practices#

• Keep your Asterisk instance on the same network or a low-latency connection to Paladin for optimal audio quality
• Use strong passwords for ARI authentication
• Restrict ARI access to known IP addresses using firewall rules
• Monitor Asterisk logs alongside Paladin logs when debugging call issues
• Keep Asterisk updated to the latest stable version for security and compatibility

Further Reading#

• Asterisk Documentation -- official reference for all Asterisk configuration
• ARI Documentation -- detailed ARI configuration and API reference