Freeze one endpoint and one failed boundary
Record the Asterisk instance and version, exact case-sensitive tech and resource, request path, ARI application and connection identity, endpoint snapshot, relevant channel IDs, expected event source, message to and from form, timestamp, HTTP result, technology response and final client behavior. Redact credentials and sensitive bodies while retaining correlation.
Classify the symptom before changing anything: the endpoint list omits the object, exact GET returns 404, state is unknown or offline, EndpointStateChange is absent, send returns 400, send returns 404, ARI accepts the send but the technology exchange fails, or the remote client receives but does not display it. These are different evidence boundaries.
Prove the exact object and its provider-owned state
Compare GET /endpoints, the technology list and the exact endpoint read without altering letter case or resource encoding. A missing object or 404 belongs first to identity, running configuration, loaded technology and endpoint lifecycle. An object with unknown, offline or online reports a provider summary; ARI does not define that field as registration, contact qualification or call readiness.
For PJSIP, inspect the endpoint, AOR, contacts, outbound registration where applicable, transport and qualify evidence. Continue with the PJSIP unavailable diagnostic or contact-flap diagnostic when those layers disagree. Do not force an ARI device state to conceal an endpoint-provider problem; ARI Device States is a different resource.
Reconcile channels without turning them into reachability proof
Capture the endpoint's channel_ids and resolve only the channels relevant to the incident. Expect a channel to disappear between reads as calls progress. Compare its endpoint association, Stasis application, bridge membership and lifecycle with the bounded time window.
An empty list does not prove the endpoint is unreachable; a populated list does not prove it will accept another call or message. If the reported endpoint is online but call setup fails, follow the actual SIP response, routing and media evidence instead of using channel count as a capacity or health signal.
Verify subscription, WebSocket and event filter
Retrieve the ARI Application state and confirm the exact endpoint:{tech} or endpoint:{tech}/{resource} source. Keep application-name mismatches, nonexistent sources and absent subscriptions distinct. Then confirm the active WebSocket owner, subscribeAll choice and event filter permit EndpointStateChange.
Correlate one real provider transition with the raw WebSocket frame and client handler. If GET changes but no raw event arrives, stay with subscription, filter and transport. If the raw event arrives but application state remains stale, fix parsing, handler lifetime, ordering or cache logic. Do not generate broad endpoint changes merely to test the listener.
Validate message form before tracing delivery
For PUT /endpoints/sendMessage, verify required technology-specific to and from identities. For PUT /endpoints/{tech}/{resource}/sendMessage, verify the exact path pair and required from. Preserve optional body and variables as sent. A 400 indicates invalid send parameters; a 404 indicates that the endpoint could not be found. Correct the demonstrated field or lifecycle issue rather than retrying with alternate identities until one happens to pass.
After API acceptance, trace the technology-specific exchange independently. For PJSIP, correlate the outbound MESSAGE, destination and source identities, response or timeout, authentication and routing as applicable. A successful ARI call is not a remote delivery receipt, and a successful SIP response is not proof that a client rendered or a user read the message.
Correct one owner and retest end to end
Correct only the proven owner: endpoint identity or configuration, provider reachability, PJSIP contact or transport, ARI application scope, WebSocket owner, event filter, message addressing, technology routing, remote policy or client rendering. Avoid changing endpoint state, subscriptions and messaging identities together; that destroys the before-and-after evidence.
Retest exact GET, one real state transition, one unrelated endpoint, reconnect, one approved outbound message, one controlled invalid request and final client outcome. Restore temporary logging and broad event scope, document the running version and rollback, and keep content out of long-lived logs. No Asterisk host, endpoint, contact, message exchange, device or call was inspected or tested for this guide.
Sources & applicability
Primary references for the technical details above. Operational examples and planning checklists are VoIP.info editorial guidance.
- Asterisk 22 ARI Endpoints REST API ↗
- Asterisk 22 ARI REST data models ↗
- Asterisk latest API: Applications subscriptions and event filters ↗
- Asterisk ARI overview ↗
- Asterisk configuration for ARI ↗
Examples require adaptation to your topology. No live PBX or hardware testing is claimed.