callstats.io

The callstats Developer Hub

Welcome to the callstats developer hub. You'll find comprehensive guides and documentation to help you start working with callstats as quickly as possible, as well as support if you get stuck. Let's jump right in!

Guides    API Reference

callstats.js Precall Test APIs

Smart Connectivity Test Suite has a lot of capabilities to perform active network tests. This section covers those aspects

Smart Connectivity Test Suite has capabilities to perform active network tests before the call (pre-call tests) or in the background at any time. This section covers the APIs to start/stop the tests and how to integrate the results from the various callback APIs .

API

To use the precalltest API, you should have added callstats.js to your app and initialized it. Specifically, steps 1 and 2 on callstats.js: Integrating with your WebRTC App.

callstats.startPrecallTests()

This API can be used to make precall tests continuously as per the interval given by the customers. The results of the precall test will be given in the preCallTestResults callback. Once we run precall tests on all the turn credentials provided, the connection recommendation is provided in the connectionRecommendation callback.

ParamsArgumentTypeDescription
iceServersRequiredObjectTURN Server list provided by customer.
intervalRequiredIntegerIndicates the delay (in seconds) after the tests to restart the pre call tests.

📘

Note

Interval default value is 60 seconds, if not provided. The minimum interval is 30 seconds, and the recommended interval is 300 seconds

callstats.startPrecallTests(iceServers, interval);

var iceServers = [
   {
      "urls":[
         "turns:taas.callstats.io:443?transport=udp",
         "turns:taas.callstats.io:443?transport=tcp",
         "turn:taas.callstats.io:80?transport=udp",
         "turn:taas.callstats.io:80?transport=tcp"
      ],
      "username":,
      "credential":,
      "label": "turn2"
   },
   {
      "urls":[
        "turn:turn-server-1.dialogue.io:3478"
      ],
      "username":,
      "credential":,
      "label": "turn2"
    }
];

callstats.stopPrecallTests()

This API to stop the precall tests started using the API startPrecallTests()

callstats.stopPrecallTests();

callstats.on()

The "on" function is used to set the callbacks for smart connectivity tests. We also use the same callback during the call, and they are documented at: callstats.js callbacks and onEvents API.

ParamsArgumentTypeDescription
eventNameRequiredStringThe allowed values are "preCallTestResults", "connectionRecommendation", "pctConnectionQualityChange".
csEventCallbackRequiredCallbackThe callback asynchronously provides new event data whenever it is available.

The pre-call test results callback (csPreCallTestResultsCallback)

The csPreCallTestResultsCallback function is set with the on() functionality. The callback is invoked when the pre-call test results are available. The pre-call test measures the Media Connectivity, Round Trip Time, Fractional Loss, and Throughput against callstats.io TURN servers. You can use the “status” to check if the pre-call test has succeeded, it will return success or failure. The pre-call test is enabled by default and is running as long as the callback is not fired. The pre-call test might return partial results if the tests are interrupted or the call begins during the pre-call test. You can disable pre-call test by setting "disablePrecalltest" to true in configParams.

ParamsTypeDescription
mediaConnectivitybooleanTrue or False.
rttfloatRound Trip Time in ms. Returns "null" if there is no result.
fractionalLossfloatFractional Loss [0-1]. Returns "null" if there is no result.
throughputfloatThroughput in kbps. Returns "null" if there is no result.
//Usage
callstats.on("preCallTestResults", csPreCallTestResultsCallback);

function preCallTestResultsCallback(status, results) {

//Check the status
  if (status == callstats.callStatsAPIReturnStatus.success) {
    //Results
    var connectivity = results.mediaConnectivity;
    var rtt = results.rtt;
    var loss = results.fractionalLoss;
    var throughput = results.throughput;
    console.log(results);
  }
  else {
    console.log("Pre-call test could not be run");
  }
}

// console log output
{
    "mediaConnectivity": true,
    "throughput": 1796.1354352637957,
    "fractionalLoss": 0.004484480852075867,
    "rtt": 57.945068359375,
    "jitter": 309.0593613654375,
    "timestamp": 1616175041022.625,
    "provider": "callstats",
}

The connection recommendation callback (csConnectionRecommendationCallback)

The csConnectionRecommendationCallback function is set with the on() functionality. The callback is invoked when the precall tests are finished for all the TURN credentials given in 'startPrecallTest'. Connection recommendation gives the statistics measured, and the ranking of the TURN servers provided.

ParamsTypeDescription
providerstringTURN label.
roundTripTimefloatRound Trip Time in ms. Returns "null" if there is no result.
jitterfloatjitter in ms
fractionLostfloatFractional Loss [0-1]. Returns "null" if there is no result.
throughputfloatThroughput in kbps. Returns "null" if there is no result.
acceptablebooleanTrue or False
//Usage
callstats.on("connectionRecommendation", results => {
  console.log(results);
})

//console log output
{
   "aggregatedStats":[
      {
         "provider":"turn1",
         "roundTripTime":46.3499755859375,
         "jitter":143.7728006389737,
         "fractionLost":0,
         "throughput":4160.657588552875
      },
      {
         "provider":"turn2",
         "roundTripTime":106.699951171875,
         "jitter":1547.3617393722136,
         "fractionLost":0.5257732840987372,
         "throughput":584.6231721117872
      }
   ],
   "providerRanking":[
      {
         "provider":"turn1",
         "acceptable":true
      },
      {
         "provider":"turn2",
         "acceptable":false
      }
   ]
}

The connection notification callback (pctConnectionQualityChange)

The pctConnectionQualityChangeCallback function is set with the on() functionality. The callback is invoked when the precall tests are finished for all the TURN credentials given in 'startPrecallTest'. Connection notification gives the insight in plain english.

ParamsTypeDescription
notificationstringInsight on connection quality in English.
notificationCodeintA code that ties to the notification. This allows you to override the text for your usecase.
csjs.on('pctConnectionQualityChange', results => {
  console.log(results);
})

//console log output
{
    notification: "The Audio call quality will be good, video quality will be terrible.",
    notificationCode: 3002,
    timestamp: 1616174746370.235
}

Updated about a month ago


callstats.js Precall Test APIs


Smart Connectivity Test Suite has a lot of capabilities to perform active network tests. This section covers those aspects

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.