Skip to main content

​
Overview

Asterisk ARI (Asterisk REST Interface) allows you to connect Dograh AI voice agents to your existing Asterisk PBX. ARI provides a WebSocket-based event model for controlling calls via Stasis applications, giving Dograh full control over call flow and audio streaming. This guide focuses on the Dograh-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 Dograh instance and Asterisk
  • Dograh 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 Dograh. 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 Dograh. These are minimal examples focused on the Dograh integration — refer to the Asterisk documentation for full configuration details.

​
Enable ARI (ari.conf)

Create an ARI user that Dograh will use to authenticate: 
[general]
enabled = yes

[dograh]
type = user
read_only = no
password = your_secure_password
The username (section name, e.g., dograh) and password here must match the Stasis App Name and App Password you configure in Dograh.

​
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 Dograh can handle them: 
[from-external]
exten => _X.,1,NoOp(Incoming call to ${EXTEN})
 same => n,Stasis(dograh)
 same => n,Hangup()
Replace dograh with the app name you configured in ari.conf and in Dograh.

​
Configure External Media Streaming (websocket_client.conf)

Dograh uses Asterisk’s external media streaming to send and receive audio over WebSocket. Configure a WebSocket client connection that points to your Dograh instance: 
[dograh_staging]
type = websocket_client
uri = ws://your-dograh-host:port/ws/audio
protocols = audio
The section name (e.g., dograh_staging) is the WebSocket Client Name you’ll enter in the Dograh 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 Dograh

​
Step 1: Navigate to Telephony Settings

  1. Go to Workflow → Phone Call → Configure Telephony
  2. Select Asterisk (ARI) as your provider

​
Step 2: Enter Your ARI Credentials

Configure the following fields:
FieldDescriptionExample
ARI Endpoint URLHTTP base URL of your Asterisk ARI serverhttp://asterisk.example.com:8088
Stasis App NameThe ARI username configured in ari.confdograh
App PasswordThe ARI password configured in ari.confyour_secure_password
WebSocket Client NameThe connection name from websocket_client.confdograh_staging
Inbound Workflow IDThe workflow to activate for inbound calls (optional)42
SIP Extensions / NumbersOptional SIP extensions or trunk numbers for outbound callsPJSIP/6001 or 6001

​
Step 3: Save and Test

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

​
How It Works

  1. An external call arrives at Asterisk and the dialplan routes it to Stasis(dograh)
  2. Asterisk fires a StasisStart event over the ARI WebSocket with the channel in Ring state
  3. Dograh identifies this as an inbound call, validates your quota, and creates a workflow run
  4. 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 Dograh
  1. Go to Workflow → Phone Call → Configure Telephony
  2. 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
  3. 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:
FieldDescription
caller_numberThe caller’s phone number or extension
called_numberThe dialed number or extension
directionAlways inbound
call_idThe Asterisk channel ID
providerAlways ari

​
Troubleshooting

  • Verify the ARI endpoint URL is correct and reachable from your Dograh instance
  • Check that the Asterisk HTTP server is running (http.conf has enabled = yes)
  • Ensure firewall rules allow traffic on the ARI port (default: 8088)
  • Confirm the ARI module is loaded: run module show like res_ari in the Asterisk CLI
  • Verify the Stasis App Name matches the ARI user section name in ari.conf
  • Check the App Password matches the password in ari.conf
  • Ensure there are no extra spaces in the credentials
  • Verify chan_websocket is loaded: run module show like chan_websocket in the Asterisk CLI
  • Check that websocket_client.conf is correctly configured with the right Dograh URI
  • Ensure the WebSocket Client Name in Dograh matches the section name in websocket_client.conf
  • Verify network connectivity and firewall rules allow WebSocket traffic between Asterisk and Dograh
  • Ensure the dialplan routes calls to Stasis(your_app_name)
  • Verify the app name in the dialplan matches the ARI user in ari.conf
  • Check Asterisk CLI for errors: asterisk -rvvv
  • Confirm the ARI WebSocket connection is active
  • Verify the Inbound Workflow ID is set in your ARI telephony configuration
  • Confirm the workflow ID exists and belongs to the same organization as the ARI config
  • Check that your organization has available quota
  • Review Dograh logs for warnings mentioning “no inbound_workflow_id configured”
  • Check the URI in websocket_client.conf points to the correct Dograh host and port
  • Verify the Dograh instance is running and accepting WebSocket connections
  • If using TLS, ensure certificates are correctly configured on both sides

​
Best Practices

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

​
Further Reading