Asterisk Functions

Asterisk functions are used in Asterisk‘s dialplan. Unlike dialplan applications, they cannot be used directly. Instead they return a value that could be used by the dialplan logic.

Functions are new in 1.2. Some functions may be read from, others may be written to. Please note that several of the builtin variables (including ENV and LEN) have been converted to functions for 1.2.

Colors:

• Green – Added/functional version
• Orange – Deprecated version
• Red – Removed/no longer in present version

Function names by practice are all capitalized letters. The names ARE CASE SENSITIVE!

Function List

• AES_DECRYPT: Decrypt a string encoded in base64 with AES given a 16 character key. (1.6.2)
• AES_ENCRYPT: Encrypt a string with AES given a 16 character key. (1.6.2)
• AGC: Set Automatic Gain Control for a channel (AGC). (1.4)
• AGENT: Gets information about an Agent. (1.2)
• ARRAY: Allows setting multiple variables at once. (1.4)
• AST_CONFIG: Retrieve a variable from a configuration file. (1.6.0)
• AUDIOHOOK_INHERIT: Set whether an audiohook may be inherited to another channel (1.4.30,1.6.0)
• BASE64_DECODE: Decode a base64 string. (1.4)
• BASE64_ENCODE: Encode a string into base64. (1.4)
• BLACKLIST: Check if the callerid is on the blacklist. (1.6.0)
• CALLERID: Get or set Caller*ID. (1.2)
• CALLERPRES: Gets or sets Caller*ID presentation on the channel. (1.6.0)
• CDR: Get or set a CDR variable. (1.2)
• CHANNEL: Gets/sets various pieces of information about the channel. (1.2)
• CHANNELS: Gets the list of channels, optionally filtering by a regular expression. (1.6.1)
• CHECKSIPDOMAIN: Checks if domain is a local domain. (1.2)
• CHECK_MD5: Checks an MD5 digest. Deprecated in 1.4, since it can be done with an expression in combination with MD5. (1.4, 1.6)
• CLEARHASH: (1.6)
• CONFBRIDGE: Get or set ConfBridge parameters (1.6.2)
• CONFBRIDGE_INFO: Get or set various ConfBridge member counts (1.6.2)
• CONNECTEDLINE: Gets or sets Connected Line data on the channel. (1.6.3)
• CSV_QUOTE: Quotes a given string for use in a CSV file, escaping embedded quotes as necessary (1.4)
• CURL: Retrieves a URL. (1.2)
• CURLOPT: Set options for use with the CURL() function (1.6.2)
• CUT: String parsing, based upon a delimiter. (1.2)
• DB: Get or set a value in the AstDB. (1.2)
• Asterisk func DB_DELETE: Delete a value from the AstDB; replaces the Asterisk cmd DBdel application. (1.4)
• DB_EXISTS: Check to see if a key exists in the Asterisk database. (1.2)
• DEC: Decrements the value of a variable, while returning the updated value to the dialplan (1.6.3)
• DENOISE: Enable noise reduction (primarily intended for analog channels). (1.6)
• DEVICE_STATE: Allows retrieving any device state in the dialplan, as well as creating custom device states that are controllable from the dialplan. (1.6)
• DIALGROUP: Poor man’s calling queue. (1.6.0)
• DIALPLAN_EXISTS:Check for the existence of a dialplan target (1.6.0)
• DUNDILOOKUP: Do a DUNDi lookup of a phone number. (1.2)
• DUNDIQUERY: Initiate a DUNDi query. (1.6.0)
• DUNDIRESULT: Retrieve results from a DUNDIQUERY (1.6.0)
• ENUMLOOKUP: General or specific querying of NAPTR records or counts of NAPTR types for ENUM or ENUM-like DNS pointers. (1.2)
• ENUMQUERY: Initiate a ENUM query. (1.6.0)
• ENUMRESULT: Retrieve results from a ENUMQUERY (1.6.0)
• ENV: Get or set an environmental variable. (1.2)
• EVAL: Evaluate stored variables. (1.2)
• EXCEPTION: Retrieve the details of the current dialplan exception. (1.6.0)
• EXISTS: Existence Test: Returns 1 if exists, 0 otherwise. (1.2)
• EXTENSION_STATE: Allows retrieving the state of any extension. (1.6.0)
• FIELDQTY: Get the number of fields, based upon a delimiter. (1.2)
• FILE: Read or write text file. (1.6.0)
• FILTER: Filter the string to include only the allowed characters (.1.4)
• GROUP: Can also return the name of the group set on a channel when used in a read environment (1.2)
• GROUP_COUNT: Counts the number of channels in the specified group (1.2)
• GROUP_LIST: Returns a space separated list of all of the groups set on a channel (1.2)
• GROUP_MATCH_COUNT: Counts the number of channels in the groups matching the specified pattern (1.2)
• HASH: Implementation of a dialplan associative array (1.6.0)
• HASHKEYS: Retrieve the keys of the HASH() function. (1.6.0)
• HINT: Allows retrieving hint information (1.6.0)
• IAXPEER: Gets IAX peer information (1.2)
• IAXVAR: Pass variables over IAX channels, somewhat similar to SIPADDHEADER() and SIP_HEADER(). (1.2)
• IF: Conditional: Returns the data following ‘?’ if true else the data following ‘:’ (1.2)
• IFMODULE: Checks if an Asterisk module is loaded in memory. (1.6.0)
• IFTIME: Temporal Conditional: Returns the data following ‘?’ if true else the data following ‘:’ (1.2)
• IMPORT: Retrieve the value of a variable from another channel. (1.6.0)
• INC: Increments the value of a variable, while returning the updated value to the dialplan (1.6.3)
• ISNULL: NULL Test: Returns 1 if NULL or 0 otherwise (1.2)
• JACK_HOOK: Interface to JACK audio for audio manipulation (1.6)
• KEYPADHASH: Hash the letters in the string into the equivalent keypad numbers. (1.4)
• LANGUAGE: Get or set the channel’s language. Deprecated in favor of Asterisk func channel. (1.2, 1.4, 1.6.0)
• LEN: Get the length of an arbitrary string. (1.2)
• LOCAL: Manage variables local to the gosub stack frame.
• LOCK: Attempt to obtain a named mutex. (1.6)
• MATH: Performs Mathematical Functions. (1.2)
• MD5: Computes an MD5 digest. (1.2)
• MUSICCLASS: Get or set the MusicOnHold class. (1.2)
• ODBC: Generic database access/queries using ODBC. (1.4)
• QUEUEAGENTCOUNT: Gets the number of members currently listening on a queue. Deprecated in favor of QUEUE_MEMBER_COUNT. (1.4, 1.6 )
• QUEUE_MEMBER_COUNT: Count number of members answering a queue. (1.4)
• QUEUE_MEMBER_LIST: Returns a list of interfaces on a queue. (1.4)
• QUEUE_WAITING_COUNT: Returns the number of callers currently waiting in a queue. (1.4)
• QUOTE: Quotes a given string, escaping embedded quotes as necessary (1.4)
• RAND: Choose a random number in a range. (1.4)
• REALTIME: This function will read or write values from/to a RealTime repository. (1.4)
• REGEX: Regular Expression: Returns 1 if data matches regular expression. (1.2)
• REPLACE: Replace a set of characters in a given string with another character.
• SET: SET assigns a value to a channel variable. (1.2)
• SHA1: Computes a SHA1 digest. (1.4)
• SHARED: Implements shared channel variables (new in 1.6, backport for 1.4). (1.6)
• SHELL: Returns output of a shell command. (1.6)
• SIPCHANINFO: Gets the specified SIP parameter from the current channel. (1.2)
• SIPPEER: Gets SIP peer information. (1.2)
• Asterisk cmd SipAddHeader: Typically used to set Alert-Info information, e.g. ring tone .wav files. (1.2)
• SIP_HEADER: Get the specified SIP header. (1.2)
• SORT: Sorts a list of keys and values into a list of keys. (1.2)
• SQL_ESC: Escapes a value for inclusion in an SQL call (prevent injection attacks). (1.4)
• STAT: Does a check on the specified file. (1.4)
• STRFTIME: Formats an epoch into an arbitrary datetime string. (1.2)
• STRPTIME: Returns the epoch of the arbitrary date/time string structured as described in the format. (1.4)
• STRREPLACE: Replace instances of a substring within a string with another string. (10.0)
• SYSINFO: Allows retrieval of system information. (1.6)
• TIMEOUT: Gets or sets timeouts on the channel. (1.2)
• TOUPPER: Converts a string to uppercase (1.6)
• TOLOWER: Converts a string to lowercase (1.6)
• TRYLOCK: Attempt to obtain a named mutex. (1.6)
• TXTCIDNAME: TXTCIDNAME looks up a caller name via DNS (1.2)
• UNLOCK: Unlocks a named mutex. (1.6)
• URIDECODE: Decodes an URI-encoded string. (1.2)
• URIENCODE: Encodes a string to URI-safe encoding. (1.2)
• VOLUME: Set the TX or RX volume of a channel (1.6)

Using Functions in Asterisk Dialplans

Example usage of the function CUT:

exten => s,1,Set(foo=${CUT(bar,,2)})

The above example sets the variable foo to the function CUT whose first parameter is ‘bar’, second parameter is empty and third parameter is ‘2’.

A function is often used to determain which “part of a variable” to set. For instance, the use of the function CALLERID:

exten => s,n,Set(CALLERID(name)=Foo Fighters)
exten => s,n,Set(CALLERID(number)=700)

Functions Reference Through the CLI

The list of available functions depends on the modules installed and loaded on the current system. To get the list of functions from the Asterisk CLI use the command show functions. This gives a list of all functions.

To get the syntax of a specific function, use the command show function FUNCNAME. This gives a longer description of the function. It is often handy to use tab completion that way to identify a function name.

See Also

Asterisk 1v2 Dial plan Functions. REMOVE, right?
Asterisk cmd Backticks

Asterisk | Applications | Functions | Variables | Expressions | Asterisk FAQ