IM Web SDK Widget Integration

Widget mode embeds customer service into a website with a <script> tag. The SDK loads the plugin configuration and renders the floating launcher and chat window.

Quick integration

Create the window.mchat queue before loading the SDK. Commands called while the SDK is loading will 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: 'alex@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 AppKey shown in the chat plugin 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 URL's ?token= parameter.

For local development, you can also use:

http://localhost:5173/?token=YOUR_APP_KEY

Set the signed-in user

Call setLoginInfo before the first chat window opens whenever possible.

window.mchat.push('setLoginInfo', {
  user_id: 'user_10001',
  nickname: 'Alex',
  user_name: 'Alex Smith',
  language: 'en-US',
  phone: '+1 202 555 0123',
  email: 'alex@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
nickname	string	No	Display name
user_name	string	No	Compatible user-name field
language	string	No	Language such as en-US or zh-CN
phone	string	No	Phone number
email	string	No	Email address
description	string	No	Internal user description
label_names	string[]	No	Customer labels
update_label_type	append | update	No	Append or replace labels
custom_fields_ext	Record<string, unknown>	No	Custom business fields

Call setLoginInfo again with a new user_id when the signed-in account changes. When the user signs out, call:

window.mchat.push('clearLoginInfo')

Pass identity to a standalone Page URL

Page mode accepts identity through query parameters. user_id is required to create signed-in identity data.

https://chat.example.com/?user_id=user_10001&nickname=Alex&language=en-US

Supported parameters include nickname, 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.

Privacy

URLs may be stored in browser history, access logs, and analytics. Never include passwords, verification codes, tokens, or other secrets 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 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 count changes
onSendMessage	function(message)	Visitor sends a message
onReceiveMessage	function(message)	Agent or system message arrives
onWindowOpen	function()	Chat window opens
onWindowClose	function()	Chat window closes
onIconClick	function()	Visitor clicks the launcher
onOpenInfoCollection	function()	Pre-chat or offline form opens
onCompleteInfoCollection	function(data)	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 declaration

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
  }
}