Jingle/SIP setup proof of concept
This tutorial will show you how to configure MongooseIM, Routr (a SIP server) and client applications to demonstrate how the Jingle/SIP integration works.
We are going to use the following open source software:
MongooseIM - https://github.com/esl/MongooseIM
- see How-to-build for details on building.
It's important to remember to run the configuration script with
tools/configure with-jingle-sip. Without this, third party dependencies required by the Jingle/SIP translator will not be included in the release.
- see How-to-build for details on building. It's important to remember to run the configuration script with
Routr (SIP server) - https://routr.io
- I recommend downloading binaries for your system from official source.
- Jitsi (XMPP and SIP client application) - https://desktop.jitsi.org
- Otalk - web based XMPP client - https://github.com/otalk/otalk-im-client
- Folow the instructions on otalk-im-client#installing to run it
We will use 2 users
First the domain
sip.example needs to be added to domains served by Routr.
To do it, paste the following content to config/domains.yml in the directory where Routr was:
1 2 3 4 5 6 7
email@example.com needs to be added to
config/agents.yml like below:
1 2 3 4 5 6 7 8 9
Now Routr can be started with
If all goes well we'll see the following output:
1 2 3 4 5 6
It is important to remember the IP address as it'll be used in next point.
A side note
In Routr's logs you may see messages like
They can be ignored for the purpose of the tutorial.
In my case the IP reported by Routr was
Now we need to use this to update
/etc/hosts file like below:
At this point I assume that MongooseIM was built with
make rel, that it is running and the current working directory is
Similar to Routr, MongooseIM also needs to know which hosts to server.
Please replace the default host defined in
etc/mongooseim.toml; the line:
should be changed to:
Now we need to enable
mod_jingle_sip, please add the following line in modules list (somewhere around line 740 in the same file)
Now we are registering both users in MongooseIM by calling the following commands:
Yes, we need to have the
firstname.lastname@example.org registered in MongooseIM.
This is needed because a Jingle call can be initiated by a regular XMPP client only when the app knows the other user's full JID.
The easiest way to achieve that is to exchange presence information between these 2 users.
This can happen automatically if 2 xmpp users have each other in the roster.
The roster can be set by us with the following commands:
Adding users to Jitsi
email@example.com has to be added to Jitsi app.
When the app is opened for the first time it will display a window to configure the user.
Later users can be configured from the
Adding a SIP user
In order to add a user who connects to the SIP server we need to choose the
SIP protocol from the available
networks in Jitsi.
SIP id field we put
firstname.lastname@example.org and in the
Password field we put
1234 as in the
Now we need to switch to
Advanced options and go to the
Here we need to unselect the
Configure proxy automatically and put the IP of our
Routr server, port number
TCP as the preferred transport.
Adding an XMPP user
Now we have to add
email@example.com to Jitsi's XMPP network in order to connect this user to MongooseIM over XMPP.
It's very similar to adding a user to Jitsi's SIP network, the only difference is the password,
for the XMPP conection it's
test_pass as set when registering the user in MongooseIM.
Here we also need to go to the
Advanced window and the
Connection tab in order to put the IP addres (the same as before) in the
Connect Server field.
Remember to check the
Override server default options box.
firstname.lastname@example.org to MongooseIM over XMPP is to cheat Jingle a bit, so that the client app for user
email@example.com can start the Jingle call.
When Jitsi connects this user, it will likely display a warning about the server's certificate.
This is because by default MongooseIM is configured with a freshly generated, self-signed certificate.
We can click
Continue anyway button in order to proceed.
Adding user to Otalk
Please follow the instructions on https://github.com/otalk/otalk-im-client#installing in order to compile and run the app. If all goes well, you should see the following message printed in the console:
This means that the app is hosted on
At this point I also recommend opening wss://localhost:5285/ws-xmpp in the same browser. This endpoint works correctly only for WebSocket connections but most probably you will be prompted about the certificate. This is again due to the self-signed certificate. We need to add an exception for this certificate in order to successfully connect from Otalk.
Now let's open http://localhost:8000 where the Otalk app is hosted.
Log in section put
firstname.lastname@example.org in the
JID field and
test_pass in the
The default WebSocket endpoint in the
WebSocket or BOSH URL field needs to be changed to:
wss protocol, Otalk will not connect the user over WebSockets if for example
https is put in the field.
Now we can hit the
Go! button and the
email@example.com will connect to MongooseIM.
Making a call
On the left side we can see that the user already has
firstname.lastname@example.org in the roster and there should be a green dot indicating that the user is online.
When we click on the contact, the
Call button should appear allowing us to initiate the call.
In Jitsi, the following window should pop up:
Behind the scene the following SIP request was send from MongooseIM to Routr.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76
And Routr sent the
Ringing response code to MongooseIM as soon as the Jitsi app displayed the incoming call window:
1 2 3 4 5 6 7 8 9
The example above showcases how you can use Jingle/SIP switch with the available open source software. Sonetel, who are this feature's sponsor, operate on a slightly different use case and utilize more of the functionality with their proprietary software. Current implementation makes following assumptions:
- The peer-to-peer stream is always encrypted.
This means that MongooseIM expects element
<fingerprint>as described in XEP-0320: Use of DTLS-SRTP in Jingle Sessions to be in the content description. Not every open source XMPP client supporting Jingle supports this encryption.
- MongooseIM expects that the
200 OKresponse contains at least one ICE candidate to set the peer-to-peer connection up.
This makes the current implementation a bit limited, but on the other hand the basic integration between XMPP and SIP world is already there. Based on the current state it can be improved and extended if needed.