This application allows one to make a HTTP request and receive the response. Output can be plain text (headers optional) or a json object.
Setup & Configuration
In order to use mod_curl, you have to tell FreeSWITCH to compile in this module by editing modules.conf in /usr/src/freeswitch/trunk and uncomment:
Now go recompile FreeSWITCH.
Tell FreeSWITCH to actually use the curl module when running by adding the module to modules.conf.xml in /usr/local/freeswitch/conf/autoload_configs:
There is no separate config file for mod_curl.
Now load up FreeSWITCH!
mod_curl provides both an API call and a dialplan application for the following:
- curl - allows you to query arbitrary data from a web server
- curl_sendfile - allows you to transmit an arbitrary along with arbitrary additional data elements to a web server/REST and optionally receive a report back.
The syntax for the curl application is:
The curl application sets the variables curl_response_data and curl_response_code. curl_response_data can also be headers/body or json if requested.
The syntax for the curl_sendfile is either of the following two options:
or an example of using the channel variable method:
You do need to urlencode the _url, _filename, _extrapost channel variables or data="" parameters. If you call the application and provide the parameters on the data="" parameter, you must specify 'nopost' if you have no additional post elements to add and wish to specify further parameters on the data line. If you specify 'uuid' for the identifier, the application will automatically use the session's uuid as the value here.
CLI / API
The CLI uses the api interface. The syntax for the curl API call is:
From the commandline line issue:
This will return google's home page.
Will give you the headers followed by the body. And
Will give you the headers and body in a structured json stream.
Send POST and GET request.
Mix with headers or JSON.
The syntax for the curl_sendfile API call is:
<url> : This is the urlencoded URL of the REST that we are sending to. It should contain the whole GET parameters that are needed, such as a specific script or application URL that will handle the processing.
<filenameParamName=filepath> : This is a key=value pair. The key is the name you wish to label this POST form element as. The value is the full path to the file you wish to transmit bound to this POST form element.
nopost|postparam1=foo&postparam2=bar... : If you wish to specify an additional set of text POST form elements, you can provide a urlencoded key=value pair string that contains them. The key is the label of the POST form element, and the value is the actual value to bind. Thus to have a POST element named jabba with a value of nobotha, specify jabba=nobotha. Additional post elements must delimit the key=value pair with a &, as you would on a GET. If you wish to attach no additional post elements, simply specify nopost.
event|stream|both|none : This parameter will determine how and where to display the output from the REST. If you specify event, it will attach the output to a custom event labeled curl_sendfile::ack and fire it off. If you specify stream, it will output to the active stream which is whichever method was used to execute the call from. If you specify both, it will fire the custom event with the output, as well as display out to the active stream. If you specify none, then no output besides +HTTP_STATUS_CODE Ok or -HTTP_STATUS_CODE Err will be displayed.
identifier: This parameter is simply an arbitrary identifier for your own purposes. It will only apply to the custom curl_sendfile::ack event, and will display there in the event header as Command-Execution-Identifier . You can use this value to track the results of your commands for completion or error statuses.
If you wish to provide the identifier value, you *must* provide the prior two optional parameters or else your command will not be parsed correctly. If you specify a reporting method that provides an event, the custom event is named curl_sendfile::ack.
Note: it is good practice to check session:ready() before any long function calls such as a HTTP request so that your script stops running and releases its resources as soon as possible if the call is hung up.
This shows how to do a GET request:
This shows how to do a POST request:
This shows how to configure a timeout (in seconds):
You can also use the API interface:
In all the above examples, the submitted values must be URL encoded.
This shows one method of encoding parameters to form a GET/POST request: (or use CGILua's urlcode)
If you want to pass basic authentication credentials then do this: