商品与订单选择器

客户问「我上周买的那个怎么还没到」，客服要先问是哪一单。这一来一回可以省掉。

做出来是什么样

在聊天输入区放一个你自己的按钮，客户点开是一个半屏列表，选中某件商品或某笔订单，就直接作为卡片发给了客服。客服看到的是带图、带价格、带订单状态的卡片，不用再问单号。

图里的示例数据只填了标题、状态和价格。实际接入时传了 imageUrl 会显示商品图，传了 description 会在标题下显示规格说明，字段表见下方。

列表数据全部由你的 APP 提供，所以这件事在工作台里配不出来，需要写代码。

两步接上

第一步，在输入区注册一个按钮。 可以在打开聊天页之前就注册，SDK 会记住，页面起来后按钮就在：

// Android — 参数顺序：id、文字、位置、图标
HecongChat.registerAction("pick_order", "选订单", "quick")

// iOS — 参数顺序：id、文字、图标、位置
HecongChat.shared.registerAction(id: "pick_order", label: "选订单", icon: nil, slot: "quick")

两端的参数顺序不一样

Android 是 slot 在前、icon 在后且可以省略；iOS 是 icon 在前、slot 在后且两个都要传。照着一端抄另一端会传反。

第二步，在按钮的点击回调里取数据、开面板：

// Android
override fun onActionClick(id: String) {
    if (id == "pick_order") {
        val items = loadMyOrders()          // 现去你自己的接口取
        HecongChat.setPickerData("order", items)
        HecongChat.openPicker("order")
    }
}

// iOS
func hecongChat(didClickAction id: String) {
    guard id == "pick_order" else { return }
    let items = loadMyOrders()
    HecongChat.shared.setPickerData("order", items: items)
    HecongChat.shared.openPicker("order")
}

setPickerData 和 openPicker 的第一个参数是类型，取 product、order 或 article，字段定义见下方。

数据要在点击那一刻现取

SDK 不保留你给过的列表，聊天页没打开时调 setPickerData 也不会生效。这是刻意的：商品库存、订单状态、客户的登录态随时在变，启动时灌一次、客户半小时后才点开，发出去的就是过期的卡片；而缓存下来还会把上一次会话的旧列表带进下一次。

把取数据的动作放在 onActionClick 里，是唯一正确的时机。

入口放在哪

slot 决定按钮出现的位置，两个取值：

取值	位置
quick	输入框正上方的快捷区，客户一眼就能看到
attach	附件面板里（输入区的 ➕ 展开后），平时收着

图里两个位置同时出现：上方那个「订单」胶囊是 quick，展开的附件面板里那个「商品」是 attach，和 SDK 自带的图片、视频、拍摄、文件排在一起。

高频动作用 quick，低频的放 attach 免得占地方。按钮文字之外还可以给一个图标，传一段以 <svg 开头的内联 SVG 字符串；不传就用通用图标。

同一个 id 重复注册是覆盖，不用先撤。要撤掉某个按钮：

HecongChat.unregisterAction("pick_order")

HecongChat.shared.unregisterAction("pick_order")

按钮点击回调里做什么完全由你决定 —— 跳转到 APP 内的订单页、触发一次人工转接、打开你自己的表单都可以，不一定要开选择器面板。

字段定义

product（商品）、order（订单）、article（文章），每类最多 50 条，超出部分不会呈现。

三类的字段各不相同，字段名必须完全一致：写错名字的字段会被静默丢弃，不报错、不提示，只表现为卡片上少了图或少了描述。

product 商品卡

字段	类型	必填	含义
title	string	是	商品名，≤200 字符
description	string	否	规格、卖点等，≤2000 字符
imageUrl	string	否	商品图外链，必须是合法 URL
price	Money	否	现价
originalPrice	Money	否	划线原价
detailUrl	string	否	商品详情页，客服点击可跳转
productId	string	否	你自己的 SKU 编号，≤128 字符
layout	'compact' | 'large'	否	卡片形态，缺省由聊天窗决定

order 订单卡

字段	类型	必填	含义
orderId	string	是	订单号，≤128 字符
title	string	是	订单标题，≤200 字符
total	Money	是	订单总额
status	见下	是	订单状态
createdAt	number	是	下单时间，毫秒时间戳
items	array	是	商品行，≤30 条
items[].name	string	是	商品名
items[].quantity	number	是	数量，正整数
items[].price	Money	是	单价
items[].imageUrl	string	否	商品图外链
detailUrl	string	否	订单详情页

status 取值：pending（待付款）、paid（已付款）、shipped（已发货）、delivered（已送达）、refunded（已退款）、cancelled（已取消）。传其他值会被拒绝。

商品行超过 30 条，这张卡整个发不出去，不是只显示前 30 条。卡片是摘要不是清单，行数多的订单挑主要商品放进去，其余让客服点 detailUrl 看详情。

article 文章卡

字段	类型	必填	含义
title	string	是	文章标题，≤200 字符
description	string	是	摘要，≤2000 字符
url	string	是	文章链接
imageUrl	string	否	封面图外链
source	string	否	来源站点名，≤100 字符

Money 金额

{ amount: 39900, currency: 'CNY' }   // ¥399.00
{ amount: 99, currency: 'USD' }      // $0.99

amount 是最小货币单位的整数（人民币为分），不接受浮点数。currency 用 ISO 4217 代码。展示时由聊天窗按客户语言格式化，你不用自己拼货币符号。

图片一律用外链

卡片图只能传 imageUrl，值是你自己的图片地址。

不要传 imageAttachmentId。那是客服在工作台上传素材时才用的字段，服务端会校验附件归属，用它发出去的卡片客户这边发不成功，而且不会有明确的报错提示。

客户选完之后

点中某一项，卡片直接作为一条消息发给客服，你不需要再做任何事。客服在工作台里看到的是完整卡片，能点进 detailUrl。

下一步

• 指定技能组接待 —— 让这次咨询直接进对的组
• 监听会话事件 —— 客服回消息时让 APP 有反应