IM Web SDK Widget 接入指南

Widget 模式适合在业务网站中通过一段 <script> 引入在线客服插件。SDK 会自动获取配置、渲染悬浮入口和聊天窗口。

快速接入

建议先创建 window.mchat 预队列，再异步加载 SDK。SDK 加载期间调用的命令会进入队列，并在初始化完成后执行。

<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: '张三',
    email: 'user@example.com',
  })
</script>

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

data-app-id 填写聊天插件的 AppKey。可以在聊天插件列表中查看。

应用标识读取顺序

Widget 会按以下顺序读取应用标识：

1. 当前 SDK 脚本的 data-app-id。
2. 当前 SDK 脚本的 data-token。
3. 页面中任意 script[data-app-id]。
4. 当前页面 URL 的 ?token=。

开发环境也可以使用：

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

设置登录用户

建议在 SDK 加载前或聊天窗口首次打开前调用：

window.mchat.push('setLoginInfo', {
  user_id: 'user_10001',
  nickname: '张三',
  user_name: '张三',
  language: 'zh-CN',
  phone: '13800138000',
  email: 'user@example.com',
  description: 'VIP 用户',
  label_names: ['VIP', '已登录'],
  update_label_type: 'append',
  custom_fields_ext: {
    member_level: 'gold',
    order_count: 12,
  },
})

字段	类型	必填	说明
user_id	string	是	业务系统中的用户唯一标识
nickname	string	否	用户昵称
user_name	string	否	兼容的用户名称字段
language	string	否	用户语言，例如 zh-CN、en-US
phone	string	否	手机号
email	string	否	邮箱
description	string	否	用户备注
label_names	string[]	否	用户标签
update_label_type	append | update	否	追加或覆盖标签
custom_fields_ext	Record<string, unknown>	否	自定义扩展字段

用户在站内切换账号时，使用新的 user_id 再次调用 setLoginInfo。退出登录时调用：

window.mchat.push('clearLoginInfo')

Page 直开模式传递用户信息

Page 模式可以通过 URL 查询参数传递登录信息。至少需要 user_id：

https://chat.example.com/?user_id=user_10001&nickname=%E5%BC%A0%E4%B8%89&language=zh-CN

支持 nickname、user_name、language、phone、email、description、label_names、update_label_type 和 custom_fields_ext。其中：

• label_names 使用英文逗号分隔。
• update_label_type 只接受 append 或 update。
• custom_fields_ext 必须是 URL 编码后的 JSON 对象字符串。

隐私

URL 可能出现在浏览器历史、日志和统计系统中。不要把密码、验证码、令牌或其他敏感凭据放入查询参数。

控制聊天窗口

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

把站内“联系客服”按钮绑定到聊天窗口：

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

事件回调

命令	回调参数	触发时机
onReady	function()	SDK 初始化完成
onUnread	function(count)	未读消息数变化
onSendMessage	function(message)	访客发送消息
onReceiveMessage	function(message)	收到客服或系统消息
onWindowOpen	function()	聊天窗口打开
onWindowClose	function()	聊天窗口关闭
onIconClick	function()	访客点击悬浮入口
onOpenInfoCollection	function()	聊前调查或离线留资打开
onCompleteInfoCollection	function(data)	信息收集提交完成

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

window.mchat.push('onUnread', function (count) {
  document.title = count > 0 ? '(' + count + ') 新消息' : '首页'
})

window.mchat.push('onCompleteInfoCollection', function (data) {
  console.log('信息收集完成:', data)
})

TypeScript 类型示例

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