Asterisk device state, extension hints and presence

Keep the three state layers separate

A device-state provider reports one named resource such as PJSIP/alice, ConfBridge:room or Custom:maintenance. An extension hint maps a dialplan extension to one or more such device identifiers and Asterisk calculates an extension state from them. Presence state is a separate, usually user-selected condition such as available, away or do not disturb.

Do not translate any one layer into the others without evidence. A registered contact can still have an unknown or unavailable device state, an extension can aggregate several devices, and a user's presence selection does not automatically make a device busy or change queue routing. State labels also belong to their provider: INUSE, BUSY, RINGING, RINGINUSE, ONHOLD, NOT_INUSE, UNAVAILABLE, INVALID and UNKNOWN are not universal proof of registration, reachability or call acceptance.

Treat the hint as a loaded dialplan mapping

A hint is a special dialplan priority: exten => extension,hint,device. Multiple device identifiers can be joined with &, and an optional presence provider follows after a comma. The extension and context are therefore part of the contract. A correctly named device in the wrong context is not the same hint, and a generated configuration file is not proof that the running dialplan loaded it.

Use core show hints to inspect the loaded extension, context, mapped providers, current aggregate state and watcher count. Query the exact extension and context with EXTENSION_STATE() only after confirming a hint exists there; use DEVICE_STATE() when the question is the provider itself. A zero watcher count describes current subscribers, not whether the underlying provider state is correct.

Prove subscription delivery independently

A phone's BLF lamp normally depends on a SIP subscription relationship in addition to the hint. For res_pjsip, preserve the SUBSCRIBE request, identified endpoint, Event and Accept headers, response, active dialog and subsequent NOTIFY bodies. The endpoint's allow_subscribe control, its configured context and the loaded event and body-generator modules all sit between a valid hint and a useful notification. The format a phone accepts is an endpoint-specific question, not something the hint proves.

Classify the first failed boundary. No matching hint is a dialplan problem; a rejected SUBSCRIBE is an identity, authorization, context, event-package or body-format problem; an accepted subscription with no update is a notifier or state-change problem; a delivered NOTIFY that the phone displays incorrectly is an endpoint interpretation or key-configuration problem. Do not edit all four layers together.

Do not make BLF a routing oracle

Extension state is an aggregate chosen for notification and dialplan decisions; it is not a packet trace or a complete call record. A composite hint can hide which device changed, and provider-specific thresholds can report busy before or after a handset would reject another call. Registration, contact qualification, current channels, call waiting, do-not-disturb and the result of an actual INVITE remain separate observations.

Queues can consume device state, but their outcome also depends on the member's state interface, pause, wrap-up, ring-in-use and strategy. A user's presence state does not automatically alter device availability or queue distribution. Confirm the exact queue member and policy rather than treating a red lamp, an away label or one core show hints row as the routing decision.

Give custom state an explicit owner

Asterisk permits DEVICE_STATE() to set values only for a Custom: provider and PRESENCE_STATE() to set values only for CustomPresence:. That mechanism is useful for application-owned conditions, but it does not discover a phone's state. Define who writes the value, which transitions are valid, how it is restored after restart and what consumes it before using a custom state in hints or call policy.

Keep device-state distribution between Asterisk nodes as a separate architecture decision. A locally correct hint and NOTIFY do not prove that another PBX has the same value or that a cluster transport is healthy. Record the node that originated each transition and test failure and recovery behavior with the actual supported distribution mechanism.

Keep ARI control, event delivery and hint consumption separate

The ARI device-state guide covers the application-controlled collection, case-sensitive resource name, update or delete operation, deviceState:{deviceName} subscription and DeviceStateChanged event. An accepted update is not proof that the ARI application received an event or that a hint, queue, NOTIFY or lamp consumed the value.

If an ARI-managed value is missing, stale or disagrees with the downstream display, use the ARI device-state diagnostic before overwriting a PJSIP or other module-owned provider.

Capture one bounded state transition

For an authorized test, record the Asterisk version, loaded modules, hint and context, each mapped provider, initial device and extension states, subscriber identity, SUBSCRIBE response, NOTIFY sequence and the phone's final display. Trigger one controlled transition—such as idle to ringing to in-use to idle—and correlate timestamps instead of inferring order from a final lamp. Protect identities and message bodies, then disable temporary SIP tracing.

Correct only the demonstrated boundary and repeat the same transition plus one nearby control case. No Asterisk host, dialplan, module, endpoint, subscription, NOTIFY body, phone, BLF key, queue, cluster, availability, compatibility, price or live call was inspected or tested for this guide. When the symptom is a stale, unknown or missing lamp, the BLF update diagnosis follows one transition from provider and loaded hint through the subscription dialog, NOTIFY body and phone display.

Keep the Asterisk 22.11.0 BLF regressions version-bound

The Asterisk Development Team's 22.12.0-rc2 change record identifies two BLF-adjacent regressions introduced in 22.11.0: no initial NOTIFY for a dialog subscription when a hint referenced CustomPresence without an AstDB entry, and missing caller identity in a ringing extension's dialog-info+xml notification. These are narrower than every stale lamp, missing update or absent caller label. Match the installed build, exact hint and presence shape, emitted body and failed display field before treating either issue as relevant.

The documented corrections were present in a release candidate on October 8, 2026. That is upstream candidate evidence, not proof that a final 22.12.0 release, distribution package or managed PBX update was available. Do not install a pre-release on production merely because a symptom resembles the change note; follow the deployment owner's supported update path and validate the final artifact when it exists.

Add AMI remote synchronization as a separate state owner

The AMI device-state guide adds version-gated remote updates and list transaction boundaries without turning a provider event into hint or BLF proof.

Keep presence providers separate from device aggregation

The AMI presence-state guide follows one presence provider into a hint without converting it into device availability or queue state.

Follow device providers into an extension aggregate

The AMI extension-state guide keeps provider state, loaded hint aggregation, presence and subscriber evidence on separate layers.

Treat a hint priority as a state mapping

The AMI runtime dialplan guide keeps hint mutation distinct from numeric executable priorities and call-path proof.

Separate an Asterisk Info subscription row from BLF delivery

The Asterisk Info guide preserves hint, watcher, event delivery and lamp state as different evidence. A subscription row does not prove that a phone received or rendered the current device state.