How to execute a custom dial plan fragment before sending a call to a trunk (for playing an announcement, etc.)

In a FreePBX forum post, Alex Edwards wanted to accomplish the following:

"I'd like to warn my FreePBX users when they're dialling an expensive international fixed-line, or worse, international mobile. (This is from the UK).

"I've put a long list of international codes as a route, with a route password - which is a great start.

"However, ideally I'd like to play an explanatory message too - possibly a Misc Destination / Application / Announcement? ....."

In other words, what he wanted to do was execute a bit of custom code (a dial plan fragment) prior to sending the call to a trunk. One way to do this is to use a CUSTOM trunk. Here's how Alex did it (slightly revised for clarity):

First, you need to add your custom dial plan fragment to extensions_custom.conf (if you have the Dialplan Injection module installed, you could also put this code fragment there, but for the moment we'll assume you're using extensions_custom.conf). Alex added the following to the top of that file (slightly modified for clarity):

Note that the final line gives the actual destination of the call, and will have to be tweaked for your own particular situation. Also, the Wait statements are probably optional, or could be made longer than one second if desired. The recording specified in the fourth line (International-Mobile-Warning) is a custom recording that tells the caller that the call will cost around £1 a minute, so look for a cheaper alternative! You will need to create the recording you want to use, if none of the standard Asterisk recordings will work in your situation.

Second, create a new CUSTOM trunk. For the Custom Dial String, use the following:
Local/$OUTNUM$@mobile-warn-custom

If you used something other than "mobile-warn-custom" to identify your custom dial plan then be sure to use that here as well. While you are creating your CUSTOM trunk, mouse over the words "Custom Dial String" and it will show you some suggested formats that might give you an idea of how the "Dial" argument in the final line of your custom dial plan should read (in case you are having trouble figuring that out).

Finally, create your route, and make sure it has higher priority than all the other routes that might otherwise handle calls to the same numbers. Don't forget to click the orange bar when finished.

An alternate method was suggested by user stonet. In /etc/asterisk/extensions.conf there is a context called macro-dialout-trunk-predial-hook which, according to comments in extensions.conf, is "intentially left blank so it may be safely overwritten for any custom requirements that an installation may have" and that any such "customizations to this dialplan should be made in extensions_custom.conf." What that means is you can create a [macro-dialout-trunk-predial-hook] context in /etc/asterisk/extensions_custom.conf and it will override the (intentionally blank) context in extensions.conf. The macro is called whenever a call goes out over any trunk, therefore if you can determine which trunk has been called you can execute your custome dial plan fragment.

That's the approach that stonet took. He wanted to play the message when calls went out on any of three trunks, so rather than giving the trunks names he gave them numbers. The SIP trunks on which he wanted to play the message he named 7000, 7001, 7002 and 7003, and then he used this code, which should be placed in /etc/asterisk/extensions_custom.conf:

[macro-dialout-trunk-predial-hook]
exten => s,1,NoOp(Trunk ${OUT_${DIAL_TRUNK}} selected)
exten => s,n,Gotoif($["${OUT_${DIAL_TRUNK}:0:7}" != "SIP/700"]?skip)
exten => s,n,NoOp(Playing Progress Announcement)
exten => s,n,Playback(pls-hold-while-try,noanswer)
exten => s,n(skip),MacroExit()

Note that the full trunk name is printed on the CLI by the first line, so you can see what needs to be matched in the Gotoif statement. It usually consists of the technology type, a forward slash, and the trunk name, although that can vary (especially in the case of a Custom trunk). When this method is used, you don't need to create any custom trunks, and you have more flexibility in the variables you can use for conditional jumps, but you are responsible for making sure that you correctly construct your conditional Gotos so they do what you need to do. This also assumes that the [macro-dialout-trunk-predial-hook] context will not be used by any other part of FreePBX. If you use this method, make sure that the last statement in the macro is MacroExit(), and it would probably be a good idea to read some documentation on Asterisk macros before you begin.

Keep in mind that the Gotoif statement can contain multiple conditions. For example, let's say that the two SIP trunks that we wanted to play an announcement on were named "voipcompany" and "foobar" - the Gotoif line could then look like this:

exten => s,n,GotoIf($[$["${OUT_${DIAL_TRUNK}" != "SIP/voipcompany"] & $["${OUT_${DIAL_TRUNK}}" != "SIP/foobar"]]?skip)

You can the use & (and), | (or), or ! (logical unary complement) characters. The first two are placed between expressions, while the ! is placed in front of an expression (with NO space between the ! and the expression) to give the opposite result of the expression (an expression that evaluates to true becomes false, and vise-versa). Usually it's clearer to just use != in an expression, however. See the page on Asterisk Expressions for more information.

You may want to check the forum thread to see if any additional comments have been posted that may clarify these procedures. The thing we want to illustrate here is that when you need to add a custom dial plan fragment prior to sending a call to an actual trunk, one way to do it is to use a CUSTOM trunk, send that to your custom dial plan, and then make the last line of your custom dial plan send the call to an actual trunk or other destination. The other way to do it is to use the [macro-dialout-trunk-predial-hook] macro call that's already built into FreePBX.

For those who may be trying to duplicate what Alex did, here is the list of numbers that Alex put into the route definition (to play a warning for high cost mobile calls). Note that this may or may not include all caller-pays mobile prefixes, and that the '9|xxxx.' variants at the bottom of the list are only required if you use 9 for an outside line: