Twilio Voice

Twilio Voice is a cloud communications platform enabling phones, VoIP, and messaging to be embedded into web, desktop, and mobile software. The platform enables software developers to programmatically make and receive phone calls and send and receive text messages using its web service APIs.

See also Twilio Video.

Integration steps

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:

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 and it will return callstats object
  // callstats object can be used to call all the native callstats.io APIs
  
  var callstats = 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);
});