Using the WebTrit WebRTC softphone app with third-party VoIP switches, cloud PBX systems and UCaaS platforms

Our Vision

Q: Why is integration even required?

WebTrit uses SIP, which has become the de-facto standard of VoIP communications. So, you might wonder if it’s possible to simply connect it to any VoIP system, such as Asterisk, FreeSwitch, or Broadsoft/Cisco. Well, that is mostly (but not 100%) correct. WebTrit indeed uses the SIP protocol to receive incoming calls and send outgoing calls to your cloud PBX, on-premise IP PBX, or UCaaS system. This will work out-of-the-box with the majority of VoIP systems that are available on the market today. 

There may, however, be some glitches due to minor differences in SIP implementation, just like the way a dialect of a language might cause small differences in translation. These differences, which are more common when you are working with an older version of an IP PBX system, may have a more serious effect on caills – for instance, some calls may not be established or may be dropped. For that reason, testing is highly recommended. 

If you want to provide a seamless user experience for the sending and receiving of VoIP calls (for instance, if you want a user of the dialer app to be able to see their monetary balance, a list of colleagues and their online status, or to be able to access a call history regardless of what phone device they are using), then you will require a different kind of integration.

Q: What data does WebTrit need from an external system?

The majority of deployment cases fall into one of two categories:

1. An external VoIP system (cloud PBX) already has phone lines and PBX extensions configured, along with additional information such as Call Detail Records(CDRs).
2. You do not have a VoIP system, but you are building a new service (for example, a dating app that includes video-chat capabilities) and all of the user information resides in a database that your team created.

For both of these scenarios (and for any type of creative, mix-and-match case), it will be necessary to organize a way to deliver the following information to the WebTrit cloud backend:

1. A general authentication decision for a user’s attempt to log in: Are they your customer, and are they allowed to use the service further?
2. User credentials for SIP authentication (in cases where an external VoIP system is involved). WebTrit works by issuing SIP registrations (SIP REGISTER) or by placing call initiation requests (SIP INVITE) to a hosted PBX system, just like a user’s desk phone would. In order to do this, WebTrit needs to know the correct username and password. (These must be exactly as they are configured on the hosted PBX, or the hosted PBX system will reject the request.)
   
   One way to solve this is by requiring the user to manually enter their SIP username and password in the app configuration (this is what mobile dialers such as Bria and Linphone do), but this solution is cumbersome: it can weaken the overall security, generate errors, and annoy your customers. Instead, it is better for the user to log into the app using normal credentials, such as:
   • Username (or email) and password
   • A one-time password sent via email or SMS
   • Scanning a QR code that is automatically generated at signup 

Then, through magic, the actual SIP username and password appears in the WebTrit system. 

3. If a user has a monetary balance attached to their account, it can be nice to extract that info so that the user can view it within the mobile app UI. 
4. Users typically want to be able to see a list of their contacts, such as a corporate directory, or – in the hypothetical example of building a new dating app with WebRTC video chat – a list of potential dates they have matched with when they log into a communications app, so they can easily get in touch.  
5. Users will also likely expect to see a list of their previous calls (also called CDRs, or call detail records, in “traditional” cloud PBX systems), including those made from devices other than the softphone (i.e., a desk VoIP phone). 
6. You can also offer additional functionality to enhance or simplify the user experience. For example, if the hosted PBX system provides call recordings, users would appreciate the ability to download and play those recordings directly from the app rather than having to log into a separate web portal.

As you can probably guess, the “magic” that makes all of these processes happen is actually achieved through the API adapter that connects the WebTrit cloud backend to the remote hosted PBX system or Business Support System (BSS). Since “API adapter” is a very generic term (you can use it for anything that connects two different systems via API!), we will use the term BSS connector, since its main function is to connect to a repository of user data.

Q: Should we connect to the hosted PBX or to the BSS?

This depends on how exactly your VoIP network is deployed. Let’s look at the options.

Small, individual IP PBX systems

If your VoIP system is a standalone PBX designed for a single company (e.g., a single Asterisk server, PBXpress or instance of 3CX PBX), the user information will typically reside within that system. In this case, all that is needed is to figure out which API you can use to access that information (and whether such an API is available at all – for instance, in the case of 3CX there does not seem to be any officially supported API to extract user info).

Multi-tenant hosted PBX systems

These are beefed-up versions of the single PBX system, in which one physical installation (or cloud deployment) can host a service for several customers, each with their own “virtual” PBX. Typically, the user data will still reside somewhere within that PBX system, and will be managed either by a “global” administrator (who has access to everyone on the platform) or by a “local” administrator (who only has access to a specific compartment; this would usually be someone who works for the company using the PBX system). A good example of a multi-tenant PBX system would be Cisco CallManager or BroadSoft (now also Cisco).

