Asterisk ARI Integration

Overview#

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

This guide focuses on the Lemu-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 Lemu instance and Asterisk
Lemu AI instance running and accessible

If you compiled Asterisk from source, ensure chan_websocket is included during the build. This module is required for external media streaming between Asterisk and Lemu. Refer to the Asterisk build system documentation for details on enabling modules.

Asterisk Configuration#

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

Enable ARI (`ari.conf`)

Create an ARI user that Lemu will use to authenticate:

[general]
enabled = yes
 
[lemu]
type = user
read_only = no
password = your_secure_password

The username (section name, e.g., lemu) and password here must match the Stasis App Name and App Password you configure in Lemu.

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 Lemu can handle them:

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

Replace lemu with the app name you configured in ari.conf and in Lemu.

Configure External Media Streaming (`websocket_client.conf`)

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

[lemu_staging]
type = websocket_client
uri = ws://your-lemu-host:port/ws/audio
protocols = audio

The section name (e.g., lemu_staging) is the WebSocket Client Name you'll enter in the Lemu telephony configuration. This name tells Asterisk which WebSocket connection to use for external media streaming during calls.

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

Configuration in Lemu#

Step 1: Navigate to Telephony Settings#

Go to Configuration in the sidebar → Telephony tab
Select Asterisk (ARI) as your provider

Step 2: Enter Your ARI Credentials#

Configure the following fields:

Field	Description	Example
ARI Endpoint URL	HTTP base URL of your Asterisk ARI server	`http://asterisk.example.com:8088`
Stasis App Name	The ARI username configured in `ari.conf`	`lemu`
App Password	The ARI password configured in `ari.conf`	`your_secure_password`
WebSocket Client Name	The connection name from `websocket_client.conf`	`lemu_staging`
Inbound Workflow ID	The workflow to activate for inbound calls (optional)	`42`
SIP Extensions / Numbers	Optional SIP extensions or trunk numbers for outbound calls	`PJSIP/6001` or `6001`

Step 3: Save and Test#

Click Save Configuration
Create a test workflow
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. Lemu automatically detects these events and activates the configured workflow.

How It Works#

An external call arrives at Asterisk and the dialplan routes it to Stasis(lemu)
Asterisk fires a StasisStart event over the ARI WebSocket with the channel in Ring state
Lemu identifies this as an inbound call, validates your quota, and creates a workflow run
The call is answered, bridged to an external media channel, and your voice agent workflow begins

Setting Up Inbound Calls#

Step 1: Configure the Asterisk dialplan

Ensure your dialplan routes inbound calls to the Stasis application as shown in the dialplan configuration above.

Step 2: Set the Inbound Workflow ID in Lemu

Go to Configuration in the sidebar → Telephony tab
In the ARI configuration, enter the Inbound Workflow ID — this is the ID of the workflow you want to activate when an inbound call arrives
Click Save Configuration

You can find a workflow's ID in the URL when viewing it (e.g., /workflows/42 means the ID is 42).

If no Inbound Workflow ID is configured, inbound calls will be hung up immediately. You must set this field for inbound calling to work.

Step 3: Test an inbound call

Place a call to a number or extension routed to your Stasis application. You should see the 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:

Field	Description
`caller_number`	The caller's phone number or extension
`called_number`	The dialed number or extension
`direction`	Always `inbound`
`call_id`	The Asterisk channel ID
`provider`	Always `ari`

Troubleshooting#

Best Practices#

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