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 API Guide

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.

ParamsArgumentTypeDescription
AppIDRequiredStringApplication ID is obtained from callstats.io.
AppSecretRequiredStringApplication secret is obtained from callstats.io.
localUserIDRequiredString (128 bytes) or Objectit is provided by the developer and MUST NOT be null or empty.
csInitCallbackOptionalCallbackasynchronously reports failure or success of the protocol messages.
csStatsCallbackOptionalCallbackasynchronously reports the conference statistics.
configParamsOptionalJSONit is the set of parameters to enable/disable certain features in the library.
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.

KeysRequiredDescription
userNameYesStrint of maximum lenth 128 characters.
aliasNameYesString of maximum length 128 characters.
loginIDNoString of maximum length 128 characters.

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:

KeysRequiredDescription
disableBeforeUnloadHandlerNoby default the value is false.
applicationVersionNoString of maximum length 30 characters.
disablePrecalltestNoby default the value is false.
siteIDNoString (256 bytes).
collectLegacyStatsNoby default the value is true.
additionalIDsNoJSON object.
collectIPNoby default the value is true.

πŸ“˜

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

KeysRequiredDescription
customerIDNoString (256 bytes) Example, walmart.
tenantIDNoString (256 bytes) Example, monster.
productNameNoString (256 bytes) Example, jitsi.
meetingsNameNoString (256 bytes) Example, jitsi loves callstats.
serverNameNoString (256 bytes) Example, jvb-prod-us-east-mlkncws12.
pbxIDNoString (256 bytes) Example, walmart.
pbxExtensionIDNoString (256 bytes) Example, 5625.
fqExtensionIDNoString (256 bytes) Example, +71 (US) +5625.
sessionIDNoString (256 bytes) Example, session-12-34.

API return values

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

ParamsDescription
statusReturns one of the values defined in callStatsAPIReturnStatus
msgReturns the corresponding message related to the status.

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).

ParamsArgumentTypeDescription
pcObjectRequiredObjectPeerConnection object.
remoteUserIDRequiredString (128 bytes) or ObjectIt is generated by the origin server.
fabricUsageRequiredEnumValid values are discussed in a later section.
conferenceIDRequiredString (256 bytes)It is generated by the origin server.
fabricAttributesOptionalObjectContains two attributes section and section.
pcCallbackOptionalCallbackthe callback asynchronously reports failure or success for pcObject.

πŸ“˜

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.

ParamsArgumentTypeDescription
pcObjectRequiredObjectPeerConnection object
conferenceIDRequiredString (256 bytes)It is generated by the origin server.
webRTCFunctionsRequiredEnumName of the WebRTC function that failed.
domErrorOptionalObjectDOMError object
localSDPOptionalObjectLocal SDP collected when errors occur.
remoteSDPOptionalObjectRemote SDP collected when errors occur.

πŸ“˜

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.

ParamsArgumentTypeDescription
pcObjectRequiredObjectPeerConnection object.
fabricEventRequiredEnumwith valid values discussed in a later section.
conferenceIDRequiredString (256 bytes)It is generated by the origin server.
eventDataOptionalObjectevent related data.

callstats.sendCallDetails()

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

ParamsArgumentTypeDescription
pcRequiredObjectRTCPeerConnection associated with this connection.
conferenceIDRequiredString (256 bytes)It is generated by the origin server.
callAttributesRequiredJSONContains information about the call.
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.

ParamsArgumentTypeDescription
pcObjectRequiredObjectPeerConnection object.
userIDRequiredString (128 bytes) or ObjectIt is generated by the origin server.
conferenceIDRequiredString (256 bytes)It is generated by the origin server.
SSRCRequiredObjectSynchronization Source Identifier, as defined in RFC3550.
usageLabelRequiredString (20 bytes)it is generated by the origin server.
associatedVideoTagOptionalStringhandler to the user's video tag.

πŸ“˜

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);
    });

Updated about a month ago



callstats.js API Guide


Suggested Edits are limited on API Reference Pages

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