Welcome to the callstats.js API!

The callstats.io’s Javascript client library enables performance monitoring features in browser-based WebRTC endpoints. The communication with callstats.io occurs over Secure HTTP (https://), the endpoint (the browser in this case) MUST support HTTP/2. Additionally, the origin server MUST allow Cross-Origin Resource Sharing (CORS) and MAY need to serve its own pages over HTTPS to avoid mixed content warnings.

Versioning

callstats.js uses semantic versioning. The latest version is in the changelog. However, programmatically the version can be fetched by invoking callstats.version.

Please subscribe to our callstats-dev mailing list to get notifications and changelogs of new callstats.js releases.

callstats.js API

callstats.initialize() with app secret

Basic authentication using a clear text AppSecret gets you integrated quickly, if you want to mitigate the risk of someone else sending data to callstats, you can set a whitelist origin URL. However, to properly authenticate and validate that the requests are intentional, you will need to use the third-party authentication based on JWT mechanics. Read more about that in Third Party Authenitcation.

var localUserID = {};
localUserID.userName = "Clark Kent";
localUserID.aliasName = "superman";
localUserID.loginID = "[email protected]"

var additionalIDs = {
  customerID: "Customer Identifier. Example, walmart.",
  tenantID: "Tenant Identifier. Example, monster.",
  productName: "Product Name. Example, Jitsi.",
  meetingsName: "Meeting Name. Example, Jitsi loves callstats.",
  serverName: "Server/MiddleBox Name. Example, jvb-prod-us-east-mlkncws12.",
  pbxID: "PBX Identifier. Example, walmart.",
  pbxExtensionID: "PBX Extension Identifier. Example, 5625.",
  fqExtensionID: "Fully qualified Extension Identifier. Example, +71 (US) +5625.",
  sessionID: "Session Identifier. Example, session-12-34",
};

var configParams = {
  disableBeforeUnloadHandler: true, // disables callstats.js's window.onbeforeunload parameter.
  applicationVersion: "app_version", // Application version specified by the developer.
  disablePrecalltest: true // disables the pre-call test, it is enabled by default.
  siteID: "siteID", // The name/ID of the site/campus from where the call/pre-call test is made.
  additionalIDs: additionalIDs, // additionalIDs object, contains application related IDs.
  collectLegacyStats: true //enables the collection of legacy stats in chrome browser
  collectIP: true //enables the collection localIP address
};

callstats.initialize(AppID, AppSecret, localUserID, csInitCallback, csStatsCallback, configParams);

JSON for UserID (supported since v3.14)

In some cases, customers want to provide the actual username in addition to the alias to callstats.io. Since callstats.js version 3.14, it accepts userID both as a String or an object. Section on generating userID provides more guidelines on choosing a localUserID.

JSON for configParams

It provides developers a method to enable or disable certain features or functions within the callstats.js library. It is a javascript object with the following OPTIONAL key-value pairs. They are:

📘

Note

Setting disableBeforeUnloadHandler to true disengages callstats.js's window.onbeforeunload handler, and you will need to send the fabricTerminated event for each active PeerConnection. See more details on fabricTerminated event

JSON for additionalIDs

API return values

All the callstats.io APIs returns an object containing status and msg.

callstats.addNewFabric()

Indicates that the WebRTC application requests callstats.js to monitor the performance of the PeerConnection between the two endpoints (represented by the corresponding UserIDs).

📘

Note

• Please note! To notify callstats.io of a fabric termination, the sendFabricEvent( ) must be called with the value fabricTerminated in fabricEvent.
• fabricAttributes is optional and default value is peer and sendrecv.

var fabricAttributes = {
  remoteEndpointType:   callstats.endpointType.peer,
  fabricTransmissionDirection:  callstats.transmissionDirection.sendrecv
};

 callstats.addNewFabric(pcObject, remoteUserID, fabricUsage, conferenceID, fabricAttributes, pcCallback);

callstats.reportError()

Notifies the callstats.io back-end about conference setup failure reason.

📘

Note

• pcObject MAY be set to NULL when passing in errors that occur when getUserMedia() is called.
• localSDP MAY be set to NULL, in case you do not want SDPs to be collected.
• remoteSDP MAY be set to NULL, in case you do not want SDPs to be collected.

callstats.reportError(pcObject, conferenceID, callstats.webRTCFunctions.createOffer);

callstats.sendFabricEvent()

Notifies the callstats.io back-end about user specific events (e.g., 'Hold', 'Mute', etc.) on a PeerConnection. It is usually generated due to local user interaction at a PeerConnection.

callstats.sendCallDetails()

This API reports the call details from Contact Centres to callstats backend.

callstats.sendCallDetails(pc, conferenceID, callAttributes);
var callAttributes = {
  callType:,  //inbound or outbound or monitoring
  role:       //agent or participant or manager
}

callstats.associateMstWithUserID()

Maps the SSRC to the userID that generated it. This is useful when multiple MediaStreamTracks (MSTs) are sent or received in a single PeerConnection.

📘

Note

• userID is localUserID for local MSTs and remoteUserID for remote MSTs.
• SSRC is typically generated by the user-agent and MUST not be null or empty.
• usageLabel can be set to front-camera, back-camera, screen, audio-in, mic, system-sound, enumeration-of-webrtcfunctions or anything that allows stream usage identification.
• associatedVideoTag is the DOM element name, if you do not provide associatedVideoTag then callstats.js is not able to collect Time-to-First-Media metric.

// Extracting SSRC from SDP
var validLine = RegExp.prototype.test.bind(/^([a-z])=(.*)/);
var reg = /^ssrc:(\d*) ([\w_]*):(.*)/;

pc.remoteDescription.sdp.split(/(\r\n|\r|\n)/).filter(validLine).forEach(function (l) {
        var type = l[0];
        var content = l.slice(2);
        if(type === 'a') {
          if (reg.test(content)) {
            var match = content.match(reg);
            if(($.inArray(match[1],ssrcs) === -1)) {
              ssrcs.push(match[1]);
            }
          }
        }
      });

    ssrcs.forEach(function(ssrc) {
      window.callstats.associateMstWithUserID(pcObject, userID, conferenceID, ssrc, usageLabel, associatedVideoTag);
    });