Asterisk ARI channel variables: scope, inheritance and events

Name the scope before reading the value

GET /channels/{channelId}/variable reads a variable or dialplan function on one channel. GET /asterisk/variable reads a global variable without a channel ID. These endpoints answer different ownership questions even when the variable text is identical. A channel value, inherited child value and global fallback must not be merged into one application field without recording which source won.

Preserve the running Asterisk version, Stasis application, exact channel ID, call-leg role, variable or function text, intended scope, producer, consumer and observation time. A caller-facing number, channel name from an earlier snapshot or linked call identifier is not a substitute for the live channel resource that owns the read.

Use explicit reads and writes for explicit state

The Channels API provides single-value GET and POST operations for a channel variable or function. The documented boundaries keep a missing parameter at 400, a missing channel or variable at 404 and a channel outside the controlling Stasis application at 409. Preserve the exact request and response instead of converting every failure into an empty value.

A variable name and a dialplan function expression are both accepted by the interface but can have different semantics. Allow-list application-owned names and the small set of functions the workflow actually needs. Do not expose a general variable-or-function proxy to untrusted input, and do not treat a successful write as proof that later dialplan logic, a child channel or an external system consumed the value.

Gate multi-variable operations by the running version

Asterisk documents bulk GET /channels/{channelId}/variables and POST /channels/{channelId}/variables from 20.20.0, 22.10.0 and 23.4.0. The read accepts a comma-separated list; the write accepts a variables object. Confirm the installed branch and point release before selecting those routes, and retain the single-variable operations for supported older builds.

A bulk response groups observations from one request but does not make several application decisions atomic. Validate every expected key and value, distinguish a missing variable from a missing channel, and keep the before-and-after state when several values jointly control a transition.

Separate explicit reads, Channel JSON and reported updates

The channelvars setting in ari.conf is a comma-separated list of variables to display in Channel JSON. Current channel-variable writes also accept report_events; bulk writes can represent a value as an object with value and optional report_events, which defaults to false. Snapshot visibility and update reporting are therefore configured behaviors, not automatic copies of every channel variable.

An absent field in a Channel object does not by itself prove the variable is unset; perform the scoped explicit read. Conversely, a value in a later snapshot does not prove an earlier event contained it or that the application processed its update. Record configuration, event subscription, event timestamp and explicit response separately.

Apply inheritance when the child is created

Asterisk documents a single leading underscore as inheritance to the next child channel, with the prefix removed there. A double underscore remains and continues across descendant channels. Setting a prefixed or unprefixed form replaces the other forms of that same variable. These rules apply at channel creation; adding a prefix later does not retroactively repair an existing child.

Map the parent and every created channel, including both Local-channel halves and an originated callee. Read the value from the channel that will consume it. If a value disappears after Local-channel optimization, use the Local-channel diagnostic before retaining the Local pair or broadening inheritance.

Keep global state narrow and non-secret

Global variables do not live on one channel and apply across calls. Asterisk supports dedicated ARI global-variable reads and writes as well as dialplan global-variable mechanisms. That scope can be appropriate for bounded system state, but it can also create cross-call coupling and last-writer-wins behavior that a channel variable avoids.

Do not place credentials, authentication material, payment data or unbounded caller data in global or broadly inherited variables. Restrict ARI write access, sanitize logs and support extracts, define retention, and use an application data store when durable concurrency, history or transactional ownership is required.

Prove the consumer and clean up the lifecycle

Acceptance retains the scoped read or write, expected Channel JSON or reported update where configured, correct child inheritance, the dialplan or application transition that consumed the value, and clean channel exit. Test a missing variable, wrong channel, channel outside Stasis, child creation and hangup so absence and lifecycle errors remain distinguishable.

Remove temporary event reporting and sensitive traces after the bounded test. A returned value proves one observation on one scope at one time; it is not proof of a completed call, durable storage or every related channel. No ARI variable, event, function, channel or call was tested for this guide.

Keep ARI access attached to the selected channel

The general channel-variable guide defines inheritance and stack boundaries beneath ARI. An ARI channel identifier does not make related channel stores interchangeable.