description: "Connect Dograh AI to your Asterisk PBX using the Asterisk REST Interface (ARI)"
---
## 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](https://docs.asterisk.org/).
## 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
- `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**.
If you compiled Asterisk from source, ensure both `chan_websocket` and `res_websocket_client` are included during the build. These modules are required for external media streaming between Asterisk and Dograh. Refer to the [Asterisk build system documentation](https://docs.asterisk.org/) for details on enabling modules.
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](https://docs.asterisk.org/) for full configuration details.
### Enable ARI (`ari.conf`)
Create an ARI user that Dograh will use to authenticate:
```ini
[general]
enabled = yes
[dograh]
type = user
read_only = no
password = your_secure_password
```
<Note>
The username (section name, e.g., `dograh`) and password here must match the **Stasis App Name** and **App Password** you configure in Dograh.
</Note>
### Enable the HTTP Server (`http.conf`)
ARI requires the Asterisk HTTP server to be enabled:
```ini
[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:
```ini
[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:
`tls_enabled = yes` is required even though the URI scheme is `wss://` — without it Asterisk will not negotiate TLS and the connection will fail. The ARI credentials (**Stasis App Name** and **App Password**) must match what you configure in the Dograh dashboard under Telephony Settings.
uri = ws://your-dograh-host:port/api/v1/telephony/ws/ari
protocols = media
```
<Note>
Self-hosted deployments on an internal network may use an unencrypted WebSocket (`ws://`). If your Dograh instance is exposed over HTTPS, use `wss://` and the corresponding hostname instead.
The section name (e.g., `dograh`) 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.
Dograh's external media channel uses **G.711 μ-law (`ulaw`)**. Make sure any PJSIP endpoint or SIP trunk that places or receives calls through Dograh allows `ulaw` (e.g. `allow=ulaw` in the endpoint config).
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](#inbound-calling) below.
3. Create a test workflow and initiate a test call to verify the connection.
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 workflow assigned to the called extension.
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. Dograh looks up the called extension in your telephony configuration's phone numbers, finds the assigned workflow, validates quota, and creates a workflow run
