Web Widget Host API

Standard Installation

The standard installation loads asynchronously and initializes automatically. The chat iframe is loaded only when the visitor opens it for the first time.

<script async src="https://support.example.com/support/embed.js" data-widget-key="YOUR_WIDGET_KEY"></script>

Only one IMCoreWidget may be mounted per page. If you need to call the API before the loader has finished downloading, use the advanced installation snippet from the “Installation Code” section of the admin console; it sets up a call queue first.

Lifecycle

IMCoreWidget.init();    // manual initialization when data-auto-init="false"
IMCoreWidget.open();
IMCoreWidget.close();
IMCoreWidget.show();    // show the widget, keeps the conversation
IMCoreWidget.hide();    // hide the widget, keeps the conversation
IMCoreWidget.destroy(); // removes the DOM; calling init() again recreates it

Except for getState(), every method returns IMCoreWidget, so calls can be chained.

Visitor and Business Context

Read profile data from the logged-in host app. Visitor profiles are used only for display and customer 360 views, never as authentication credentials; the server still issues its own anonymous guest ID and a short-lived JWT.

IMCoreWidget.setVisitor({
  name: 'Ada',
  email: 'ada@example.com',
  phone: '+86 138 0000 0000',
  avatar: 'https://example.com/ada.png',
  fields: {
    member_level: 'gold',
    account_id: 'account-42'
  }
});

IMCoreWidget.setSessionVariables({
  order_id: 'order-123',
  product_sku: 'sku-7'
});

fields and session variables are each capped at 50 items; keys are limited to 64 characters and values to 512 characters. The server re-validates length and type.

On initialization the loader automatically collects the current page’s URL path (without query/hash), title, referrer path, and language, so tokens or private data in query parameters are never auto-uploaded. After an SPA route change, call:

IMCoreWidget.updateContext();

You can also pass values explicitly:

IMCoreWidget.updateContext({
  url: location.href,
  title: document.title,
  language: document.documentElement.lang
});

Events

const unsubscribe = IMCoreWidget.on('ready', (state) => {});
IMCoreWidget.on('open', (state) => {});
IMCoreWidget.on('close', (state) => {});
IMCoreWidget.on('visibility_changed', ({ open, visible }) => {});
IMCoreWidget.on('connection_changed', ({ connection }) => {});
IMCoreWidget.on('message', ({ direction, messageID, senderID }) => {});
IMCoreWidget.on('unread_count_changed', ({ unread }) => {});
IMCoreWidget.on('handover_changed', ({ stage }) => {});
IMCoreWidget.on('error', ({ code, message }) => {});

unsubscribe();
// or IMCoreWidget.off('ready', handler)

connection is idle | connecting | open | closed; stage is ai | requesting | waiting | human. Each event is also dispatched as a same-named DOM event on window, for example imcore:widget:ready.

The current state can be read synchronously:

const state = IMCoreWidget.getState();

The state includes initialized, ready, open, visible, connection, unread, stage, visitor, and context.

Security and Deployment

• Configure an exact allowed origin for each widget, for example https://shop.example.com.
• The host CSP must at least allow script-src, connect-src, and frame-src for the widget domain. The advanced installation includes an inline queue script that requires a nonce or hash; sites with a strict CSP can keep the standard installation and call the API from the load callback of an external business script.
• Both directions of loader–iframe communication verify the exact origin, sender window, and message type; arbitrary command pass-through is not accepted.
• Never put passwords, payment card data, access tokens, or other secrets into visitor fields/session variables.