asterisk CURL function

asterisk CURL function

Asterisk’s ability to retrieve and store data to realtime backends is most commonly associated with relational databases. One of the lesser-known realtime backends available in Asterisk is cURL. Using this realtime backend makes Asterisk use HTTP GET and POST requests in order to retrieve data from and store data to an HTTP server.

It’s very common that we want to use external services from our Asterisk Dialplan, and many times those external services are accessible via HTTP (such as a REST HTTP API).

In this article we are going to see how we can use cURL to query an external HTTP service and read a response in JSON format and take action on the values returned to control the call flow in our dialplan.

 

Description

Syntax

CURL(url,post-data)
Arguments
  • url
  • post-data – If specified, an HTTP POST will be performed with the content of post-data, instead of an HTTP GET (default).

Return value

Returns the resulting string/page.

Dependencies and Installation

Asterisk’s realtime cURL backend is provided by the module res_config_curl.so. In order to build this module, you will first need to have the libcurl development library installed on your machine. If you wish to install the library from source, you can find it here. If you would rather use your Linux distribution’s package management, then you should be able to download the development libraries that way instead.

If you use a distribution with aptitude-based packaging (Debian, Ubuntu, Mint, et al), then use this command to install:

apt-get install libcurl4-openssl-dev

 

If you use a distribution with yum-based packaging (CentOS, RHEL, Fedora, et al), then use this command to install:

yum -y install libcurl-devel

Both of the above commands assume that you have permission to install the packages. You may need to prepend the command with “sudo” in order to be able to install the packages.

Once you have the libcurl development libraries installed, you need to run Asterisk’s configure script in order for Asterisk to detect the installed library:

$ ./configure

In addition to the libcurl development library, res_config_curl.so relies on two other modules within Asterisk: res_curl.so and func_curl.sores_curl.so initializes the cURL library within Asterisk. func_curl.so provides dialplan functions ( CURL and CURLOPT) that are used directly by res_config_curl.so.

After running the configure script, run

$ make menuselect

to select which modules to build. Ensure that you can select res_curl and res_config_curl from the “Resource Modules” menu and that you can select func_curl from the “Dialplan Functions” menu. Once you have ensured that these have been selected, save your changes (‘x’ key if using curses-based menuselect or select the “Save & Exit” option if using newt-based or gtk-based menuselect). After, you just need to run

$ make && make install

in order to build Asterisk and install it on the system. You may need to prepend “sudo” to the “make install” command if there are permission problems when attempting to install. Once you have installed Asterisk, you can test that res_config_curl.so has been installed properly by starting Asterisk:

Configuration

Make sure curl is on your system (on “Ubuntu 8.04 server” users can run apt-get install libcurl4-dev)
Then in the asterisk sources re-run the ./configure script and check if it detects curl.
Run make menuselect and look under the Dialplan Functions for the func_curl entry, making sure there are no XXX’s there before compiling and installing asterisk.

Once Asterisk has started, type the following on the CLI:

*CLI> module show like res_config_curl
Module                         Description                              Use Count  Status
res_config_curl.so             Realtime Curl configuration              0          Running
1 modules loaded

The output when you run the command should look like what is shown above. If it does, then Asterisk is capable of using cURL for realtime.

Example

exten => s,1,Set(foo=${CURL(https://nicedial.com/api/integration.xyz?x=5&y=4)})

Example (POST-Method):

exten => _X.,2,curl(https://www.nicedial.com/may_be_a_dir/file_to_call.php,postdata_var1=1&postdata_var2=something)
exten => _X.,3,Wait(5)
exten => _X.,4,NoOp(CURL-RESPONSE: ${CURL})

Example (GET-Method):

exten => _X.,2,curl(https://www.nicedial.com/may_be_a_dir/file_to_call.php?postdata_var1=1&postdata_var2=something)
exten => _X.,3,Wait(5)
exten => _X.,4,NoOp(CURL-RESPONSE: ${CURL})

Example to get the content of a text file

exten => _X.,1,Set(CURL_RESULT=${CURL(http://domain.com/test.txt)})