JavaScript SDK Quickstart Guide

Getting Started

1. Add Web Application in Webex Connect
2. Setup FCM for Chrome and Firefox Browsers
3. Download and Integrate JavaScript SDK in your Website
4. Code Integration

1. Add Web Application in Webex Connect

To view how to create Web App Asset, visit Web App Asset in Webex Connect

2. Setup FCM for Chrome and Firefox Browsers

Please follow this link to learn how to set up Firebase Cloud Messaging (FCM) for Chrome and Firefox browsers.

3. Download and Integrate JavaScript SDK in your Website

To download and integrate the JavaScript SDK into your website, please refer to the detailed instructions provided here.

4. Code Integration

Here is a summary of the process required to implement Live Chat Messaging.

1. Include SDK
2. Startup plugin
3. Check if user is already registered
4. Register user
5. Register Listener for Live Chat Messaging
6. Connect
7. Create a thread
8. Send message using publishMessage

1. Include SDK

If you have downloaded the SDK files up to version v1.7.x, Please refer to the Include SDK section on Integration Steps for JavaScript until v1.7.x.

How to integrate the latest JavaScript SDK

1. To download the JavaScript SDK, go to GitHub page. Download and extract dist.zip.
   1. Create an assets/js folder in your project.
   2. Copy webex-connect-sdk.min.js and imi-environment.js to assets/js/ folder.
2. Move the service worker file sw.min.js to root of your project. You can specify a subfolder if needed as per steps outlined in Managing Assets page.
3. Include dependencies.
   JavaScript

   <script src="https://code.jquery.com/jquery-1.12.4.js"></script>
   

4. For Push Notifications, include Firebase SDK files
   1. Include supported Firebase SDK files
      JavaScript

      <script type="text/javascript" src="https://www.gstatic.com/firebasejs/11.1.0/firebase-app-compat.js"></script>
      <script type="text/javascript" src="https://www.gstatic.com/firebasejs/11.1.0/firebase-messaging-compat.js"></script>
      

   2. Include manifest.json file.
      Copy the extracted manifest.json from dist.zip into the same assets/manifest/ folder.
      JavaScript

      /assets/manifest/manifest.json
      

5. Include JavaScript SDK files in your HTML page:

<script src="assets/js/imi-environments.js"></script>
<script type="text/javascript" src="assets/js/webex-connect-sdk.min.js"></script>  

imi-environments.js file is available from the Downloads section using Webex Connect UI. Refer to Create a Mobile App Asset in Webex Connect section for more information.

📘

Migrate from previous SDKs

If you have downloaded the SDK files up to version v1.7.x, please refer to the Migrate from previous SDKs page for more information.

2. Startup plugin

In Browser Console, verify if the plugin is available by typing IMI. It should output this:

Follow below step to setup Live Chat Messaging

Call plugin’s startup() method:

IMI.IMIconnect.startup();

📘

Note

Refer Managing Assets for managing multiple assets and paths.

startup(callback, inputConfig)

Initializes the SDK. The method now accepts an optional inputConfig object that provides the full environment configuration at runtime, removing the requirement to define environments in imi-environments.js beforehand.

Syntax:

IMI.IMIconnect.startup(callback, inputConfig)

Parameters

Example - Single app (legacy, unchanged):

IMI.IMIconnect.startup();

Example - With dynamic config:

var config = {
    asset: {
        appId: "YOUR_APP_ID_A",
        appSecret: "< your App Secret here >",
        pathConfig: { assetPath: "/assets/", root: "/" }
    },
    imiclient: {
        authdomain: "https://your-auth-domain.com",
        rtmsdomain: "wss://your-rtms-domain.com",
        shouldRequestNotificationPermission: true,
        config: {
            apiKey: "< your Firebase API key >",
            projectId: "< your Firebase project ID >",
            messagingSenderId: "< your sender ID >",
            appId: "< your Firebase app ID >"
        }
    },
    sw: {
        config: {
            appid: "YOUR_APP_ID_A",
            serverUrl: "https://your-server.com"
        }
    }
};

IMI.IMIconnect.startup(null, config);

📘

Note

When inputConfig is provided, the target field in imi-environments.js is ignored. Each startup() call creates an isolated app instance with its own Service Worker scope, storage namespace, and messaging connection.

3. Check if user is already registered

IMI.IMIconnect.isRegistered()

4. Register user

var userID = 1;
var deviceID = userID + new Date().getTime(); //any random no.
var deviceProfile = new IMI.ICDeviceProfile(deviceID, userID);
var registerCallback = {
   onSuccess: (msg) => {
      console.log(msg);
   },
   onFailure: (err) => {
      console.log(err);
   },
};
IMI.IMIconnect.register(deviceProfile, registerCallback);

📘

Note

The SDK automatically unregisters the app user if the app isn't opened for over 40 days. To ensure a seamless user experience, always check if the user is registered by calling isRegistered whenever the app launches, and if not registered, register the user with register. For further details of the profile clean up process, including how profiles are deemed inactive, please see this article.

5. Register Listener for Live Chat Messaging

var msgCallBack = {
   onConnectionStatusChanged: (statuscode) => {
      console.log('onConnectionStatusChanged to', statuscode);
   },
   onMessageReceived: (message) => {
      console.log('onMessageReceived ', message);
   }
};
var messaging = IMI.ICMessaging.getInstance();
messaging.setICMessagingReceiver(msgCallBack);

6. Connect

In registration onSuccess callback, add below code:

var messaging = IMI.ICMessaging.getInstance();
if (!messaging.isConnected())
   messaging.connect();

Create a thread

createThread(title) {
   var title = title || "New Conversation";
   var thread = new IMI.ICThread();
   thread.setTitle(title);
   thread.setStatus(IMI.ICThreadStatus.Active);
   thread.setType(IMI.ICThreadType.Conversation);
   var messaging = IMI.ICMessaging.getInstance();
   messaging.createThread(thread, createThreadCallBack);
}
createThreadCallBack = {
   onSuccess: (threadObj) => {},
   onFailure: (err) => {

   },
};

Send message using publishMessage

var publishMessageCallback = {
   onSuccess: function (msg) {
      console.log("message sent", msg);
   },
   onFailure: function (errormsg) {
      console.log("failed to send message", errormsg);
   },
};

function publish() {
   var text = "Sample message text";
   var message = new IMI.ICMessage();
   message.setMessage(text);
   message.setThread(icThreadObj);
   var messaging = IMI.ICMessaging.getInstance();
   messaging.publishMessage(message, publishMessageCallback);
}

To set up push notifications, please follow this link: Sending Push Messages to Customers

New Method: uninit

Tears down the current app instance gracefully without reloading the page. Use this method for app switching or per-app logout. This method returns a promise, which should be awaited before the app switch.

Syntax:

IMI.IMIconnect.uninit()

Parameters: None.

Behavior

• Deregisters the current tab from the Service Worker's client map.
• Removes the Firebase messaging app instance.
• Clears all in-memory state, including tokens, config, flags, and listeners.
• Does not unregister the device from the server. The device profile persists.
• Does not explicitly disconnect MQTT. The Service Worker auto-disconnects when no tabs remain for the app.

Note: uninit() is designed for app switching without de-registering the account. Other tabs using the same account are not affected. Background push notifications continue to work because the device remains registered on the server and the Service Worker stays active.

Example - App switching:

// Tear down current app
await IMI.IMIconnect.uninit();

// Initialize a different app
IMI.IMIconnect.startup(null, imiEnvironments["OTHER_APP"]);

Example - Per-app logout (without device unregister):

await IMI.IMIconnect.uninit();
// User stays on page, app state cleared, ready to init again