API能力能支持API的自定义扩展属性（ext字段存储额外数据）吗？

美洽API在多数接口上允许携带自定义扩展字段ext，用于存储或透传与会话、消息、访客等相关的业务数据，格式通常为JSON。使用时要关注字段命名、字符编码、大小上限和安全性，避免透传敏感信息，并在服务端做校验与脱敏。具体能力、字段名和限制以美洽官方文档或控制台配置为准。也可通过API或SDK验证。详情

Table of Contents

先把概念讲清楚：什么是 ext？为什么需要它

想象一下，客服系统本身像是一张空白表格，表格里有固定的列（比如消息内容、发送时间、用户ID）。但现实业务往往需要在表里附加一些“自定义备注”——订单号、商品 SKU、渠道 ID、会话来源等。ext 就是这个“备注”的容器：一个可以被API透传、储存、回调的自定义字段，通常以JSON结构承载任意键值对。

用一句话解释

ext 是透传的自定义 JSON 字段，用于在消息、会话或用户等对象上携带业务侧需要的额外信息。

美洽的 ext 能做什么（典型场景）

在用户发起会话时携带订单号（order_id），客服界面或后台可以直接显示并用于工单关联。
发送消息时附带商品信息（sku、price），便于智能机器人和客服快速定位商品详情。
在会话生命周期内透传归因信息（campaign、utm），用于后续转化分析。
在 webhook 推送中包含 ext，第三方系统可以接收并做实时处理或落库。

深入一点：ext 的技术形态与限制（该怎么看）

不同平台对 ext 的实现细节会有差别，但常见的规律和注意点如下：

数据格式：通常为 JSON，键名是字符串，值可为字符串、数字、布尔或嵌套对象。
字符编码：使用 UTF-8 能避免中文或特殊字符编码问题。
大小限制：多数接口会对单个 ext 的大小做限制（建议控制在几 KB 内），超过限制可能被截断或导致请求失败。
透传 vs 索引：ext 常常被设计为“透传”字段，平台可能不会对其中内容做全文索引或搜索，除非明确支持自定义属性映射。
展示与存取：前端 SDK 和后台管理界面是否显示 ext，取决于产品配置；有时需要把 ext 的某些键映射到“访客字段”或“工单字段”才能在页面可见。

一个简短的示例（概念）

比如，在发送消息时你可以带上：

字段	示例值
ext	{“order_id”:”20251234″,”product”:{“sku”:”SKU123″,”name”:”耳机”},”channel”:”wechat”}

怎么使用 ext：一步步的思路（费曼式说明）

把复杂的事情拆成几步，你会更容易上手：

定义用途：先明确要在 ext 中保存什么：是用于页面展示、分析还是后端联动？
设计结构：用简洁键名（如 order_id、product.sku），避免深层嵌套，便于后续解析。
实现传递：在调用发送消息或创建会话的 API 时把 ext 作为参数传入；或在 SDK 初始化/identify 时带入访客级 ext。
服务端校验：接收 ext 的服务端要做字段校验、长度校验和必要的脱敏（不要把身份证、银行卡明文放进去）。
映射与展示：如果需要在客服后台显示某些 ext 字段，把这些键映射成自定义访客字段或工单字段。

实践层面的细节与建议（常见问题与解决办法）

字段命名规范：小写加下划线或驼峰均可，但保持团队统一，便于前后端协作。
不要滥用 ext：ext 适合存放业务关联数据，不要把大量日志或临时大体积数据放入。
敏感信息处理：任何个人敏感信息都应先脱敏或以引用 ID 形式存放，再在后端系统中做安全关联。
回调可见性：如果你通过 webhook 接收会话或消息事件，检查回调 payload 中是否包含 ext；若不包含，可能需要在控制台勾选相关项或联系支持。
兼容性：前端 SDK 在不同版本中对 ext 的处理可能有差异，升级 SDK 后要做回归测试。

调试步骤（实操）

在测试环境发送带 ext 的请求，记录请求体。
通过查询消息/会话的查询接口检查是否返回 ext。
查看后台或客服面板，确认映射字段是否显示。
检查 webhook 回调的 payload，验证第三方是否收到 ext。

安全与合规：要非常认真

别把隐私当成可选项——特别是在中国国内和跨境场景下，要遵守相关数据保护要求。把用户的身份证、银行卡、详细地址等敏感信息不要以明文放入 ext，采用脱敏、哈希或只存引用 ID 的方式，同时控制 ext 的读取和日志存储权限。

常见误区与 FAQ（我遇到过的那些小坑）

误区：把 ext 当成万能的数据库。实际上 ext 更像是“透传注记”，平台可能不会把它作为主索引字段。
问题：为什么 ext 在后台看不到？
解答：可能是因为后台界面没有把该键映射为可显示字段，或者前端 SDK 并未提交到可见层级，建议先在 API 调用结果中确认 ext 是否存在。
问题：ext 丢失或被截断怎么办？
解答：检查请求体大小、编码和平台限制，必要时把过长的内容裁切或放到后端关联表。

实施范例：如何在消息发送接口里带 ext（伪代码示意）

这里不贴具体 SDK 的完整代码，但给一段伪代码说明思路：

步骤	示例（伪）
构建 ext	{“order_id”:”20251234″,”source”:”h5″,”product”:{“sku”:”SKU123″,”name”:”耳机”}}
发送请求	POST /api/message { “to”:”agent_1″, “text”:”您好”, “ext”:{…} }
校验返回	检查响应体或通过查询接口确认 ext 已保存

与其他系统的对接建议

在 CRM 或数据仓库中建立对应的字段或表，把 ext 的关键信息拆出来做结构化存储，便于统计与分析。
尽量在服务端做“最终解释权”，不要把所有业务逻辑依赖于客户端传入的 ext。

最后一点实用建议（略带生活气息）

我自己在接入客服系统时发现，最简单也最稳妥的办法是先把 ext 当作“不可靠但有用”的补充信息：能透传就透传，重要的数据还是要在服务端双写一份索引化记录。这样万一界面不显示、回调丢失或者平台变更，业务侧仍有可追溯的数据链路。嗯，这也是我工作中反复踩过的坑，分享给你。

如果你想，我可以帮你把要保存的字段列成一份规范模板（含字段名、类型、示例值、是否敏感、是否展示到客服界面），便于快速落地。