接口速查

命令对象 hc 的全部接口。需要完整用法和示例时，点对应的功能页。

script 标签属性

接入代码上能配的只有这两个，其余外观与文案配置都在工作台里。

属性	必填	说明
data-channel-id	✅	渠道编号，工作台复制出来的代码里已经填好
data-language		访客界面语言，BCP 47 标记如 zh-CN / en / ja

详见接入代码与配置项。

命令对象

拿到命令对象的方式：

<script>
  window.hecong = window.hecong || function (c) { (window.hecong.q = window.hecong.q || []).push(c) }
  window.hecong(function (hc) {
    // hc 就是下表里的命令对象
  })
</script>

第一行占位函数的作用见接入代码与配置项，照原样复制，一个页面一份即可。

两种渠道交给你的是同一套命令，形状完全一致。少数几个在对话链接上不成立的命令保留着但不生效，调了也不会报错。

拿到命令对象的入口名不同：网页接入是 window.hecong(cb)，对话链接是 window.hecongLink(cb)。除了这一行，其余业务代码两边可以照搬。

命令	作用	网页接入	对话链接
identify(args)	绑定已登录客户	✅	✅
reset()	清身份并结束当前对话	✅	✅
open()	打开聊天窗	✅	不生效
close()	关闭聊天窗	✅	不生效
toggle()	开关切换	✅	不生效
setLocale(locale)	运行时切换界面语言	✅	✅
setColorScheme(scheme)	切换浅色 / 深色	✅	✅
setRouting(input)	指定由哪个技能组接待	✅	✅
registerComposerAction(action)	往附件面板加入口	✅	✅
registerQuickReply(action)	往快捷按钮区加入口	✅	✅
setPresend(input)	带入咨询内容（文字 / 卡片）	✅	✅
setPickerData(type, items)	供给选择器数据	✅	✅
openPicker(type)	打开某类选择器	✅	✅
on(event, handler)	订阅事件，返回退订函数	✅	✅
isOpen	只读，聊天窗是否打开	✅	恒为 true
state	只读，连接状态	✅	✅

对话链接是整页聊天，没有可关闭的窗口，所以 open() / close() / toggle() 在那边不做任何事。调 close() 时会在控制台留一条提示，免得你以为代码没生效。

state 的取值：idle（尚未连接）、connecting、open、reconnecting、closed。

网页接入渠道默认懒连接。访客点开聊天窗之前，isOpen 一直是 false。state 更晚一步：要到真正建立连接才离开 idle，通常是访客发出第一条消息、或者系统查到他还有没结束的对话的时候 —— 只点开翻看，state 仍是 idle。对话链接是整页聊天，进页面就开始连。

对话链接没有 data-language 这种写在接入代码上的地方，改用链接参数：?lang=en 指定界面语言、?cs=dark 指定深浅色，官方域名生成的链接同样适用。详见切换界面语言与深色模式。

事件适用性

事件	网页接入	对话链接
message / message:incoming / message:button-click / unread	✅	✅
conversation:start / conversation:end	✅	✅
assignee:change / header:change	✅	✅
user:identified / user:reset	✅	✅
session:started / network:online / network:offline	✅	✅
form:submitted / rating:submitted / picker:request	✅	✅
chat:open / chat:close / launcher:click	✅	不触发

对话链接没有窗口和按钮这两个概念，这三个事件订阅了也永远不会触发，但不会报错。

数据类型

interface IdentifyArgs {
  id: string
  profile?: ProfileFields
  data?: DataFields
}

interface ProfileFields {
  name?: string
  phone?: string
  email?: string
  avatar?: string             // https:// 开头，最长 500 字符
}

type DataFields = Record<string, string | number | boolean>

interface IdentifyResult {
  userId?: string
  customerCreatedOrMerged?: boolean   // 是否新建档案或发生跨账号合并
  conversationIds?: string[]
  acceptedKeys?: string[]             // data 中实际写入的字段名
}

interface ComposerCustomAction {
  id: string
  label: string
  icon?: string               // 内联 SVG 字符串
  onClick(): void
}

interface PublicMessageInfo {
  serverId?: string           // 本地还没发出去的占位消息没有这个字段
  from: 'visitor' | 'agent' | 'bot' | 'system'
  text: string                // 富消息取其可读文本，没有文本内容时是空串
  contentType: string         // text / image / video / file / audio / card ...
  createdAt: number           // 服务端时间戳，毫秒
}

interface PublicAssigneeInfo {
  type: 'agent' | 'bot' | null   // null = 无人接待（排队中或对话已结束）
  name?: string
}

interface PublicHeaderIdentity {
  nickname?: string
  avatar?: string
  signature?: string
  source: 'agent' | 'bot' | 'channel' | null   // 'channel' = 无人接待时的渠道兜底身份
  pending: boolean                             // true = 身份解析中，建议画占位
}

type RoutingInput = string | RoutingOptions | null

interface RoutingOptions {
  skillGroup: string | null            // 技能组名称，允许中文
  fallback?: 'normal' | 'group' | 'leave_message'
  fallbackGroup?: string               // fallback 为 'group' 时必填
}

type PickerType = 'product' | 'order' | 'article'

type SdkState = 'idle' | 'connecting' | 'open' | 'reconnecting' | 'closed'

命令与事件之外，还有一个一次性 DOM 事件 hecong:ready（e.detail 即命令对象），用法与时序限制见监听聊天窗事件。

各命令的说明页

命令	详见
identify / reset	传客户资料给客服
open / close / toggle / isOpen	打开与关闭聊天窗
setLocale	切换聊天窗的界面语言
setColorScheme	深色模式
setRouting	指定由哪个技能组接待
setPickerData / openPicker	商品、订单与文章选择器
registerComposerAction / registerQuickReply	同上
on	监听聊天窗事件