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

How to choose Identifiers: UserIDs, ConferenceIDs

Generating userID, conferenceID, and JWT

userID

The userID is expected to be unique, and the max length is 256 bytes. It is used by callstats.io to distinguish between different endpoints. The userIDs generated by the origin server and therefore the origin server decides if these identifiers are ephemeral or actual usernames.

callstats.io treats userIDs as opaque identifiers, the origin server MAY choose to pass the same identifiers as it is using or send a SHA1 hash of the username instead (where the username and domain are the ones used by the origin server). If you are not going to search by userID, we prefer that you use ephemeral userIDs. Alternatively, we support internationalization, and non-English named usernames, we automatically encode all incoming userID strings into UTF-8, and they are case-sensitive.

Typically, if the same user joins the conference via multiple means (devices or browsers) at the same time, the origin server MAY use the same userID. If the userID changes, the app MUST call initialize() again.

  • localUserID: The local userID that creates the PeerConnection, this userID is used when calling initialize()

  • remoteUserID: This is the userID of the remote peer, in a mesh topology this is the userID of the remote participant. Alternative, when communicating with a conferencing server there are two choices.

    1. Using multiple PeerConnections between a local userID and conference server: The number of PeerConnections perhaps uniquely match 1:1 with the number of participants in the session. That is, there may be one PeerConnection which just sends media to the conference server and multiple PeerConnections carrying MediaStreamTracks (MSTs) associated with different participants. In this case, it may be advisable to use the conferenceServerID as the remoteUserID for the outbound media, and the actual remoteUserIDs for the inbound media.

    2. Multiple MSTs in a PeerConnection: There is only one PeerConnection between the localUserID and the conference bridge and the PeerConnection carries all the MediaStreamTracks (MSTs) received at the bridge from the various participants. In this case, the remoteUserID is the name of the conference bridge (e.g., conferenceServerID). More discussion about this is covered in the following blog post.

Connections viewed by a single participant.Connections viewed by a single participant.

Connections viewed by a single participant.

UserID objects

In some cases, customers want to provide the actual username in addition to the alias to callstats.io. For example, the actual username can be accessed by the customer support, while the alias is shown to engineering team. The customer service representative needs to know the real names of the users to perform their work, while the engineering team does not. This functionality helps callstats.io separate the userID information and show the correct end-user information based on the user role.

Since callstats.js version 3.14, it accepts userID both as a String or an object.

conferenceID

The conferenceID is a unique call identifier to associate all userIDs in a conference. Therefore, all participants in a common call MUST use the same conferenceID. It is also generated by the origin server and MUST be temporally unique (i.e., for the duration of the call), the origin server MAY reuse the conferenceID identifier again for separate conferences at a later time, after the previous call using it has ended. The maximum length of the conferenceID is 256 bytes.

Like userIDs, callstats.io treats conferenceIDs as opaque identifiers, the origin server MAY use the same identifier as the one generated by the conference bridge, or use the URL of the page where the WebRTC call is taking place (e.g., www.example.com/conferenceID), concatenate current time-stamp with a random number, or pass a SHA1 hash of one of the above schemes. To enable internationalization, and non-English named conferenceIDs, we automatically encode all incoming conferenceID strings into UTF-8, and these strings are case-sensitive. This helps you as an app-developer or WebRTC service operator to easily perform dashboard search by directly copy-pasting (e.g., インターネット, интернэт, ອິນເຕີເນັດ).

The origin server MAY reuse the userID within the same conference call, i.e., two or more endpoints report using the same userID and conferenceID. while this is NOT RECOMMENDED, the callstats.io will still attempt to distinguish these userIDs as distinct entities.

❗️

Note

If the value of any developer generated String is empty, undefined, or null, the dashboard will show an empty string.

Updated 7 months ago


How to choose Identifiers: UserIDs, ConferenceIDs


Suggested Edits are limited on API Reference Pages

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