Skip to content
Phone Guides

Review and modernise a legacy Asterisk dialplan

Begin with the routes callers use and the permissions those routes grant. Replacing an old application name is only one part of moving a dialplan to a newer release.

Source-reviewed, 19 October 2026. Prepared from the cited documentation. No legacy migration has been independently tested by Phone Guides. Scope: review method for an Asterisk 22 target; source-version behaviour must be established separately.

Inventory reachable behaviour

Record contexts, includes, patterns, subroutines, feature codes, channel-driver references and integrations. Identify which endpoints and trunks enter each context. Keep generated configuration separate from owner-maintained source.

For each used application or function, record its arguments and interpreted result. An application still existing in the target branch does not establish that an old argument position or option retains the same meaning.

Use the Asterisk 22 application index to locate the target reference, and upgrade guidance to review every crossed release boundary.

Handle removed components explicitly

The Asterisk 21 change notes record removed components including app_macro and chan_sip. Do not carry an old book example forward as a current recipe when its dependency is absent.

Legacy dependency Review question
Macro/subroutine What arguments, variables and return path does it require?
Driver-specific channel What destination and account object replace it?
Queue options Are argument positions and exit behaviour valid in the target?
Conference/parking feature Which current application and configuration own it?
External script/API What assumptions about identifiers and events does it make?
Shell/file operation Are inputs and service privileges constrained?

For a returning subroutine, use the documented Gosub reference and its return semantics. Do not promise that substituting Gosub for Macro preserves every scope or special variable automatically.

For a simple Macro whose only job is to set a value and then return, the call shape can be rewritten with explicit Gosub arguments and Return():


; Old call site
same => n,Macro(set-route-caller,${CALLERID(num)})

; New call site
same => n,Gosub(sub-route-caller,s,1(${CALLERID(num)}))

[sub-route-caller]
exten => s,1,Set(ROUTE_CALLER=${ARG1})
 same => n,Return()

Treat this only as a simple argument-and-return pattern. Before replacing a real Macro, find uses of MacroExit, Goto, MACRO_OFFSET, MACRO_EXTEN, MACRO_CONTEXT and MACRO_PRIORITY, and map each caller's expected continuation explicitly. Gosub returns to its saved priority through Return(); an old jump or macro exit may not have meant that. Asterisk's Gosub guide describes arguments and return behaviour; the Asterisk 21 change notes describe removal impacts in Dial, Queue, voicemail and other modules.

Preserve routing intent

Write the expected destination and denied cases before simplifying patterns or includes. Check invalid-input and timeout paths as well as successful calls. A broader pattern can make a route appear repaired while granting unintended calling access.

Use contexts and patterns and variables and Gosub for the current examples. Keep prompts, language and business-hours decisions with the route that uses them.

Make changes reviewable and reversible

Group one route or feature change at a time and retain its prior source. Compare the loaded target dialplan with the intended source after application. Check module/startup errors rather than treating a successful file write as a successful migration.

For a managed PBX, use the supported configuration owner and extension points. A manual edit to generated output can disappear on the next apply operation even if it worked temporarily.

Reader checks

When exercising the target, check each entry context, successful destination, denied destination, timeout, invalid input and transfer/return path. Include application failure and hangup during an external request. State the tested versions and leave unexercised paths labelled accordingly.

Return to Asterisk documentation.