Project Clearwater / Matrix Gateway Hack by Matt Williams

clearwater matrixOver the weekend of April 11-12, I attended TADHack-mini, held at IDEALondon. The theme was WebRTC, and for my hack I built a gateway between Project Clearwater (which speaks SIP) and Matrix (which supports WebRTC).

Project Clearwater is a massively-scalable, open-source IMS core, built from the ground up to run in the cloud. Matrix is an open communication standard, focusing on messaging, VoIP and Internet of Things, and emphasizing federation, linking “silos of communication”. The PSTN is quite a big “silo” but I thought it would be interesting to connect it into Matrix and enable voice and video calling between them.

The architecture for my hack is shown below:

clearwater matrix

Project Clearwater includes lots of IMS components – core I-CSCF, S-CSCF and BGCF plus basic P-CSCF, IBCF and MMTEL TAS. From the IMS core’s perspective, my gateway appears to be an IBCF, i.e. a portal to off-net destinations. Calls come into the I/S-CSCF, it recognizes that the destination is not local and sends them to the BGCF and then the BGCF routes them to the IBCF (or, in this case, Project Clearwater/Matrix Gateway).

The Matrix project includes an open-source “Synapse” reference implementation. It exposes an application service interface over HTTP, which allows trusted applications to act on behalf of local users without needing their authentication credentials.

The Project Clearwater/Matrix Gateway sits between the two, speaking SIP to Project Clearwater and HTTP to Synapse. Project Clearwater’s SIP routing components are built on a common “Sproutlet” API, and it was on this that I built my gateway. When a call arrives over SIP, the infrastructure calls into my gateway code, which creates a Matrix user to represent the caller and a Matrix room to hold the call in, invites the callee to join the room and, when they do, sets up the call.

The gateway just handles signaling, not media. As a result, for my demo, I had to get my SIP client to speak WebRTC (“SAVPF”) media, like Synapse uses, rather than traditional (“AVP”) RTP media. Since Project Clearwater has a SIP/WebSocket gateway, I used jsSIP, a SIP/WebSocket and WebRTC softphone that runs in the browser.

With about five minutes to go before the hackathon presentations started, I finally got a call through from my Project Clearwater IMS core to a remote user in a Matrix federation. I only had enough time to test it a couple of times, so I was very pleased when the demo went smoothly!

The gateway only ended up being about 1500 lines of new C++ code – I was able to reuse a lot of existing Project Clearwater infrastructure. As next steps, I’d like to

  • integrate a media gateway to translate between WebRTC and AVP RTP media
  • support calling out from Matrix, as well as calling in
  • add messaging support.

It’s all open-source so, if you’re interested in using it (or contributing!), you can grab the code from the github repo.

Thanks to Alan for organizing TADHack and to Matthew, Dave and Oddvar from Matrix for all their help over the weekend!