Web

The Help Lightning Web SDK is a JavaScript SDK that allows Help Lightning calls to be embedded into your web application.

Prerequisites

Before you can use the SDK, you must have an API Key which requires a Help Lightning site with an Enterprise Tier.

Installing the SDK

The latest version of the web SDK is 1.8.0

The Help Lightning web SDK is available from Help Lightning’s CDN. React and ReactDOM are bundled into the SDK. The only external dependency you must load yourself is the Zoom Video SDK.

Pin to a specific release by including the version in the URL. For example, to pin to 1.8.0:

<!-- Zoom Video SDK (required; version must match the Help Lightning release) -->
<script src="https://source.zoom.us/videosdk/zoom-video-2.4.5.min.js"></script>

<!-- Help Lightning Web SDK -->
<link rel="stylesheet" href="https://helplightning.net/hlsdk/1.8.0/style.css" />
<script src="https://helplightning.net/hlsdk/1.8.0/helplightning.umd.js"></script>

For EU sites, use the EU host instead:

<link rel="stylesheet" href="https://eu1.helplightning.net/hlsdk/1.8.0/style.css" />
<script src="https://eu1.helplightning.net/hlsdk/1.8.0/helplightning.umd.js"></script>

Do not load jQuery, OpenTok, or a separate PDF.js script tag. Those were required by the legacy lime-js SDK (5.28.x) and are not used by the current SDK.

Runtime assets (`assetBaseUrl`)

At call time the SDK loads Zoom /lib WASM/workers (and the PDF worker) from a base URL. Your page’s origin will not host those files, so you must point assetBaseUrl at the same CDN version path you loaded the bundle from:

const callClient = HL.CallClientFactory.CallClient;
callClient.assetBaseUrl = 'https://helplightning.net/hlsdk/1.8.0';

Using the SDK

The SDK exposes the HL namespace by default.

The first step is to create your CallClient from the factory, set assetBaseUrl, and set up your delegate, which will handle callbacks:

const callClient = HL.CallClientFactory.CallClient;
callClient.assetBaseUrl = 'https://helplightning.net/hlsdk/1.8.0';

callClient.delegate = {
  onCallEnded: (reason) => {
    console.log('HelpLightning call has ended', reason);
  },
  onCallEntered: (callId) => {
    console.log('Entered call', callId);
  },
  onActiveSessionsChanged: (sessions) => {
    console.log('Active sessions changed', sessions);
  },
  onWillJoinCall: (sessionId) => {
    console.log('Will join call', sessionId);
  },
  onScreenCaptureCreated: (dataUrl) => {
    // Full data URL, e.g. "data:image/png;base64,..."
    console.log('HelpLightning captured a screenshot');
    // TODO: save this or upload it somewhere
  },
  onRecordingUpdated: (recordingEnabled) => {
    console.log('HelpLightning recording status changed to:', recordingEnabled);
  }
};

Then you need to create a Call object. This should have all the necessary tokens and URLs of the server to join. This information is obtained by interacting with the server RESTful API to create a call/session between users. Typically, this is handled by your integration server.

// dataCenter selects the backend environment: 'dev' | 'eu1' | 'produs'
// (default 'produs'). Legacy values 'US' / 'EU' map to 'produs' / 'eu1'.
const call = new HL.Call(
  sessionId,
  sessionToken,
  userToken,
  gssUrl,
  apiKey,
  name,
  avatarUrl,
  'produs'
);

// start the call; pass a reference to the <div> container where the
// Help Lightning call will be embedded
const container = document.getElementById('hlcall');

callClient.startCall(call, container).then((callID) => {
  console.log('Call started...', callID);
}).catch((err) => {
  if (err instanceof HL.CallException) {
    console.error('Help Lightning error', err.message, err.code);
  } else {
    console.error('Error starting Help Lightning call', err);
  }
});

Theming

Basic branding is available through HL.Theme. Set the theme before calling startCall:

