Asterisk ARI Integration

Overview

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

This guide focuses on the Talkr-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 with chan_websocket and res_websocket_client modules available. Known-working setups: (a) Asterisk 22+, (b) Asterisk 20 LTS with these modules included
• ARI module enabled in Asterisk
• chan_websocket (WebSocket channel driver) and res_websocket_client (loads websocket_client.conf) enabled in your Asterisk build. Verify with asterisk -rx "module show like chan_websocket" and asterisk -rx "module show like res_websocket_client" — both should report Running.
• Network connectivity between your Talkr instance and Asterisk
• Talkr AI instance running and accessible

Asterisk Configuration

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

Enable ARI (ari.conf)

Create an ARI user that Talkr will use to authenticate:

[general]
enabled = yes

[talkr]
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 Talkr can handle them:

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

Replace talkr with the app name you configured in ari.conf and in Talkr.

Configure External Media Streaming (websocket_client.conf)

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

[talkr]
type = websocket_client
uri = wss://talkr.intelstacks.com/api/v1/telephony/ws/ari
protocols = media
tls_enabled = yes
ca_list_file = /etc/ssl/certs/ca-certificates.crt

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

Apply the configuration changes

After editing any of the files above, reload the affected Asterisk modules from the Asterisk CLI (asterisk -rvvv):

ari reload                                 # picks up ari.conf changes
dialplan reload                            # picks up extensions.conf changes
module reload res_websocket_client.so      # picks up websocket_client.conf changes

Changes to http.conf require a full Asterisk reload (core reload) or a service restart.

Configuration in Talkr

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. Talkr 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(talkr)
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. Talkr 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(talkr)
 same => n,Hangup()

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

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

Replace talkr with the app name you configured in ari.conf and in Talkr.

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

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

   Adding the extension in Talkr doesn't change Asterisk's dialplan — that's what Step 1 is for. The Talkr entry tells the StasisStart handler which workflow to run when a call to that extension reaches the Stasis app.

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 Talkr for optimal audio quality
• Use strong passwords for ARI authentication
• Restrict ARI access to known IP addresses using firewall rules
• Monitor Asterisk logs alongside Talkr 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