Webex Teams

SDK for Browsers

Integrate Webex Teams calling into your client-side JavaScript applications quickly

Features

Integrate the Browser SDK in client-side JavaScript applications. Place and receive video calls via the SDK:

  • Audio and/or video 1:1 calling
  • Group space calling new
  • Dial by email address, SIP address, or PSTN number new
  • Call and event controls
  • Audio and video call control
  • Maximum bandwidth controls new
  • View shared content new
  • Share screen from Firefox new
  • Share application from Firefox new
Getting Started Guide

In this example, we'll use Node.js to create a simple JavaScript web app that will make a single party call using Webex Teams.

If you're interested in interfacing with Webex Teams from your backend Node.js applications, check out the Webex Teams Node.js SDK.

Overview

  • Create a Node.js project with the Browser SDK
  • Make a Webex Teams call

Requirements

  • Node.js LTS 6.x and later, npm 3.x and later
  • Optionally: nvm to manage Node.js versions
  • Supported Browsers: Google Chrome (latest) or Mozilla Firefox (latest)

Step 1: Create the New Project & Install the SDK

  1. First, create the project directory and change directories into it, as shown below:

    mkdir sample-browser-single-party-call
    cd sample-browser-single-party-call
    

  2. Next, create a new project by using the node package manager (npm) to create a package.json file for your project:

    npm init
    

    You'll be asked several questions to initially configure the project. The npm init command will create a package.json file based on the options you select. The default settings will usually be good enough.

  3. Install ciscospark and save it to your package.json file, as shown below:

    npm install --save ciscospark
    

Step 2: Bundle/Compile the SDK

In this example we'll use Browserify to build the SDK and bundle it for use in our web app. We'll link the SDK via a <script> tag in our app.

Install Browserify

First, let's add Browserify to our project:

npm install --save-dev browserify

Next, let's create the a JavaScript file in our app to load the SDK: index.js. At the top of the file, require the ciscospark module:

window.ciscospark = require('ciscospark');

Bundle the SDK

To use the SDK in our web app, we'll need to bundle it into a file that can be used via a <script> tag in our app. Use the bundle command to include the SDK in a file called bundle.js. We'll include this file in our web app to use the SDK.

browserify index.js > bundle.js

Step 3: Create HTML for App

For this app, we'll create a very simple HTML file to load the SDK, provide a form to specify who we'll call, and buttons to dial and hangup. We'll wire up this form in JavaScript to make a call! Create a file called index.html in the root of the project directory with the following contents:

<!DOCTYPE html>
<html>
  <title>Webex Teams Call Quick Start</title>
  <body>
    <h1>Calling Quick Start</h1>
    <p>This sample demonstrates how to place a call using Webex Teams in the browser.</p>

    <form id="dialer">
      <input
        id="invitee"
        name="invitee"
        placeholder="Person ID or Email Address or SIP URI or Room ID"
        type="text">
        <input title="dial" type="submit" value="dial">
    </form>

    <div style="display: flex">
      <video style="width:50%" id="self-view" muted autoplay></video>
      <video style="width:50%"id="remote-view" autoplay></video>
    </div>

    <button id="hangup" title="hangup" type="button">cancel/hangup</button>

    <!-- /bundle.js is the bundled CiscoSpark Browser SDK -->
    <script src="/bundle.js"></script>
    <!-- app.js is your application code -->
    <script src="app.js"></script>
  </body>
</html>

Step 4: Authenticate App with Webex Teams

For this example, we'll use your personal OAuth development token from the Webex for Developers portal. This token provides access to your account for testing purposes, and shouldn't be used for anything other than testing. If you're logged into this site, you can see your token by clicking on your avatar in the top right corner of this page. If you don't already have a Webex Teams account, click Sign Up to create an account.

Authenticate with Webex Teams

Create a new file called app.js. This file will have the main application logic for the web app. At the top, add this code to authenticate with Webex Teams, replacing YOUR_ACCESS_TOKEN with your development token:

spark = ciscospark.init({
  credentials: {
    access_token: `YOUR_ACCESS_TOKEN`
  }
});

Step 5: Create JavaScript App

All of the calling functionality for this app will live in our app's main JavaScript file, app.js. We'll wire it up to our HTML file to make the call.

