Looking for a job? We're hiring!

Integrating Twilio client SDK with callstats.io

NOTICE: Twilio's SDK does not currently send all metrics required by callstats.io. As a result we are not able to show a complete set of metrics and calculate objective quality.

Introduction

The Twilio Client SDK embeds voice into a Web application. The integration with callstats.io provides quality monitoring to the Twilio Web client. The callstats-twilio-client.min.js is a shim that integrates the twilio-client SDK with callstats.min.js. The Twilio Client exposes the PeerConnection and other useful APIs which we’ve automatically integrated with the shim, however, a few integration steps still remain. They are listed below:

Basic WebRTC call between Alice and Bob

Integration Steps

Step 1: Include callstats-twilio-client.min.js

  • Add the callstats-twilio-client.min.js to the HEAD tag. Please refer to our API page for more information on the dependencies.
<script src="https://api.callstats.io/static/callstats-twilio-client.min.js"></script>

If you are using require.js, you can use the configuration in our sample app on GitHub.

Step 2: Authenticating localUserID with callstats.io

Within Twilio.Device.ready() callback call CallstatsTwilio.initialize() with the appropriate parameters. See API page for more information. When the authentication to callstats.io succeeds, callstats-twilio-client.min.js will receive an appropriate authentication token to make subsequent API calls. Provide an appropriate callback (csInitCallback) to catch callstats.io events.

CallstatsTwilio.initialize

Parameters:

  • AppID: of type String. It is obtained from callstats.io backend.
  • AppSecret: of type String. It is obtained from callstats.io backend.
  • localUserId: of type String, maximum length 256 bytes and MUST NOT be null or empty. It is provided by the developer or fetched from the Twilio SDK’s Device Object.
  • configParams: is OPTIONAL, it is the set of parameters to enable/disable certain features in the library. See Step 2 of the API page.
  • csInitCallback: providing a callback function is OPTIONAL, the callback asynchronously reports failure or success. See Callback and Error Handling section of API page.
  • csStatsCallback: providing a callback function is OPTIONAL, the callback asynchronously reports the conference statistics. See Step 8 of the API page.
Twilio.Device.ready(function (device) {
  $("#log").text("Client '' is ready");
  
  // localUserId can be set by the developer. 
  // Or assign the userID already initialized in the Device Object.
  // e.g., this can be Alice or Bob.
  localUserId = device._clientName;

  // Include all the necessary parameters
  CallstatsTwilio.initialize(appID, appSecret, localUserID, configParams, csInitCallback, csStatsCallback);
});

Step 3: Start the call, set the call params.

The last step is to set the remoteUserId and conferenceID at the caller and the callee.

CallstatsTwilio.setCallParams:

Parameters:

  • remoteUserId: of type String, maximum length 256 bytes. It is generated by the origin server and MUST NOT be null or empty; See how to generate userID from our API page.
  • conferenceID: of type String, maximum length 512 bytes. It is generated by the origin server and MUST NOT be null or empty; See how to generate a conferenceID from our API page.

Step 3a: Caller (e.g. Alice): starts the call

At the caller, add setCallParams within the call function:

function call() {
  // get the phone number or client to connect the call to
  params = {"PhoneNumber": $("#number").val()};
  var connection = Twilio.Device.connect(params);

  // remoteUserId can be set by the developer. 
  // or parsed from the form on a webpage.
  // e.g., the remoteUserId is Bob.
  remoteUserId = $("#number").val();

  // The conferenceID can be set by the developer.

  // In this example, we are using the following scheme
  // The caller, uses the callee's name as the conferenceID.
  // and the callee, uses its name as the conferenceID.
  // this way both parties in the call use the same conferenceID.

  //Based on the figure above, the conferenceID is Bob, because Alice is calling Bob.
  conferenceID = remoteUserId;

  CallstatsTwilio.setCallParams(remoteUserId, conferenceID);
  console.log("connection is ",connection);
}

Step 3b: Callee (e.g. Bob): receives the call

At the callee, add setCallParams within the Twilio.Device.incoming() callback:

Twilio.Device.incoming(function (conn) {
  $("#log").text("Incoming connection from " + conn.parameters.From);
  // accept the incoming connection and start two-way audio
  conn.accept();
  
  // remoteUserId can be set by the developer. 
  // Or assign the userID already initialized in the Connection Object.
  // e.g., the remoteUserId is Alice.
  remoteUserId = conn.parameters.From.replace("client:", "");
  
  // The conferenceID can be set by the developer.

  // In this example, we are using the following scheme
  // The caller, uses the callee's name as the conferenceID.
  // and the callee, uses its name as the conferenceID.
  // this way both parties in the call use the same conferenceID.
  
  // Based on the figure above, the conferenceID is Bob, because Bob is recieving the call.
  conferenceID = conn.device._clientName;

  CallstatsTwilio.setCallParams(remoteUserId, conferenceID);
  console.log("connection is ",conn);
});

Reference Implementation

An integration with the Twilio Client sample app is available on GitHub.

Feedback

Send your comments and feedback to our groups/callstats-dev.