openvidu-webcomponent 🔗

Check it on GitHub

OpenVidu Web Component is the simplest and quickest way to add videoconference capabilities to your existing web application. It brings many of the features of OpenVidu platform, making it very powerful. With just a few lines of code you will have your first video call working!

Running this tutorial 🔗

1) Clone the repo:

git clone -b v2.20.0

2) You will need an http web server installed in your development computer to execute the tutorial. If you have node.js installed, you can use http-server to serve application files. It can be installed with:

npm install -g http-server

3) Run the tutorial:

http-server openvidu-tutorials/openvidu-webcomponent/web

4) OpenVidu Platform service must be up and running in your development machine. The easiest way is running this Docker container which wraps both of them (you will need Docker CE):

# WARNING: this container is not suitable for production deployments of OpenVidu Platform
# Visit

docker run -p 4443:4443 --rm -e OPENVIDU_SECRET=MY_SECRET openvidu/openvidu-server-kms:2.20.0

5) Go to http://localhost:8080 to test the app once the server is running. The first time you use the docker container, an alert message will suggest you accept the self-signed certificate of openvidu-server when you first try to join a video-call.

If you are using Windows, read this FAQ to properly run the tutorial

To learn some tips to develop with OpenVidu, check this FAQ

Understanding the code 🔗

This application is very simple. It has only 4 files:

  • openvidu-webcomponent-{VERSION}.js: JavaScript file of OpenVidu Web Component. You don't have to manipulate this file.
  • openvidu-webcomponent-{VERSION}.css: styles for OpenVidu Web Component. You don't have to manipulate this file.
  • app.js: sample application main JavaScript file.
  • index.html: HTML code of the application.

Let's see how OpenVidu Web Component works:

index.html 🔗

Inside of the head section of index.html, we reference our app.js script and openvidu-webcomponent files:


    <!--... other imports ...-->

    <script src="app.js"></script>
    <script src='openvidu-webcomponent-{VERSION}.js'></script>
    <link rel="stylesheet" href="openvidu-webcomponent-{VERSION}.css">

As you can see, the index.html body has the form to connect to a video-session and the OpenVidu Web Component, which starts hidden:


    <!-- Form to connect to a video-session -->
    <div id="main" style="text-align: center;">
        <h1>Join a video session</h1>
        <form onsubmit="joinSession(); return false" style="padding: 80px; margin: auto">
                <input type="text" id="sessionName" value="SessionA" required>
                <input type="text" id="user" value="User1" required>
                <input type="submit" value="JOIN">

    <!-- OpenVidu Web Component -->
    <openvidu-webcomponent style="display: none;"></openvidu-webcomponent>


app.js (I): OpenVidu Web Component events 🔗

OpenVidu Web Component emits events sessionCreated, publisherCreated or error, so we can handle them in our JavaScript code.

