Asterisk ARI device states: ownership, subscriptions and consumers

Separate provider state from application-owned state

Asterisk device-state providers report named resources such as PJSIP/, ConfBridge: and Custom:. The provider and loaded modules determine what a state means. ARI's collection lists ARI-controlled device states; it is not a directory of every endpoint, contact, hint or presence record in Asterisk.

Choose an application-owned name and record its purpose, writer, permitted values, consumers and lifetime. Do not use an ARI write to imitate the current state of a PJSIP endpoint or another module-owned device. A 409 response for an uncontrolled name is an ownership boundary, not a reason to replace the provider.

Use exact names and bounded values

ARI device-state paths and parameters are case-sensitive. GET /deviceStates/{deviceName} retrieves the current state for one exact resource. PUT accepts NOT_INUSE, INUSE, BUSY, INVALID, UNAVAILABLE, RINGING, RINGINUSE or ONHOLD and implicitly creates an ARI-controlled state when ownership permits.

Preserve the unambiguous logical name before URL encoding, the requested value, response and immediate read-back. The broader DeviceState model can report UNKNOWN, but the current PUT list does not make UNKNOWN an accepted write value. Do not translate an omitted or failed update into whichever state is most convenient for a dashboard.

Treat update, event and consumer as three gates

A successful PUT changes the named ARI-controlled resource. The DeviceStateChanged data model carries a DeviceState object, application and timestamp, but delivery still depends on an event WebSocket and subscription. A downstream extension hint, queue rule, SIP NOTIFY or phone lamp is a later consumer with its own mapping and acceptance evidence.

Retain the HTTP result, explicit GET, event and consumer transition separately. A matching read without an event can be a subscription or event-stream problem. A matching event without a lamp change belongs downstream in the hint, subscription or phone path.

Subscribe to the exact event source

The Applications API accepts deviceState:{deviceName} as an event source. Subscription distinguishes missing parameters, missing applications and missing event sources with 400, 404 and 422 responses. Unsubscription can also return 409 when the application was not subscribed. Preserve the exact application name and event-source URI returned in application state.

Do not rely on a remembered subscription after an application restart or a replacement WebSocket. Reconcile the current application, socket, resource and subscription before processing state. Broad subscribeAll behavior and event filters are separate settings; use only the visibility the integration requires.

Keep device, extension and presence states distinct

Device state maps one provider resource. An extension hint can aggregate one or more device identifiers, while presence represents a separate user condition. Registration, contact qualification, current channels and actual call acceptance are other observations again.

A custom BUSY value can deliberately drive an application or hint without proving that a handset rejected a call. Conversely, an idle custom value does not prove that a registered endpoint is reachable. Document which layer is authoritative for each policy and never make a BLF colour the only evidence for routing or service health.

Define startup, concurrency and deletion behavior

An application-controlled state needs one writer or an explicit conflict policy. On startup, read current ARI-controlled resources, compare them with the application's durable desired state and publish only deliberate corrections. Timestamp and correlate competing writes so a late worker cannot silently restore an obsolete value.

DELETE /deviceStates/{deviceName} destroys an ARI-controlled state and preserves 404 and 409 ownership failures. Delete only when the resource lifecycle is over and every hint or consumer has a defined missing-state behavior. Deletion is not a substitute for publishing a valid idle state.

Protect control access and prove the bounded outcome

ARI depends on Asterisk's separately configured HTTP server and authenticated users. Restrict write access, network reachability and accepted resource names; use TLS where supported and keep a browser behind an application authorization layer rather than connecting it directly to ARI. Device-state names and events can expose operational activity, so minimize logs and retention.

Acceptance retains the intended value, exact resource, update response, read-back, subscribed event, expected hint or application transition and explicit cleanup. It does not infer endpoint reachability, a completed call or user availability. No device state, application, subscription, endpoint, lamp or call was tested for this guide.

Do not substitute an AMI remote update for ARI ownership

The AMI device-state guide keeps remote synchronization, ARI-controlled resources and local module providers distinct.