mirror of
https://github.com/dograh-hq/dograh.git
synced 2026-06-07 07:55:16 +02:00
feat: add asterisk ARI websocket interface (#159)
* chore: remove old files * feat: ari outbound dialing * feat: add websocket configuration for ARI * feat: handling inbound calls * delete ext channel from redis on stasis end * fix: add lock in workflow run update, refactor _handle_stasis_start * chore: update submodule --------- Co-authored-by: Sabiha Khan <sabihak89@gmail.com>
This commit is contained in:
Abhishek
GitHub
parent
ee4a874e54
commit
7552b6c819
37 changed files with 2076 additions and 4172 deletions
215
docs/integrations/telephony/asterisk-ari.mdx
Normal file
215
docs/integrations/telephony/asterisk-ari.mdx
Normal file
|
|
@ -0,0 +1,215 @@
|
|||
---
|
||||
title: "Asterisk ARI Integration"
|
||||
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 (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
|
||||
|
||||
<Note>
|
||||
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](https://docs.asterisk.org/) for details on enabling modules.
|
||||
</Note>
|
||||
|
||||
## 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](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:
|
||||
|
||||
```ini
|
||||
[dograh_staging]
|
||||
type = websocket_client
|
||||
uri = ws://your-dograh-host:port/ws/audio
|
||||
protocols = audio
|
||||
```
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
Refer to the [Asterisk WebSocket documentation](https://docs.asterisk.org/) 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:
|
||||
|
||||
| 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` | `dograh` |
|
||||
| **App Password** | The ARI password configured in `ari.conf` | `your_secure_password` |
|
||||
| **WebSocket Client Name** | The connection name from `websocket_client.conf` | `dograh_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
|
||||
|
||||
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](#configure-the-stasis-dialplan-extensionsconf).
|
||||
|
||||
**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`).
|
||||
|
||||
<Note>
|
||||
If no Inbound Workflow ID is configured, inbound calls will be hung up immediately. You must set this field for inbound calling to work.
|
||||
</Note>
|
||||
|
||||
**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
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Cannot connect to ARI endpoint">
|
||||
- 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
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Authentication failed">
|
||||
- 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
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="No audio during calls">
|
||||
- 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
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Calls not reaching 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
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Inbound calls are immediately hung up">
|
||||
- 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"
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="WebSocket client connection issues">
|
||||
- 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
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 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
|
||||
|
||||
- [Asterisk Documentation](https://docs.asterisk.org/) -- official reference for all Asterisk configuration
|
||||
- [ARI Documentation](https://docs.asterisk.org/Configuration/Interfaces/Asterisk-REST-Interface-ARI/) -- detailed ARI configuration and API reference
|
||||
|
|
@ -19,6 +19,9 @@ Dograh AI supports inbound calling across all supported telephony providers. Whe
|
|||
<Card title="Vobiz" href="/integrations/telephony/vobiz">
|
||||
Cloud-based telephony with global reach and competitive pricing
|
||||
</Card>
|
||||
<Card title="Asterisk ARI" href="/integrations/telephony/asterisk-ari">
|
||||
Connect to your own Asterisk PBX via the Asterisk REST Interface
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Note>
|
||||
|
|
@ -46,6 +49,7 @@ The telephony configuration for inbound calling is **identical** to outbound cal
|
|||
- [Twilio Configuration](/integrations/telephony/twilio#configuration)
|
||||
- [Cloudonix Configuration](/integrations/telephony/cloudonix#configuration)
|
||||
- [Vobiz Configuration](/integrations/telephony/vobiz#configuration)
|
||||
- [Asterisk ARI Configuration](/integrations/telephony/asterisk-ari#configuration-in-dograh)
|
||||
|
||||
### Step 2: Get Your Workflow Webhook URL
|
||||
|
||||
|
|
@ -75,6 +79,7 @@ Each telephony provider requires additional configuration to route incoming call
|
|||
- [Vonage Inbound Setup](/integrations/telephony/vonage#inbound-calling-setup)
|
||||
- [Cloudonix Inbound Setup](/integrations/telephony/cloudonix#inbound-calling-setup)
|
||||
- [Vobiz Inbound Setup](/integrations/telephony/vobiz#inbound-calling-setup)
|
||||
- [Asterisk ARI Inbound Setup](/integrations/telephony/asterisk-ari#inbound-calling)
|
||||
|
||||
|
||||
## Testing Inbound Calls
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue