If you need to talk to external API and parse JSON in Asterisk dialplan you will need res_json installed. Unfortunately it’s not bundled in Asterisk installation yet but here is how you can install res_json in Asterisk:
1) Download Asterisk source code, from https://www.asterisk.org/downloads. unzip and untar it, but don’t proceed to building it yet.
2) cd into the directory where you unzipped / untarred asterisk (the “asterisk root”), and get the res_json module (git must be installed on your machine): git clone git://github.com/drivefast/asterisk-res_json.git
3) we now need to move the source files to their appropriate places in the asterisk directory. A shell script was provided for that, so run ./asterisk-res_json/install.sh. After it runs, you need to manually edit addons/Makefile (sorry about that, but i really don’t have a better solution):
add res_json to the ALL_C_MODS macro, explicitely tell the linker to add the res_json symbols by adding a line like:
res_json.so: cJSON.o res_json.o
4) edit the file main/asterisk.exports.in and add the following line next to the similar ones:
LINKER_SYMBOL_PREFIXcJSON_*;
5) only now proceed with building asterisk (./configure --libdir=/usr/lib64; make menuconfig; make; make install). In the installation menu make sure you now have res_json in the list:
If you already built asterisk from source in this directory, you may need to run ./bootstrap.sh before running ./configure --libdir=/usr/lib64.
After installation finished you should see the res_json.so in /usr/lib64/asterisk/modules directory
6) start asterisk, login to its console, and try core show function JSONELEMENT. You should get an usage description.
You will get a bunch of apps and functions:
JSONELEMENT(doc,path) (r/o function) – gets the value of an element at a given path in a json document
jsonvariables(doc) (app) – reads a single level json document (dictionary) into dialplan variables
jsonadd(doc,path,elemtype,name,value) (app) – adds an element to the json document at the given path
jsonset(doc,path,newvalue) (app) – changes the value of an element in the json document
jsondelete(doc,path) (app) – deletes an element in the json document
JSONPRETTY(doc) (r/o function) – formats a json document for nice printing
JSONCOMPRESS(doc) (r/o function) – formats a json document for minimum footprint
None of the functions or the apps above would fail in such a way that would terminate the call. If any of them would need to return an abnormal result, they would do so by setting the value of a dialplan variable called JSONRESULT. These values are:
ASTJSON_OK (0) – the operation was successful
ASTJSON_UNDECIDED (1) – the operation was aborted mid-way and the results are not guaranteed
ASTJSON_ARG_NEEDED (2) – missing or invalid argument type
ASTJSON_PARSE_ERROR (3) – the string that was supposed to be a json document could not be parsed
ASTJSON_NOTFOUND (4) – the expected element could not be found at the given path
ASTJSON_INVALID_TYPE (5) – invalid element type for a jsonadd or jsonset operation
ASTJSON_ADD_FAILED (6) – the jsonadd operation failed
ASTJSON_SET_FAILED (7) – the jsonset operation failed
ASTJSON_DELETE_FAILED (8) – the jsondelete operation failed
IMPORTANT NOTE: all the functions and apps expect the name of a dialplan variable containing the json document, instead of the parseable string itself. for example, if the document is stored in the variable named json, we would call the function and execute an app using json as parameter:
exten => s,n,set(el=${JSONELEMENT(json,path/to/elem)})
exten => s,n,jsonset(json,path/to/elem,123)
and !!NOT!! the contents of the json variable, like in:
exten => s,n,set(el=${JSONELEMENT(${json},path/to/elem)}) ;; WRONG
exten => s,n,jsonset(${json},path/to/elem,123) ;; WRONG
the decision on this type of usage was made because, typically, the json representations contain a lot of commas. escaping the json content such that the arguments are parsed correctly becomes therefore pretty complicated.
Applications and Functions
JSONELEMENT(doc,path)
returns the value of an element at the given path. the element type is set in the dialplan variable JSONTYPE. depending on the type of the json variable, the values are:
True, False => returned values are 1 or 0 respectively; JSONTYPE is bool
NULL => returned value is an empty string; JSONTYPE is null
Number => returned value is a number; JSONTYPE is number
String => returned value is a number; JSONTYPE is string
Array => returned value is a json representation of an array; JSONTYPE is array
Object => returned value is a json representation of the underlying object; JSONTYPE is node
parameters:
doc: the name (not the contents!) of a variable that contains the json document
path: path to the element we’re looking for (like /path/to/element, or /path/to/element/3 to identify the element with index 3 in an array)
jsonvariables(doc)
reads a single level json document into dialplan variables with the same names. the json document is considered to be the representation of a dictionary, or key-value pairs, containing scalar values. for example {“one”:1,”two”:”deuce”,”three”:”III”} will set the values of the dialplan variables one, two and three to the values 1, deuce, and III respectively. depending on the type of each variable, their possible values are:
True, False => 1, 0
NULL => resulting asterisk variable will contain an empty string
number, string => the number or the string
array => the string !array! (array values cannot be returned into a single variable)
object => string, the json representation of the underlying object parameters
parameters:
doc: the name (not the contents!) of a variable that contains the json document
jsonadd(doc,path,elemtype,[name][,value])
adds an element to the json document at the given path. the value of the variable that contains the json document is updated to reflect the change. the element to be added has a type (elemtype), a name, and a value. elemtype can be one of bool, null, number, string, node or array. a bool “false” value is represented as either an empty string, 0, n, no, f or false (case insensitive); any other value for a bool elemtype is interpreted as true. for a null elemtype, the value paramenter is ignored. the value parameter is also ignored for an array elemtype: in this case, and an empty array is created. further on, you may append elements to this array using repeated calls to the jsonadd app. something like this:
exten => s,n,jsonadd(json,path/there,array,vec)
exten => s,n,jsonadd(json,path/there/vec,string,,abcd)
exten => s,n,jsonadd(json,path/there/vec,number,,1234)
exten => s,n,noop(${JSONELEMENT(json,path/there/vec/0)} & ${JSONELEMENT(json,path/there/vec/1)})
the last line will display abcd & 1234 to the console.
Parameters:
doc: the name (not the contents!) of a variable that contains the json document
path: path to the element to which we’re adding (like /path/to/element, or /path/to/element/3 to identify the element with index 3 in an array)
elemtype: element type, one of bool, null, number, string, node or array
name: the name of the element to be added (may be missing if adding elements to an array)
value: value to be set for the element we added
jsonset(doc,path,newvalue)
sets the value of the element in the json document at the given path. the value of the variable that contains the json document (doc) is updated to reflect the change. the element that changes the value preserves its name and its type, and must be a boolean, number, or string. the new value is converted to the type of the existing document. that means, if you would try to set the value of a number element to abc, its resulting value will be 0, or if you try to set a boolean element to 13, you will end up with it being true. to set a “false” value to a bool element, use an empty string, 0, n, no, f or false (case insensitive); anything else is interpreted as true.
Parameters
doc: the name (not the contents!) of a variable that contains the json document
path: path to the element to which we’re adding (like /path/to/element, or /path/to/element/3 to identify the element with index 3 in an array)
newvalue: value to be set
jsondelete(doc,path)
delete the element at the given path, from the given document. the value of the variable that contains the json document (doc)is updated to reflect the change. you may delete any type of element.
Parameters
doc: the name (not the contents!) of a variable that contains the json document
path: path to the element to which we’re adding (like /path/to/element, or /path/to/element/3 to identify the element with index 3 in an array)
JSONPRETTY(doc)
returns the nicely formatted form of a json document, suitable for printing and easy reading. the function has cosmetic functionality only.
Parameters
doc: the name (not the contents!) of a variable that contains the json document. the value will not change.
JSONCOMPRESS(doc)
returns the given json document formatted for a minimum footprint (eliminates all unnecessary characters). the function has cosmetic functionality only.
Parameters
doc: the name (not the contents!) of a variable that contains the json document. the value will not change.
Author, licensing and credits
Radu Maierean radu dot maierean at gmail
Copyright (c) 2010 Radu Maierean
the res_json module is distributed under the GNU General Public License version 2. The GPL (version 2) is included in this source tree in the file COPYING.
the res_json module is built on top of David Gamble’s cJSON library. i used his code with very minor and insignificant changes, to make my picky compiler happy. the res_json module is intended to be used with asterisk, so you will have to follow their usage and distribution policy. and i guess so do i. i’m no lawyer and i have to take the safe route, and this is why i go with the same level of license restriction as asterisk does.