const theme = new HL.Theme();
theme.setUseCustomTheme(true);
theme.setColor(HL.ThemeKeys.COLOR_MAIN, '#181E21');

Only HL.ThemeKeys.COLOR_MAIN is applied today (as the brand / accent color). Other legacy theme keys are accepted but ignored.

Ending a call

callClient.stopCurrentCall();

Migrating from lime-js 5.28.x

If you are upgrading from the previous OpenTok-based web SDK, the call lifecycle API (HL.CallClientFactory, HL.Call, startCall, delegate assignment) is intentionally similar. The main deltas are:

Area	Legacy (5.28.x)	Current (1.8.x)
CDN path	`/sdk/<version>/`	`/hlsdk/<version>/`
Scripts	jQuery + `helplightning.min.js` + OpenTok + PDF.js	Zoom Video SDK + `helplightning.umd.js` + `style.css`
Runtime assets	Served beside the bundle	Set `callClient.assetBaseUrl` to the CDN version path
`HL.Call`	7 constructor args	Optional 8th arg: `dataCenter` (`dev` / `eu1` / `produs`)
Screen capture	Raw JPEG bytes (base64-encode yourself)	Full `data:` URL string
Theme	Full `Theme` / `ThemeKeys` surface	`COLOR_MAIN` only (other keys are no-ops)
Knowledge delegates	`onSelectShareKnowledge`, `onSelectKnowledgeOverlay`	Not present on the current delegate
Minimizing	`setMinimizingView`	Not present on the current delegate

Full example

<html>
  <head>
    <title>Remote Assistance</title>
    <meta charset="utf-8" />
    <script src="https://source.zoom.us/videosdk/zoom-video-2.4.5.min.js"></script>
    <link rel="stylesheet" href="https://helplightning.net/hlsdk/1.8.0/style.css" />
    <script src="https://helplightning.net/hlsdk/1.8.0/helplightning.umd.js"></script>
  </head>

  <body onload="startCall()">
    <div id="in-call-frame"></div>

    <script>
      function startCall() {
        var theme = new HL.Theme();
        theme.setUseCustomTheme(true);
        theme.setColor(HL.ThemeKeys.COLOR_MAIN, '#181E21');

        var params = getUrlVars();
        var callClient = HL.CallClientFactory.CallClient;
        callClient.assetBaseUrl = 'https://helplightning.net/hlsdk/1.8.0';

        callClient.delegate = {
          onCallEnded: function (reason) {
            console.log('Call ended', reason);
          },
          onScreenCaptureCreated: function (dataUrl) {
            // dataUrl is already a complete data: URL
            console.log('Screenshot ready', dataUrl.slice(0, 32) + '...');
          }
        };

        var call = new HL.Call(
          params['sessionId'],
          params['sessionToken'],
          params['userToken'],
          params['serverUrl'],
          params['apiKey'],
          decodeURIComponent(params['userName'] || ''),
          '',
          params['dataCenter'] || 'produs'
        );

        callClient.startCall(call, document.getElementById('in-call-frame'))
          .then(function (callID) {
            console.log('Call started', callID);
          })
          .catch(function (error) {
            if (error instanceof HL.CallException) {
              console.log('HL error: ' + error.message);
            } else {
              console.log('Unknown error: ' + error.message);
            }
          });
      }

      function getUrlVars() {
        var vars = {};
        window.location.href.replace(/[?&]+([^=&]+)=([^&]*)/gi, function (m, key, value) {
          vars[key] = value;
        });
        return vars;
      }
    </script>
  </body>
</html>

Session credentials (sessionId, sessionToken, userToken, serverUrl / GSS URL, apiKey) are provisioned via the server RESTful API.

Full Examples

Help Lightning maintains a working example in JavaScript. Please read through the documentation in the top level of the repository as it is necessary to run the sample integration server!

Javascript Sample

Web