YundaDesk有些渠道天生就不在“现成列表”里——自建的购物App、小程序、ERP里嵌的客服入口,这些地方的对话没法靠装个插件解决。这时候要用的是自定义API:把你自己系统里产生的消息,按约定的接口喂给 YundaDesk,让它跟网站挂件、WhatsApp、邮件这些渠道一样,进同一个工作台、共享同一份客户档案。这篇不讲营销话术,直接讲接入的四个环节:鉴权、会话映射、消息回传、转人工回调。
什么时候该用自定义API,而不是现成渠道
YundaDesk 覆盖网站挂件、WhatsApp、Telegram、Messenger、Instagram、TikTok、LINE、微信、VKontakte、Zalo、YouTube、邮件这些常见渠道,大多数出海团队直接接现成的就够用。自定义API是留给那些“渠道本身是你自己的”的场景:
- 自建App或小程序里有独立的IM模块,想让客服能力接进去,而不是让用户跳出App去用第三方渠道。
- 内部系统(比如订单管理后台、ERP)里需要嵌一个客服入口,给内部客服团队或者B2B客户用。
- 已经有一套自研的消息网关,统一处理多个渠道的接入,想把这套网关接到 YundaDesk 而不是逐个渠道重新对接。
不管走哪条路,目标只有一个:所有渠道的对话最终都汇入同一个共享工作台,用同一份跨境客户档案,AI客服和人工看到的是同一个人、同一段历史。
鉴权:先把“谁能调这个接口”钉死
自定义API接入的第一步不是发消息,是把鉴权配好。核心是两件事:
- API Key/Secret 配对:在后台生成一对凭证,每次请求带上,服务端校验签名。凭证按渠道/按业务线分开申请,不要一套凭证打遍所有渠道——一旦某个前端泄露了凭证,影响范围只限那一个渠道。
- 请求来源校验:配置允许调用的域名/IP白名单,尤其是消息回传和Webhook回调这两个方向,避免被伪造请求污染会话数据。
会话映射:让AI和坐席认得出“这是同一个人”
鉴权只解决“能不能连上”,真正决定接入质量的是会话映射——你的系统里怎么标识一个用户、一次对话,直接决定 YundaDesk 能不能把这些消息正确归到同一个客户档案下。
映射时至少要传三类字段:
| 字段类型 | 作用 | 常见坑 |
|---|---|---|
| 外部用户ID | 关联到你系统里的账号/设备ID,用于跨会话识别同一个人 | 用临时Session ID代替稳定用户ID,导致同一个人每次开App都被当成新客户 |
| 会话ID | 标识一次连续的对话,决定消息该续在哪条历史后面 | 前端刷新页面就换了新会话ID,历史记录被拆断 |
| 基础档案字段 | 国家/语言/时区等出厂字段,配合跨境CRM做分群 | 只传了用户ID,不传语言字段,AI客服判断语言全靠猜 |
这三类字段传对了,后续的知识库匹配、多身份合并才有意义——比如同一个客户在自建App里问过一次,又通过邮件问了一次,只要外部用户ID能对应到同一个人,系统会自动合并成一份档案,AI客服作答时能看到完整背景,不用客户重新自我介绍。
消息回传:把AI/坐席的回复送回你的系统
接入不是单向的。YundaDesk 这边生成的回复(不管是AI客服自动作答,还是坐席在共享工作台里发的)需要通过回调接口送回你的系统,再由你的前端展示给用户。这一步要注意:
- 回调要幂等:同一条消息可能因为网络重试被推送多次,你的接收端要能识别重复消息ID并去重,避免用户看到重复气泡。
- 消息类型要透传:文本、图片、表格这类富文本格式需要在回调里保留结构,不要压缩成纯文本,否则政策条款、订单信息这类结构化回复会变得难读。
- 失败要有重试和告警:回调接口如果短时间不可用,消息需要进重试队列,而不是直接丢弃——客服回复丢失是接入类故障里最容易被忽视、也最影响体验的一种。
转人工回调:AI答不上或客户要求时,怎么无缝交给人
自定义API接入里最容易被低估的一环是转人工回调。产品的边界很清楚:AI客服是先接的一层,答不上、客户明确要求、或者触发了退款/赔付这类高风险动作,就必须转人工,这个逻辑不因为渠道是自定义API就打折扣。
技术上要接的是一个事件回调:当会话状态从“AI处理中”变成“待人工介入”时,YundaDesk 会推送一个转人工事件到你配置的回调地址,你的系统可以据此做两件事:
- 在你自己的前端界面上给客户一个“已转接人工,请稍候”的提示,避免客户以为消息没发出去。
- 如果你的系统里有自己的客服排队/工单逻辑,可以把这个事件同步过去做统一的坐席调度。
转人工之后,坐席在共享工作台里能看到AI处理过程中的完整上下文——客户问了什么、AI给过什么答复、AI判断为什么没接住,不需要重新问客户一遍。这跟走微信、WhatsApp这类现成渠道时的转人工体验是一致的,自定义API不是“降级版”接入。
自定义 API 会话上线后的分流账（示例）
以 1,000 通自建渠道会话为口径
高风险动作:退款、赔付走审批,不走自动回调
有一类回调不能简化——涉及退款、赔付、改价这类高风险动作时,不管是AI客服判断该退款,还是坐席在处理过程中要执行退款,这个动作永远需要人工审批,不会因为走的是自定义API就自动执行。
接入之后:自定义渠道的对话也一样“越用越聪明”
自定义API接入的对话,进入的是同一套学习闭环——坐席在你自建渠道里处理的会话,如果做了修正、补答了AI没答上的问题,系统同样会生成一条待确认的学习建议,进老板的评审台。评审通过之后,这条经验才会沉淀进AI的判断依据,下次同一渠道甚至其他渠道遇到类似问题,AI的回答会更贴近团队的实际处理方式。
这套机制的细节可以看越用越聪明是怎么运作的——核心是一条:学习绝不自动生效,每条修正可追溯、可测试、可一键回滚,自定义渠道和现成渠道走的是完全一样的规则,不存在“自定义接入就少一道保险”这种情况。
上线前自检清单
- API Key/Secret 按渠道分开申请,回调域名已加白名单
- 测试环境跑通“发消息—收回复—转人工”完整闭环
- 外部用户ID用的是稳定标识,不是临时Session ID
- 消息回传接口做了幂等去重,失败有重试队列
- 转人工事件回调已接通,前端有对应的状态提示
- 退款/赔付等高风险动作事件已同步进已有审批流程
自定义API接入的价值不在于“多一个渠道”,而在于把你自己系统里的对话拉进同一套AI先接、人工兜底、越用越聪明的机制里。鉴权、会话映射、消息回传、转人工回调这四步都配对了,自建渠道的客户体验就能跟微信、WhatsApp这些现成渠道站在同一条线上,而不是一个体验打折的“备用入口”。