In this case, just like with a single PBX, we would need to find a way to access the user data through some type of API.

UCaaS / Cloud PBX Platforms 

These are typically deployed by larger telecom operators, with a single system serving thousands of customers – again, each having their own “virtual” PBX. These systems are usually designed with two factors:

• There is a SIP proxy component that handles the actual VoIP calls (typical products used for this purpose are SIP:Wise, Kamailio, or PortaSIP); this consults the BSS in order to authorize calls (based on the user’s available funds and tariff plan), trigger charging after the call completion, etc.
• There is also an external repository for user data (the BSS), which is a crucial part of the operation. This repository can be a full-scale billing system (such as PortaBilling) accessed via telecom authorization and charging protocols such as RADIUS; or it can be a simple database (e.g., MySQL or MongoDB) that stores user data, which is then accessed via its own database connector. 

In this case, all the information we need resides in the BSS, and we would need to find a way to access it via API.

Q: How exactly is the integration done?

So once you have the BSS connector code ready, you then package it into a container (referred to as “building a container’s image”), and launch it in the cloud provider of your choice, such as GCP, AWS, Azure, or DigitalOcean. Once your service is up and running, you can reconfigure your instance of WebTrit to use it. 

From there, when a user logs into the softphone app or WebTrit web dialer, the request from the app is first sent to the WebTrit backend and then to your own BSS connector. The custom BSS connector code then contacts your BSS or hosted PBX system, and the response is delivered to the app in the reverse order. And voila! Your customers are authenticated against your own VoIP system, their outgoing calls are sent through it, and they have access to their call history and anything else they need.

Q: Which programming language should I use to write my BSS connector?

Since your code will run in a container, it doesn’t matter what language you choose – as long as your code provides a proper REST API to connect to WebTrit and correctly extract the data from your hosted PBX or BSS. We mean it when we say it doesn’t matter – it could (but probably should not) even be written in COBOL. :-) 

Obviously, the first consideration you should take into account is your proficiency in a specific programming language. So, choose the one you already know well (NodeJS or Python seem to be the most common choice for these types of tasks).

If your hosted PBX system or BSS does not provide a modern API (such as REST) and has a proprietary API (e.g., Broadsoft uses XSI, which is XML sent over HTTP), then there is another important consideration: the availability of software libraries for a specific programming language, which you can use to avoid having to write the code for things like formatting requests, or parsing replies from scratch. (And you can also skip all that time you’d have to spend on debugging that would come with it!) 

Q: What’s the fastest way to write a BSS connector?

If you plan to use a modern API (e.g., REST or a direct connection to a database), we have published a fully functional sample BSS connector on GitHub that can help. This sample connector is written in Python, uses the FastAPI framework to provide a REST interface toward WebTrit, and generally has everything you need to build a container. (In fact, there is already a container you can use on Docker Hub.)

Since it is a sample, it does not connect to any “real” BSS, but instead allows you to define a list of authorized users directly in the source code (or YAML file), which is suitable for initial testing and to start building your own integration module. Simply download a copy, add/change a few relevant pieces of code (for instance, to make sure the user data is retrieved not from the “example.py” file but from your real database!), and you have your own working integration. 

Q: If I build a connector for a specific cloud PBX system, can I share it to help other WebTrit users  launch their own mobile dialer apps or WebRTC widgets for websites using that same VoIP system?

Of course you can. Not only can, but should! This  is what open-source is all about. Since your code will reside in a separate container, it will be logically and physically isolated from the rest of the WebTrit cloud backend code. That means there is no need to submit it for our review, stress about any kind of code rejection, wait for it to be merged with other changes, or deal with any other type of red tape. Just publish it in your own repository on GitHub, GitLab, or some other provider of your choice. And then let us know about it so we can add it to our list of integrations and mention you in our next news update to the WebTrit community! You can send us an email to contribution<?>@webtrit.com, but replace the <?> with char(115) – we want to receive emails from developers, not from spammers ;-). We look forward to hearing about what you build. 

Still have questions about connecting the WebTrit WebRTC dialer to third-party VoIP switch, cloud PBX systems, or a proprietary telco BSS?

Write to us about your project: What type of service do you want to launch using the WebRTC softphone app or a web dialer? Which VoIP system do you want it to connect to? What existing softphone solution are you trying to replace? Tell us about what you want to do and we’ll try to help you – and then we’ll publish any answers to new frequent questions  in a future post.