VoIP.infoThe independent guide to business communications.
VoIP.info Guide

Asterisk ARI endpoints: state, subscriptions and out-of-call messaging

Observe technology and resource endpoint state, subscribe to exact changes and send bounded out-of-call messages without treating coarse ARI state as registration, contact reachability or delivery proof.

Reviewed 2026-10-10Asterisk 22 ARI Endpoints API and REST data models, current Applications API, ARI overview and ARI security configuration reviewed October 10, 2026; no Asterisk host, endpoint, contact, registration, ARI application, WebSocket, subscription, message exchange, device, client or call was inspected or testedAdvancedDocumentation based · not lab tested

Treat an endpoint as one technology and resource snapshot

ARI identifies an Endpoint with the pair technology and resource. GET /endpoints lists endpoint objects, GET /endpoints/{tech} narrows the list by technology and GET /endpoints/{tech}/{resource} reads one endpoint. The path parameters are case-sensitive, so retain the exact pair rather than normalizing names in the client.

The model can expose a coarse optional state and associated channel_ids; it is not a PJSIP configuration object or a contact list. Preserve the retrieval time and Asterisk instance with every snapshot. A successful GET proves that Asterisk exposed that object at that moment, not that a device is registered, a contact is qualified, a new call can complete or an endpoint supports text messaging.

Interpret state and channel IDs narrowly

The documented Endpoint state values are unknown, offline and online. Treat them as the endpoint technology provider's current summary. Do not translate online into authenticated, callable or media-ready, and do not translate offline into one universal root cause. For PJSIP, inspect endpoint, AOR, contact, registration and qualify evidence in the PJSIP layer before changing transport or reachability settings.

channel_ids associates current channel identifiers with the endpoint snapshot. It is not an active-call counter, license total, queue occupancy value or proof that those channels are in the expected Stasis application. Resolve each relevant channel and its lifecycle separately; tolerate disappearance between the endpoint read and a later channel read.

Subscribe to the exact endpoint event source

Endpoint reads and endpoint events are separate controls. To observe changes outside automatic Stasis ownership, subscribe the ARI application to endpoint:{tech} for a technology or endpoint:{tech}/{resource} for one resource. The Applications API accepts comma-separated event-source URIs and documents distinct failures for a missing parameter, absent application and nonexistent source.

Keep the event WebSocket connected to the same application, inspect its filter and retain EndpointStateChange events with their embedded Endpoint object. A correct GET does not establish that a subscription exists, that a filter allows the event or that a client received and processed it. Use the broader ARI events and subscriptions guide for connection ownership, subscribeAll and filter behavior.

Choose one outbound message addressing form

ARI provides a technology-URI form, PUT /endpoints/sendMessage, with required to and from values, and an endpoint-path form, PUT /endpoints/{tech}/{resource}/sendMessage, with the destination in the case-sensitive path and a required from value. Both accept an optional body and technology-specific variables. Keep the chosen form, exact identities, encoded path, body policy and variables together in one application-owned request record.

Validate the running Asterisk branch and loaded technology support before exposing this operation. The Asterisk 22 documentation names PJSIP and XMPP resources for messaging, but that does not establish support in a particular build, endpoint, network or client. Treat documented 400 invalid-parameter and 404 endpoint-not-found responses as different failures rather than retrying either blindly.

Separate API acceptance from transport and user outcome

A successful send operation establishes only that ARI accepted the request for the selected technology path. It does not prove that a SIP MESSAGE or other technology exchange left Asterisk, received a successful remote response, reached the intended device, rendered in a user interface or was read. Correlate ARI response, technology logs, wire exchange where authorized and final client behavior as separate evidence.

Inbound TextMessageReceived carries a required TextMessage and an optional Endpoint. Its from, to, body and optional variables remain message data; an absent Endpoint is not proof of an anonymous or invalid sender, and a present Endpoint is not an authorization decision. Apply application-level sender policy, content limits and logging redaction before downstream processing.

Secure and test a bounded lifecycle

Keep ARI on a protected management path, use TLS where supported, grant a dedicated identity only the required operations and place browser-facing tools behind an application authorization layer. Bound message size and rate, avoid credentials or sensitive message bodies in URLs and logs, and reject unapproved technology URIs before they reach Asterisk.

