JS SDK

Previous Next
SUPSIS JS SDK v2.0 ● Web Widget Integration & Automation API

Supsis JavaScript SDK Reference

Integrate the live support chat widget on your website, synchronize user data, and manage 182+ Core & Automation SDK methods remotely.

🔍 Search 182+ API Methods / Jump to Reference ↓

1. Integration Setup

To add the Supsis Chat Widget to your website, insert the following script snippet inside the <head> section of every page.

💡 SDK Advantages & Features:
  • The Supsis SDK loads asynchronously without affecting your site's page load performance.
  • Include it only on pages where you want the chat widget to be visible.
  • Once the SDK loads and becomes ready, the widget appears automatically.

Integration Code

<script>
  window.supsis = window.supsis || function () {
    (supsis.q = supsis.q || []).push(arguments);
  };
  supsis.l = +new Date;
</script>

<script
  src="https://SITE_DOMAIN_NAME.visitor.supsis.live/static/js/loader.js"
  type="text/javascript"
  async
  defer>
</script>
📌 Domain Configuration: Replace SITE_DOMAIN_NAME with your unique domain name registered with Supsis.
If you are using IdeaSoft, your IdeaSoft domain name will serve as your Supsis domain name. (e.g. SITE_DOMAIN_NAME=market71 if logging in via market71.supsis.live).

2. SYNC API & Method Comparison

The SYNC API uses the supsis. syntax, whereas the ASYNC API uses the supsis() syntax. Both synchronous and asynchronous calls are fully supported.

METHOD SYNC API Usage
Open Chat Window supsis("open") / supsis.open()
Minimize Chat Window supsis("minimize") / supsis.minimize()
Hide Chat Widget supsis("hide") / supsis.hide()
End Conversation supsis("closechat") / supsis.closeChat()
Set User Data supsis("setUserData",{fullname:'Ali',email:'a@a.com',phone:'5396829048'})
Set Contact Properties supsis("setContactProperty",{badget:'gold-member'})
Mark Visitor as VIP supsis("setVisitorVip", false) 
supsis("ready", (supsis) => {
    // You can use supsis synchronously within this scope
    supsis.open();
    supsis.setUserData({ fullname: "Ali", email: "a@a.com", phone: "5396829048" });
});

Alternatively, you can load the SDK synchronously and run your custom scripts immediately afterwards:

⚠️ Performance Note: Synchronous loading may introduce a slight overhead to initial page load speeds. 
<script src="https://SITE_DOMAIN_NAME.visitor.supsis.live/static/js/loader.js" type="text/javascript">
    supsis.open()
    supsis.setUserData({fullname:'Ali',email:'a@a.com',phone:'5396829048'})
</script>

3. ASYNC API Methods

Since the Supsis SDK loads asynchronously, your API calls will execute sequentially after initialization.

Configuration Syntax:

supsis(API_FUNCTION_NAME, payload);
  • "API_FUNCTION_NAME" is a string representing the target method (e.g. supsis("open")).
  • payload is passed whenever the method requires parameters.

Visitor Management Methods

// Mark Visitor as VIP (false = Not VIP, true = VIP)
supsis("setVisitorVip", false);

// Minimize Chat Window
supsis("minimize");

// Hide Chat Widget
supsis("hide");

// Open Chat Window
supsis("open");

// End Conversation
supsis("closeChat");

// Switch Department
supsis("department", "$DEPARTMENT_TITLE");

Department Reason

* Department title values must match across all languages.

4. Updating Visitor Information and Login Form Data

If you supply your visitors' personal information to the Supsis SDK before they click on the chat bubble, their details will be configured automatically. Customers can start chatting directly using their logged-in name, email address, and phone number.

ℹ️ Note: If user data is not provided, the chat conversation begins with the credentials gathered via the standard Supsis Login Form.

Updating Visitor Info for Default Login Form

supsis("setUserData", {
    fullname: "Logged-in user's full name",
    email: "Logged-in user's email address",
    phone: "Logged-in user's phone number",
});

Updating Visitor Info for Custom Login Form

  • Mandatory fields in custom login forms: fullname, email, phone
  • Additional fields can be added as needed. Each field must have a designated identifier.

