IM Web SDK Widget Integration Guide

Widget mode lets you add the online customer service widget to a business website with a <script> tag. The SDK automatically loads the configuration and renders the floating launcher and chat window.

Quick Integration

Create the window.mchat queue before loading the SDK asynchronously. Commands called while the SDK is loading are added to the queue and run after initialization.

<script>
  window.mchat = window.mchat || {
    _q: [],
    push: function () {
      this._q.push(Array.prototype.slice.call(arguments))
    },
  }

  window.mchat.push('setLoginInfo', {
    user_id: 'user_123',
    nickname: 'Alex',
    email: 'user@example.com',
  })
</script>

<script
  src="https://your-domain.com/plugin.js"
  data-app-id="YOUR_APP_KEY"
  async
></script>

Set data-app-id to the chat widget's AppKey. You can find it in the chat widget list.

Application ID Lookup Order

The widget looks for an application ID in this order:

1. data-app-id on the current SDK script.
2. data-token on the current SDK script.
3. Any script[data-app-id] on the page.
4. The current page URL's ?token= parameter.

Set the Signed-In User

Call the following before the SDK loads or before the chat window opens for the first time:

window.mchat.push('setLoginInfo', {
  user_id: 'user_10001',
  user_name: 'Alex Smith',
  language: 'en-US',
  phone: '+1 202 555 0123',
  email: 'user@example.com',
  description: 'VIP customer',
  label_names: ['VIP', 'Signed in'],
  update_label_type: 'append',
  custom_fields_ext: {
    member_level: 'gold',
    order_count: 12,
  },
})

Field	Type	Required	Description
user_id	string	Yes	Unique user ID from your business system
user_name	string	No	User name field
language	string	No	User language, such as en-US or zh-CN
phone	string	No	Phone number
email	string	No	Email address
description	string	No	User note
label_names	string[]	No	User labels
update_label_type	append | update	No	Append or replace labels
custom_fields_ext	Record<string, unknown>	No	Custom extension fields

When the user switches accounts on your site, call setLoginInfo again with the new user_id. When the user signs out, call:

window.mchat.push('clearLoginInfo')

Pass User Information in Page Mode

Page mode accepts sign-in information through URL query parameters. At least user_id is required:

https://chat.example.com/?user_id=user_10001&user_name=Alex%20Smith&language=en-US&phone=%2B12025550123&email=user%40example.com&description=VIP%20customer&label_names=VIP,Signed%20in&update_label_type=append&custom_fields_ext=%7B%22member_level%22%3A%22gold%22%2C%22register_source%22%3A%22web%22%2C%22order_count%22%3A12%7D

Supported parameters are user_name, language, phone, email, description, label_names, update_label_type, and custom_fields_ext.

• Separate label_names with commas.
• update_label_type accepts only append or update.
• custom_fields_ext must be a URL-encoded JSON object string.

Privacy

URLs may appear in browser history, logs, and analytics systems. Never include passwords, verification codes, tokens, or other sensitive credentials in query parameters.

Control the Chat Window

window.mchat.push('openChat')
window.mchat.push('closeChat')
window.mchat.push('hideIcon')
window.mchat.push('showIcon')

Connect a custom Contact Support button to the chat window:

<button type="button" id="contact-service">Contact Support</button>
<script>
  document.getElementById('contact-service').addEventListener('click', function () {
    window.mchat.push('openChat')
  })
</script>

Event Callbacks

Command	Callback argument	Trigger
onReady	function()	SDK initialization completes
onUnread	function(count)	Unread message count changes
onSendMessage	function(message)	The visitor sends a message
onReceiveMessage	function(message)	An agent or system message arrives
onWindowOpen	function()	The chat window opens
onWindowClose	function()	The chat window closes
onIconClick	function()	The visitor clicks the floating launcher
onOpenInfoCollection	function()	The pre-chat survey or offline form opens
onCompleteInfoCollection	function(data)	The information form is submitted

window.mchat.push('onReady', function () {
  console.log('SDK ready')
})

window.mchat.push('onUnread', function (count) {
  document.title = count > 0 ? '(' + count + ') New messages' : 'Home'
})

window.mchat.push('onCompleteInfoCollection', function (data) {
  console.log('Information collected:', data)
})

TypeScript Type Example

type MChatCommand =
  | 'setLoginInfo'
  | 'clearLoginInfo'
  | 'openChat'
  | 'closeChat'
  | 'hideIcon'
  | 'showIcon'
  | 'onReady'
  | 'onUnread'
  | 'onSendMessage'
  | 'onReceiveMessage'
  | 'onWindowOpen'
  | 'onWindowClose'
  | 'onIconClick'
  | 'onOpenInfoCollection'
  | 'onCompleteInfoCollection'

interface MChatApi {
  version?: string
  _q?: Array<[string, unknown]>
  push(command: MChatCommand, data?: unknown): void
}

declare global {
  interface Window {
    mchat: MChatApi
  }
}