Asterisk dialplan variables and Gosub
Use a variable when a value needs a name, and a subroutine when a group of instructions needs a clear entry and return. Keep permission decisions visible rather than hiding them inside a general-purpose routine.
Source-reviewed, 20 October 2026. Prepared from the cited documentation. These examples have not been independently tested by Phone Guides. Scope: Asterisk 22 file-based dialplans and existing internal endpoint 6002.
Set and read a channel value
Set(PG_TARGET=6002) assigns a value on the executing channel. ${PG_TARGET} substitutes that value later. Variable names are case-sensitive, so use a consistent spelling. An assignment without an inheritance prefix should not be treated as an automatic value for every channel created later in the call.
The official variable overview distinguishes channel and global values. Before relying on propagation into another call leg, consult the channel-variable inheritance reference. A value on the calling channel and a value on the called channel are different observations.
Choose channel inheritance or subroutine scope
Inheritance prefixes apply when a new channel is created; they are not a Gosub() scope setting. In Asterisk 22, a normal variable stays on the current channel, _NAME passes to one child channel and loses its prefix there, while __NAME continues to descendant channels. Assigning the same name with another prefix removes its other forms, so avoid setting both as if they were independent values.
Use LOCAL() when a working value should exist only for one subroutine stack frame:
[pg-dial-one]
exten => s,1,Set(LOCAL(PG_ATTEMPT)=1)
same => n,NoOp(Attempt ${LOCAL(PG_ATTEMPT)} for ${ARG1})
same => n,Dial(PJSIP/${ARG1},20)
same => n,Return()
The branch-22 [LOCAL() reference](https://docs.asterisk.org/Asterisk_22_Documentation/API_Documentation/Dialplan_Functions/LOCAL/) says the value is lost on Return() or the earlier value is restored. Use this for temporary subroutine state; it does not pass the value to a child call channel. Use a deliberately prefixed channel variable only when the called leg needs the value, and check it on that leg before depending on it.
Call a small subroutine
This original example sets a fixed internal target, passes it to a routine and then ends the remaining route:
[pg-sub-example]
exten => 7100,1,Set(PG_TARGET=6002)
same => n,Gosub(pg-dial-one,s,1(${PG_TARGET}))
same => n,Hangup()
[pg-dial-one]
exten => s,1,Dial(PJSIP/${ARG1},20)
same => n,Return()
The subroutine begins at s, priority 1, in pg-dial-one. ARG1 holds the first argument within the subroutine call. Return() resumes the calling route when execution reaches it; an earlier hangup can end execution instead. Do not use Goto() where you require a saved return point.
The upstream Gosub guide and branch-22 application reference describe the call structure. The Return reference describes returning values when a routine needs a result.
Decide what the routine may accept
The example passes a literal account under administrator control. It does not accept a caller-supplied SIP URI, command, file path or unrestricted provider number. Before using external input as an application argument, define the accepted values and how invalid input is rejected.
Keep a routine's contract small: accepted arguments, channel on which it runs, values it changes and how it returns or hangs up. Document whether the caller should inspect an application status after return. For more elaborate routing, use the relevant application's documented result variable rather than interpreting the lack of an error message as success.
Check the loaded flow
Inspect both contexts with dialplan show, including any contexts that make the example reachable. After a file-based change, reload the dialplan and check errors. For your own execution checks, compare an available target, unavailable target and caller hangup. Confirm that the remaining caller instructions behave as intended in each case.
Do not recreate old Macro() examples on this branch. Asterisk 21's removal notes explain why older macro-dependent dialplans need review. A mechanical name replacement does not establish equivalent argument, scope or call-leg behaviour.
Read contexts and patterns first if lookup is unclear. Return to Asterisk documentation.