Asterisk AMI runtime dialplan inspection and exact extension mutation

Inspect the narrowest loaded scope

ShowDialPlan reports dialplan contexts and extensions and accepts both Extension and Context. Prefer the exact pair needed for the change: the upstream action warns that showing the full dialplan can consume substantial capacity. Preserve the ActionID, request scope, timestamp and raw response.

This is loaded-state evidence. Compare it with the owned configuration or generator output separately; a manager view does not identify which file, database, module or management layer should make a durable change.

Address one exact mutation key

DialplanExtensionAdd names Context, Extension, Priority, Application and optional application data. The action can create a context that is absent. Priority must be numeric or hint, and the extension field may include a caller-ID match after /. Record every field exactly rather than reducing the target to a displayed extension number.

A hint is a state mapping, not an executable call step. A caller-ID-qualified extension is also a different match from the unqualified name. Review both forms deliberately before issuing a write.

Make replacement an explicit decision

For an existing context–extension–priority key, Replace true overwrites that priority. Without a true value, the documented action fails and leaves the existing extension in place. Default to the failing form for creation; use replacement only after retaining the old application and data and approving the exact rollback.

An accepted action proves the transaction response, not that an intended caller will select the row, that the application is available, or that later priorities form a valid path.

Bound removal by priority

DialplanExtensionRemove requires the context and extension. With Priority, it removes only that priority; without Priority, it removes all priorities for the extension. Treat omission as a materially wider destructive operation and verify the target immediately before execution.

Re-inspect the same loaded scope after removal. Check adjacent priorities because Asterisk normally advances in sequence, and a missing next priority can terminate the call path.

Separate loaded state from durable source

The official configuration workflow describes dialplan source in extensions.conf and a dialplan reload after source changes. The AMI mutation references do not promise a write to that file, another configuration backend or a management system. Do not label a successful action persistent or reload-safe without deployment-specific proof.

Name the configuration owner, capture its intended source, and test the next reload or regeneration in a controlled window. If a platform generates dialplan, make the durable change through that owner rather than treating a runtime patch as the source of truth.

Verify match, execution and outcome separately

Within a context, Asterisk searches explicit extensions, pattern matches, includes and switches in that order, and pattern specificity has its own rules. Confirm the originating channel context, caller ID, dialed digits, include graph and chosen priority; a visible row is not proof that a channel selected it.

Then verify application execution, channel lifecycle, signaling, answer and media at their owners. Grant AMI write classes only to the automation that needs them and restrict manager network access. No PBX, module, manager session, configuration file, loaded dialplan, channel, packet, media stream or live call was inspected or tested for this guide.

Keep runtime dialplan mutation distinct from file update

The AMI configuration-file guide covers persistent file operations; neither surface alone proves reload survival or call outcome.