接口速查

对话链接能用的全部网址参数和命令。需要完整用法和示例时，点对应的功能页。

网址参数

在链接后面带参数即可，不需要写代码。合从官方域名生成的链接同样支持。

默认链接的 ?c= 是渠道编号，必须保留，其余参数用 & 接在后面。自有域名部署时渠道编号写在页面文件里，网址上只带需要的参数。

参数	作用	怎么填	详见
c	渠道编号	工作台生成的链接里已经带上；自有域名部署不需要	默认链接接入
u	客户 ID	客户在你系统里的唯一标识，两个客户不能共用一个值	传客户资料给客服
n / p / e	姓名 / 手机号 / 邮箱	需 URL 编码，要和 u 一起传，档案里该字段为空时才写入	传客户资料给客服
d.*	你自己的业务字段	写成 d.<字段标识>=值；字段标识要先在工作台的自定义字段里建好	传客户资料给客服
pt	预填到输入框的文字	需 URL 编码；只能带文字，卡片走接口	带入咨询内容
lang	界面语言	BCP 47 语言标记，填你在工作台配过的语言，如 en	切换界面语言
cs	首帧深浅色	light / dark / auto	深色模式
hh	隐藏顶部标题栏	1 / true	隐藏顶部标题栏
sg	指定接待的技能组	技能组名称，和工作台里建的一致	指定由哪个技能组接待
fb / fbg	指定不到人时的降级方式 / 兜底技能组	fb 填 normal、group 或 leave_message	指定由哪个技能组接待
utm_source	投放来源	自己定，建议用英文	区分投放来源

隐藏顶部标题栏

?hh=1 会隐藏聊天页顶部的标题栏，也就是显示客服头像、昵称、签名的那一行。长名 ?hideHeader=1 效果相同。

打开这条链接的地方已经有自己的标题或导航时用它，不然客户会看到上下两条标题。常见的有 APP 的 WebView、微信里打开的页面、嵌在你自己页面里的窗口，具体要不要隐藏由你判断。写法：

https://<链接域名>/?c=<渠道编号>&hh=1

自有域名部署一样有效，链接上不带 c：https://你的域名/chat.html?hh=1。

使用要点：

• 只认 1 和 true，值不区分大小写。填其他值或者不带这个参数，标题栏正常显示。没有 hh=0 强制显示的写法
• 工作台里没有对应的开关，隐藏标题栏只能在链接上指定。同一个渠道可以生成两条链接：常规投放的不带参数，投到有自己标题栏的地方就加上 hh=1
• 整条标题栏连同栏内的按钮一起不显示，聊天内容、输入区和附件发送不受影响
• 参数会留在地址栏，页面刷新、前进后退之后仍然生效
• 仅对话链接渠道有效，网页接入渠道（JS 嵌入）没有这个参数

命令

命令对象 hc 的全部接口。拿到它的方式：

<script>
  window.hecongLink(function (hc) {
    // hc 就是下表里的命令对象
  })
</script>

用官方域名的链接调不了这些命令

下面这些命令对自有域名部署完全成立。用合从官方域名生成的链接，页面由合从托管，你没有地方写这段 JS，所以只能通过网址参数传客户资料，用不了选择器、事件订阅这些要写代码的能力。

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

拿到命令对象的入口名不同：网页接入是 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'

各命令的说明页

命令	详见
identify / reset	传客户资料给客服
setLocale	切换聊天窗的界面语言
setColorScheme	深色模式
setRouting	指定由哪个技能组接待
setPresend	带入咨询内容
setPickerData / openPicker	商品、订单与文章选择器
registerComposerAction / registerQuickReply	商品、订单与文章选择器
on	监听聊天页事件