Irish technology company Spearline acquires Callstats from 8x8.  Learn More

New API: Smart Connectivity Notifications

By callstats on October 22, 2021

When a customer reports an issue that endusers are facing, oftentimes it is the enduser's device, network, or environment which is causing the issue. We introduced Pre-call tests in 2017, Global Release in 2018, and based on the feedback we evolved it to run in the background at regular intervals, not just before the call (`startPreCall(iceServers, interval)`). In v2, we rebranded precall test to Smart Connectivity Test,  by introducing the concept of running test on different networkTypes (wifi, ethernet, mobile) and doppler tests (against near and far location), this provides robust insight (csConnectionRecommendationCallback) to the app on which path to use. 

Today, we are launching v3, which we are calling Smart Connectivity Test Notifications (pctConnectionQualityChange), which looks at short- and long-term trends of your connectivity and provides Actionable Insights preflight or when your connection deteriorates. Most importantly, all the analysis is done locally, ergo preserving privacy!

Why did we build Smart Connectivity Notifications?

Ever since we released the ability to run the tests at regular intervals, our customers have been asking us to provide more insights. The csConnectionRecommendationCallback helped contact center (CC) and unified communications (CC) apps to programatically decide which route is more performant and route the call over that interface. For example, a contact center site that has multiple ISPs connected to it, may use least cost routing or failover strategies to route traffic through a particular ISP. In these cases, running Smart Connectivity Tests (SCTs) at regular intervals, allowed contact center operators the flexibility of using a particular ISP on a per-call basis. 

In 2020, majority of the population is working remotely, be it call center agents, knowledge workers, students, teachers, doctors, lawyers, which has put a lot of stress on our home networks. Unlike the offices or corporate networks which are monitored closely and managed by the IT admins or at the very least have enterprise support from the ISP, the home networks are managed by the end-users. When things go awry, they may not know what is causing it and have very limited options to solve that issue. 

What does Smart Connectivity Notifications provide?

Very simply: the notifications provides insights. We expect the application to run smart connectivity tests (SCTs) at regular intervals. The `precalltest` library takes the responsibility to store and organise the data internally. Consequently, the library keeps track of long-term and short-term trends and when it observes a change in behaviour, things getting better or worse, the library alerts the application via the `pctConnectionQualityChange` event callback. It is up to your application code to handle the event. 

While all the trend analysis is done locally. However, we do allow sending the data to callstats, so that you can simultaneously alert the IT admins when several similar users are struggling with the same issue.

How does this work?

To enable SCT notifications feature, send the feature request to callstats support team. In addition, precall test is running at regular intervals in the background and you need to set the interval in callstats.startPrecallTests(iceServers, interval). The argument iceServers can be set to null unless the purpose is to run tests against multiple TURN servers provided in the list. The current version of SCT notifications is not handling multiple server tests and it considers the results of the first server in the list. You can read more about setting this on our code docs

When the algorithm detects degradation or improvement in the network, it will trigger an on event. Your app needs to pass a function into the csEventCallback in the callstats.initialize(). The event that you are interested in is: pctConnectionQualityChange. When  the event is triggered, the callstats library will pass a JSON object.

csjs.on('pctConnectionQualityChange', results => {

//console log output
"timestamp": "405241500"
"notificationID": "766172756e6c6f76657363616c6c7374617473"
"connectivityCode": 3
"connectivity": "success"
"statusCode": 4
"status": "good"
"summaryCode": 75
"summary": "connection is Good, Fair bandwidth (good audio, poor video)"
"notificationCode": 700
"notification": "Current bandwidth is enough for good audio quality, but poor video quality or screen sharing"
"networkType": "wifi"
"localIp": ""
"isp": "VPN"
"city": "Helsinki"
"country": "Finland"

When the application gets the alert it can use the summaryCode to update the connectivity indicator for example, change it from red to amber to green depending on how you map the summaryCode.

You can read more about the notifications from our docs site or reach out to our team via email,

Visualising the SCT Notification to the end-users

The application can choose to show the notification directly to the enduser in myriad of ways. The UI can be a badge, a widget, an alert he UI or set as a badge, you are free to experiment with the user experience depending on the alert. For example, this how the 8x8 app uses the data from the notifications API to show an alert to the end-user.

Depending on the privacy setting, this information may also be mirrored in the callstats dashboard, i.e., an IT Admin in addition to the alerts, would be able to see the trends that lead the callstats algorithm to alert the end-user.

How do I turn this feature on?

We are looking for early adopters, developers, operators, that want to incorporate it into their app, experiment with showing these alerts in the UI, as a widget or icons, or notification badges. Please write to, and someone from our team will help you onboard. There are different flags a) to start performing the SCT Notifications, b) webhook for SCT Notification Alerts. Finally, we are ready to GA the feature, you will be able to configure the feature via the callstats dashboard.

The callstats team has been working on the root-cause analysis for a while now, and we introduced `pctConnectionQualityChange` earlier this year. In this release, we have expanded the level of insights and will continue make improvements to the algorithms behind the scenes.

We are quite proud of what the team has achieved in a very short time and continuously working on improving the algorithms.


This feature was built by Navid, Nate, Karthik.

Tags: WebRTC Monitoring, Smart Connectivity Test, dashboard, changelog, privacy