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

Asterisk AMI Getvar and Setvar: scope, functions and events

Read or write the intended channel, global variable or dialplan function without confusing an accepted manager response, VarSet event or later call outcome.

Reviewed 2026-10-19Current branch-23 AMI Getvar, Setvar and VarSet references, channel-variable setting and inheritance guidance, global and shared-variable documentation, external-protocol function safeguards and AMI event filtering were reviewed October 19, 2026. Installed branch, manager permissions, channel lifetime, variable namespace, function availability, event selection, dialplan ownership and application outcomes remain deployment specific. No PBX, manager account, session, channel, variable, function, event, dialplan, packet, media stream or live call was inspected or testedAdvancedDocumentation based · not lab tested

Choose the namespace before sending the action

AMI Getvar reads a channel variable or a dialplan-function result. Setvar writes a channel variable or writable dialplan function. Both accept ActionID, optional Channel and Variable; Setvar also accepts Value. The current action references say that omitting Channel selects a global variable.

That makes the channel header a scope boundary, not optional decoration. Record the complete live channel name, Uniqueid and Linkedid when channel scope is intended. Keep a channel variable, inherited variable, global variable, SHARED() namespace and another dialplan function as different targets.

Correlate the synchronous response first

Assign a unique ActionID and retain the matching response. For Getvar, distinguish an action error, an empty or unset value and a function result. For Setvar, an accepted response means Asterisk processed the write request; it is not proof that later dialplan logic read that value or produced the intended service outcome.

AMI messages are header blocks with an empty-line terminator. Preserve exact header spelling, delimiters and framing before interpreting a timeout as a variable failure.

Treat channel lifetime as part of the key

A channel variable lives on a channel structure. A stale display label, prefix match or channel name captured before masquerade, transfer, Local-channel optimization or hangup can address no channel or the wrong live channel. Resolve the exact channel at the time of each action.

Do not reuse a prior call’s channel name as durable state. Use purpose-built persistent or application-owned storage where the business requirement must outlive the channel, with explicit concurrency and recovery design.

Preserve inheritance semantics instead of editing the child late

A single leading underscore causes one generation of inheritance and is removed on the child. Two leading underscores continue across descendants. Asterisk also documents that assigning any prefixed or unprefixed version replaces the other versions of that variable on the channel.

Inheritance happens when a child is created. Setting _FOO or __FOO after the target child already exists does not retroactively populate it. Capture the parent value before creation and the child value after creation rather than inferring one from the other.

Bound global, SHARED and function side effects

Omitting Channel selects global scope. That is broader than one call and can expose races or stale state across unrelated calls. SHARED() is a separate namespace for data shared between channels, and the current function reference explicitly warns that concurrent channels can change it without notice. Read a shared value into a regular channel variable before multi-step calculations.

Function evaluation can have side effects. Asterisk documents safeguards for privilege-escalating functions reached through AMI or ARI, controlled by live_dangerously; do not relax that safeguard to make a general-purpose remote write work. Give manager users only the required action classes and allowable inputs.

Use VarSet as change evidence, not an outcome receipt

VarSet reports the channel snapshot plus Variable and new Value; the generated reference has distinct variants for ordinary, LOCAL() and SHARED() writes. Event delivery also depends on the manager session’s event mask, permissions and filters. A missing event therefore does not by itself prove the write failed.

Correlate the action response, exact target, optional event and a fresh read. Then verify the dialplan branch or application outcome separately. Redact credentials, tokens and personal data before logging variables. No PBX, manager account, session, channel, variable, function, event, dialplan, packet, media stream or live call was inspected or tested.

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

Troubleshooting · Current branch-23 AMI Getvar, Setvar and VarSet references, channel-variable setting and inheritance guidance, global and shared-variable documentation, external-protocol function safeguards and AMI event filtering were reviewed October 19, 2026. Installed branch, manager permissions, channel lifetime, variable namespace, function availability, event selection, dialplan ownership and application outcomes remain deployment specific. No PBX, manager account, session, channel, variable, function, event, dialplan, packet, media stream or live call was inspected or tested

Asterisk AMI Getvar or Setvar is wrong, blank or missing a VarSet event

Trace manager framing, ActionID, exact channel lifetime, variable namespace, function policy, event filters and the later consumer before changing the dialplan.

Read guide →
Guide · Current Asterisk variable-inheritance guidance and Asterisk 22 Set, CHANNEL, MASTER_CHANNEL, LOCAL, LOCAL_PEEK, VARIABLE_EXISTS and IMPORT documentation reviewed October 15, 2026; channel creation, inheritance depth, Gosub stack frames, master-channel lifetime, cross-channel access and loaded dialplan remain deployment specific; no PBX, channel, variable, subroutine, transfer, Local-channel path or live call was inspected or tested

Asterisk channel-variable scope and inheritance

Choose channel, child-depth, Gosub-frame, master-channel or explicit cross-channel scope before using a variable to control a call.

Read guide →
Guide · Current Asterisk branch-23-generated Events, Filter, WaitEvent, Login and Ping action references, matching branch-22 Events, Filter and WaitEvent references, the official AMI event-filtering guide and Manager TCP/IP API reviewed October 16, 2026; installed branch, manager user permissions, login mask, static and dynamic filters, connection type, event queue, client parser, reconnect behavior, action concurrency, downstream storage and call activity remain deployment specific; no PBX, AMI session, manager user, permission, configuration file, socket, HTTP session, event queue, channel, bridge, packet, media stream or live call was inspected or tested

Asterisk AMI event delivery, filters and WaitEvent

Trace event delivery through manager read permissions, login and Events masks, configured and session filters, TCP or HTTP transport, WaitEvent queueing and client processing without treating silence as a failed PBX.

Read guide →
Guide · Asterisk Latest API branch 23 LOCK, TRYLOCK and UNLOCK documentation, Asterisk 22 SHARED documentation and current global-variable guidance reviewed October 14, 2026; function availability, loaded func_lock and func_global modules, exact lock names, channel ownership, protected data, wait duration, dialplan branches and external side effects remain deployment specific; no PBX, module, dialplan, channel, lock, variable, database row, file, external service or call was inspected or tested

Asterisk dialplan locks: serialize shared state without hiding call failure

Use LOCK, TRYLOCK and UNLOCK around the smallest shared-state update, preserve channel ownership and failure branches, and keep the protected operation distinct from mutex acquisition.

Read guide →
Guide · Asterisk branch-23-generated Login, Challenge, Logoff and Events references, branch-22-generated Login reference, and official AMI syntax, v2, permission and network-security documentation reviewed October 16, 2026; installed branch and maintenance release, listener and transport, manager.conf ownership, username, secret rotation, ACL, read and write classes, login event mask, connection lifetime, client timeout, reconnect policy and downstream operations remain deployment specific; no PBX, manager configuration, credential, ACL, socket, manager session, request, response, event, channel, packet, media stream or live call was inspected or tested

Asterisk AMI session authentication, Login, Logoff and Challenge

Keep manager identity, authentication exchange, transport protection, event mask, permissions and session lifetime as separate AMI evidence.

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 →