NOTE: New event names and properties have been defined (sessionCreated , publisherCreated previous ones are still available (joinSession and leaveSession) but deprecated.

We just need to get the element once the document is ready and add all the listeners we want:

$(document).ready(() => {
    var webComponent = document.querySelector('openvidu-webcomponent');

    webComponent.addEventListener('sessionCreated', (event) => {
        var session = event.detail;

        session.on('connectionCreated', (e) => {
            console.log("connectionCreated", e);

        session.on('streamDestroyed', (e) => {
            console.log("streamDestroyed", e);

        session.on('streamCreated', (e) => {
            console.log("streamCreated", e);

        session.on('exception', (exception) => {

    webComponent.addEventListener('publisherCreated', (event) => {
        console.log("publisherCreated event", event);
        var publisher = event.detail;

        publisher.on('streamCreated', (e) => {
            console.log("Publisher streamCreated", e);
    webComponent.addEventListener('error', (event) => {
        // Do something

Now, we will be able to use session and publisher in the same way as if we used openvidu-browser directly, and of course use openvidu-browser API

In this tutorial, we just alternate the view between the form and the web component, hiding or showing them when receiving connectionCreated or sessionDisconnected events.

app.js (II): Configuring OpenVidu Web Component 🔗

Session Configuration 🔗

Method joinSession() gets:

  • The form input values, with the video-call to connect and the nickname the user will have in it.
  • The tokens from OpenVidu Server. Check out next point to see how this is done.

When we have our tokens available, the only thing left to do is to give the desired configuration to openvidu-webcomponent. To do so we use an object with three parameters: sessionName, user and tokens.

  • sessionName: the session name that will be displayed inside the component
  • user: the nickname that the user will have in the session
  • tokens: the retrieved tokens from OpenVidu Server

However, if we give the openvidu-url and openvidu-secret, the webcomponent will build the token for us.

async function joinSession() {
    var sessionName = document.getElementById('sessionName').value;
    var user = document.getElementById('user').value;
    var tokens = [];
    var form = document.getElementById('main');
    var webComponent = document.querySelector('openvidu-webcomponent'); = 'none'; = 'block';

    if(webComponent.getAttribute("openvidu-secret") != undefined && webComponent.getAttribute("openvidu-server-url") != undefined ){
    }else {
        var token1 = await getToken(sessionName);
        var token2 = await getToken(sessionName);
        tokens.push(token1, token2);
        webComponent.sessionConfig = { sessionName, user, tokens};

That's it. Once you configure the token into the webcomponent, it will automatically join the proper session (sessionCreated event will be dispatched so you can update your web). The user will see in the webcomponent all other users joined to the same session and will publish the webcam. You have a video-call working!

Interface Configuration 🔗

Optionally, you can add an extra JSON param inside of webcomponent.sessionConfig object named ovSettings. This parameter allows you to set up an extra custom interface. We have the choice to enabling or disabling the chat and each of the toolbar buttons. Besides, openvidu-webcomponent allows you configure your camera and audio device, your avatar and your nickname before join to the room. To do that, you only have to set autopublish property to false.

To do that, is necessary to declare the following ovSettings variable:

var ovSettings = {
  chat: true,
  autopublish: true,
  toolbar: true,
  footer: true,
  toolbarButtons: {
    audio: true,
    video: true,
    screenShare: true,
    fullscreen: true,
    layoutSpeaking: true,
    exit: true,

and add it inside of webcomponent.sessionConfig object:

webComponent.sessionConfig = { sessionName, user, token, ovSettings };

Get a token from OpenVidu Server 🔗

WARNING: This makes this tutorial an insecure application. We need to ask OpenVidu Server for a user token in order to connect to our session. This process should entirely take place in our server-side, not in our client-side. But due to the lack of an application backend in this tutorial, the JavaScript code itself will perform the POST operations to OpenVidu Server

The token must has inside of an array. If you want that the app allows the screen sharing you must include two differents tokens in the array. If you only add one, the app doesn't allow the screen sharing funcionality.

getToken(sessionName).then((token) => {
    // Send the 'token' to OpenVidu web component

In a production environment we would perform this operations in our application backend, by making use of the REST API, OpenVidu Java Client or OpenVidu Node Client. Here we have implemented the POST requests to OpenVidu Server in a method getToken() that returns a Promise with the token. Without going into too much detail, this method performs two ajax requests to OpenVidu Server, passing OpenVidu Server secret to authenticate them:

  • First ajax request performs a POST to /openvidu/api/sessions (we send a customSessionId field to name the session with our sessionName value retrieved from HTML input)
  • Second ajax request performs a POST to /openvidu/api/sessions/<sessionId>/connection (the path requires the sessionId to assign the token to this same session)

You can inspect this method in detail in the GitHub repo.

Extra features of OpenVidu Web Component 🔗

Alternatives to connect to OpenVidu session 🔗

In the example above, OpenVidu Web Component receives the sessionConfig parameter dynamically like this:

webComponent.sessionConfig = { sessionId, user, token };

But you can also set them statically, for example if you are building your template in the backend:

<openvidu-webcomponent session-config='{"sessionName":"SessionA", "user":"User1", "token": "[TOKEN_RETRIEVED_FROM_OPENVIDU_SERVER]"}'></openvidu-webcomponent>

Besides, openvidu-webcomponent allows you to add ovSettings parameter statically:

<openvidu-webcomponent session-config='{"sessionName":"SessionA", "user":"User1",               "ovSettings": {"chat": true, "autopublish": true, "toolbar": true, "footer": true, "toolbarButtons": {"audio": true,
 "video": true, "screenShare": true, "fullscreen": true, "layoutSpeaking": true, "exit": true }}}'>

And if you want to let the webcomponent get the token for you, you can just dispense with the token and provide two more attributes to it. This is only meant for developing purposes, as you need to hardcode the secret of your OpenVidu Server in the JavaScript code:

<openvidu-webcomponent  openvidu-server-url="https://localhost:4443" openvidu-secret="MY_SECRET" session-config='{"sessionName":"SessionA", "user":"User1", "ovSettings": {"chat": true, "autopublish": true, "toolbar": true, "footer": true, "toolbarButtons": {"audio": true, "video":true, "screenShare": true, "fullscreen": true, "layoutSpeaking": true, "exit": true }}}'>
WARNING: As you can see, when you add parameters to OpenVidu web component statically, you have to replace the camelCase with a hyphen between words.

Close the session dynamically 🔗

You can also disconnect the user from the session assigning dynamically empty object to the sessionConfig property :

ov.sessionConfig = {};

Choose a theme 🔗

OpenVidu allows you to choose between two themes. By default, the theme selected is dark theme but if you prefer change it for a light them, you can add theme="light"

<openvidu-webcomponent theme="light"></openvidu-webcomponent>

OpenVidu webcomponent allows you to replace the default static resources (icons and images). You only have to go to web/assets/images/ and add your custom images files with the following names:

  • openvidu_globe.png: The application icon.
  • openvidu_logo.png: The application logo.
  • poster.png: The application image which will appear when a participant has the video muted.