The Hitchhiker's Guide to Asterisk | ||
---|---|---|
<<< Previous | Creating Dialplans | Next >>> |
Macros are used to reduce the amount of redundent code in the dialplan. This works by allowing you to pass arguments to the macro which then perform a certain set of actions which you specify. Once you have defined your macro and the actions you wish it to perform, you can call it at any time within your dialplan with a single line.
Macros are identified in the dialplan by starting a context name with "macro-". The 's' extension is used within macros since we want the actions to be performed automatically when we call them. Information is passed to the Macro as arguments such as ${ARGn} where 'n' is the argument number.
As an example lets show how you can use a macro to limit the number of lines which are required to setup a new extension.
[macro-stdexten] exten => s,1,Dial(${ARG1},20) exten => s,2,Voicemail(u${MACRO_EXTEN} exten => s,3,Hangup exten => s,102,Voicemail(b${MACRO_EXTEN}) exten => s,103,Hangup |
Our simple macro above Dials an extension as supplied by the argument ${ARG1} which is defined when we call the macro. If after 20 seconds the line is not picked up, we go to our second priority which calls Voicemail using the extension number that called the macro (as defined by ${MACRO_EXTEN}). Once voicemail has completed, the call is Hungup. If the line was busy when the Dial application was executed, the macro would jump n+101 priorities to priority 102. The Voicemail application would then be executed, playing the busy message for the extension which called the macro as defined by ${MACRO_EXTEN}.
The macro is called using the 'Macro' application. The format for calling a macro is Macro(<macro_name>,<ARG1>,<ARG2$gt;,<ARGn>). As we can see in our example, we are calling the 'stdexten' macro with the argument 'SIP/1000'. SIP/1000 is then used in the stdexten macro where you see ${ARG1}. The ${MACRO_EXTEN} is a predefined local variable which passes the extension number calling the macro. In our example above this would be extension 1000 as defined in the [default] context.
Some other local variables you can use in macros include:
${MACRO_CONTEXT} - The context of the extension which calls the macro |
${MACRO_PRIORITY} - The priority which the macro was called from |
${MACRO_OFFSET} - When complete, return to priority n + ${MACRO_OFFSET} |
Asterisk is able to jump to different priorities based on the status returned from Dial(). Using the ${DIALSTATUS} local variable we can perform different actions based on the returned status message. Valid status messages include NOANSWER, BUSY, CHANISUNAVAIL, CONGESTION and ANSWER. We can modify our stdexten macro above to demonstrate how this works.
[macro-stdexten] exten => s,1,Dial(${ARG1},20) exten => s,2,Goto(s-${DIALSTATUS},1) exten => s-NOANSWER,1,Voicemail(u${MACRO_EXTEN}) exten => s-NOANSWER,2,Goto(default,s,1) exten => s-BUSY,1,Voicemail(b${MACRO_EXTEN}) exten => s-BUSY,2,Goto(default,s,1) exten => s-.,1,Goto(s-NOANSWER,1) exten => a,1,VoicemailMain(${MACRO_EXTEN}) |
We can assume that we are going to call the macro using the same example as above (exten => 1000,1,Macro(stdexten,SIP/1000)). Our first line of this macro example will Dial() SIP/1000 for 20 seconds. After the Dial() command has completed the status of the call is saved in the variable ${DIALSTATUS}.
On the second line we use a Goto() statement to jump to the associated extension. The format for the extension name is "s-${DIALSTATUS}" where ${DIALSTATUS} is equal to NOANSWER, BUSY, CHANISUNAVAIL, CONGESTION or ANSWER. If our Dial() command rings for 20 seconds without an answer, the ${DIALSTATUS} variable will contain NOANSWER. The s-NOANSWER extension will then execute all available priorities in order starting with the Voicemail() command (line 3) and play the unavailable message. The second priority of the s-NOANSWER extension will execute a Goto() statement if the user presses "#" before Voicemail hangs up the line. Similarily the busy voicemail message will be played if a ${DIALSTATUS} of BUSY is returned.
The second last line of our macro is a catch all statement. The period (.) after the s- means to match anything that is returned. If neither NOANSWER or BUSY are returned, then we will assume a NOANSWER and execute the Goto() statement. This will send us to the s-NOANSWER extension, which as explained earlier, will execute Voicemail and play the busy message.
Our last line is another new extension type. The 'a' extension will execute if the user presses the asterisk (*) key while the unavailable or busy message is being played. When the asterisk key is pressed, it will execute the VoicemailMain() application and send it to the ${MACRO_EXTEN}. What this essentially does is send the user to their mailbox and prompts them for a password (if configured to require a password). This allows the user to check their voicemail without requiring them to login to a separate extension.
<<< Previous | Home | Next >>> |
Variables | Up | Call Flow |