EVAL_SUB(priority[,context,extensions])
The EVAL_SUB function executes up a dialplanThe core call-routing configuration of Asterisk, written mostly in extensions.conf as contexts, extensions, and priorities that decide how every call is handled. Full definition → location by contextA named section of the dialplan that groups extensions. Calls enter a specific context and can only reach extensions visible from it, making contexts the basic unit of call routing and security.,extensionA dialplan entry that matches a dialed number or pattern within a context and triggers a sequence of prioritized steps.,priority, with optional arguments and returns the contents of the Return statement. The arguments to EVAL_SUB are exactly like they are with Gosub.
This function is complementary to EVAL_EXTEN. However, it is more powerful, since it allows executing arbitrary dialplanThe core call-routing configuration of Asterisk, written mostly in extensions.conf as contexts, extensions, and priorities that decide how every call is handled. Full definition → and capturing some outcome as a dialplan function's return value, allowing it to be used in a variety of scenarios that do not allow executing dialplan directly but allow variables and functions to be used, and where using EVAL_EXTEN would be difficult or impossible.
Consequently, this function also allows you to implement your own arbitrary functions in dialplan, which can then be wrapped using the Asterisk function interface using EVAL_SUB.
While this function is primarily intended to be used for executing Gosub routines that are quick and do not interact with the channelA single call leg passing through Asterisk. Channels represent connections to endpoints and are what dialplan applications act on., it is safe to execute arbitrary, even blocking, dialplan in the called subroutine. That said, this kind of usage is not recommended.
This function will always return, even if the channel is hung up.
[islocal]
exten => _X!,1,ExecIf($[${LEN(${EXTEN})}<10]?Return(1))
same => n,Set(LOCAL(npanxx)=${EXTEN:-10:6})
same => n,ReturnIf(${EXISTS(${DB(localcall/${npanxx})})}?${DB(localcall/${npanxx})})
same => n,Set(LOCAL(islocal)=${SHELL(curl "https://example.com/islocal?npanxx=${EXTEN:-10:6}")})
same => n,Set(LOCAL(islocal)=${FILTER(A-Z,${islocal})})
same => n,Set(DB(localcall/${npanxx})=${islocal})
same => n,Return(${islocal})
[outgoing]
exten => _1NXXNXXXXXX,1,Set(CDR(toll)=${IF($["${EVAL_SUB(islocal,${EXTEN},1)}"="Y"]?0:1)})
same => n,Dial(DAHDI/1/${EXTEN})
same => n,Hangup()
This example illustrates an example of logic that would be difficult to capture in a way that a single call to EVAL_EXTEN would return the same result. For one, conditionals are involved, and due to the way Asterisk parses dialplan, all functions in an application call are evaluated all the time, which may be undesirable if they cause side effects (e.g. making a cURL request) that should only happen in certain circumstances.
The above example, of course, does not require the use of this function, as it could have been invoked using the Gosub application directly. However, if constrained to just using variables or functions, EVAL_SUB would be required.
contextextensionspriorityrequired
User Notes
Know a tip or gotcha for this topic? Share it below and help others.
Contribute a note
Share a tip, gotcha, or practical example. Keep it under 2000 characters. No questions (use the Asterisk community forums for support). Wrap code in backticks.