OpenTok Developer Guide

In these pandemic situations nowadays, video calling is now making interaction easy. Such video call integration platforms like OpenTok make development easy. Let’s make OpenTok easier to understand and start with some basics of OpenTok and overview, continuing with will go through the authentication process and connecting and disconnecting sessions.

What Is OpenTok?

OpenTok is a platform that provides API to stream live video calling functionality into our web application. It allows many features to integrate into web applications like screen sharing, text chat, and many more.

Overview Of OpenTok

opentok overview

Why To Choose OpenTok?

The best part of the OpenTok platform is it doesn’t store data into their servers. They provide an archive API to store the streaming data into their server or path which we provide. All data is encrypted while streaming, which is the best security they provide, even if we use public hotspots.

What Are The Encryption Algorithms And Strength Of The Keys Being Used?

– OpenTok WebRTC-compatible endpoints use the AES cipher with 128-bit keys to encrypt audio and video, and HMAC-SHA1 to verify data integrity.

– End to end encryption and serve content using HTTPS URLs (All API are secured with secured layers https)

What Keys Are Being Used For The Encryption?

The endpoints generate random keys at the beginning of the session and in addition, they change periodically during the conversation to make it even safer.

Simple And Easy To Understand

– OpenTok is easy to understand and implement and available for all platforms

– Only needs to understand the concept of subscriber and publisher, Yes you are ready to call now.

How Does OpenTok Support HIPAA Compliance Or PHI?

HIPAA requires a secure channel between the communication of patients and doctors, but As I mentioned earlier OpenTok does not store data into their servers unless we set options as an archive while connecting or calling archive API. Because encryption data security is maintained, secures data transmission between patient and doctor.

“Wide range of healthcare companies who have elected to build applications utilizing the OpenTok platform”.

Alerts And Controls Provided By OpenTok Related To Connections

-Limit the maximum number of users in a session.

-Display subscribers count.

-Set up Moderator permissions to force a disconnect.

-Allocate Subscriber-only permissions for those that do not need to publish.

How OpenTok Gives Best Results

There are many companies such as — PubNub, Sinch, Quickblox, and Twilio whose source code can be integrated with third-party APIs like — WebRTC, Restful, and JavaScript, etc. But, OpenTok

  • Supports multiple platforms like IOS, web, android.
  • Provides SDK for all platforms.
  • Gives the best security for all streams connected.
  • Provides REST API for integration.
  • Charges apply on subscribing to the call it means when the call is connected.
  • Provides features and functionality to set the video call quality, volume and many more
  • A very important part of video calling is auto-connect when the internet is off, due to many reasons video calling can be interrupted.

Things To Be Noted

How To Start With OpenTok?

Steps To Generate

  1. Create your account. Go to -> create a project
  2. Get AP I and Secret Key to connect with the OpenTok API.
  3. Authenticate your API and Secret Key using JWT.


    "iss": "12345678",
    "ist": "project",
    "iat": 1588667570,
    "exp": 1588900001

iss is project API key.

ist can be “project” or “account” for session creation project is passed

iat is current epoch timestamp in seconds

exp is expiration time will be maximum 5 mins

Generates JWT token


Generating tokens in JAVA

import com.OpenTok.TokenOptions;
import com.OpenTok.Role;

// Generate a token from just a sessionId (fetched from a database)

String token = OpenTok.generateToken(sessionId);

// Generate a token by calling the method on the Session (returned from createSession)

String token = session.generateToken();

