监听聊天页事件

聊天页发生状态变化时收到通知，用于埋点统计或联动你自己的业务逻辑。

什么时候用

• 想统计有多少客户真的发起了咨询
• 客户把页面切到后台时，想在自己的 APP 或小程序里给个提示
• 想在客户身份绑定完成后触发自己的逻辑

开始之前

• 已完成自有域名部署，能改到 chat.html 这个文件
• 下面的代码写在文件末尾【你的脚本写这里】区域

<script>
  window.hecongLink(function (hc) {
    // 下面的代码都写在这里
  })
</script>

官方域名的链接改不了页面

用合从官方域名生成的链接，页面由合从托管，你没有地方写这段代码。需要监听事件就改用自有域名部署。

怎么订阅

const off = hc.on('message:incoming', function (msg) {
  console.log('客服发来一条消息', msg.text)
})

// 不需要再监听时
off()

hc.on() 返回一个退订函数。同一个事件可以挂多个回调，按注册顺序依次执行。某个回调里抛了异常不会影响其他回调，也不会影响聊天窗本身。

事件名写错不会抛异常，而是在控制台输出一条提示并列出可用的事件名，返回一个空的退订函数。

可订阅的事件

对话与消息

事件	什么时候触发	回调参数
message	任意消息，包含客户自己发出并送达的	PublicMessageInfo
message:incoming	只有对方的消息（客服、机器人、系统）	PublicMessageInfo
unread	未读数变化	{ count: number }
message:button-click	消息里的按钮或菜单项被点	见下
conversation:start	新对话创建	{ conversationId: string }

message:button-click 的回调参数是 { actionId?: string, text: string, url?: string }。 | conversation:end | 对话结束（客服关闭或超时归档） | { conversationId?: string } | | assignee:change | 接待人变化，机器人与人工之间切换 | PublicAssigneeInfo | | header:change | 聊天窗标题栏显示的身份变化 | PublicHeaderIdentity |

做红点、震动、消息推送用 message:incoming，它不会被客户自己发的消息触发。

assignee:change 常用来在转人工时给客户一个提示，或者统计机器人的解决率：

{
  type: 'agent',   // 'agent' 人工 / 'bot' 机器人 / null 无人接待（排队中或对话已结束）
  name: '小王'      // 接待人昵称，拿不到时没有这个字段
}

header:change 用来在你自己的页面上显示「当前为您服务的客服」—— 比如把接待人的头像昵称画进你的页头。它报的是聊天窗标题栏此刻显示的身份：会话开始前是渠道的兜底身份，客服或机器人接待后换成接待者，转接时再变。和 assignee:change 的区别在无人接待时 —— assignee:change 给 null，header:change 仍给渠道身份，所以拿它画界面不用自己准备兜底。

hc.on('header:change', function (h) {
  // h.nickname / h.avatar / h.signature 都可能缺，按字段可能不存在来写
  // h.source：'agent' 人工 / 'bot' 机器人 / 'channel' 渠道兜底 / null 无
  // h.pending 为 true 时身份还在解析中，建议先画占位，别画空白
  renderServiceHeader(h)
})

PublicMessageInfo 的字段：

字段	类型	说明
serverId	string?	服务端消息 ID。本地还没发出去的占位消息没有这个字段
from	'visitor' | 'agent' | 'bot' | 'system'	谁发的
text	string	纯文本内容。富消息取其可读文本，没有文本内容时是空串
contentType	string	text / image / video / file / audio / card 等
createdAt	number	服务端时间戳，毫秒

消息对象只有这五个字段，其余属于内部结构，不要依赖。

身份

事件	什么时候触发	回调参数
user:identified	identify() 完成，包括再次调用更新资料	IdentifyResult
user:reset	reset() 完成	IdentifyResult

IdentifyResult 里的 customerCreatedOrMerged 告诉你这次是新建了档案还是合并到已有客户，acceptedKeys 是 data 里实际写进去的字段名。

连接

事件	什么时候触发	回调参数
session:started	首次与合从建立连接，匿名访客也算	无
network:online	连接恢复	无
network:offline	连接断开	无

表单与评价

事件	什么时候触发	回调参数
form:submitted	表单提交成功	{ formId?: string, formType?: string, fields: Record<string, unknown> }
rating:submitted	会话评价提交成功	{ score: number, comment?: string }

三种表单都会触发 form:submitted，用 formType 区分是哪一种：

formType	对应
prechat	询前表单
leave	留言表单
message	消息里的表单

formId 只有消息里的表单才有，询前表单和留言表单没有这个字段。fields 是访客填写的内容，键名是字段标识。

只在提交成功后触发，提交失败不触发。

别拿它做业务对账

这是浏览器里的事件。访客提交完立刻关掉页面、网络断了、或者被浏览器插件拦掉，你都可能收不到这条通知。用它做实时提醒、埋点统计、同步到自己的 CRM 都合适，但不要当成一条都不会少的数据来源 —— 完整的表单内容以工作台里的记录为准。

选择器

事件	什么时候触发	回调参数
picker:request	选择器打开但没有缓存数据，等你回填	{ type: 'product' | 'order' | 'article' }

没有 ready 和 error 事件

拿到 hc 的时候就已经是就绪状态，不需要额外的 ready 事件。

内部错误也不通过事件暴露，失败信息在各个方法返回的 Promise 里。

没有窗口开关事件

网页接入渠道有 chat:open 和 chat:close，对话链接是整页聊天，没有可开关的窗口，这两个事件订阅了也不会触发，但不会报错。这是有意为之，好让同一份业务代码在两种渠道上都能跑。

下一步

• 接口速查 —— 全部命令、事件与类型定义