kamailio: controlling presence with new module `pua_json`

I recently submitted a new module to the kamailio project which adds an interface to update/control presence records using json. Effectively, you can turn on/off a phone’s Busy Lamp Field (BLF) by sending an http request containing json body to kamailio. The following is a quick guide on how to set up kamailio to accept http requests and update presence using two modules: xhttp and pua_json.

xhttp module

To setup kamailio to listen for http requests, you need to listen on a tcp interface.  I’ve setup kamailio to listen on localhost because I don’t need to expose this service outside of the local machine. So in my kamailio.cfg, I have:

# allow http requests
listen=tcp:127.0.0.1:8080
tcp_accept_no_cl=yes

# load the module
loadmodule "xhttp.so

pua_json module

The pua_json requires no configuration parameters at this time. It simply exposes a function to update presentity from a json object. You will probably want the json module loaded so you can parse and validate some of the json. And you will need to properly configure all your presence modules to handle SIP SUBSCRIBEs, etc…

# load modules
loadmodule "json.so"
loadmodule "pua_json.so"

the event route

The last piece of the setup is the xhttp event_route which is used to handle the http requests containing json object. This is a simple example of such a route:

event_route[xhttp:request] {
    if ($hu != "/presence/") {
        xlog("L_INFO", "invalid request [$hu]");
        xhttp_reply("404", "Not Found", "text/html", "");
        return;
     }
     $var(call-id) = $(rb{json.parse,Call-ID});
     xlog("L_INFO", "$var(call-id)|log|[$hu] payload $rb");
     if ($(rb{json.parse,Event-Package}) == "dialog") {
        xlog("L_INFO", "$var(call-id)|log|received $(rb{json.parse,Event-Package}) update for $(rb{json.parse,From}) $rb");
        pua_json_publish($rb);
    }
    xhttp_reply("200", "OK", "text/html", "$rb");
}

The route basically checks to make sure the http endpoint matches `/presence/` and only executes presence updates for “dialog” events. I showed an example of how to parse the Call-ID using the json module as well.

the curl request

Once you have kamailio configured, you are ready to send a curl request to test presence!
Turn on a hold light with a request like so:

curl -d '{"Call-ID":"park+01@test03.vxs.local","Event-Category":"presence","Event-Name":"update","Event-Package":"dialog","Expires":"3600","To":"sip:user01@test03.vxs.local","To-User":"user01","To-Realm":"test03.vxs.local","From":"sip:park+01@test03.vxs.local","From-User":"park+01","From-Realm":"test03.vxs.local","State":"confirmed"}' http://localhost:8080/presence/

Turn off a hold light with a request like (the only difference from above, is the “state” in this request):

curl -d '{"Call-ID":"park+01@test03.vxs.local","Event-Category":"presence","Event-Name":"update","Event-Package":"dialog","Expires":"3600","To":"sip:user01@test03.vxs.local","To-User":"user01","To-Realm":"test03.vxs.local","From":"sip:park+01@test03.vxs.local","From-User":"park+01","From-Realm":"test03.vxs.local","State":"terminated"}' http://localhost:8080/presence/

If you have a phone subscribed to “park+01@test03.vxs.local” you should see the BLF color change when the state is confirmed, and then change back to the original color after the 2nd curl request.