Functions

Asterisk 1v2 Dial plan Functions


The following text has been cut and pasted from the command line. Text in red has been added to clarify things a little! Where is more full explanation is given, it's probably cut and pasted from "Show function FUNCTION". Where a function can be used to set a value, this is accomplished by embedding the function to be set within the SET function - e.g. to set the absolute timeout to sixty seconds, use "Set(TIMEOUT(absolute)=60)".

Just to make things more complicated... You can refer to these functions from the old style dial plan by treating them as variables (i.e. using "${}" around them). This can get a little hard to follow - this is a line from a dial plan I'm working on (taken from a function which checks a username ${ARG1} against an input password ${ARG2}):

; Firstly, sanity check the data. Rather than check ISNULL(${ARG1})
; and GroupID, we can just use the function DB_EXISTS which won't barf if
; passed dodgy data.
exten => s,n,GotoIf($[${DB_EXISTS(org/${GroupID}/${ARG1}/secret)} = 0]?nomatch,1)
; And now check that the value for that family/key matches the one passed to us.
; Because we haven't sanity checked ARG2, we'll just use the 'foo' workaround instead.
exten => s,n,GotoIf($[${DB(org/${GroupID}/${ARG1}/secret)}foo != ${ARG2}foo]?nomatch,1)



  • QUEUEAGENTCOUNT(<queuename>) - Count number of members answering a queue. This function has been renamed in trunk as QUEUE_MEMBER_COUNT, to increase clarity of its function.

  • SORT(key1:val1[...][,keyN:valN]) - Sorts a list of key/vals into a list of keys, based upon the vals. Takes a comma-separated list of keys and values, each separated by a colon, and returns a comma-separated list of the keys, sorted by their values. Values will be evaluated as floating-point numbers.

  • CUT(<varname>,<char-delim>,<range-spec>) - Slices and dices strings, based upon a named delimiter. "varname" - variable you want cut, "char-delim" - defaults to '-', "range-spec" - number of the field you want (1-based offset) may also be specified as a range (with -) or group of ranges and fields (with &)

  • CALLERID(datatype) - Gets or sets Caller*ID data on the channel. The allowable datatypes are "all", "name", "num", "ANI", "DNID", "RDNIS".

  • MUSICCLASS() - Read or Set the MusicOnHold class

  • LANGUAGE() - Gets or sets the channel's language. Gets or sets the channel language. This information is used for the syntax in generation of numbers, and to choose a natural language file when available. For example, if language is set to 'fr' and the file 'demo-congrats' is requested to be played, if the file 'fr/demo-congrats' exists, then it will play that file, and if not will play the normal 'demo-congrats'. For some language codes, changing the language also changes the syntax of some Asterisk functions, like SayNumber.

  • TIMEOUT(timeouttype) - Gets or sets timeouts on the channel. Values for "timeouttype" are as follows:

    • absolute: The absolute maximum amount of time permitted for a call. A setting of 0 disables the timeout.
    • digit: The maximum amount of time permitted between digits when the user is typing in an extension. When this timeout expires, after the user has started to type in an extension, the extension will be considered complete, and will be interpreted. Note that if an extension typed in is valid, it will not have to timeout to be tested, so typically at the expiry of this timeout, the extension will be considered invalid (and thus control would be passed to the 'i' extension, or if it doesn't exist the call would be terminated). The default timeout is 5 seconds.
    • response: The maximum amount of time permitted after falling through a series of priorities for a channel in which the user may begin typing an extension. If the user does not type an extension in this amount of time, control will pass to the 't' extension if it exists, and if not the call would be terminated. The default timeout is 10 seconds.

  • DB_EXISTS(<family>/<key>) - Check to see if a key exists in the Asterisk database. This function will check to see if a key exists in the Asterisk database. If it exists, the function will return "1". If not, it will return "0". Checking for existence of a database key will also set the variable DB_RESULT to the key's value if it exists. Note that this can also be used for validating data as even if the family/key youre checking is complete garbage, this function will only return '0' and not barf - e.g. DB_EXISTS(org///this is garbage data and/can't/possibly////////be a real familiy/key combination.) == 0.

  • DB(<family>/<key>) - Read or Write from/to the Asterisk database. This function will read or write a value from/to the Asterisk database. DB(...) will read a value from the database, while DB(...)=value will write a value to the database. On a read, this function returns the value from the datase, or NULL if it does not exist. On a write, this function will always return NULL. Reading a database value will also set the variable DB_RESULT.

  • ENV(<envname>) - Gets or sets the environment variable specified

  • IFTIME(<timespec>?[<true>][:<false>]) - Temporal Conditional: Returns the data following '?' if true else the data following ':'

  • IF(<expr>?[<true>][:<false>]) - Conditional: Returns the data following '?' if true else the data following ':'

  • EXISTS(<data>) - Existence Test: Returns 1 if exists, 0 otherwise.

  • SET(<varname>=[<value>]) - SET assigns a value to a channel variable. SET(<varname>=) sets the variable to NULL value.

  • ISNULL(<data>) - NULL Test: Returns 1 if NULL or 0 otherwise

  • CDR(<name>[|options]) - Gets or sets a CDR variable. Option 'r' searches the entire stack of CDRs on the channel.

  • EVAL(<variable>) - Evaluate stored variables. Using EVAL basically causes a string to be evaluated twice. When a variable or expression is in the dialplan, it will be evaluated at runtime. However, if the result of the evaluation is in fact a variable or expression, using EVAL will have it evaluated a second time. For example, if the variable ${MYVAR} contains "${OTHERVAR}", then the result of putting ${EVAL(${MYVAR})} in the dialplan will be the contents of the variable, OTHERVAR. Normally, by just putting ${MYVAR} in the dialplan, you would be left with "${OTHERVAR}".

  • STRFTIME([<epoch>][,[timezone][,format]) - Returns the current date/time in a specified format.

  • LEN(<string>) - Returns the length of the argument given

  • REGEX("<regular expression>" <data>) - Regular Expression: Returns 1 if data matches regular expression.

  • FIELDQTY(<varname>,<delim>) - Count the fields, with an arbitrary delimiter

  • GROUP_LIST() - Gets a list of the groups set on a channel.

  • GROUP([category]) - Gets or sets the channel group.

  • GROUP_MATCH_COUNT(groupmatch[@category]) - Counts the number of channels in the groups matching the specified pattern

  • GROUP_COUNT([groupname][@category]) - Counts the number of channels in the specified group. Calculates the group count for all groups that match the specified pattern. Uses standard regular expression matching (see regex(7)).

  • MATH(<number1><op><number 2>[,<type of result>]) - Performs Mathematical Functions. Perform calculation on number 1 to number 2. Valid ops are: +,-,/,*,%,<,>,>=,<=,== and behave as their C equivalents. <type_of_result> - wanted type of result: f, float - float(default), i, int - integer, h, hex - hex, c, char - char Example: Set(i=${MATH(123%16,int)}) - sets var i=11

  • CHECK_MD5(<digest>,<data>) - Checks an MD5 digest. Returns 1 on a match, 0 otherwise.

  • MD5(<data>) - Computes an MD5 digest.

  • SIPCHANINFO(item) - Gets the specified SIP parameter from the current channel. Valid items are:
    • peerip - The IP address of the peer.
    • recvip - The source IP address of the peer.
    • from - The URI from the From: header.
    • uri - The URI from the Contact: header.
    • useragent - The useragent.
    • peername - The name of the peer.

  • SIPPEER(<peername>[:item]) - Gets SIP peer information. Valid items are:
    • ip (default) - The IP address.
    • mailbox - The configured mailbox.
    • context - The configured context.
    • expire - The epoch time of the next expire.
    • dynamic - Is it dynamic? (yes/no).
    • callerid_name - The configured Caller ID name.
    • callerid_num - The configured Caller ID number.
    • codecs - The configured codecs.
    • status - Status (if qualify=yes).
    • regexten - Registration extension
    • limit - Call limit (incominglimit)
    • curcalls - Current amount of calls (Only available if incominglimit is set)
    • language - Default language for peer
    • useragent - Current user agent id for peer
    • codec[x] - Preferred codec index number 'x' (beginning with zero).

  • SIP_HEADER(<name>) - Gets or sets the specified SIP header

  • IAXPEER(<peername>[:item]) - Gets IAX peer information. Valid items are:
    • ip (default) - The IP address.
    • mailbox - The configured mailbox.
    • context - The configured context.
    • expire - The epoch time of the next expire.
    • dynamic - Is it dynamic? (yes/no).
    • callerid_name - The configured Caller ID name.
    • callerid_num - The configured Caller ID number.
    • codecs - The configured codecs.
    • codec[x] - Preferred codec index number 'x' (beginning with zero).

Asterisk 1v2 Dial plan Functions


The following text has been cut and pasted from the command line. Text in red has been added to clarify things a little! Where is more full explanation is given, it's probably cut and pasted from "Show function FUNCTION". Where a function can be used to set a value, this is accomplished by embedding the function to be set within the SET function - e.g. to set the absolute timeout to sixty seconds, use "Set(TIMEOUT(absolute)=60)".

Just to make things more complicated... You can refer to these functions from the old style dial plan by treating them as variables (i.e. using "${}" around them). This can get a little hard to follow - this is a line from a dial plan I'm working on (taken from a function which checks a username ${ARG1} against an input password ${ARG2}):

; Firstly, sanity check the data. Rather than check ISNULL(${ARG1})
; and GroupID, we can just use the function DB_EXISTS which won't barf if
; passed dodgy data.
exten => s,n,GotoIf($[${DB_EXISTS(org/${GroupID}/${ARG1}/secret)} = 0]?nomatch,1)
; And now check that the value for that family/key matches the one passed to us.
; Because we haven't sanity checked ARG2, we'll just use the 'foo' workaround instead.
exten => s,n,GotoIf($[${DB(org/${GroupID}/${ARG1}/secret)}foo != ${ARG2}foo]?nomatch,1)



  • QUEUEAGENTCOUNT(<queuename>) - Count number of members answering a queue. This function has been renamed in trunk as QUEUE_MEMBER_COUNT, to increase clarity of its function.

  • SORT(key1:val1[...][,keyN:valN]) - Sorts a list of key/vals into a list of keys, based upon the vals. Takes a comma-separated list of keys and values, each separated by a colon, and returns a comma-separated list of the keys, sorted by their values. Values will be evaluated as floating-point numbers.

  • CUT(<varname>,<char-delim>,<range-spec>) - Slices and dices strings, based upon a named delimiter. "varname" - variable you want cut, "char-delim" - defaults to '-', "range-spec" - number of the field you want (1-based offset) may also be specified as a range (with -) or group of ranges and fields (with &)

  • CALLERID(datatype) - Gets or sets Caller*ID data on the channel. The allowable datatypes are "all", "name", "num", "ANI", "DNID", "RDNIS".

  • MUSICCLASS() - Read or Set the MusicOnHold class

  • LANGUAGE() - Gets or sets the channel's language. Gets or sets the channel language. This information is used for the syntax in generation of numbers, and to choose a natural language file when available. For example, if language is set to 'fr' and the file 'demo-congrats' is requested to be played, if the file 'fr/demo-congrats' exists, then it will play that file, and if not will play the normal 'demo-congrats'. For some language codes, changing the language also changes the syntax of some Asterisk functions, like SayNumber.

  • TIMEOUT(timeouttype) - Gets or sets timeouts on the channel. Values for "timeouttype" are as follows:

    • absolute: The absolute maximum amount of time permitted for a call. A setting of 0 disables the timeout.
    • digit: The maximum amount of time permitted between digits when the user is typing in an extension. When this timeout expires, after the user has started to type in an extension, the extension will be considered complete, and will be interpreted. Note that if an extension typed in is valid, it will not have to timeout to be tested, so typically at the expiry of this timeout, the extension will be considered invalid (and thus control would be passed to the 'i' extension, or if it doesn't exist the call would be terminated). The default timeout is 5 seconds.
    • response: The maximum amount of time permitted after falling through a series of priorities for a channel in which the user may begin typing an extension. If the user does not type an extension in this amount of time, control will pass to the 't' extension if it exists, and if not the call would be terminated. The default timeout is 10 seconds.

  • DB_EXISTS(<family>/<key>) - Check to see if a key exists in the Asterisk database. This function will check to see if a key exists in the Asterisk database. If it exists, the function will return "1". If not, it will return "0". Checking for existence of a database key will also set the variable DB_RESULT to the key's value if it exists. Note that this can also be used for validating data as even if the family/key youre checking is complete garbage, this function will only return '0' and not barf - e.g. DB_EXISTS(org///this is garbage data and/can't/possibly////////be a real familiy/key combination.) == 0.

  • DB(<family>/<key>) - Read or Write from/to the Asterisk database. This function will read or write a value from/to the Asterisk database. DB(...) will read a value from the database, while DB(...)=value will write a value to the database. On a read, this function returns the value from the datase, or NULL if it does not exist. On a write, this function will always return NULL. Reading a database value will also set the variable DB_RESULT.

  • ENV(<envname>) - Gets or sets the environment variable specified

  • IFTIME(<timespec>?[<true>][:<false>]) - Temporal Conditional: Returns the data following '?' if true else the data following ':'

  • IF(<expr>?[<true>][:<false>]) - Conditional: Returns the data following '?' if true else the data following ':'

  • EXISTS(<data>) - Existence Test: Returns 1 if exists, 0 otherwise.

  • SET(<varname>=[<value>]) - SET assigns a value to a channel variable. SET(<varname>=) sets the variable to NULL value.

  • ISNULL(<data>) - NULL Test: Returns 1 if NULL or 0 otherwise

  • CDR(<name>[|options]) - Gets or sets a CDR variable. Option 'r' searches the entire stack of CDRs on the channel.

  • EVAL(<variable>) - Evaluate stored variables. Using EVAL basically causes a string to be evaluated twice. When a variable or expression is in the dialplan, it will be evaluated at runtime. However, if the result of the evaluation is in fact a variable or expression, using EVAL will have it evaluated a second time. For example, if the variable ${MYVAR} contains "${OTHERVAR}", then the result of putting ${EVAL(${MYVAR})} in the dialplan will be the contents of the variable, OTHERVAR. Normally, by just putting ${MYVAR} in the dialplan, you would be left with "${OTHERVAR}".

  • STRFTIME([<epoch>][,[timezone][,format]) - Returns the current date/time in a specified format.

  • LEN(<string>) - Returns the length of the argument given

  • REGEX("<regular expression>" <data>) - Regular Expression: Returns 1 if data matches regular expression.

  • FIELDQTY(<varname>,<delim>) - Count the fields, with an arbitrary delimiter

  • GROUP_LIST() - Gets a list of the groups set on a channel.

  • GROUP([category]) - Gets or sets the channel group.

  • GROUP_MATCH_COUNT(groupmatch[@category]) - Counts the number of channels in the groups matching the specified pattern

  • GROUP_COUNT([groupname][@category]) - Counts the number of channels in the specified group. Calculates the group count for all groups that match the specified pattern. Uses standard regular expression matching (see regex(7)).

  • MATH(<number1><op><number 2>[,<type of result>]) - Performs Mathematical Functions. Perform calculation on number 1 to number 2. Valid ops are: +,-,/,*,%,<,>,>=,<=,== and behave as their C equivalents. <type_of_result> - wanted type of result: f, float - float(default), i, int - integer, h, hex - hex, c, char - char Example: Set(i=${MATH(123%16,int)}) - sets var i=11

  • CHECK_MD5(<digest>,<data>) - Checks an MD5 digest. Returns 1 on a match, 0 otherwise.

  • MD5(<data>) - Computes an MD5 digest.

  • SIPCHANINFO(item) - Gets the specified SIP parameter from the current channel. Valid items are:
    • peerip - The IP address of the peer.
    • recvip - The source IP address of the peer.
    • from - The URI from the From: header.
    • uri - The URI from the Contact: header.
    • useragent - The useragent.
    • peername - The name of the peer.

  • SIPPEER(<peername>[:item]) - Gets SIP peer information. Valid items are:
    • ip (default) - The IP address.
    • mailbox - The configured mailbox.
    • context - The configured context.
    • expire - The epoch time of the next expire.
    • dynamic - Is it dynamic? (yes/no).
    • callerid_name - The configured Caller ID name.
    • callerid_num - The configured Caller ID number.
    • codecs - The configured codecs.
    • status - Status (if qualify=yes).
    • regexten - Registration extension
    • limit - Call limit (incominglimit)
    • curcalls - Current amount of calls (Only available if incominglimit is set)
    • language - Default language for peer
    • useragent - Current user agent id for peer
    • codec[x] - Preferred codec index number 'x' (beginning with zero).

  • SIP_HEADER(<name>) - Gets or sets the specified SIP header

  • IAXPEER(<peername>[:item]) - Gets IAX peer information. Valid items are:
    • ip (default) - The IP address.
    • mailbox - The configured mailbox.
    • context - The configured context.
    • expire - The epoch time of the next expire.
    • dynamic - Is it dynamic? (yes/no).
    • callerid_name - The configured Caller ID name.
    • callerid_num - The configured Caller ID number.
    • codecs - The configured codecs.
    • codec[x] - Preferred codec index number 'x' (beginning with zero).

Created by: bcnit, Last modification: Thu 14 of Jun, 2012 (19:15 UTC) by admin
Please update this page with new information, just login and click on the "Edit" or "Discussion" tab. Get a free login here: Register Thanks! - Find us on Google+