Embedded buttons and SDK controls

Create custom launcher buttons and control the chat and video experience in your web app using methods from the Zoom Customer Experience SDK for web.

SDK initialization check

The SDK script loads when the page loads, but won't fully load until resource allocation completes. Before executing any SDK functions, perform the zoomCampaignSdk:ready check to avoid an undefined error in the console and ensure proper execution of the SDK.

window.addEventListener("zoomCampaignSdk:ready", () => {
    // customer can do something here:
    // ...
    // eg. using it to open campaign
    zoomCampaignSdk.open();
});

SDK capabilities

Use the SDK to perform specific tasks, such as open, close, or send a message. The following reference shows the events and methods available.

enum Events{
    OPEN:"open";
    CLOSE:"close";
    SHOW:"show";
    HIDE:"hide";
    SEND_MESSAGE:"send_message";
}
zoomCampaignSdk:{
    open(): void;
    close(): void;
    show(): void;
    hide(): void;
    endChat(): void;
    on(eventName:"string",handler:any): void;
    off(eventName:"string",handler?:any): void;
}

After receiving zoomCampaignSdk:ready, call these methods or listen for these events in your code.

window.addEventListener("zoomCampaignSdk:ready", () => {
    window.zoomCampaignSdk.open();
});

Explicit SDK interactions

Use the SDK to open, close, or hide the chat or video modal.

if (window.zoomCampaignSdk) {
    // To open the Contact Center modal and start a new conversation if one has not started
    window.zoomCampaignSdk.open();
    // To hide the Contact Center modal, including the invitation
    window.zoomCampaignSdk.hide();
    // To show the Contact Center modal, including the launcher widget
    window.zoomCampaignSdk.show();
    // To close or collapse the modal so that only the launcher widget is visible
    window.zoomCampaignSdk.close();
}

if (window.zoomCampaignSdk) {
    // To open the Zoom Virtual Agent modal and start a new conversation if one has not started
    window.zoomCampaignSdk.open();
    // To hide the Zoom Virtual Agent modal, including the invitation
    window.zoomCampaignSdk.hide();
    // To show the Zoom Virtual Agent modal, including the launcher widget
    window.zoomCampaignSdk.show();
    // To close or collapse the modal so that only the launcher widget is visible
    window.zoomCampaignSdk.close();
    // To end engagement, keep the Zoom Virtual Agent modal as it is
    window.zoomCampaignSdk.endChat();
}

Initialize the SDK

Provide required parameters, such as your API key, when you initialize the SDK.

Script tag

Import the SDK using script tags and copy parameters directly in the admin backend. When importing with script tags, pass parameters directly as tag attributes, converting camelCase names to the data- attribute format (for example, someParamItem becomes data-some-param-item).

For some websites, using jQuery to load a script tag to introduce the SDK may result in the SDK being unable to read the apikey parameter, causing it to fail to function properly. To fix this, add parameters globally so that the SDK can read the relevant parameters.

window.zoomCampaignSdkConfig = {
    env: "your_env",
    apikey: "your_apikey",
};

JavaScript

Import the SDK using JavaScript, replacing the example values below with values from the campaign script.

<script>
    (function () {
        const el = document.createElement("script");
        el.type = "module";
        el.setAttribute("data-apikey", "your_apikey");
        el.src = "https://test.example.com/sample/web-sdk/chat-client.js";
        document.body.appendChild(el);
    })();
</script>

Development mode

In development mode only, concatenate parameters after the URL.

https://xx.example.com/test.html?apikey=your_apikey

Parameters

The following table describes parameters you can use when initializing the SDK.

Troubleshooting

Here are some common issues you may encounter and their solutions.

When importing the SDK with the script tag, the script doesn't load properly when clicking on a third-party website link

If the script tag has the defer attribute, clicking a link to a third-party site while the page is still loading may cancel the script's execution. Remove defer, or change it to async, to resolve the issue.

Why can't the menu in the upper right corner be displayed when I click it?

Due to CSS level issues, if either the body or html element has overflow: hidden set, the popup layer may not be displayed correctly. Check if there is a style definition for the body or HTML elements.

body,
html {
    overflow: hidden;
}