Register with Webex Teams Cloud

We'll need to register with the Webex Teams Cloud before attempting to make a call. Add the following code to your app.js file:

spark.phone.register()
.catch((err) => {
  console.error(err);
  alert(err);
  throw err;
});

Set up Event Listeners for Call Events

When we make a call, the SDK will generate several events to keep us informed about the call's progress such as media stream changes, hangups, etc. Let's watch for these events by adding this code:

function bindCallEvents(call) {
  call.on(`error`, (err) => {
    console.error(err);
    alert(err);
  });

  call.once(`localMediaStream:change`, () => {
    document.getElementById(`self-view`).srcObject = call.localMediaStream;
  });

  call.once(`remoteMediaStream:change`, () => {
    document.getElementById(`remote-view`).srcObject = call.remoteMediaStream;
  });

  call.on(`disconnected`, () => {
    document.getElementById(`self-view`).srcObject = document.getElementById(`remote-view`).srcObject = undefined;
    call = undefined;
  });

We'll also want to know if we click the hangup button. Add a listener for the hangup button:

document.getElementById(`hangup`).addEventListener(`click`, () => {
  call.hangup();
});
}

Set up Event Listener for the Dial Button

In our simple HTML page, we added a form with a few buttons to start and end the call. Let's add an event listener to initiate the call when the dial button is clicked:

document.getElementById(`dialer`).addEventListener(`submit`, (event) => {
  event.preventDefault();

  const call = spark.phone.dial(document.getElementById(`invitee`).value);

  bindCallEvents(call);
});

Now, when we click dial, we'll use the SDK's phone.dial instance method to start the call.

Step 6: Load the Web App

Let's load the web app in our browser to make a call! First, install and start a simple web server (httpster) to serve our web app.

npm install -g httpster
httpster

By default, httpster will listen on port 3333. Open the app (http://localhost:3333) in your browser to use your new web app! Enter the Person ID or email address of who you want to call and click the dial button. Congratulations, you've made your first call in the browser using the Webex Teams Browser SDK!

To see the full example code we have used here to place a single party call, check out the sample app in GitHub.

Browser SDK Samples

We've put together several samples of the Browser SDK in action. All of the sample code is available in GitHub. Take the SDK for a spin with a live demo and check out the sample code:

Sample Description Live Demo Sample Code
Single Party Call Make or receive 1:1 video calls with another Webex Teams user Demo JS | HTML
Single Party Call with Mute Make or receive 1:1 video calls with another Webex Teams user, with the option to mute your audio and/or video streams Demo JS | HTML
Multi Party Call Start or join a Webex Teams video call with multiple participants Demo JS | HTML
Call with Content Sharing Make or receive video calls with the ability to share your screen or an application (Firefox only) Demo JS | HTML
Authentication - Implicit Grant Flow Authenticate as a Webex Teams user with the Implicit Grant Flow Demo JS | HTML
Authentication - Guest Issuer Authenticate as a Webex Teams guest user with a Guest Issuer token Demo JS | HTML
Troubleshooting the Browser SDK

If you're having trouble with the Browser SDK, here's some more information to help troubleshoot the issue.

SDK Requirements

Review the following SDK requirements to make sure you're using the correct minimum versions of Node.js, npm, etc.:

  • Node.js LTS 6.x and later
  • npm 3.x and later
  • Optionally: nvm to manage Node.js versions
  • Supported Browsers: Google Chrome (latest) or Mozilla Firefox (latest)
  • A Webex Teams account and an integration with the necessary scopes

Additional Logging

You can add additional logging to your application to help narrow down any issues with the SDK.

Change the Log Level Within Your App

Set the log level to info to see more logging to help troubleshoot the issue:

spark.config.logger.level = `info`;

To see even more logging, set the log level to debug.

Firewall Ports

The Browser SDK makes use of several network protocols and ports. If you're encountering connection or connectivity issues, make sure there aren't any firewalls blocking or preventing communication with any Webex Teams endpoints. For more information about the network and web security requirements for Webex Teams services, please see this Webex Teams help article.

Getting Support

If you're stumped, contact the Webex Developer Support team for more help with the SDK.