// Set some options in a token
String token = session.generateToken(new TokenOptions.Builder()

.expireTime((System.currentTimeMillis() / 1000L) + (7 * 24 * 60 * 60)) // in one week

4. Create A Session And Get Your SessionId

Create session

REST API calls must be authenticated using a custom HTTP header — X-OpenTok-AUTH — along with a JSON web token

Type: POST

Headers :

headers: { ‘X-OpenTok-AUTH’:’Token’, ‘Content-Type’: ‘application/json’ },

Pass params :

location: IP address
ArchiveMode: always (to archive the session automatically by default it’s manual, we can archive session by calling REST /archive POST method).
p2p.preference: disabled (if archiveMode is always)


        "properties": null,
        "session_id":        "1_MX40NjcyMDI3Mn5-MTU4ODY4Mzc3MDYyNn5jRmRCcjk2cy9Ndk1MOFBVQzlKYjZHUHF-fg",
        "project_id": "12345678", // api key
        "partner_id": "12345678",
        "create_dt": "Tue May 05 06:02:50 PDT 2020",
        "session_status": null,
        "status_invalid": null,
        "media_server_hostname": null,
        "messaging_server_url": null,
        "messaging_url": null,
        "symphony_address": null,
        "ice_server": null,
        "session_segment_id": "2736846a-cf56-417f-9d94-6116b07fd71a",
        "ice_servers": null,
        "ice_credential_expiration": 86100

5. Init Session – Session Initialization Will Allow To Publish And Subscribe The Session

// Replace with your OpenTok API key and session ID:

var session = OT.initSession(apiKey, sessionID);

6. Create Connection Using Connect Function (Use JWT Token)

session.connect(token, function(error) {
  if (error) {
    console.log("Error connecting: ",, error.message);
  } else {
    console.log("Connected to the session.");


7. The Session Can Be Disconnected Due To An Any Error, Find The Error By Listening To The “SessionDisconnected” Event And Find The Reason Using “Event.Reason

  sessionDisconnected: function(event) {
    if (event.reason === 'networkDisconnected') {
      showMessage('You lost your internet connection.'
        + 'Please check your connection and try connecting again.');


Now we have done with creating a connection. I hope you like it and surely help you out to start with OpenTok, we will learn more about how to start with video calling and how chat applications can be built using OpenTok.

Part II of this article, Let’s start with Video Calling

I hope you guys have read OpenTok Guide in which I have mentioned some basics of opentok and initializing the sessions. Now, Let’s start with creating, destroying connections and publishing and subscribing sessions to start the video call and signaling events.

Note:  We are referring to the examples of javascript or typescript. If you are using angular typescript then we need to use npm package npm i @opentok/client --save



The Session object dispatches a connectionCreated event when a client (including your own) connects to a Session. It also dispatches a connectionCreated event for every client in the session when you first connect.

While you are connected to the session, the Session object dispatches a connectionDestroyed event when another client disconnects from the Session

session.on("connectionCreated", function(event) {
session.on("connectionDestroyed", function(event) {


The Publisher object provides the mechanism through which control of the published stream is accomplished. Calling the OT.initPublisher() method creates a Publisher object.

var publisherProperties = {width: 400, height:300, name:"Bob's stream"};
publisher = OT.initPublisher('publisherElement', publisherProperties);
  • Show default UI make insertDefaultUI property true else false.
  • Show default controls make showControls property true or false.
  • Set facingMode property to “user” for facing mode,”environment” for rear view.
  • For audio call you can just pass false to publishAudio(value) function in OT.initPublisher() function.

Other than these properties we have:

Custom properties:

Disable audio properties : (Mute and unmute mic)

If value is true audio is enabled else audio is disabled.


Disable video properties : (Enable and disable camera)

If value is true video is enabled else video is disabled.


Switching the camera : (Front and Rear)


Unpublish publisher whenever user gets disconnected.



Once a user is published a stream is created on another side. When you subscribe to a stream, its video stream appears in the client page and its audio is played.

Session dispatches “streamCreated” event whenever user publishes.
session.on("streamCreated", function (event) {
   console.log("New stream in the session: " +;

Subscribe a stream

We need to subscribe to the stream to show the published user on another side.

session.subscribe(stream, replacementElementId);

We can subscribe the stream when streamCreated event is dispatched

session.on('streamCreated', function(event) {
  var subscriberProperties = {insertMode: 'append'};
  var subscriber = session.subscribe(,
    function (error) {
      if (error) {
      } else {
        console.log('Subscriber added.');

Unsubscribe a stream

Unsubscribing from a stream can be done when we want to remove the person from the call or user leaves the call.



When a stream, other than your own, leaves a session the Session object dispatches a streamDestroyed event.

session.on("streamDestroyed", function (event) {
console.log("Stream stopped. Reason: " + event.reason);

The streamDestroyed event is defined by the StreamEvent class. The event includes a reason property, which details why the stream ended. These reasons include “clientDisconnected”, “forceDisconnected”, “forceUnpublished”, or “networkDisconnected”


Subscriber gives more information regarding the reconnecting the video call.

  disconnected: function() {
    // Display a user interface notification.
  connected: function() {
    // Adjust user interface.
  destroyed: function() {
    // Adjust user interface.

You can add your custom messages inside the function.
Subscriber can also detect whether subscribers audio is blocked to show mute icon on subscribers side.

  audioBlocked: function(event) {
   console.log("Subscriber audio is blocked.")
  audioUnblocked: function(event) {
   console.log("Subscriber audio is unblocked.")

You can stream information whenever property is changed.


Signaling can be used for chat while video call, where “data” property can be used for passing messages.

  • Signals can be sent to all clients connected in the session.
  • Signals can be sent to a specific client.


Sending messages to specific client (user)

To send a signal to a specific client in a session, call the signal() method of the Session object and set the to property of the signal parameter. Here,

“to” parameter is used to send the signal to a specific client which should be connectionId,
“data” is used to pass messages which will be received in the event object.
“type” is used to separate out the type to receive a specific message.

    to: connection1,
  function(error) {
    if (error) {
      console.log("signal error ("
                   + "): " + error.message);
    } else {
      console.log("signal sent.");

Sending messages to all clients (users)

  function(error) {
    if (error) {
      console.log("signal error ("
                   + "): " + error.message);
    } else {
      console.log("signal sent.");

You can receive the signal by listening to the signal event.

session.on("signal", function(event) {
      console.log("Signal sent from connection " +;
      // Process the property, if there is any data.

Receiving the signal using type “signal:type”

session.on("signal:foo", function(event) {
 console.log("Signal sent from connection " +;
 // Process the property, if there is any data.

Disconnect session

Disconnecting sessions will disconnect all the clients in the session. This can be done from the publisher side.

To start with a new call, you need to again initialize the session using OT.initsession().


Calling Disconnect method will dispatch the events

sessionDisconnected If stream is connected streamDestroyed and connectionDestroyed.

I hope this blog will help you to now create your own video calling application.

Keep Reading

Keep Reading

Struggling with EHR integration? Learn about next-gen solutions in our upcoming webinar on Mar 6, at 11 AM EST.

Register Now

Let's create something together!