Sample custom login fields: (fullname, email, phone, identityNumber)

Custom Login Form

supsis("setUserData", {
    fullname: "John Doe",
    email: "jonh.doe@gmail.com",
    phone: "5396829048",
    identityNumber: "13451123445",
});

5. Updating Custom User Contact Properties

You can dynamically update custom contact properties configured via the Supsis dashboard through the SDK. This is ideal for identifying customer tier levels or segment tags when connecting to live chat support.

Example Scenario: Defining User Membership Rank

To pass customer membership rank, create a custom label named User Rank in the admin panel:

User Rank Tag

Then execute the setContactProperty method to assign the label:

supsis("ready", (supsis) => {
    // Event listener when Supsis is fully initialized
    const member = {
        badget: "gold_member",
    };
    supsis.setContactProperty({ badget: member.badget });
});

5.1 Webchat Event Listeners & GTM Integration

The Supsis Web Widget triggers clientside JavaScript events upon critical visitor interactions, such as clicking the chat bubble or establishing a live connection with an agent. By listening to these events, you can dispatch real-time conversion events into Google Tag Manager (GTM), Google Analytics 4 (GA4), or Meta Pixel.

GTM dataLayer Integration Code

// 1. Chat Bubble Click Event (Widget Opening)
supsis("ready", (supsis) => {
    if (supsis.i && supsis.i.openButton) {
        supsis.i.openButton.addEventListener("click", () => {
            window.dataLayer = window.dataLayer || [];
            window.dataLayer.push({
                event: "supsis_chat_opened",
                event_category: "Supsis Webchat",
                event_action: "Chat Bubble Opened"
            });
        });
    }
});

// 2. Visitor Connected to Live Support Event
window.addEventListener("message", function (e) {
    if (e.data && e.data.command === "visitor-connected") {
        window.dataLayer = window.dataLayer || [];
        window.dataLayer.push({
            event: "supsis_visitor_connected",
            event_category: "Supsis Webchat",
            event_action: "Live Support Connected",
            chat_id: e.data.id || null
        });
    }
});

Live Console Verification

You can verify that event listeners trigger properly in your browser console (F12) as shown below:

Supsis GTM Event Console Test Verification

6. Programmatic WhatsApp Bulk Messaging & Queue Management via Automation SDK

Within Supsis Automation Code Blocks (Automation SDK / JS Scripting), you can utilize supsis.whatsapp and supsis.queue methods to execute bulk WhatsApp template campaigns safely within background queue architectures.

Key SDK Methods & Implementation Workflow

  • Channel & Template Validation: Validate active channels and templates via supsis.channel.get(channelId) and supsis.whatsapp.getTemplate({ channelId, templateId }).
  • Audience Segmentation: Filter contacts using supsis.contact.searchV2({ filters, cursor }) by platform, tags, and phone number.
  • Background Fire-and-Forget Queue: Enqueue supsis.whatsapp.sendTemplateMessage calls via supsis.queue.add(fn, "queue_name") to preserve provider rate limits.
  • Queue Status Monitoring: Inspect active, pending, and completed queue jobs via supsis.queue.status("queue_name").

7. Omnichannel Contact Search, Auto-Creation & Messaging via Automation SDK

In Supsis Automation Code Blocks (Automation SDK), you can resolve contacts using WhatsApp, Instagram, Telegram, or Messenger IDs, auto-create missing contact cards, and send messages via contact.sendTextMessage, contact.sendImageMessage, and contact.sendAssetMessage.

Key Methods

  • Omnichannel Contact Resolution: supsis.contact.get(contactId), supsis.contact.searchV2({ filters }) (WhatsApp/Phone), or supsis.contact.search({ groups }) (Instagram instagramUserId, Telegram telegramUserId, Messenger messengerUserId).
  • Automatic Contact Creation: Create new contact records for unlisted recipients via supsis.contact.create({ platform, fullname, phone, channelIds }).
  • Multi-Channel Message Dispatch: contact.sendTextMessage({ from, text }), contact.sendImageMessage({ from, url, caption }), and contact.sendAssetMessage({ from, url, assetType, filename }).
Bulk Messages API
↑↓ Gezin
↵ Aç
ESC Kapat