JS SDK

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

Supsis JavaScript SDK Reference

Integrate the live support chat widget into your website, synchronize user data, manage chat states remotely, and update custom visitor contact properties dynamically.

1. Integration Setup

To add the Supsis Chat Widget to your website, add the following code snippet to the top (<head> section) of every page on your site.

💡 SDK Features & Benefits:
  • SUPSIS SDK loads asynchronously and does not affect page load speed.
  • You can include it only on pages where you want the chat widget to appear.
  • The widget will automatically display once the Supsis SDK is loaded and ready.

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: The SITE_DOMAIN_NAME part should be replaced with the domain name you specified when registering with Supsis.
If you registered via IdeaSoft, your IdeaSoft domain name will serve as your Supsis domain name. (For example: if you log in via market71.supsis.live, use SITE_DOMAIN_NAME=market71).

2. SYNC API & Method Comparison

SYNC API is invoked with supsis. syntax, whereas ASYNC API uses supsis() syntax. API methods can be invoked both synchronously and asynchronously.

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

Alternatively, you can load the SDK synchronously and run your code immediately after:

⚠️ Performance Note: Synchronous loading may add a minor overhead to your site's initial page load. 
<script src="https://SITE_DOMAIN_NAME.visitor.supsis.live/static/js/loader.js" type="text/javascript">
    supsis.open()
    supsis.setUserData({name:'Ali',email:'a@a.com'})
</script>

3. ASYNC API Methods

Since the Supsis SDK is loaded asynchronously, your API calls will execute after the SDK has finished loading.

Method Invocation Syntax:

supsis(API_FUNCTION_NAME, payload);
  • "API_FUNCTION_NAME" is a string representing the target function name (e.g. supsis.open() ===> supsis("open")).
  • payload is supplied when the called function requires parameters.

Visitor Management Methods

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

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

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

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

// End Conversation
supsis("closeChat");

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

Department Title

* Department title values must be identical 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 and email address.

ℹ️ 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", {
    name: "Logged-in user's full name",
    email: "Logged-in user's email address",
});

Updating Visitor Info for Custom Login Form

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

Sample custom login form fields: (name, email, phone, identityNumber)

Custom Login Form

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

5. Updating Custom User Data (User Contact Properties)

You can update custom user tags or attributes created in the admin panel via the SDK. This is ideal for displaying customer membership tiers or segments when a visitor connects to live support.

Example Scenario: Setting Membership Rank (User Rank)

To pass a customer's membership rank, first create a tag named User Rank in the admin panel:

User Rank Tag

Then execute the setContactProperty method within the SDK to assign this User Rank attribute to the visitor:

supsis("ready", (supsis) => {
    // Listen for the event when Supsis is ready
    // Retrieve member data from your website
    const member = {
        badget: "gold_member",
    };
    supsis.setContactProperty({ badget: member.badget });
});

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

In Supsis Automation Code Blocks (Automation SDK / JS Scripting), you can use supsis.whatsapp and supsis.queue methods to trigger bulk WhatsApp template broadcasts using background queues.

Key SDK Methods & Logic

  • Channel & Template Verification: Verify channel status (`supsis.channel.get(channelId)`) and template existence (`supsis.whatsapp.getTemplate({ channelId, templateId })`).
  • Target Audience Segmentation: Filter contacts using `supsis.contact.searchV2({ filters, cursor })` based on platform, tags, and valid phone numbers.
  • Background Queueing (Fire-and-Forget): Push individual `supsis.whatsapp.sendTemplateMessage` calls into `supsis.queue.add(fn, "queue_name")` to ensure smooth rate-limit compliance.
  • Queue Status Monitoring: Monitor remaining, processed, and active queue jobs in real time 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