Asterisk ARI events and subscriptions: scope, filters and WebSocket ownership

Keep REST requests and asynchronous events independent

ARI uses HTTP requests to inspect or change resources and a WebSocket to deliver asynchronous JSON events. A successful REST response does not prove that the event connection was registered, subscribed, able to receive the corresponding message or able to process it. Conversely, an event can describe a state change that did not originate from the same client request.

Record the Asterisk branch, ARI application name, HTTP result, WebSocket connection identity, event type, event timestamp, optional asterisk_id and referenced resource IDs. Use application-owned correlation and idempotency keys for business actions; the event envelope is evidence of an Asterisk message, not proof that downstream logic committed its result.

Register the exact application before handing it channels

The event WebSocket is opened at /ari/events with one or more application names. Asterisk's configuration guide says a channel entering Stasis(app) is handed to the connected application, automatically subscribed for that channel and announced with StasisStart. Without a connected WebSocket for that name, the channel is immediately returned to the dialplan; after a previously connected client breaks, events can be missed.

Application names and API parameters are case-sensitive. Treat process health, HTTP authentication, WebSocket upgrade, application registration, StasisStart, first accepted control action and StasisEnd as separate gates. Prefer HTTPS and WSS, restricted network reachability and a narrowly authorized ARI user.

Subscribe deliberately to resources outside automatic scope

A resource already controlled by an application can produce the events expected for that relationship, but other channels, bridges, endpoints and device states do not become visible merely because the same ARI user can read them over HTTP. The Applications API documents explicit subscriptions using channel:{channelId}, bridge:{bridgeId}, endpoint:{tech}[/{resource}] and deviceState:{deviceName} event-source URIs, including comma-separated sources.

Retain the exact source URI and the Application object returned after the change. A subscribe request can return 400 for a missing parameter, 404 when the application does not exist and 422 when the event source does not exist. Unsubscribe additionally documents 409 when the application was not subscribed. These outcomes are not interchangeable with an empty event stream.

Use subscribeAll only as an explicit broad-scope policy

The Events API documents subscribeAll=true as subscribing the listed application to all Asterisk events and effectively disabling application-specific subscriptions; the default is false. That setting changes scope rather than repairing one missing event. It can also increase sensitive data volume and application workload.

Choose the narrowest resource scope that supports the application. If broad observation is genuinely required, define which event families are accepted, how tenant or call boundaries are enforced, how reconnects are reconciled and how event content is retained or redacted. Do not expose the event WebSocket directly to untrusted browser code.

Apply event filters after proving subscription scope

The Applications API documents event-type filtering from Asterisk 13.26.0 and 16.3.0. A filter body can contain allowed and/or disallowed arrays whose entries name event types with case-sensitive type strings. An allow-list containing only StasisStart and StasisEnd, for example, deliberately prevents other event messages from reaching that application.

Confirm the running branch supports the operation, retrieve the current Application state, and compare the exact event type against the installed API model before editing the filter. A correct resource subscription with a restrictive filter is different from an absent source, a closed socket or a client that discarded a parsed event.

Give one WebSocket ownership of each application

Asterisk's REST data model says one application can be subscribed by only one WebSocket at a time. If another WebSocket subscribes to the same application, the newer connection wins and the older connection receives ApplicationReplaced. Treat that as an ownership transfer, not as a harmless second observer.

Assign one active connection owner or an explicit failover design, and give every process instance a unique log identity. On reconnect, reconcile application registration, subscription state, filters and in-flight resource state before resuming actions. Do not assume that two client logs showing the same application name prove duplicate server emission; they may span a replacement boundary or application-level replay.

Prove delivery, processing and recovery separately

For a bounded test resource, preserve the server-side state transition, the expected subscription and filter, the raw WebSocket message, client parse result, handler entry, application state transition and any downstream action. Detect duplicate processing with application-owned event and resource keys rather than deleting repeated-looking messages without context.

Test normal registration, one expected event, explicit unsubscribe where applicable, reconnect, replacement protection and a neighboring unaffected resource. Restore temporary broad subscriptions, filters and verbose logs. Use the missing-or-duplicated event diagnostic when these layers disagree. No Asterisk host, ARI user, application, WebSocket, subscription, filter, event, resource, client handler or call was inspected or tested for this guide.

Trace talking events through the Stasis application

Use the TALK_DETECT diagnostic to separate detector output from application scope, WebSocket continuity and consumer handling.

Subscribe to intercepted hold events on the intended channel

Use the HOLD_INTERCEPT guide to keep event creation, Stasis subscription, WebSocket delivery, consumer processing and any later hold action independently observable.

Subscribe to the ChannelTransfer event on the owning application

The PJSIP transfer-handling guide keeps WebSocket delivery, application scope, REFER data and transfer action as separate evidence.

Prove the ARI listener and event socket independently

Use the built-in HTTP service guide and endpoint diagnostic before treating a REST response as proof of a subscribed ARI event stream.