Skip to main content
Menace Voice

Asterisk ARI Integration

Connect Menace Voice to your Asterisk PBX using the Asterisk REST Interface (ARI)
9 min read

Overview#

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

This guide focuses on the Menace Voice-specific configuration. For general Asterisk installation and administration, refer to the official Asterisk documentation.

Is Asterisk the right option?#

Asterisk is PBX software, not a phone-number provider. Use this integration if you already operate an Asterisk server or have someone who manages it for you. If you simply need to buy a number and connect it, choose Twilio, Telnyx, Plivo, Vobiz, or Vonage from the telephony overview.

Estimated price#

Asterisk does not publish a phone-number price because it does not sell numbers. Your SIP carrier bills the DID and call usage, and you are responsible for Asterisk hosting and administration. Confirm those amounts with the carrier and hosting provider you choose.

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 Menace Voice instance and Asterisk
  • Menace Voice instance running and accessible
Note

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 Menace Voice. Refer to the Asterisk build system documentation for details on enabling modules.

How setup fits together#

Setup crosses between the two systems, so the order matters:

WhereWhat
1AsteriskCreate the ARI user, enable the HTTP server, and add the external-media WebSocket client — the values Menace Voice asks for
2Menace VoiceEnter those values and save. Menace Voice generates a Stasis App Name unique to this configuration
3AsteriskPut that generated name in your dialplan as Stasis(<name>) and reload
4Menace VoiceRegister the extensions that should reach an agent, then place a test call

The dialplan comes last because the Stasis application name does not exist until the configuration is saved. Everything else can be set up in advance.

Part 1: Asterisk connection settings#

These are minimal examples focused on the Menace Voice integration -- refer to the Asterisk documentation for full configuration details.

Enable ARI (ari.conf)#

Create an ARI user that Menace Voice will use to authenticate:

Note

The username (section name, e.g., dograh) and password here are the ARI Username and App Password you enter in Menace Voice. This name authenticates to Asterisk — it is not the Stasis application name, which Menace Voice generates for you in Part 2.

Enable the HTTP Server (http.conf)#

ARI requires the Asterisk HTTP server to be enabled:

Configure External Media Streaming (websocket_client.conf)#

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

Note

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 (ARI Username and App Password) must match what you configure in the Menace Voice dashboard under Telephony Settings.

Note

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

Note

Configure the uri as a base URL only, without a query string. During each call, Menace Voice asks Asterisk to create an externalMedia channel and Asterisk appends workflow_id, organization_id, and workflow_run_id through the v() transport data for that call. Opening /api/v1/telephony/ws/ari directly in a browser or with wscat can return HTTP 403 because those routing parameters are missing; that is expected and does not indicate a websocket_client.conf misconfiguration.

Note

Menace Voice's external media channel uses G.711 μ-law (ulaw). Make sure any PJSIP endpoint or SIP trunk that places or receives calls through Menace Voice allows ulaw (e.g. allow=ulaw in the endpoint config).

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

Apply the configuration changes#

Reload the affected Asterisk modules from the Asterisk CLI (asterisk -rvvv):

Changes to http.conf require a full Asterisk reload (core reload) or a service restart. core reload also covers both commands above if you would rather reload everything at once.

Part 2: Create the configuration in Menace Voice#

Step 1: Start the phone-number wizard#

  1. Open Phone numbers and click Add phone number.
  2. Select Asterisk ARI and continue.

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
ARI UsernameThe 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
From ExtensionsOptional SIP extensions or trunk numbers for outbound callsPJSIP/6001 or 6001

Stasis App Name is not something you enter — Menace Voice generates it when you save and displays it on the configuration for you to copy.

Step 3: Save and copy the Stasis App Name#

Complete the number and agent steps, then finish setup. Open the saved Asterisk provider connection. Menace Voice assigns it a Stasis App Name — something like dograh_a1b2c3d4e5f6. Copy it; you need it for Part 3.

Note

The Stasis App Name is generated, not chosen. Asterisk gives a Stasis application to whichever ARI connection registered for it most recently and stops delivering events to the previous one, with no error on either side. If two configurations named the same application on one Asterisk, one would silently stop receiving calls while the other received calls that were not its own. Generating the name is what prevents that.

Part 3: Route calls into the Stasis application#

Configure the Stasis Dialplan (extensions.conf)#

Route incoming calls into the Stasis application Menace Voice generated for your configuration:

Replace dograh_a1b2c3d4e5f6 with the Stasis App Name from your configuration, then reload the dialplan:

Warning

Until the dialplan names the generated application, calls reach Asterisk but never arrive at Menace Voice. This is the most common reason a correctly configured ARI integration receives no calls.

Part 4: Add extensions and test#

  1. 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.
  2. 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. Menace Voice 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 into your configuration's Stasis application
  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. Menace Voice 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 you configured in Part 3. Either route a specific extension:

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

Replace dograh_a1b2c3d4e5f6 with the Stasis App Name shown on your Menace Voice configuration.

Step 2: Add the extension as a phone number in Menace Voice

  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

    Note

    Adding the extension in Menace Voice doesn't change Asterisk's dialplan — that's what Step 1 is for. The Menace Voice 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:

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#

Cannot connect to ARI endpoint
  • Verify the ARI endpoint URL is correct and reachable from your Menace Voice 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
Authentication failed
  • Verify the ARI Username 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
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 Menace Voice URI
  • Ensure the WebSocket Client Name in Menace Voice matches the section name in websocket_client.conf
  • Verify network connectivity and firewall rules allow WebSocket traffic between Asterisk and Menace Voice
Calls not reaching Menace Voice
  • Ensure the dialplan routes calls to Stasis(...) using the Stasis App Name from your Menace Voice configuration, not the ARI username
  • Confirm you ran dialplan reload after editing extensions.conf
  • If two Menace Voice configurations point at this Asterisk, check that they do not name the same Stasis application — the one that connected most recently takes the application over and the other stops receiving calls entirely
  • Check Asterisk CLI for errors: asterisk -rvvv
  • Confirm the ARI WebSocket connection is active
Inbound calls are immediately hung up
  • Verify the called extension is added as a phone number under your ARI configuration in /telephony-configurations and has an Inbound workflow assigned
  • Confirm the workflow exists and belongs to the same organization as the ARI config
  • Check that your organization has available quota
  • Review Menace Voice logs for warnings like "no matching phone number registered for config" or "has no inbound_workflow_id assigned"
WebSocket client connection issues
  • Check the URI in websocket_client.conf points to the correct Menace Voice host and port
  • Verify the Menace Voice 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 Menace Voice for optimal audio quality
  • Use strong passwords for ARI authentication
  • Restrict ARI access to known IP addresses using firewall rules
  • Monitor Asterisk logs alongside Menace Voice logs when debugging call issues
  • Keep Asterisk updated to the latest stable version for security and compatibility

Further Reading#

Vobiz IntegrationVICIdial Integration