Acceptance should cover exact endpoint read, absent endpoint, state-change subscription, unrelated-event exclusion, reconnect, one permitted message, invalid addressing, unavailable destination and application shutdown. Restore temporary broad subscriptions and verbose logging. No endpoint, message, device or call was tested for this guide, and no compatibility, availability, rendering or delivery result is claimed.

Sources & applicability

Primary references for the technical details above. Operational examples and planning checklists are VoIP.info editorial guidance.

Examples require adaptation to your topology. No live PBX or hardware testing is claimed.

Continue your research

Hub

Asterisk

Understand the programmable PBX and follow the Asterisk 22 LTS documentation baseline.

Explore topic →
Guide · Current Asterisk interface documentation reviewed September 30, 2026; implementation must be checked against the installed branch and integration library

Asterisk AMI, ARI and AGI: choose the control boundary

Separate management events, synchronous dialplan work and application-owned call control before exposing an integration.

Read guide →
Guide · Current Asterisk ARI configuration and getting-started guidance, latest Applications API, Certified Asterisk 22.8 Events API and Asterisk 22 REST data models reviewed October 10, 2026; no Asterisk host, ARI user, application, WebSocket, subscription, filter, event, resource, client handler or call tested

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

Design ARI event delivery by separating application registration, automatic and explicit subscriptions, subscribe-all scope, event filters, connection ownership and client processing.

Read guide →
Guide · Current first-party Asterisk 22 ARI Devicestates, Applications, Events and data-model documentation plus device-state and DEVICE_STATE references reviewed October 10, 2026; no Asterisk process, module, HTTP server, ARI identity, WebSocket, application, device-state resource, provider, hint, endpoint, subscription, NOTIFY, queue, call or display was inspected or tested

Asterisk ARI device states: ownership, subscriptions and consumers

Manage application-owned device states without confusing provider state, ARI control, event delivery, extension hints, presence, reachability or call outcomes.

Read guide →
Guide · Current Asterisk res_pjsip and AMI references plus Asterisk 22 contact-event schemas reviewed October 6, 2026; no endpoint, PBX, DNS path, proxy, OPTIONS exchange, event stream, call or media result was inspected or tested

Asterisk PJSIP contact qualification: read OPTIONS status correctly

Interpret PJSIP OPTIONS, timeouts and contact-event vocabulary without turning qualification into proof of registration, authentication or a usable call.

Read guide →
Troubleshooting guide · Asterisk 22 ARI Endpoints API and REST data models, current Applications API, ARI overview and ARI security configuration reviewed October 10, 2026; no Asterisk host, endpoint, contact, registration, ARI application, WebSocket, subscription, message exchange, device, client or call was inspected or tested

Asterisk ARI endpoint is offline, missing or rejects a message

Trace one technology and resource through endpoint lookup, provider state, exact event scope, message addressing, API result, technology exchange and final client behavior.

Read guide →
Troubleshooting guide · Current Asterisk ARI configuration and getting-started guidance, latest Applications API, Certified Asterisk 22.8 Events API and Asterisk 22 REST data models reviewed October 10, 2026; no Asterisk host, ARI user, application, WebSocket, subscription, filter, event, resource, client handler or call tested

Asterisk ARI events are missing, duplicated or delivered to the wrong client

Trace one expected event through application registration, resource scope, subscribe-all policy, event filters, WebSocket ownership and client processing before changing ARI behavior.

Read guide →
Troubleshooting · Asterisk 22 LTS · FreePBX 17 / Debian 12 checks

Asterisk PJSIP endpoint shows unavailable

Distinguish object loading, contact existence and qualify results before replacing a working configuration.

Read guide →
Diagnostic · Current Asterisk res_pjsip, ContactStatus, ContactStatusDetail, PJSIP contact-listing and troubleshooting documentation reviewed September 29, 2026; no PBX, endpoint, AoR, contact, registration, DNS result, proxy, network path, qualify transaction or call was tested

Asterisk PJSIP contact keeps switching reachable and unreachable

Correlate one contact's registration, expiration, OPTIONS response, RTT and network path before changing qualify timers or contact limits.

Read guide →
Guide · Operational guidance; Asterisk 22 / FreePBX 17 where applicable

Least privilege for PBX users and integrations

Separate the right to register, place calls, administer the PBX and read sensitive data.

Read guide →
Guide

PBX logs and packet captures: useful evidence with limited exposure

Collect enough to diagnose a call while protecting identities, secrets and audio.

Read guide →