# 云蝠开发文档

源码文档日期：2026-10-31。中文指南；接入与上线状态以你的环境验收为准。

本文与开放平台的“开发文档”使用同一内容源。完整接口字段见现有“接口文档”，这里按平台组织安装、生命周期、示例及排错。

下载链接使用站点相对路径：请在实际部署的云蝠主机打开，或在源码 public/downloads/ 中取得对应文件。

## 下载

- [有界批次调用示例](/downloads/api-batch-example.mjs)
- [业务回调接收示例](/downloads/business-callback-receiver.mjs)
- [业务回调验签模块](/downloads/verify-business-callback.mjs)
- [回调持久收件箱示例](/downloads/business-callback-inbox-postgres.mjs)
- [服务端只读接入示例](/downloads/server-api-read-example.mjs)
- [洞察录音API导入示例（Python）](/downloads/insights-audio-import.py)
- [下载 Web 客户端与示例](/downloads/yunfu-web-integration-kit.zip) · [校验清单](/downloads/yunfu-web-integration-kit.json)
- [下载 iOS 源码示例](/downloads/yunfu-ios-integration-kit.zip) · [校验清单](/downloads/yunfu-ios-integration-kit.json)
- [下载 Android 源码示例](/downloads/yunfu-android-integration-kit.zip) · [校验清单](/downloads/yunfu-android-integration-kit.json)
- [下载鸿蒙源码示例](/downloads/yunfu-harmony-integration-kit.zip) · [校验清单](/downloads/yunfu-harmony-integration-kit.json)
- [下载 Uniapp 源码示例](/downloads/yunfu-uniapp-integration-kit.zip) · [校验清单](/downloads/yunfu-uniapp-integration-kit.json)
- [下载小程序 SDK 源码与示例](/downloads/yunfu-wechat-miniapp-sdk.zip) · [校验清单](/downloads/yunfu-wechat-miniapp-sdk.json)
- [客户端合集接入包](/downloads/yunfu-client-integration-kit.zip) · [校验清单](/downloads/yunfu-client-integration-kit.json)
- [Uni-app 微信小程序 / H5 文本示例](/downloads/yunfu-uniapp-text-integration-kit.zip) · [校验清单](/downloads/yunfu-uniapp-text-integration-kit.json)
- [开发者对接指南（Markdown）](/downloads/yunfu-developer-guide.md)
- [OpenAPI 接口定义](/api/api-catalog?format=openapi)
- [接口目录（JSON）](/api/api-catalog?format=json)
- [接口参考手册（Markdown）](/api/api-catalog?format=markdown)
- [企业 SSO / MFA OpenAPI](/api/api-catalog?format=openapi&scope=identity)
- [语音 OpenAPI 定义](/api/api-catalog?format=openapi&scope=voice)
- [实时语音客户端](/api/voice-sdk?file=voice-client.mjs)
- [ESP32 语音接入头文件](/api/voice-sdk?file=yunfu-esp32-voice.h)
- [ESP32 固件接入指南](/api/voice-sdk?file=esp32-voice.md)
- [服务端开发客户端](/api/voice-sdk?file=developer-client.mjs)
- [语音客户端类型声明](/api/voice-sdk?file=voice-client.d.mts)
- [语音客户端通用类型声明](/api/voice-sdk?file=voice-client.d.ts)
- [语音协议指南](/api/voice-sdk?file=voice-protocol.md)
- [语音接入最佳实践](/api/voice-sdk?file=voice-best-practices.md)
- [预约语音联调示例](/api/voice-sdk?file=orbitbook-demo.zip)
- [全部客服技能包](/skills/all.zip)
- [技能安装工具](/skills/install.py)
- [技能版本与校验目录](/skills/index.json)
- [Codex 客服插件](/plugins/codex/yunfu-codex-plugin.zip)
- [MCP 接入说明](/plugins/mcp/README.md)
- [Harness 通用 Runner](/downloads/harness-cli-runner.mjs)
- [客服新手向导技能包](/skills/yunfu-service-guide/skill.zip)
- [接入与能力发现技能包](/skills/yunfu-api-integration/skill.zip)
- [智能体构建与优化技能包](/skills/yunfu-agent-builder/skill.zip)
- [号码与客户名单导入技能包](/skills/yunfu-number-import/skill.zip)
- [外呼任务管理技能包](/skills/yunfu-outbound-campaign/skill.zip)
- [线路诊断与呼叫测试技能包](/skills/yunfu-phone-test/skill.zip)
- [通话记录查询与导出技能包](/skills/yunfu-call-record-export/skill.zip)
- [通话结论与分析获取技能包](/skills/yunfu-call-conclusions/skill.zip)
- [工作流与渠道绑定技能包](/skills/yunfu-workflow-channel/skill.zip)
- [知识库建设与检索技能包](/skills/yunfu-knowledge-publisher/skill.zip)
- [客户资料与跟进技能包](/skills/yunfu-customer-crm/skill.zip)
- [回调订阅与恢复技能包](/skills/yunfu-callback-integrator/skill.zip)
- [结构化会话导入技能包](/skills/yunfu-conversation-import/skill.zip)
- [录音导入与质检技能包](/skills/yunfu-insights-audio/skill.zip)
- [服务分析与质量巡检技能包](/skills/yunfu-service-review/skill.zip)
- [余额与用量核查技能包](/skills/yunfu-billing-audit/skill.zip)
- [日常运营与持续推进技能包](/skills/yunfu-operations-manager/skill.zip)
- [人工接待与工单运营技能包](/skills/yunfu-reception-operator/skill.zip)
- [业务工具与数据接入技能包](/skills/yunfu-tool-integrator/skill.zip)
- [帮助中心运营技能包](/skills/yunfu-help-center-manager/skill.zip)
- [记忆与黑名单治理技能包](/skills/yunfu-memory-governance/skill.zip)
- [版本恢复与资源下线技能包](/skills/yunfu-resource-lifecycle/skill.zip)
- [语音与演练诊断技能包](/skills/yunfu-voice-diagnostics/skill.zip)
- [实时服务监看技能包](/skills/yunfu-live-monitor/skill.zip)
- [客服新手向导使用说明](/skills/yunfu-service-guide/SKILL.md)
- [接入与能力发现使用说明](/skills/yunfu-api-integration/SKILL.md)
- [智能体构建与优化使用说明](/skills/yunfu-agent-builder/SKILL.md)
- [号码与客户名单导入使用说明](/skills/yunfu-number-import/SKILL.md)
- [外呼任务管理使用说明](/skills/yunfu-outbound-campaign/SKILL.md)
- [线路诊断与呼叫测试使用说明](/skills/yunfu-phone-test/SKILL.md)
- [通话记录查询与导出使用说明](/skills/yunfu-call-record-export/SKILL.md)
- [通话结论与分析获取使用说明](/skills/yunfu-call-conclusions/SKILL.md)
- [工作流与渠道绑定使用说明](/skills/yunfu-workflow-channel/SKILL.md)
- [知识库建设与检索使用说明](/skills/yunfu-knowledge-publisher/SKILL.md)
- [客户资料与跟进使用说明](/skills/yunfu-customer-crm/SKILL.md)
- [回调订阅与恢复使用说明](/skills/yunfu-callback-integrator/SKILL.md)
- [结构化会话导入使用说明](/skills/yunfu-conversation-import/SKILL.md)
- [录音导入与质检使用说明](/skills/yunfu-insights-audio/SKILL.md)
- [服务分析与质量巡检使用说明](/skills/yunfu-service-review/SKILL.md)
- [余额与用量核查使用说明](/skills/yunfu-billing-audit/SKILL.md)
- [日常运营与持续推进使用说明](/skills/yunfu-operations-manager/SKILL.md)
- [人工接待与工单运营使用说明](/skills/yunfu-reception-operator/SKILL.md)
- [业务工具与数据接入使用说明](/skills/yunfu-tool-integrator/SKILL.md)
- [帮助中心运营使用说明](/skills/yunfu-help-center-manager/SKILL.md)
- [记忆与黑名单治理使用说明](/skills/yunfu-memory-governance/SKILL.md)
- [版本恢复与资源下线使用说明](/skills/yunfu-resource-lifecycle/SKILL.md)
- [语音与演练诊断使用说明](/skills/yunfu-voice-diagnostics/SKILL.md)
- [实时服务监看使用说明](/skills/yunfu-live-monitor/SKILL.md)

## 目录

### 产品与快速入门

- [阅读路线与示例使用方法](#reading-paths)
- [官方原始接入文档](#official-references)
- [选择接入方式](#integration-center)
- [云蝠接入概览](#overview)
- [自建渠道接入指南](#custom-channels)
- [快速入门：完成第一次接待](#first-conversation)
- [能力与交付状态](#capabilities)

### 隐私与权限

- [隐私告知与权限申请](#privacy)
- [入口、身份与凭据](#credentials)
- [生命周期与账号切换](#account-switch)

### iOS

- [iOS：快速接入](#ios-install)
- [iOS：生命周期、权限与排错](#ios-lifecycle)

### Android

- [Android：快速接入](#android-install)
- [Android：生命周期、权限与排错](#android-lifecycle)

### Harmony 鸿蒙

- [Harmony 鸿蒙：快速接入](#harmony-install)
- [Harmony 鸿蒙：生命周期、权限与排错](#harmony-lifecycle)

### Uniapp

- [Uniapp：快速接入](#uniapp-install)
- [Uniapp：生命周期、权限与排错](#uniapp-lifecycle)
- [Uni-app：微信小程序与 H5 客服](#uniapp-text)

### Web / H5

- [网站 / H5 嵌入](#web-embed)
- [无 UI Web 客户端快速接入](#web-client)
- [消息、人工转接与历史](#messages)
- [附件与业务扩展](#media)

### 微信小程序 SDK

- [小程序 SDK：安装与首条消息](#miniapp-install)
- [小程序生命周期与事件](#miniapp-events)
- [小程序 API 与能力边界](#miniapp-api)
- [与微信原生客服按钮的区别](#miniapp-native-contact)

### 服务端 API 与回调

- [服务端认证与首次调用](#server-auth)
- [企业 SSO 与 MFA 身份打通](#enterprise-sso)
- [幂等、版本与错误处理](#server-errors)
- [服务端 SDK、分页与失败恢复](#server-api-read)
- [Webhook：订阅、验签与回执](#callbacks)
- [业务回调接入：验签、去重与故障恢复](#callback-receiver)
- [API 性能与稳定接入](#api-performance)
- [语音接入与消息 SDK 的边界](#voice)
- [ESP32 语音智能体固件接入](#esp32)

### 业务服务接入

- [质检待办与整改复查](#insights-quality)
- [录音导入与语音质检](#insights-audio)
- [会话纪要与有据问答](#insights-minutes)
- [业务服务接入目录](#service-directory)

### 第三方渠道与业务模块

- [第三方渠道接入目录](#channel-directory)
- [主流接入覆盖与补齐计划](#mainstream-integration)
- [淘宝闪购](#channel-taobao-flash)
- [小红书](#channel-xiaohongshu)
- [Bilibili](#channel-bilibili)
- [微信小店](#channel-wechat-shop)
- [美团闪购](#channel-meituan-flash)
- [微信小程序](#channel-wechat-mini)
- [微信客服](#channel-wechat-kf)
- [微信公众号](#channel-wechat-mp)
- [企业微信](#channel-wecom)
- [抖音企业号](#channel-douyin)
- [百度营销](#channel-baidu)
- [X / Twitter](#channel-twitter)
- [WhatsApp](#channel-whatsapp)
- [Facebook](#channel-facebook)
- [Instagram](#channel-instagram)
- [LINE](#channel-line)
- [Discord](#channel-discord)
- [Google Play](#channel-google-play)
- [App Store](#channel-app-store)
- [钉钉](#channel-dingtalk)
- [飞书](#channel-feishu)
- [有赞](#channel-youzan)
- [微盟](#channel-weimob)
- [POPO](#channel-popo)
- [邮件](#channel-email)
- [Web / H5](#module-web)
- [iOS / Android / Harmony / Uniapp](#module-app-sdk)
- [微信小程序原生 SDK](#module-miniapp-sdk)
- [CRM / 客户资料](#module-crm)
- [工单 / 接待转人工](#module-tickets)
- [知识库](#module-knowledge)
- [AI Agent / 工具](#module-ai-agent)
- [呼叫 / 外呼任务](#module-call)
- [会话记录 / 数据回传](#module-records)
- [业务事件 / Webhook](#module-callbacks)
- [智能质检](#module-quality)
- [员工 / 组织 / 单点登录](#module-staff)
- [短信](#module-sms)

### AI 工具与技能

- [AI 工具、MCP、CLI 与技能接入](#automation)

### 排错与更新记录

- [SDK 错误与待核对请求](#sdk-errors)
- [接入常见问题](#troubleshooting)
- [联调与上线验收清单](#acceptance)
- [下载与更新记录](#downloads)

<a id="insights-quality"></a>

## 质检待办与整改复查

从需要处理的会话出发，在同一证据工作台完成核对、改判、复核与整改。

### 三步处理一条质检待办

1. **看处理重点**：进入洞察 → 会话分析 → 智能质检，默认只展示正式会话的优先待办。
2. **核对原文**：点击会话直达质检详情，查看实际执行方案、命中原因与引用。
3. **处理并复查**：必要时逐项改判、保存人工复核，再关联负责人和期限，沿用整改任务跟进。

### 每个状态代表什么

| 队列 | 含义 | 下一步 |
| --- | --- | --- |
| 风险待复核 | 当前结果有可核对的原文命中，尚未完成人工复核 | 核对服务方/客户角色、上下文和规则后再判定 |
| 依据待补齐 | 尚未分析、原文已变、角色未确认、规则unknown或引用不足 | 补齐录音角色或资料，重新分析；信息不足不计为通过 |
| 整改待跟进 | 人工复核后仍保留风险命中，且当前轮尚未完成对应整改 | 在原质检项下创建或跟进整改，记录处理和复查 |
| 已完成人工复核 | 当前结果有独立人工评分及复核理由 | 不代表规则全部通过，也不代表业务问题已解决 |

### 按实际执行版本查看

顶部按日期、来源、接待类型及实际质检方案版本筛选；已经退役的方案仍可通过会话保留的执行快照核对。不要把提取字段版本当成质检方案版本。

卡片统计当前筛选范围，队列筛选决定列表显示哪些待办。指标可以重叠，例如一条会话既有可靠命中，也有其他规则需要补充依据，不能把四张卡片相加当成会话总数。

默认排除演示数据；需要演练时在“数据性质”中明确选择演示数据。导出只包含当前可见队列的会话，不会夹带隐藏或其他筛选范围的记录。

### 原判、复核和整改分别保留

原文、角色或来源变化后，旧分析不能继续作为当前有效结果。模型的命中/通过必须能定位到对应角色的真实原话；unknown、不适用和证据不足不能折算为满分。

人工评分与模型原判分别保留。认为误判时使用逐项改判并填写依据；仅把人工评分设成100分不会自动删除命中项。

整改任务固定创建时的质检依据。旧分析轮次的已关闭任务不能消除新一轮待办；当前命中项仍有未关闭任务时继续跟进。即使任务关闭，原风险和复查记录仍保留，不自动宣称客户问题已解决或优化已见效。

### 避免重复整改并完成本轮复查

1. 同一会话、同一质检项已有未关闭任务时，点击“查看已有任务”直接进入对应记录。重新分析不会创建第二个待办，也不会覆盖旧任务的负责人、期限和证据。并发创建被拒绝时保留当前表单，明确提示本次填写尚未保存。
2. 效果记录提交成功但读取失败时，点击“刷新已保存效果”，或使用页面“刷新”。恢复只读取数据，不重新提交；读到保存后的任务版本才能继续操作。
3. 关闭任务前须记录本轮效果复查结果，数据不足也需如实说明。已关闭任务的效果记录保留供核对；继续整改时先点击“重新打开”，建立新轮次的基线和观察周期。上一轮结果不能代替本轮复查。

### 先确定何时检查，再判断检查要求

1. 在已有分析方案的规则卡中填写“何时检查（选填）”，例如“客户明确申请退款时”；在“检查要求”填写应核查的行为，例如“服务方明确说明受理动作与处理时限”。条件留空则沿用原规则。
2. 保存草稿不会修改已发布版本或已有会话。候选方案仍须经过既有学习与评测流程，再明确启用；实际执行时保留该轮条件、要求和版本。
3. 模型在同一次分析内输出条件依据和要求依据。条件明确成立才检查要求；有明确反向事实才可提议不适用。没有提到退款，不等于客户没有退款诉求，条件不明须保留unknown。
4. 条件证据须是已知角色的真实原话，要求证据还须满足该规则的核查角色。缺失或虚构依据不会放行通过；不适用仍不折算满分，须人工核对。
5. 这些约束只能验证引用来源和状态一致性，不能形式证明模型对自然语言的解释一定正确；关键结论继续对照原文进行人工复核。

### 人工补齐条件依据

1. 打开会话的“质检与行动”，在对应规则下点击“人工改判”。先核对“何时检查”，填写“适用性确认”“条件核对说明”，并选择真实的条件原话来源。
2. 条件原话可来自已确认身份的客户或服务方，检查要求的原话仍须符合规则指定的核查角色。两种依据分别保存；条件不明时，不能将该项保存为命中或通过。点击依据可回到原文核对。
3. 人工判为不适用时须写清理由，并完成整通会话的人工复核。该结果不会计入完整分数，也不会自动变成通过；模型原判与人工改判依据分别保留。

### 在同一业务问题内切换多通沟通

先通过已有“关联问题”入口填写明确的工单、订单或业务问题编号。当前可见记录中存在同编号的多条沟通时，详情会出现“同一业务问题”切换控件，可在文字、电话或导入录音间逐通核对。

只使用当前账号已获授权、业务编号相同且数据性质一致的记录；正式会话和演示会话不会混在同一组。按真实时间排序，切换继续遵守未保存修改保护。

每通沟通保留自己的原音、原文、规则版本与评分。这里不生成跨会话合并分数，不会按姓名或相似内容自动归并客户。

### 围绕具体业务检查

1. 使用已有分析方案设置场景、核查角色、自然语言规则和权重。例如售后可检查处理承诺、跟进安排及客户是否明确确认解决。
2. 需要关联重复咨询时，在会话详情使用明确的工单或业务问题编号；洞察改进页可核对跨会话矛盾与后续反馈。不会按相同姓名自动合并客户，也不把关联线索冒充多会话联合质检。
3. 有录音时先转写、核对说话人，再进入语义质检；声学指标须来自实际音频测量或人工核听，不能由文字推测。
4. 本轮使用现有分析与整改能力，不会因为打开质检页就批量调用模型，也不把已接入会话数当成全量自动质检完成数。

### 从反馈分类回到客户原话

1. 进入洞察 → 洞察改进，默认只看正式会话。在“字段快照”选择当时的实际字段版本，再选“分类字段”，例如诉求、反馈方向或客户问题。分类来自已有提取结果，不按关键词临时猜测情绪。
2. 需要交叉核对时选择“同会话标签”，例如查看同一通会话是否同时提到某产品。此处只表示会话共现，不自动建立主题与情绪的对应关系；多主题、多标签需要分别核对两类原话。点击分类可查看会话数、原话段数，展开“上下文”核对前后轮次，点击“核对原话”定位到证据工作台的原文。
3. 同一会话可以提供多段原话，多选分类也可能重叠。这里统计会话和原话，不将它们当成独立客户数，也不把各分类数量直接相加。
4. 只有客户角色的真实引用才能支持分类。尚未完成语义分析、录音角色未确认、过期或执行快照不一致的记录不纳入统计。分类缺失、引用不可信和人工修订待补依据保留在“分类待核实”，不会冒充有效分类。
5. 演示数据须明确切换，仅演示会话参与当次统计；与正式数据严格分开。打开页面、搜索和切换分类不触发模型调用。

### 看清每项要求的执行依据

在同页切换“执行观察”，按完整执行方案快照分别查看检查项。符合率为“符合 ÷（符合 + 风险命中）”，同时展示分母、待核实和不适用数量；没有有效分母时显示横线。

点击检查项，再选择“符合”“风险命中”“待核实”或“不适用”，即可核对具体会话和原话。人工改判会单独标记；人工总评分不能替代逐项判断，未知和不适用不能折算通过。

不同字段或规则快照不合并成同一执行率。本页暂不提供人员绩效排名、客户人数、周期改善归因或实时接待建议；需要这些能力时先补齐可比较的业务范围及来源。

### 对照服务执行与业务结果

1. 在会话详情点击“登记业务结果”，选择订单成交、预约到店或问题解决，填写已核对的来源、业务编号、结果时间与依据。状态分为已达成、未达成和待确认；AI提取的处理结果、客户意向和创建工单成功不会自动变为业务已达成。
2. 每条会话保留一个当前业务目标，修改前结果留在操作历史。操作者与登记时间由服务器记录，过期版本必须刷新再改；原渠道文本重新同步时保留业务结果，质检仍需重新分析。
3. 进入洞察改进 → 结果对比，选择业务目标和执行快照。按来源与业务编号去重，选结果发生前最后结束的会话；同编号的状态或结果时间冲突时整组排除。结果早于会话结束、待确认、无效记录、待核实和不适用检查项不进入达成率分母。
4. 符合组与风险命中组分别显示已达成数、有效分母、达成率及百分点差。每组不足10个业务结果会提示样本少；这些是观察性关联，不是因果结论或显著性检验。点击比例核对业务记录和会话原话，可从同一工作台继续整改跟进。
5. 可按会话来源、接待人标记查看摘要；尚未接入完整组织、全量接待或订单台账，因此不计算团队绩效排名和录音覆盖率。当前业务结果仅支持授权工作台人工登记，尚未开放业务结果写入API，也没有自动接通订单或预约系统。

### 导出带时效说明的质检报告

质检页导出当前可见队列，包含实际执行方案与版本、结果时效、处理重点、模型原判与原得分、当前逐项判定及得分、人工评分和改判依据。原文已变化的旧分数会明确标记为历史结果，不能作为当前有效结论。

报告按当前账号号码可见权限脱敏，方案名称等自定义文字也会处理；导出不重新运行模型，也不改变复核和整改状态。

继续阅读：[录音导入与语音质检](#insights-audio) · [会话纪要与有据问答](#insights-minutes) · [业务服务接入目录](#service-directory)

实现依据（仓库内路径）：`lib/insights/insights-customer-discovery.ts`、`frontend/components/insights/discovery-explorer.tsx`、`lib/insights/insights-quality-queue.ts`、`lib/insights/insights-quality-export.ts`、`lib/insights/rule-applicability.ts`、`frontend/components/insights/related-conversations.tsx`、`frontend/components/insights/workspace-content.tsx`、`backend/services/insights/insights-analysis-state.ts`

<a id="insights-audio"></a>

## 录音导入与语音质检

从网页或服务端上传原始录音，跟踪文件识别、确认说话人并执行可核验的质检。

### 接入流程

1. **上传原音**：创建任务并分块上传，保留私有原音。
2. **异步转写**：校验真实时长后提交百炼文件识别；持久化供应商任务号。
3. **确认角色**：声道和说话人编号先作为未知身份，人工映射客户、坐席或AI。
4. **分析与复核**：选择已发布分析方案，查看逐字证据、字段、风险、评分及人工复核。

### 准备条件

1. 平台为企业开通洞察；网页操作者须为具备服务与报表权限的企业管理员。API还需开放平台权限，并给密钥明确授权对应insights.audio操作。
2. 管理员在「语音引擎 → 洞察 ASR」独立配置百炼北京密钥、文件识别模型和企业授权，不必配置或修改语音智能体。也可在录音上传时明确选择复用已授权的语音 ASR。仅一个独立资源时优先使用；多个独立资源须明确选择。旧 cn 语音资源按北京处理。
3. 文件识别使用语音分钟额度，提交前预留、识别成功后按已验证文件时长向上取整分钟结算；文本模型分析另走已有模型计费。
4. 在洞察设置中选择当前企业可用的分析模型；本地规则检查也可运行，但不能视为模型语义质检。

### 文件与容量

支持WAV、MP3、M4A、AAC、FLAC、OGG和WebM，单文件100MB、单/双声道、最长2小时；逐次上传1MiB分块。非标准PCM WAV需要服务端ffprobe解码校验（macOS本地预览可使用系统afinfo）；工具缺失或解码失败时明确拒绝，不假装识别成功。

每个企业最多300个尚未清理原音的录音任务、声明原音总量2GiB；列表只加载最近100个任务，原音不写入会话JSON或公开目录。原音清理后释放相应上传容量，任务、转写、质检和复核记录独立保留。

单会话语义质检最多1000段、6万字。大文件识别超过此范围保留失败状态，不能截断后伪装完整质检。

### 原始音频保留时间

1. 进入洞察 → 配置管理 → 工作区设置，由企业管理员设置原始音频保留期。默认365天，支持1–3650天，例如5天。API上传也遵循上传时的企业策略。
2. 默认只影响之后上传的录音；每个任务保存当时的保留期和到期时间，后续改设置不会自动修改已有录音。期限以任务创建（开始上传）时间计算，不以录音发生时间计算。
3. 需要调整已有录音时，单独勾选历史范围，先查看影响数量、将立即到期的数量与容量，再明确确认。配置或任务变化会拒绝旧预览，重新核对后再保存。已到期或已清理原音不能通过延长期限恢复。
4. 到期立即停止回听、上传续传和新识别/重试，原音访问返回410。已有供应商识别任务可查回已经产生的转写，不重新提交。后台维护按索引分批清理平台保存的原始音频，不把大量清理放进页面请求。
5. 保留转写、纪要、质检、复核及费用核对记录；原音到期后显示明确状态。此设置不承诺删除供应商侧副本，也不等于删除原始业务渠道自身保留的录音。

### API操作与状态

| 操作 | 方法及路径 | 用途 |
| --- | --- | --- |
| 创建任务 | POST /v1/operations/insights.audio.create | requestId、filename、bytes、source、startedAt、channels、asrResourceId、asrModel |
| 上传分块 | POST /v1/operations/insights.audio.chunk | jobId、从0开始的index、纯Base64 data；同序号同内容可重放 |
| 完成上传 | POST /v1/operations/insights.audio.complete | jobId；校验完整分块、格式和时长，随后异步处理 |
| 查询任务 | GET /v1/operations/insights.audio.read?jobId=任务ID | 查询任务、conversation的转写/质检结果/复核及说话人片段；不传jobId返回最近任务 |
| 推进/接续 | POST /v1/operations/insights.audio.advance | jobId；服务重启或浏览器关闭后可接续已有供应商任务 |
| 确认角色 | POST /v1/operations/insights.audio.roles | jobId、当前会话revision、roles对象；使用返回的speaker键 |
| 执行质检 | POST /v1/operations/insights.audio.analyze | jobId、会话revision、requestId、engine=model或local、planMode=bound或latest |
| 人工复核 | POST /v1/operations/insights.audio.review | jobId、revision、score(0–100)、reason(1–3000字依据)；不覆盖模型原结论 |
| 明确重试 | POST /v1/operations/insights.audio.retry | jobId、confirmProviderRetry=true；可补asrResourceId/asrModel，先核对供应商任务和费用 |

### 状态与恢复

uploading表示原音未传完；queued表示已保存待识别；submitting表示可能已调用供应商；recognizing表示已保存供应商任务号；transcribed表示已转写待角色与质检；completed表示当前会话已有未过期分析。

failed不代表业务质检不合格，通常是配置/识别未完成。uncertain表示提交结果未知，必须先核对供应商控制台和费用，再明确重试；禁止自动重复提交。明确未提交/供应商明确失败释放预留，未知结果保留待核对；再次提交使用新的预留凭证，原未知预留会在任务中显示，不自动冒充退款。分析失败仍保留原音及转写，可以在同一会话重新分析或恢复已有模型回执。

当前音频只作为证据回放与ASR输入。语义模型只接收转写，不把文字推断成音量、噪声、静音或抢话的声学测量；这些信息需结合原音人工核查。

### 可下载的上传示例

本节下方及下载中心提供标准库Python导入示例（insights-audio-import.py）下载。密钥从环境变量读取，不写入源码。

所有写请求需要8–100位Idempotency-Key。每个分块保持稳定key；advance每次使用新key，否则网关会重放旧状态。相同requestId不能对应不同文件元数据。

使用位置：`run-import.sh` · 命令文件

运行前：
- 先下载 insights-audio-import.py，与本脚本放在同一目录。
- 设置脚本列出的环境变量；时间、声道和文件必须对应自己的已授权录音。

```sh
#!/bin/sh
# Copy beside insights-audio-import.py; set all values for your own authorized recording.
set -eu
: "${YUNFU_BASE_URL:?Set the service HTTPS origin}" "${YUNFU_API_KEY:?Set the server API key}"
: "${YUNFU_RECORDING_STARTED_AT:?Set the actual recording timestamp with timezone}"
: "${YUNFU_AUDIO_PATH:?Set the recording file}" "${YUNFU_ASR_RESOURCE_ID:?Set the authorized ASR resource}"
: "${YUNFU_CHANNELS:?Set the actual channel count}" "${YUNFU_REQUEST_ID:?Retain one stable ID for this import}"
python3 ./insights-audio-import.py "$YUNFU_AUDIO_PATH" --origin "$YUNFU_BASE_URL" \
  --resource "$YUNFU_ASR_RESOURCE_ID" --channels "$YUNFU_CHANNELS" \
  --request-id "$YUNFU_REQUEST_ID" --wait 600
```

预期结果：执行会上传录音并等待状态；未知结果沿用原 requestId 核对，不重新创建导入。

### 验收与错误处理

1. 上传一个自有、已获授权的短录音；核对bytes、声道及真实时长，确认跨企业jobId返回404。
2. 等待transcribed后，按原音确认说话人角色；unknown不会自动变为客户或坐席，未确认不能执行质检。
3. 核对质检采用的方案/模型、原话证据、字段缺失和规则unknown；模型成功不代表服务已解决。
4. 人工复核保留说明及历史，再按原有整改任务跟进。400/413为输入问题，402为额度，403为开通/权限，409为版本冲突，422为配置/解码，429为并发限制。

继续阅读：[会话纪要与有据问答](#insights-minutes) · [服务端认证与首次调用](#server-auth) · [业务服务接入目录](#service-directory) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`backend/services/insights/insights-audio-service.ts`、`backend/services/insights/insights-audio-provider.ts`、`backend/services/insights/insights-audio-retention.ts`、`database/stores/insights-audio-retention-store.ts`、`app/api/insights-audio/route.ts`

<a id="insights-minutes"></a>

## 会话纪要与有据问答

围绕同一会话生成不同视角的纪要，保留原文引用、待确认行动与历史版本。

### 从会话进入

1. 在洞察的会话中心或录音分析打开会话，进入会话证据工作台的“会话纪要”页签。平台须开通洞察，操作者须具备服务与报表权限。
2. 先在洞察设置选择已开通的文本分析模型。点击“生成纪要”才调用模型并产生用量；刷新、切换版本和导出已保存纪要不会再次调用模型。音频须先转写，模型只阅读当前会话文字。

### 按业务选择阅读视角

| 模板 | 适合场景 | 阅读重点 |
| --- | --- | --- |
| 通用纪要 | 会议、咨询和回访 | 议题、明确结论、后续行动、待核实事项 |
| 销售机会 | 销售沟通和商机跟进 | 明确需求、顾虑、购买条件、后续安排 |
| 服务复盘 | 客服接待和售后处理 | 客户诉求、实际处理、承诺与未解决事项 |
| 回访跟进 | 客户回访和结果核对 | 现状、反馈、变更、下一步核对事项 |

### 从结论回到原话

摘要、议题、结论和行动均需引用当前会话中的原话。展开“原文依据”，可定位转写片段；带时间的片段同时显示时间位置。没有足够依据时明确显示信息不足。

负责人和截止时间只有原文明确出现才展示，未提及显示“未明确”，不根据“说话人1”等编号猜测真实身份。行动项是待确认清单，不代表已创建工单、已通知成员或业务已完成。

模型只读转写，不把文本猜测成音量、静音、抢话或噪声的声学测量；原音仍可在其有效保留期内核对。

### 围绕当前会话提问

展开“基于这段会话提问”，输入希望核对的问题，例如“客户提出了哪些顾虑”或“哪些承诺仍待确认结果”。回答仍受原文引用约束；问题和回答保存为独立版本，不覆盖已有纪要或质检。

本功能仅分析当前会话，不会检索整个企业的全部历史会话或代替业务系统执行操作。当前入口是登录后的洞察工作台；开放API录音导入完成后，可在工作台继续查看与生成纪要。

### 版本、恢复和导出

1. 每次生成新增不可覆盖的版本，每会话最多20次请求记录；切换版本查看模板、生成时间、模型与来源版本。达到上限后请明确管理业务记录，系统不会静默淘汰审计记录。
2. 原文、角色或来源内容变化后，旧纪要标记为历史版本并保留原引用，禁用向新原文跳转。刷新原文后可以再次生成，质检、人工复核和整改记录分别保留。
3. 请求中断不等于未计费；先核对原请求状态和费用。已有模型回执可恢复时使用恢复入口，不重新调用模型；未知结果不自动重试。
4. 可下载当前选中的Markdown纪要，包含模板、模型、版本、原话及历史版本提示。导出遵循当前账号手机号可见权限。

### 验收建议

1. 选择一段有明确后续安排的自有会话，生成通用纪要，逐条展开引用并核对原文。
2. 使用另一模板或提问生成新版本，确认原纪要、质检与复核结果仍存在。
3. 核对缺失负责人和时间没有被自动补全；修改原文后，旧纪要必须显示历史提示并停止定位到新原文。
4. 核对已脱敏账号的页面与Markdown导出均不暴露完整手机号；原音到期后，已有转写和纪要仍可阅读。

继续阅读：[录音导入与语音质检](#insights-audio) · [业务服务接入目录](#service-directory) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/insights/insights-minutes.ts`、`backend/services/insights/insights-minutes-service.ts`、`frontend/components/insights/minutes-panel.tsx`

<a id="reading-paths"></a>

## 阅读路线与示例使用方法

先选目标，再完成一个最小闭环；按文件位置使用同一接入包的示例。

### 按目标开始

| 目标 | 先读什么 | 本轮完成的结果 |
| --- | --- | --- |
| 在网站或 App 中接待 | 自建渠道 → 对应客户端快速接入 | 真实客户发出一条消息，接待台找到同一会话和回复 |
| 集成语音互动 | 对应客户端 → 语音边界 → 官方平台原文 | 实际收音、AI 出声、可打断、挂断与后台清理分别确认 |
| 业务系统调用接口 | 服务端认证 → capabilities → 接口参考 | 当前密钥确有目标操作权限，用当前字段完成一次授权调用 |
| 连接外部 AI 助手 | AI 工具接入 → 企业连接核对 → 对应任务 | 客户端确认实际企业和最小权限，再按具体任务检查执行结果 |

### 打开对应路线

- [客户端与渠道接入](#custom-channels)
- [语音互动接入](#voice)
- [服务端 API 首次调用](#server-auth)
- [AI 助手与工具接入](#automation)
- [官方平台前提与原始说明](#official-references)

### 使用代码示例的顺序

1. 先看“使用位置”和“运行前”，从同一下载包复制对应文件并保留相对目录。不要把模块文件当作浏览器控制台命令。
2. 替换自己的公开入口参数；服务端密钥只设置在服务端环境。示例里的占位值不对应真实可用资源。
3. 先执行只读检查，再由用户点击打开接待或语音。看到代码或复制成功，不代表连接、录音或业务已完成。
4. 核对“预期结果”，再做拒绝权限、网络未知、重复提交、账号切换与关闭清理。较长完整文件可展开或从接入包中阅读。

### 如何确认示例是当前版本

本指南的全部代码块来自接入包中的源码文件，或现有只读预检命令；在线页面与离线手册使用同一份生成结果。修改示例源码后须重新生成并检查，不能只改页面里的一段代码。

接口参考的五种语言示例继续由当前开放操作和请求契约生成；只有请求骨架时必须先补齐真实业务字段。原生工程编译、真机媒体和真实业务调用的验收边界分别保留。

继续阅读：[快速入门：完成第一次接待](#first-conversation) · [下载与更新记录](#downloads) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`scripts/developer-guide-examples.mjs`、`lib/developer-docs/developer-guide-examples.json`

<a id="official-references"></a>

## 官方原始接入文档

按接入阶段查阅微信、腾讯 TRTC 和各客户端平台的官方说明，并对照云蝠交付边界。

### 先区分两类文档

先按云蝠指南完成入口、智能体和服务配置，再按下列官方原文配置宿主权限或供应商资源。外部文档说明对应平台能力，不代表云蝠已开放其中全部接口；腾讯 SecretKey、签名密钥和管理 API Key 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。

### 谁需要完成哪些配置

| 负责方 | 负责内容 | 核对结果 |
| --- | --- | --- |
| 企业管理员 | 开通语音、启用渠道入口、绑定已发布智能体并准备可用额度 | 入口配置与服务资源可用；未开通时不显示可开始语音的入口 |
| 宿主开发者 | 按官方说明配置微信类目/域名/隐私或 App 权限，安装对应接入包 | 实际宿主允许录音、播放和退出清理；系统授权与网页授权分别核对 |
| 部署维护者 | 在服务端配置腾讯应用、签名、AI 对话资源与回收任务 | 进房和 AI 任务结果可核对，挂断后任务及计费正确结束 |
| 联调人员 | 用同一入口完成首条消息、实际语音、打断、拒绝和账号切换 | 云端返回成功、页面显示成功与实际音频结果分别留证 |

### Uni-app 微信小程序与 H5 客服

- [DCloud · CLI 创建与构建](https://uniapp.dcloud.net.cn/quickstart-cli.html)：核对 Vue2 Vue CLI / webpack 与 Vue3 Vite 的不同构建入口、编译目标和输出目录；编译不等于平台发布。
- [DCloud · web-view 原版网页承载](https://uniapp.dcloud.net.cn/component/web-view.html)：核对微信业务域名、全屏展示及宿主导航；原版页面和原生文本模式使用不同域名类别。
- [DCloud · 页面与生命周期](https://uniapp.dcloud.net.cn/tutorial/page.html)：合并页面与应用事件，防止隐藏路由继续轮询。
- [DCloud · 小程序开发注意事项](https://uniapp.dcloud.net.cn/tutorial/miniprogram-subject.html)：区分 Vue 组件与原生微信组件注册，核对目标能力。

### 微信小程序：网络与域名

- [微信开放文档 · 小程序网络与合法域名](https://developers.weixin.qq.com/miniprogram/dev/framework/ability/network.html)：原生请求需配置 request、uploadFile、downloadFile 合法域名；WebView 另需业务域名，关闭校验不能代替正式配置。

### 微信小程序：隐私与录音

- [微信开放文档 · 隐私授权开发指引](https://developers.weixin.qq.com/miniprogram/dev/framework/user-privacy/PrivacyAuthorize.html)：接入宿主隐私告知和同意流程；隐私同意、系统麦克风授权与实际收音分别验收。
- [微信开放文档 · wx.authorize 授权接口](https://developers.weixin.qq.com/miniprogram/dev/api/open-api/authorize/wx.authorize.html)：核对 scope.record 与拒绝后的处理；进入聊天页或点击普通按钮不等于已完成录音授权。
- [微信开放文档 · live-pusher 原生推流组件](https://developers.weixin.qq.com/miniprogram/dev/component/live-pusher.html)：核对原生推流组件、主体及类目权限；与腾讯 SDK 配置配套，在真机验证音频事件。

### 腾讯 TRTC：实时语音与 AI 对话

- [腾讯云 · 原生小程序快速接入](https://cloud.tencent.com/document/product/647/116548)：先核对企业主体、允许类目、推拉流权限、TRTC 套餐和 SDK 域名，再完成进房、发布音频与退房；开发工具不能代替真机。
- [腾讯云 · 实现 AI 对话](https://cloud.tencent.com/document/product/647/108901)：理解 RTC、识别、LLM、TTS、转录和打断的职责；具体参数与频率以对应接口的当前版本为准。
- [腾讯云 · 开始 AI 对话任务 · StartAIConversation](https://cloud.tencent.com/document/product/647/108514)：服务端适配时核对地域、SdkAppId、房间、目标用户与模型配置，保留 TaskId/RequestId；返回成功还需核对手机是否实际出声。
- [腾讯云 · 控制 AI 对话 · ControlAIConversation](https://cloud.tencent.com/document/product/647/109408)：核对供应商支持的播报和模型触发命令；仅供服务端适配参考，不可直接当作云蝠公开操作调用。
- [腾讯云 · 停止 AI 对话 · StopAIConversation](https://cloud.tencent.com/document/api/647/108513)：结束服务端 AI 对话任务并核对原 TaskId 的回收结果；退出客户端页面不应被当作云端任务已停止的证明。
- [腾讯云 · 高级权限控制](https://intl.cloud.tencent.com/zh/document/product/647/35157?lang=zh)：评估服务端 UserSig、PrivateMapKey 与房间隔离；通用平台表不证明小程序和 AI bot 已兼容，启用前须在实际应用核对入房。

### Web / H5：网页麦克风与嵌入权限

- [MDN · getUserMedia 麦克风采集](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia)：核对 HTTPS、用户授权、设备和浏览器兼容性；打开页面不等于麦克风可用。
- [MDN · Permissions-Policy: microphone](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/microphone)：配置父站点允许的客服来源并配合 iframe allow；响应头限制仍生效，不能用放开 CORS 解决麦克风拒绝。

### iOS：系统用途说明与 WebKit 授权

- [Apple · NSMicrophoneUsageDescription](https://developer.apple.com/documentation/bundleresources/information-property-list/nsmicrophoneusagedescription)：将真实录音用途写入宿主 Info.plist；只复制 Swift 容器不足以完成权限接入。
- [Apple · WKUIDelegate 媒体采集权限](https://developer.apple.com/documentation/webkit/wkuidelegate/webview%28_%3Arequestmediacapturepermissionfor%3Ainitiatedbyframe%3Atype%3Adecisionhandler%3A%29)：按可信 origin、frame 与媒体类型处理网页请求；系统录音权限和网页媒体授权需要分别处理。

### Android：系统录音与 WebView 媒体权限

- [Android Developers · 请求运行时权限](https://developer.android.com/training/permissions/requesting)：声明并请求 RECORD_AUDIO；处理拒绝、永久拒绝及恢复，不把权限请求回调当作全部获准。
- [Android Developers · WebView PermissionRequest](https://developer.android.com/reference/android/webkit/PermissionRequest)：在 UI 线程仅授予当前可信来源的音频资源，处理取消请求；不直接 grant(getResources()) 放行未知媒体权限。

### Harmony：ArkWeb 事件与权限声明

- [OpenHarmony · ArkWeb onPermissionRequest](https://github.com/openharmony/docs/blob/master/en/application-dev/reference/apis-arkweb/arkts-basic-components-web-events.md#onpermissionrequest9)：核对网页音频授权事件与 grant/deny；文档主干会更新，本包 API12+ 示例仍须用目标 SDK 编译并真机验收。
- [OpenHarmony · 声明应用权限 · 5.0 Release](https://github.com/openharmony/docs/blob/OpenHarmony-5.0.0-Release/zh-cn/application-dev/security/AccessToken/declare-permissions.md)：合并 MICROPHONE、用途字符串与实际 Ability 的 usedScene；清单声明不能代替运行时授权。

### Uniapp：选择目标与基座权限

- [DCloud · uni-app web-view 组件](https://uniapp.dcloud.net.cn/component/web-view)：区分 App-vue、H5 iframe 和微信目标；不同内核不能复用同一套原生权限假设。
- [DCloud · manifest.json 配置](https://uniapp.dcloud.net.cn/tutorial/app-manifest.html)：合并 Android 录音权限和 iOS 麦克风用途说明，并重新制作实际使用的自定义基座。
- [DCloud · plus.android.requestPermissions](https://www.html5plus.org/doc/zh_cn/android.html#plus.android.requestPermissions)：分别检查 granted、deniedPresent、deniedAlways；系统授权成功不等于远端 WebView 已收音，需基座验收。

### API 契约：OpenAPI 标准

- [OpenAPI Initiative · OpenAPI Specification 3.1.0](https://spec.openapis.org/oas/v3.1.0)：理解本站 OpenAPI 文件的 schema、安全方案与导入格式；实际云蝠接口、字段和权限仍以本站接口参考为准。

继续阅读：[小程序 SDK：安装与首条消息](#miniapp-install) · [网站 / H5 嵌入](#web-embed) · [语音接入与消息 SDK 的边界](#voice) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/developer-official-references.ts`

<a id="integration-center"></a>

## 选择接入方式

先选目标，再查看对应指南、示例和下载。

### 你要接入什么？

- [网站、App 与小程序客服](#custom-channels)
- [服务端 API 与业务系统](#server-auth)
- [语音互动与电话](#voice)
- [AI 助手与工具](#automation)

### 完成首次接入

1. 按对应指南准备入口、智能体和所需权限。
2. 使用同一接入包的示例，替换自己的入口参数；API Key 只保存在服务端。
3. 核对首条消息或真实接口调用结果，再按需扩展。语音还需分别验证收音、出声、打断和挂断。

### 渠道与客户端

- [自建渠道接入指南](#custom-channels)
- [主流接入覆盖与补齐计划](#mainstream-integration)
- [网站 / H5 嵌入](#web-embed)
- [Web 无 UI 消息 SDK](#web-client)
- [微信小程序 SDK](#miniapp-install)
- [iOS · WKWebView 源码](#ios-install)
- [Android · WebView 源码](#android-install)
- [HarmonyOS 鸿蒙 · ArkWeb 源码](#harmony-install)
- [Uni-app · App-vue 源码](#uniapp-install)
- [第三方渠道接入目录](#channel-directory)

### 接口与业务服务

- [服务端认证与首次调用](#server-auth)
- [企业 SSO 与 MFA 身份打通](#enterprise-sso)
- [客户、工单、知识、智能体与业务模块](#service-directory)
- [Webhook 订阅与验签](#callbacks)
- [幂等、版本和错误处理](#server-errors)

### 语音与 AI 工具

- [语音接入指南与能力边界](#voice)
- [Codex、Claude Code、WorkBuddy 与 MCP / CLI / Skills](#automation)

### 下载、联调与上线

- [官方原始接入文档与职责分工](#official-references)
- [下载中心：接入包、语音客户端、插件与离线文档](#downloads)
- [入口、身份与凭据](#credentials)
- [隐私与权限](#privacy)
- [联调与上线验收](#acceptance)
- [接入常见问题](#troubleshooting)

继续阅读：[自建渠道接入指南](#custom-channels) · [下载与更新记录](#downloads) · [快速入门：完成第一次接待](#first-conversation)

实现依据（仓库内路径）：`lib/developer-docs/developer-guide.ts`、`lib/developer-docs/developer-documentation-downloads.ts`

<a id="service-directory"></a>

## 业务服务接入目录

复用当前服务与接口，逐项核对权限、交付状态和真实执行回执。

### 选择业务服务

- [Web / H5](#module-web)
- [iOS / Android / Harmony / Uniapp](#module-app-sdk)
- [微信小程序原生 SDK](#module-miniapp-sdk)
- [CRM / 客户资料](#module-crm)
- [工单 / 接待转人工](#module-tickets)
- [知识库](#module-knowledge)
- [AI Agent / 工具](#module-ai-agent)
- [呼叫 / 外呼任务](#module-call)
- [会话记录 / 数据回传](#module-records)
- [业务事件 / Webhook](#module-callbacks)
- [智能质检](#module-quality)
- [员工 / 组织 / 单点登录](#module-staff)
- [短信](#module-sms)

### 洞察与录音分析

- [质检待办、证据核对与整改复查](#insights-quality)
- [录音导入、保留时间与语音质检](#insights-audio)
- [会话纪要、原文引用与有据问答](#insights-minutes)

### 阅读接入状态

具体模块文档保留当前支持范围和准备中状态。公开说明和下载包不代表企业已经开通、第三方已经授权或真实业务操作已经成功。

### 接口与回调

- [认证与首次调用](#server-auth)
- [业务回调和验签](#callbacks)
- [重试、幂等与结果核对](#server-errors)

继续阅读：[选择接入方式](#integration-center) · [下载与更新记录](#downloads) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`、`lib/developer-api/developer-operations.ts`

<a id="channel-directory"></a>

## 第三方渠道接入目录

按实际渠道选择接入流程，支持范围与验收要求在各篇文档中维护。

### 选择第三方渠道

- [淘宝闪购](#channel-taobao-flash)
- [小红书](#channel-xiaohongshu)
- [Bilibili](#channel-bilibili)
- [微信小店](#channel-wechat-shop)
- [美团闪购](#channel-meituan-flash)
- [微信小程序](#channel-wechat-mini)
- [微信客服](#channel-wechat-kf)
- [微信公众号](#channel-wechat-mp)
- [企业微信](#channel-wecom)
- [抖音企业号](#channel-douyin)
- [百度营销](#channel-baidu)
- [X / Twitter](#channel-twitter)
- [WhatsApp](#channel-whatsapp)
- [Facebook](#channel-facebook)
- [Instagram](#channel-instagram)
- [LINE](#channel-line)
- [Discord](#channel-discord)
- [Google Play](#channel-google-play)
- [App Store](#channel-app-store)
- [钉钉](#channel-dingtalk)
- [飞书](#channel-feishu)
- [有赞](#channel-youzan)
- [微盟](#channel-weimob)
- [POPO](#channel-popo)
- [邮件](#channel-email)

### 接入前核对

准备渠道自身要求的账号、应用、域名和权限。未提供可用收发适配器的渠道保留准备中说明，不能以登记配置代替消息收发验收。

继续阅读：[选择接入方式](#integration-center) · [自建渠道接入指南](#custom-channels) · [主流接入覆盖与补齐计划](#mainstream-integration) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="mainstream-integration"></a>

## 主流接入覆盖与补齐计划

把主流渠道从“有文档”推进到“可收发、可接管、可核对业务结果”，并明确本轮暂缓的非主流模块。

### 当前覆盖矩阵

| 优先级 | 对象 | 当前状态 | 当前证据 | 缺口与下一步 |
| --- | --- | --- | --- | --- |
| P0 | Web / H5 | 已具备基础能力 | 已有网页入口、嵌入代码、同源消息客户端和用户点击后展开的接入指南。 | 没有把接入配置、消息回执和业务结果统一成一张连接状态单。 补齐入口健康状态、最近一次真实收发、人工接管和业务回执四项可核对证据。 |
| P0 | 微信小程序 | 已有 SDK / 文档，待宿主验收 | 已有原生聊天源码组件、客户端 API、下载包和真机验收清单。 | 扫码 / OpenID 身份绑定尚未形成标准流程；卡片消息、订阅消息和语音能力尚未闭环；合法域名与回调验签仍需按企业逐一验收 先交付文本、附件、人工接管和 OpenID 绑定四项 P0 能力，再单独评估语音和卡片。 |
| P0 | 微信客服 / 公众号 | 已有连接器，待真实账号验收 | 已有微信客服、公众号和小程序的配置入口与文本回调范围说明。 | 媒体消息和客服账号生命周期不完整；OAuth / 回调验签、撤权和人工接管证据没有统一留存 统一公众号、微信客服和小程序的身份、回调、收发、撤权和人工接管契约。 |
| P1 | 企业微信 | 已有连接器，待真实账号验收 | 已有企业微信机器人文本链路；客户联系和员工应用被明确区分。 | 外部客户联系、员工应用和内部机器人尚未共用一套身份与路由模型；应用可见范围与转人工归属缺少验收回执 先落地企业微信外部客户联系的文本收发和人工转接，再扩展员工应用。 |
| P1 | 抖音企业号 | 已登记，尚无收发连接器 | 已有准入和授权准备说明，没有把旧资料当作当前可用协议。 | 当前没有可证明的私信入站、发送、撤权和人工接管适配器。 取得当前企业号私信准入和正式消息协议后，先做文本单聊适配器；未获批前保持准备中。 |
| P1 | 钉钉 / 飞书 | 已有连接器，待真实账号验收 | 已有应用机器人事件与文本回复实现及各自配置指南。 | 事件订阅、应用发布、会话权限和消息回执尚未沉淀为统一验收单。 抽象机器人事件适配器，统一签名校验、消息去重、回复状态和人工转接。 |
| P1 | Telegram | 已有连接器，待真实账号验收 | 源码已有 Bot API 的凭据检查、Webhook secret、update_id 去重和文本回复适配器。 | 开发者文档目录尚未列出该适配器的凭据、Webhook 和限流边界。 把 Telegram 的 BotFather、Webhook、secret token、私聊和人工接管验收整理进统一文档。 |
| P1 | Slack | 已有连接器，待真实账号验收 | 源码已有 auth.test、Events API 签名校验、事件去重和 chat.postMessage 适配器。 | 开发者文档目录尚未列出 Events API、Message Content 权限和频道边界。 补充 Slack 应用安装、签名验证、事件回调、频道 / 私聊策略和人工接管验收。 |
| P1 | QQ 机器人 | 已有连接器，待真实账号验收 | 源码已有 QQ OAuth token、回调验签、消息发送和错误结果映射。 | QQ 机器人尚未进入开发者文档目录，群聊和私聊范围需要独立说明。 补充 QQ 开放平台应用、回调、access token、私聊 / 群聊范围和人工转接验收。 |
| P1 | WhatsApp Business | 已有连接器，待真实账号验收 | 已有 Cloud API 文本收发和 Business 号码凭据准备说明。 | 模板消息、会话窗口、媒体和业务结果回执未形成完整闭环。 先完成 Cloud API 文本单聊和人工接管，再按模板审批结果开放模板与媒体。 |
| P2 | Facebook / Instagram | 已登记，尚无收发连接器 | 已有准备表单和两类授权边界说明，尚未实现主页或专业账号消息适配器。 | Page / Professional Account 授权、私信、评论和人工窗口未接通。 在获得正式应用审核后优先支持 Page / Professional Account 文本私信，评论与媒体另行排期。 |
| P2 | LINE Official Account | 已有连接器，待真实账号验收 | 已有签名校验、Push 文本回复、重试身份核对和七天窗口策略。 | 媒体、群聊和完整 Reply Token 体验不在当前范围，需明确产品边界。 先完成单聊文本的生产账号验收，把媒体和群聊作为独立能力评估。 |
| P0 | 统一身份与回调网关 | 已有连接器，待真实账号验收 | 已有访客身份、事件签名、通知去重、分页和账号隔离相关接口。 | 各渠道仍可能分别维护 uid / OpenID / phone / externalMessageId，缺少跨渠道规范化映射。 建立 channelIdentity、conversationBinding、inboundEvent 和 deliveryReceipt 四类持久记录，统一未知结果和重试。 |
| P0 | CRM / 订单 / 工单业务桥 | 已有连接器，待真实账号验收 | 已有客户、工单、知识、智能体和业务回调操作；均要求服务端权限与真实回执。 | 渠道消息与客户、订单、工单之间的关联键、幂等键和完成条件还没有统一。 选择一个真实报修或预约场景，贯通收集、核实、受控执行、持久回执、转人工和结果确认。 |
| P0 | 路由、分配与人工接管 | 已具备基础能力 | 已有转人工、客服组、负责人和服务记录能力。 | 意图、客户等级、坐席能力、负载和熟客规则尚未统一成可解释的分配策略。 把路由决策、人工负责人、接管时间和客户通知写入同一会话记录，并支持回放。 |
| P1 | 接入健康与业务结果观测 | 已具备基础能力 | 已有服务记录、回调日志、计费和结果页面，但接入状态仍需要按证据分层。 | 配置成功、消息被平台接受、业务执行成功、客户确认解决尚未完全分开统计。 以每日聚合保留接入成功率、未知回执、转人工率、业务完成率和客户确认率，原始事件按保留策略归档。 |
| 暂缓 | 非主流与已退出市场渠道 | 暂不纳入 | 目录中仍保留历史资料入口，但没有把资料筹备标成可用连接器。 | 淘宝闪购、POPO、旧式评价回复等非实时客服渠道不进入本轮主流连接器排期。 仅保留文档和迁移说明，不计入主流接入完成率；只有出现明确客户需求、官方协议和验收账号时再单独立项。 |

### 先补齐四层基础能力

1. 身份层：每个渠道保存自己的 externalUserId、OpenID、手机号或账号标识，并映射到租户内的客户 ID；不能按姓名合并客户。
2. 消息层：原始入站事件先落盘，完成签名、时间窗口、租户和来源校验，再用 externalEventId 去重；回复要分别记录平台接受、明确拒绝和未知结果。
3. 接管层：记录路由原因、客服组、负责人、接管时间和客户通知；人工接管后停止 AI 自动发送，撤权后停止渠道写入。
4. 业务层：用幂等键连接客户、订单、工单和业务回执；执行失败、待审批和未知结果都保持待跟进，不能把模型成功或消息发送成功当成业务完成。

### 每个主流渠道的最小验收单

| 阶段 | 必须看到的证据 | 不通过时的处理 |
| --- | --- | --- |
| 授权 | 账号、应用、回调地址和权限可回读；撤权后令牌失效 | 保持准备中，不进入已接通 |
| 入站 | 真实用户消息带稳定外部 ID，原始事件可查询 | 检查签名、域名、版本和租户隔离 |
| 回复 | 平台返回可关联的 message ID 或明确接受状态 | 未知结果进入待核对，禁止盲目重复发送 |
| 人工 | 转人工后有负责人、时间和客户可见通知，AI 停止 | 回退到接待台人工处理并保留原会话 |
| 业务 | 客户 / 订单 / 工单操作有持久回执和最终确认 | 失败或待审批进入待跟进，不计入自动完成率 |

### 本轮主流范围

优先推进 Web / H5、微信小程序、微信客服 / 公众号、企业微信、钉钉、飞书、抖音企业号、WhatsApp、Facebook / Instagram 和 LINE。它们分别覆盖国内网页与微信生态、企业协作、短视频私信和海外主流消息场景。

淘宝闪购、POPO、旧式应用评价回复等没有稳定实时客服闭环的模块，本轮只保留资料与迁移边界，不计入主流接入完成率；只有出现正式协议、明确客户需求和可验收账号时再单独立项。

### 对照文档与进入方式

对方文档强调多渠道入口、访客身份、企业 API、回调鉴权、客户 / 订单资料和机器人会话等边界。本页把这些能力映射到云蝠现有的渠道、服务端操作和接待台，不会复制对方品牌或把对方接口当成云蝠接口。

### 按顺序交付

- [微信小程序](#channel-wechat-mini)
- [微信客服](#channel-wechat-kf)
- [微信公众号](#channel-wechat-mp)
- [Webhook 订阅与验签](#module-callbacks)
- [CRM / 客户资料](#module-crm)
- [工单 / 接待转人工](#module-tickets)
- [联调与上线验收](#acceptance)

继续阅读：[选择接入方式](#integration-center) · [第三方渠道接入目录](#channel-directory) · [自建渠道接入指南](#custom-channels) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/mainstream-integration-coverage.ts`、`lib/developer-docs/integration-playbooks.ts`、`lib/developer-docs/developer-guide.ts`

<a id="automation"></a>

## AI 工具、MCP、CLI 与技能接入

统一查阅公开插件、技能与通用 Runner；企业连接和操作授权继续由原流程管理。

### 选择客户端

Codex、Claude Code 和 WorkBuddy 使用已有接入方式。下载中心提供当前实际发行的插件、技能源码、MCP 说明和通用 Runner；没有发行的二进制包不会展示为可下载 SDK。

### 连接与验证

1. 先下载并阅读相应说明，保留客户端已有项目和其它连接。
2. 由本人在真实企业中完成授权，按原接入流程保存本机连接；文档和下载页不会展示实际密钥。
3. 使用只读诊断确认站点、企业和可见资源；需要写入、发布或外发的操作继续经过现有权限与审批。

### Runner 与个人配置

下载的是不含凭据的通用执行器。任务配置、环境变量和个人 Runner 下载仍在原有管理流程中生成，不放入公开目录。

### 相关资料

- [查看插件、技能、MCP 说明与通用 Runner 下载](#downloads)
- [服务端认证与权限](#server-auth)
- [智能体与工具接入](#module-ai-agent)

继续阅读：[选择接入方式](#integration-center) · [下载与更新记录](#downloads) · [幂等、版本与错误处理](#server-errors)

实现依据（仓库内路径）：`sdk/service-guide.mjs`、`lib/developer-docs/developer-mcp-connection.ts`、`lib/workspace-harness/platform-skills.ts`、`public/downloads/harness-cli-runner.mjs`

<a id="overview"></a>

## 云蝠接入概览

从接入方式、凭据和服务能力开始，选择适合自己产品的路径。

### 下载接入包

- [下载 Web 客户端与示例](/downloads/yunfu-web-integration-kit.zip) · [校验清单](/downloads/yunfu-web-integration-kit.json)：含原版渠道 iframe 示例及无 UI 客户端。复用完整渠道外观请选择 web/voice-example.html 或渠道嵌入代码；无 UI 客户端需自行绘制界面。
- [下载 iOS 源码示例](/downloads/yunfu-ios-integration-kit.zip) · [校验清单](/downloads/yunfu-ios-integration-kit.json)：WKWebView Swift 容器示例，加入现有 Xcode 工程编译；不含预编译 framework。
- [下载 Android 源码示例](/downloads/yunfu-android-integration-kit.zip) · [校验清单](/downloads/yunfu-android-integration-kit.json)：WebView Kotlin 容器和 Manifest 合并片段，需宿主工程编译；不含 AAR。
- [下载鸿蒙源码示例](/downloads/yunfu-harmony-integration-kit.zip) · [校验清单](/downloads/yunfu-harmony-integration-kit.json)：ArkWeb API 12+ 页面和权限片段，需 DevEco 宿主工程编译；不含 HAR。
- [下载 Uniapp 源码示例](/downloads/yunfu-uniapp-integration-kit.zip) · [校验清单](/downloads/yunfu-uniapp-integration-kit.json)：App-vue 容器与 Vue2 / Vue3 的 H5、微信示例默认加载当前原版渠道。原生文本为替代方案，按目标配置并完成真机验收。
- [下载小程序 SDK 源码与示例](/downloads/yunfu-wechat-miniapp-sdk.zip) · [校验清单](/downloads/yunfu-wechat-miniapp-sdk.json)：默认 web-view 复用原版渠道页面，需业务域名；另含原生聊天与语音替代组件，按各自能力与权限完成真机验收。

### 服务如何连接

用户点击入口 → 创建访客会话 → 入口绑定的已发布智能体接待 → 按规则或请求转人工 → 在接待台跟进，独立确认业务结果。各端统一连接云蝠接待服务。

### 接入方式对照

| 场景 | 使用方式 | 交付边界 |
| --- | --- | --- |
| 网站 / H5 | 渠道生成的 widget.js 或 iframe | 现有网页接待界面；异域网站优先此方式 |
| 自定义 Web UI | 同源 HTTPS 无 UI SDK | 文字、人工、分页、附件等；自行实现界面 |
| 微信小程序 | 原生聊天源码组件 / 客户端 API / 可选 RTC 语音组件 | 非微信市场插件；实时语音需腾讯配置、微信准入和真机验收，录音消息未提供 |
| iOS / Android / Harmony / Uniapp | 源码 WebView 容器 | 需宿主编译和真机验收，非发行版原生 SDK |
| 业务系统 | /v1/operations/{operationId} | 仅服务端持有 API Key，按操作授权 |
| 第三方客服渠道 | 对应平台连接器 | 每个平台独立授权、回调和真实收发验收 |

### 如何判断接通

下载、初始化、保存配置、加载页面或收到 HTTP 200 都不等于服务接通。分别记录 AI 实际回答、人工接管与回复、渠道接受、业务执行回执和客户确认。本文示例占位值必须替换；不会自动创建账号或发布配置。

继续阅读：[自建渠道接入指南](#custom-channels) · [快速入门：完成第一次接待](#first-conversation) · [能力与交付状态](#capabilities) · [入口、身份与凭据](#credentials)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`、`sdk/client-kit/README.md`

<a id="custom-channels"></a>

## 自建渠道接入指南

选择自己的客户端，下载接入包，按准备、安装、功能接入和上线检查完成接待。

### 下载接入包

- [下载 Web 客户端与示例](/downloads/yunfu-web-integration-kit.zip) · [校验清单](/downloads/yunfu-web-integration-kit.json)：含原版渠道 iframe 示例及无 UI 客户端。复用完整渠道外观请选择 web/voice-example.html 或渠道嵌入代码；无 UI 客户端需自行绘制界面。
- [下载 iOS 源码示例](/downloads/yunfu-ios-integration-kit.zip) · [校验清单](/downloads/yunfu-ios-integration-kit.json)：WKWebView Swift 容器示例，加入现有 Xcode 工程编译；不含预编译 framework。
- [下载 Android 源码示例](/downloads/yunfu-android-integration-kit.zip) · [校验清单](/downloads/yunfu-android-integration-kit.json)：WebView Kotlin 容器和 Manifest 合并片段，需宿主工程编译；不含 AAR。
- [下载鸿蒙源码示例](/downloads/yunfu-harmony-integration-kit.zip) · [校验清单](/downloads/yunfu-harmony-integration-kit.json)：ArkWeb API 12+ 页面和权限片段，需 DevEco 宿主工程编译；不含 HAR。
- [下载 Uniapp 源码示例](/downloads/yunfu-uniapp-integration-kit.zip) · [校验清单](/downloads/yunfu-uniapp-integration-kit.json)：App-vue 容器与 Vue2 / Vue3 的 H5、微信示例默认加载当前原版渠道。原生文本为替代方案，按目标配置并完成真机验收。
- [下载小程序 SDK 源码与示例](/downloads/yunfu-wechat-miniapp-sdk.zip) · [校验清单](/downloads/yunfu-wechat-miniapp-sdk.json)：默认 web-view 复用原版渠道页面，需业务域名；另含原生聊天与语音替代组件，按各自能力与权限完成真机验收。

### 接入流程一览

1. **选择方案**：按网站、小程序或 App，选择对应教程与接入包。
2. **准备入口**：发布智能体，配置接待组，取得专用入口参数。
3. **接入客户端**：配置域名与页面，用户点击后才打开客服。
4. **验证收发**：验证 AI 回复、人工接管、账号切换，再发布。

### 选择接入平台

网站可直接嵌入现有聊天界面，也可使用同源消息 SDK。小程序提供原生聊天源码组件；App 提供网页容器源码示例。下载文件的交付形式与支持范围在各教程中说明。

- [网站 / H5：嵌入聊天窗口](#web-embed)
- [Web：无 UI 消息 SDK](#web-client)
- [微信小程序：源码组件接入](#miniapp-install)
- [iOS：快速接入](#ios-install)
- [Android：快速接入](#android-install)
- [Harmony 鸿蒙：快速接入](#harmony-install)
- [Uniapp：快速接入](#uniapp-install)

### 1. 接入准备

1. 准备已部署的公网 HTTPS 主机；确认企业账号、模型资源、接待权限和可用余额。
2. 配置并发布智能体，在「渠道 → 自建渠道」创建专用渠道和服务入口，绑定智能体或工作流、人工组及服务时段。
3. 从入口复制公开 key 与 entryId，记录自己的 baseUrl。公开入口标识用于访客接入；管理 API Key 和 AppSecret 只放服务端。

### 2. 安装与初始化

1. 下载本页或具体教程提供的接入包，按对应目录集成到现有工程；保留宿主自己的签名、路由与权限配置。
2. 按平台配置 HTTPS 来源或合法域名，替换示例中的占位值。小程序需要配置 request、uploadFile、downloadFile 域名。
3. 用户点击“聊一聊”后再打开界面、建立会话；退出登录或切换账号前清理旧会话与回调。

### 3. 按需接入功能

先完成文字收发与人工接管，再按实际交付范围启用附件、客户资料、评价和业务操作。消息 SDK、网页容器和平台原生客服入口分别使用各自的协议。

- [消息、转人工与历史](#messages)
- [图片、文件与视频](#media)
- [小程序功能与 API](#miniapp-api)
- [账号切换与会话隔离](#account-switch)
- [服务端业务 API](#server-auth)
- [各平台能力对照](#capabilities)

### 4. 联调与上线

1. 在测试入口实际发送业务问题，核对 AI 回复、人工接管和人工回复在客户界面与接待台一致。
2. 检查手机键盘、展开收起、断网恢复、重复消息、账号切换及已启用的附件功能；App 和小程序需要真机测试。
3. 逐项记录环境、入口、包摘要和结果。保存配置或 HTTP 成功不等于业务完成，订单、退款和工单以实际业务回执与确认结果为准。

### 相关文档

- [隐私与权限](#privacy)
- [上线验收清单](#acceptance)
- [接入常见问题](#troubleshooting)
- [全部接入包与更新说明](#downloads)
- [微信原生客服入口与 SDK 的区别](#miniapp-native-contact)

继续阅读：[快速入门：完成第一次接待](#first-conversation) · [入口、身份与凭据](#credentials) · [下载与更新记录](#downloads)

实现依据（仓库内路径）：`lib/channels/channel-products.ts`、`sdk/client-kit/README.md`、`sdk/wechat-miniapp/README.md`

<a id="first-conversation"></a>

## 快速入门：完成第一次接待

以一个独立测试入口贯通 AI 和人工，之后再扩展业务功能。

### 开始之前

1. 准备自己的公网 HTTPS 服务域名及可用证书。检查服务版本、余额、模型资源和接待权限。
2. 在「智能体」完成配置、测试和发布；在「渠道 → 自建渠道」创建独立入口，绑定该智能体、人工组及服务时段。
3. 复制入口中的公开 key 和 entryId；主机部分为 baseUrl。为不同 App 或小程序分别命名入口。

### 接入顺序

1. 先选网页嵌入、小程序源码组件或原生容器教程；所有 YOUR_* / example.com 都是占位值。
2. 用户阅读隐私告知并点击“聊一聊”后再连接。发送一个业务问题，检查实际回答和接待台记录。
3. 发起人工请求并由客服实际接管、回复；确认 AI 外发停止，客户看到人工回复。
4. 断网后恢复、切换账号、关闭页面，再分别检查重复消息和历史隔离。最后记录测试环境、入口、版本和结果。

### 接入后再做什么

按业务需要接入附件、公开知识、留资与评价。订单、退款或工单的成功必须来自服务端业务回执；不要用客户端消息发送成功代表业务完成。

继续阅读：[网站 / H5 嵌入](#web-embed) · [小程序 SDK：安装与首条消息](#miniapp-install) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`sdk/client-kit/README.md`、`sdk/wechat-miniapp/README.md`

<a id="capabilities"></a>

## 能力与交付状态

区分源码支持、页面已接线与真实设备验收。

### 各端能力表

| 能力 | Web 无 UI / 小程序客户端 | 原生容器的 /support 页面 |
| --- | --- | --- |
| AI / 人工消息 | 支持，需启用入口并实际验收 | 沿用网页服务路由 |
| 显式转人工按钮 / 历史翻页 | handoff() / loadEarlier() | 尚未接线；当前读取最近 100 条 |
| 图片 / 文件 / 视频 | 服务端鉴权上传下载 | 依赖宿主；Harmony 示例未实现文件选择 |
| 公开知识 / 留资 / 评价 / 记忆 | 提供 API；组件按可用配置展示 | 以页面实际展示及配置为准 |
| 前台未读 | 支持，首次历史不累计新未读 | 不提供原生未读或推送桥 |
| 可信宿主身份 / 跨设备历史 | 未实现 | 未实现 |
| 实时语音 / 语音消息 | 消息内核不含媒体；当前小程序接入包提供可选原生 RTC 组件 | 实时语音需完成腾讯配置与真机验收；录音消息未提供 |
| 离线推送 | 未实现 | 未实现 APNs / 厂商推送 |

### 交付形式

小程序交付源码组件；Web 交付打包的 ESM 客户端；四个 App 平台交付宿主集成源码示例。按具体教程配置云蝠入口参数；当前没有预编译 framework、AAR、HAR 或已上架的微信插件。

### 验证范围

仓库检查验证接口契约和隔离逻辑；不能替代开发者工具、宿主编译、真实模型、真机和生产渠道验收。各平台的最低系统与兼容范围应由你的宿主构建结果确认。

继续阅读：[联调与上线验收清单](#acceptance) · [下载与更新记录](#downloads) · [语音接入与消息 SDK 的边界](#voice)

实现依据（仓库内路径）：`sdk/client-kit/README.md`、`sdk/wechat-miniapp/index.d.ts`

<a id="privacy"></a>

## 隐私告知与权限申请

在连接和收集之前说明用途，只申请实际需要的权限。

### 接入检查

1. 在宿主隐私说明中列明对话文本、主动填写的联系方式、附件、用途及保存规则。用户点击后才建立连接。
2. 配置网络请求、上传和下载域名；不要为了测试关闭正式环境的 HTTPS 或域名检查。
3. 文件选择只访问用户选中的文件；没有实现的录音功能不申请麦克风权限。
4. 留资必须取得明确同意；记忆的 ignore / stop / forget 不等于删除企业服务记录和审计。

### 本地与日志

访客令牌存放在对应会话的本地存储；不要写入 URL、埋点或日志。限制设备共享场景的续接，退出账号先忘记旧会话并销毁实例。不要将包含凭据的附件 URL 交给第三方下载器。

### 上线审核

隐私文本、平台类目、备案、合法域名和权限描述应由自己的应用按实际收集范围完成审核。本文是产品接入检查，不代表已替你的应用通过平台审核。

### 官方原始接入文档

先按云蝠指南完成入口、智能体和服务配置，再按下列官方原文配置宿主权限或供应商资源。外部文档说明对应平台能力，不代表云蝠已开放其中全部接口；腾讯 SecretKey、签名密钥和管理 API Key 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。

- [微信开放文档 · 小程序网络与合法域名](https://developers.weixin.qq.com/miniprogram/dev/framework/ability/network.html)：原生请求需配置 request、uploadFile、downloadFile 合法域名；WebView 另需业务域名，关闭校验不能代替正式配置。
- [微信开放文档 · 隐私授权开发指引](https://developers.weixin.qq.com/miniprogram/dev/framework/user-privacy/PrivacyAuthorize.html)：接入宿主隐私告知和同意流程；隐私同意、系统麦克风授权与实际收音分别验收。
- [微信开放文档 · wx.authorize 授权接口](https://developers.weixin.qq.com/miniprogram/dev/api/open-api/authorize/wx.authorize.html)：核对 scope.record 与拒绝后的处理；进入聊天页或点击普通按钮不等于已完成录音授权。
- [微信开放文档 · live-pusher 原生推流组件](https://developers.weixin.qq.com/miniprogram/dev/component/live-pusher.html)：核对原生推流组件、主体及类目权限；与腾讯 SDK 配置配套，在真机验证音频事件。

继续阅读：[入口、身份与凭据](#credentials) · [生命周期与账号切换](#account-switch) · [小程序 SDK：安装与首条消息](#miniapp-install)

实现依据（仓库内路径）：`sdk/client-kit/README.md`、`sdk/wechat-miniapp/README.md`

<a id="credentials"></a>

## 入口、身份与凭据

公开入口标识和服务端密钥不能混用。

### 凭据说明

| 名称 | 放在哪里 | 用途 |
| --- | --- | --- |
| baseUrl / key / entryId | 宿主客户端，可公开 | HTTPS 主机、入口公开 key 与入口 ID，不是管理授权 |
| visitor Bearer | SDK 管理的本地会话存储 | 服务端签发，只能访问对应访客范围；不要自行生成 |
| userScope / clientSession | 宿主本地隔离编号 | 隔离本地会话，不是身份认证或客户查询权限 |
| visitorContext | 可选客户资料 | 自述信息，不能证明会员或 openid 身份 |
| API Key | 你自己的服务端环境变量 | 访问明确授权的 /v1/operations 操作，不能放前端 |
| AppSecret / 回调签名密钥 | 服务端渠道配置或验签服务 | 第三方授权与签名，不能放进 SDK 包 |

### 访客授权与 Cookie

SDK 使用 Authorization: Bearer 访客令牌。显式 Authorization 优先，不能失败后回退其他用户 Cookie。带 x-yunfu-visitor-auth: bearer 的隔离入口忽略共享访客 Cookie；创建会话也不写共享访客 Cookie。普通网页的兼容 Cookie 流程独立保留。

### 可信身份边界

设置名字、客户 ID、手机号、userScope 或 clientSession 不会认证客户。当前客户端未实现宿主登录态的服务端签名身份交换，不开放基于这些自报字段读取私有 CRM 或跨设备合并历史。

继续阅读：[生命周期与账号切换](#account-switch) · [服务端认证与首次调用](#server-auth) · [隐私告知与权限申请](#privacy)

实现依据（仓库内路径）：`lib/channels/visitor-credentials.ts`、`lib/channels/hosted-client-session.ts`、`backend/services/channels/visitor-service.ts`

<a id="account-switch"></a>

## 生命周期与账号切换

销毁运行资源与忘记旧会话是两件不同的事。

### 正确顺序

1. 同一个主机、key、entryId、userScope 只创建一个客户端；同一账号下反复打开复用该实例。
2. 前台展示时 setChatVisible(true)，折叠时 false；小程序 onShow / onHide 接到客户端，后台暂停轮询。
3. 退出登录前 forgetSession()，在 finally 中 destroy()；注销订阅和宿主事件。
4. 为新账号使用新的随机隔离编号。不要仅改昵称、重用旧 UUID 或恢复旧页面实例。

### Web 账号切换清理

使用位置：`web/account-switch.mjs` · 模块文件 · 接入包 0.3.15

运行前：
- client 为当前账号创建的实例，unsubscribe 是对应订阅返回值。

```javascript
// Call before replacing the host's signed-in account. Neither argument authenticates the user.
export function disposeSupportForAccountChange(client, unsubscribe) {
  try {
    client.forgetSession();
  } finally {
    try { unsubscribe?.(); }
    finally { client.destroy(); }
  }
  // Create the next instance with a fresh host-owned userScope; never replay old pending writes.
}
```

预期结果：退出账号前调用此函数；即使清理出错也销毁旧实例。下一账号使用新 userScope。

### 清理边界

destroy() 只释放资源，不能代替清除本机凭据；forgetSession() 不撤销企业账户，也不取消已经到达服务端的工作。原生容器按各端生命周期教程关闭整个旧页面。

继续阅读：[iOS：生命周期、权限与排错](#ios-lifecycle) · [Android：生命周期、权限与排错](#android-lifecycle) · [小程序生命周期与事件](#miniapp-events) · [SDK 错误与待核对请求](#sdk-errors)

实现依据（仓库内路径）：`sdk/wechat-miniapp/index.js`、`sdk/client-kit/web/client.mjs`

<a id="web-embed"></a>

## 网站 / H5 嵌入

异域网站优先使用渠道生成的现有网页组件。

### 下载接入包

- [下载 Web 客户端与示例](/downloads/yunfu-web-integration-kit.zip) · [校验清单](/downloads/yunfu-web-integration-kit.json)：含原版渠道 iframe 示例及无 UI 客户端。复用完整渠道外观请选择 web/voice-example.html 或渠道嵌入代码；无 UI 客户端需自行绘制界面。

### 接入步骤

1. 在自建渠道创建入口，绑定已发布智能体，并在“皮肤与代码”选择网页聊天框。
2. 配置允许嵌入的网站域名，复制该入口生成的 widget.js / iframe 代码。保留生成的 key 与 entryId，不手改为其他企业入口。
3. 将生成代码放到自己的站点，设置由“聊一聊”触发打开；检查首次访问不会自动展开或开始语音。
4. 在桌面和手机分别检验展开、收起、键盘和关闭，并验证真实 AI / 人工收发。

### 嵌入与无 UI SDK

外站使用网页嵌入；同源 HTTPS 才使用下一篇的无 UI 客户端。不要仅为了跨域放开全部 API CORS。自定义 UI 不继承现有网页的所有功能，需要自己处理状态与错误。

### H5 完整语音接入

接入包 0.3.0 的 web/voice-embed.mjs 与 voice-example.html 提供完整渠道界面和现有语音引擎；无 UI 消息 SDK 不提供音频。只在用户点击打开后创建 iframe，在渠道内点击开始才申请录音。

父子页面均需 HTTPS；iframe 只委派精确客服 origin 的 microphone/autoplay。父站点 Permissions-Policy、CSP 与渠道允许来源仍须匹配；allow 属性不能突破响应头限制。嵌套 iframe 每层都需委派，勿放开全域 CORS。

新 helper 在关闭、pagehide 或父页面隐藏时停止并移除 iframe；回前台需要再次打开，不自动开麦。停止消息检查父窗口、精确来源、公开 key 和入口；账号退出 destroy 后换 UUID。现有 widget 折叠行为不改。

### 来源限制

线上主机、协议和允许来源需一致。原生容器可能没有 Referer，应使用专用渠道评估公开入口策略；不能为 App 接入删除原网站的来源限制，也不能伪造 Referer。

### 完整 H5 语音页面示例

使用位置：`web/voice-example.html` · 完整网页文件 · 接入包 0.3.15

运行前：
- 从 Web 包保留 voice-embed.mjs 和根目录 hosted-url.mjs 的相对位置。
- 替换公开参数，通过 HTTPS 打开；父站点允许客服 origin 的麦克风和 iframe。

```html
<!doctype html>
<html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover"><title>云蝠语音客服接入示例</title>
<style>body{margin:20px;font:15px system-ui;color:#24334d;background:#f6f8fc}main{max-width:760px;margin:auto}button{padding:10px 16px;margin:0 8px 12px 0}#support{height:75dvh;min-height:360px;background:white;border-radius:14px;overflow:hidden}#status{line-height:1.6}</style></head>
<body><main><h1>在线客服</h1><p>打开后可选择文字或语音咨询，开始语音时才申请麦克风。</p><button id="open">打开客服</button><button id="close">关闭客服（结束语音）</button><p id="status" role="status"></p><div id="support"></div></main>
<script type="module">
import { createHostedVoiceEmbed } from './voice-embed.mjs';
let support;
document.querySelector('#open').onclick = () => {
  try {
    support ||= createHostedVoiceEmbed({
      container: document.querySelector('#support'), origin: 'https://YOUR_CUSTOMER_SERVICE_ORIGIN',
      key: 'YOUR_PUBLIC_KEY', entryId: 'YOUR_ENTRY_ID', clientSession: crypto.randomUUID(),
    });
    support.open();
    document.querySelector('#status').textContent = '语音需要企业及入口已启用；授权成功后仍需核对实际 AI 回复。';
  } catch (error) { document.querySelector('#status').textContent = error.message === 'VOICE_REQUIRES_HTTPS' ? '请通过 HTTPS 站点打开此示例。' : '请先填写有效的客服服务地址和入口参数。'; }
};
document.querySelector('#close').onclick = () => support?.close();
// The host must call support.destroy() before logout/account change, then create a new UUID.
</script></body></html>
```

预期结果：点击打开仅显示渠道界面，在渠道内点击开始才申请录音；关闭或切后台结束语音。

### 官方原始接入文档

先按云蝠指南完成入口、智能体和服务配置，再按下列官方原文配置宿主权限或供应商资源。外部文档说明对应平台能力，不代表云蝠已开放其中全部接口；腾讯 SecretKey、签名密钥和管理 API Key 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。

- [MDN · getUserMedia 麦克风采集](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia)：核对 HTTPS、用户授权、设备和浏览器兼容性；打开页面不等于麦克风可用。
- [MDN · Permissions-Policy: microphone](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/microphone)：配置父站点允许的客服来源并配合 iframe allow；响应头限制仍生效，不能用放开 CORS 解决麦克风拒绝。

继续阅读：[无 UI Web 客户端快速接入](#web-client) · [快速入门：完成第一次接待](#first-conversation) · [接入常见问题](#troubleshooting)

实现依据（仓库内路径）：`frontend/components/channels/embed-page.tsx`、`sdk/client-kit/README.md`、`sdk/client-kit/web/voice-embed.mjs`

<a id="web-client"></a>

## 无 UI Web 客户端快速接入

下载 ESM 客户端，在同源 HTTPS 页面接入自定义聊天界面。

### 下载接入包

- [下载 Web 客户端与示例](/downloads/yunfu-web-integration-kit.zip) · [校验清单](/downloads/yunfu-web-integration-kit.json)：含原版渠道 iframe 示例及无 UI 客户端。复用完整渠道外观请选择 web/voice-example.html 或渠道嵌入代码；无 UI 客户端需自行绘制界面。

### 安装

1. 下载本页 Web 接入包，将 web/ 整个目录发布到你的同源静态资源目录。包内包含已打包的 ESM 客户端、类型声明和示例。
2. 将示例占位值替换为自己的公开 key 与 entryId。baseUrl 使用当前 HTTPS origin。
3. 订阅状态并以 textContent 渲染消息，用户点击时再 connect；不要把 AI 消息作为未过滤的 HTML 注入。

### 最小示例

使用位置：`web/example.mjs` · 模块文件 · 接入包 0.3.15

运行前：
- 从 Web 包复制 web/ 目录并保留同目录 yunfu-web-client.mjs。
- 填写自己的公开 key 和 entryId，仅在同源 HTTPS 页面使用。

```javascript
import { createWebVisitorClient } from './yunfu-web-client.mjs';
// Serve on the same HTTPS origin as Yunfu. Cross-origin sites should use widget.js / iframe instead.
const options = {
  baseUrl: location.origin,
  key: 'YOUR_PUBLIC_KEY',
  entryId: 'YOUR_ENTRY_ID',
  userScope: crypto.randomUUID(),
};
let client;
export async function openSupport(render) {
  if (!client) {
    client = createWebVisitorClient(options);
    client.subscribe(render); // render text as textContent, never inject message HTML
  }
  client.setChatVisible(true);
  await client.connect(); // errors/pending writes are exposed; do not automatically replay sends
  return client;
}
export function closeSupport() {
  client?.setChatVisible(false);
}
export function logout() {
  // Host must call before replacing the signed-in user, then use a fresh scope for that user.
  try {
    client?.forgetSession();
  } finally {
    client?.destroy();
    client = undefined;
    options.userScope = crypto.randomUUID();
  }
}
```

预期结果：在点击事件中调用 openSupport(render)；返回 client 后按发送事件调用 sendText，退出前调用 logout。

### Vue2 与 Vue3 宿主

Web 客户端不依赖 Vue。Vue2 在 mounted 中创建并订阅实例，在 beforeDestroy 中取消订阅并 destroy；Vue3 对应使用 onMounted / onBeforeUnmount。将 SDK 实例保存在组件外的私有引用中，仅把可展示的状态复制到响应式数据。退出或切换账号先执行 forget 再创建新实例，不能只更换界面名称。Uni-app 请使用专用 Vue2 / Vue3 共用组件，合并页面与 App 的隐藏、恢复、卸载事件。

### 页面刷新与会话续接

上例每次加载创建随机 userScope，仅演示当前页面生命周期。需要刷新后恢复聊天与 pending 时，由宿主在当前登录会话内持久化并复用随机 UUID；退出或切换账号先清理旧实例与存储，再更换编号。存储失败应停止，不自动生成新身份继续发送。

### 失败处理

请捕获 Promise 拒绝并展示 code / status / retryAfter。sessionStorage 被禁用时不要自动换身份；验证码要求转现有完整网页入口处理。所有示例中的网络动作都由宿主明确触发。

### 官方原始接入文档

先按云蝠指南完成入口、智能体和服务配置，再按下列官方原文配置宿主权限或供应商资源。外部文档说明对应平台能力，不代表云蝠已开放其中全部接口；腾讯 SecretKey、签名密钥和管理 API Key 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。

- [MDN · getUserMedia 麦克风采集](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia)：核对 HTTPS、用户授权、设备和浏览器兼容性；打开页面不等于麦克风可用。
- [MDN · Permissions-Policy: microphone](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/microphone)：配置父站点允许的客服来源并配合 iframe allow；响应头限制仍生效，不能用放开 CORS 解决麦克风拒绝。

继续阅读：[消息、人工转接与历史](#messages) · [附件与业务扩展](#media) · [SDK 错误与待核对请求](#sdk-errors) · [生命周期与账号切换](#account-switch)

实现依据（仓库内路径）：`sdk/client-kit/web/example.mjs`、`sdk/client-kit/web/client.d.mts`

<a id="messages"></a>

## 消息、人工转接与历史

同一套消息 API 供 Web 无 UI 客户端和小程序客户端使用。

### 下载接入包

- [下载 Web 客户端与示例](/downloads/yunfu-web-integration-kit.zip) · [校验清单](/downloads/yunfu-web-integration-kit.json)：含原版渠道 iframe 示例及无 UI 客户端。复用完整渠道外观请选择 web/voice-example.html 或渠道嵌入代码；无 UI 客户端需自行绘制界面。
- [下载小程序 SDK 源码与示例](/downloads/yunfu-wechat-miniapp-sdk.zip) · [校验清单](/downloads/yunfu-wechat-miniapp-sdk.json)：默认 web-view 复用原版渠道页面，需业务域名；另含原生聊天与语音替代组件，按各自能力与权限完成真机验收。

### 方法说明

| 方法 | 返回 / 行为 | 注意事项 |
| --- | --- | --- |
| connect() / refresh() | Promise<State>；建立 / 读取当前会话 | 初始化不应自动发送客户问题 |
| sendText(text, mediaIds?) | Promise<View>；文字最多 2000 字 | 附件先 upload，按服务端消息 ID 去重 |
| handoff() | Promise<View>；请求人工 | waiting 不等于客服已接管，需验证真人回复 |
| loadEarlier() | Promise<State>；更早历史 | before 游标，每页最多 100；不读其他访客 |
| end() / restart() | Promise<View> / Promise<State> | 未知写入保留 pending；不要自动创建新身份 |
| setChatVisible(bool) / markRead() | 前台未读与已读 | 首次历史不计未读，不是离线推送 |

### 关键状态

| 字段 | 含义 |
| --- | --- |
| view.state | ai / human / waiting / closed |
| view.messages | id、role（customer / ai / service）、text、time、media |
| view.hasMore / view.before | 当前会话分页信息；不要替换成通用 page/pageSize |
| pending（数组） | 每项含 action、operation、text、inFlight、received；结果可能待核对 |
| unread / error / storageError | 前台未读、错误信息与本地存储失败；不含访客 token |

### 渲染与对账

客户消息进入记录不代表 AI 已完成回答。刷新后按消息 ID 合并，逐项检查 state.pending.find(p => p.action === "message")?.received，区分已收取与未确认。转人工后由服务端所有权控制 AI 外发。用户关闭界面也不等于结束服务端会话。

继续阅读：[SDK 错误与待核对请求](#sdk-errors) · [附件与业务扩展](#media) · [小程序 API 与能力边界](#miniapp-api)

实现依据（仓库内路径）：`sdk/wechat-miniapp/index.d.ts`、`sdk/wechat-miniapp/index.js`

<a id="media"></a>

## 附件与业务扩展

统一使用访客鉴权，按当前入口权限展示能力。

### 下载接入包

- [下载 Web 客户端与示例](/downloads/yunfu-web-integration-kit.zip) · [校验清单](/downloads/yunfu-web-integration-kit.json)：含原版渠道 iframe 示例及无 UI 客户端。复用完整渠道外观请选择 web/voice-example.html 或渠道嵌入代码；无 UI 客户端需自行绘制界面。
- [下载小程序 SDK 源码与示例](/downloads/yunfu-wechat-miniapp-sdk.zip) · [校验清单](/downloads/yunfu-wechat-miniapp-sdk.json)：默认 web-view 复用原版渠道页面，需业务域名；另含原生聊天与语音替代组件，按各自能力与权限完成真机验收。

### 附件限制

| 项目 | 限制 |
| --- | --- |
| 图片 | 最大 5 MB |
| 视频 / 文件 | 最大 10 MB；视频限 60 秒 |
| 每条消息 | 最多 3 件，总计不超过 12 MB |
| 类型与访问 | 服务端复核 MIME、类型、入口与访客权限 |

### 上传并发送

使用位置：`web/attachments.mjs` · 模块文件 · 接入包 0.3.15

运行前：
- client 来自已打开的 Web 接待实例，file 来自用户选择的 File/Blob。
- 仅 Web 示例；小程序上传传本地临时路径，下载返回临时路径，不调用 releaseDownload。

```javascript
// client comes from openSupport(); file is the File/Blob selected by the customer.
export async function uploadAndSend(client, file) {
  const media = await client.upload(file);
  // On an uncertain result inspect pending state; do not upload/send again automatically.
  await client.sendText('请查看这个附件', [media.id]);
  return media;
}

export async function useDownload(client, mediaId, consume) {
  const localUrl = await client.download(mediaId);
  try { return await consume(localUrl); }
  finally { client.releaseDownload(localUrl); }
}
```

预期结果：按用户操作调用 uploadAndSend；useDownload 在消费完成或失败后均释放本地 URL。

### 扩展方法

| 方法 | 约束 |
| --- | --- |
| submitContact({ phone?, email?, consent: true }) | 用户明确同意后提交，不预勾选同意 |
| rate(score, comment?) | 服务端下发评价邀请后使用，分值按当前 maxScore |
| searchKnowledge(text?, page?, articleId?) | 只读取入口绑定的公开知识库 |
| memory() / changeMemory("ignore" \| "stop" \| "forget") | 控制记忆，不代表删除企业依法保留的记录 |

### 安全下载

下载使用当前访客 Bearer，得到本地 blob URL 或小程序临时文件。不要把令牌加到 URL，不转交第三方域名；Web 在预览后 releaseDownload，销毁也会回收资源。

继续阅读：[消息、人工转接与历史](#messages) · [隐私告知与权限申请](#privacy) · [小程序 API 与能力边界](#miniapp-api)

实现依据（仓库内路径）：`sdk/wechat-miniapp/README.md`、`sdk/client-kit/web/client.d.mts`

<a id="miniapp-install"></a>

## 小程序 SDK：安装与首条消息

默认通过 web-view 复用当前原版渠道页面；原生组件作为替代方案。

### 下载接入包

- [下载小程序 SDK 源码与示例](/downloads/yunfu-wechat-miniapp-sdk.zip) · [校验清单](/downloads/yunfu-wechat-miniapp-sdk.json)：默认 web-view 复用原版渠道页面，需业务域名；另含原生聊天与语音替代组件，按各自能力与权限完成真机验收。

### 先选接入方式，再准备对应参数

- [对照两种方式与管理员操作](#miniapp-native-contact)
- [配置微信原生客服消息连接器](#channel-wechat-mini)

| 客户在哪里聊天 | 使用哪条链路 | 需要准备什么 |
| --- | --- | --- |
| 原版渠道页面（默认） | pages/hosted-support/ 的 web-view | 具备 web-view 使用资格，配置业务域名、HTTPS 主机、公开 key 和 entryId |
| 原生组件（主动选择） | pages/support/ 的 yunfu-chat 组件 | 配置 request / uploadFile / downloadFile 合法域名；同步基础外观，不等同于完整网页 |
| 微信原生客服窗口 | 小程序客服消息连接器 | 小程序管理员、服务端凭据及安全 XML 消息推送；不要填到 SDK 的 config.js |

### 开发、管理员和客服各自要完成什么

| 负责人 | 操作 | 完成证据 |
| --- | --- | --- |
| 开发者 | 导入自己的 AppID，默认配置 web-view 业务域名与公开入口；原生方案另注册组件与服务器域名 | 检查入口可读取；不把管理密钥放进小程序 |
| 企业管理员 | 启用入口、发布智能体、配置接待组和服务时间 | 入口与已发布版本匹配；需要人工时有在线坐席 |
| 测试人员与客服 | 体验版真机发业务问题，接待台核对同一会话，再完成转人工 | 手机有实际回复；两端消息、来源和人工接管状态一致 |

### 从下载到首条回复

1. **准备入口与域名**：在自建渠道创建入口；默认方案配置微信业务域名。
2. **导入示例并检查**：导入解压根目录，选择自己的 AppID，填写 config.js；保留 hosted-support 为首页。
3. **点击“进入客服”**：同意宿主隐私说明后进入原版渠道，再发送测试问题。
4. **核对两端结果**：手机看到回复，接待台找到对应记录；再测人工。

### 开始前准备这些信息

| 准备项 | 在哪里取得 / 配置 | 核对结果 |
| --- | --- | --- |
| 小程序 AppID | 自己的微信小程序后台与开发者工具 | 工程使用本企业 AppID；不把 AppSecret 放入小程序 |
| baseUrl | 云蝠已部署的公网 HTTPS 站点 | 只包含协议和主机，不带 /console 路径 |
| 公开 key、entryId | 本文“统一填写公开入口配置”可选择渠道查看；也可在渠道 → 自建渠道 → 服务入口 → 皮肤与代码取得 | 属于同一入口；入口已启用、绑定智能体已发布 |
| 业务域名（默认原版方案） | 微信后台 web-view 业务域名配置 | 具备 web-view 使用资格并完成域名校验；request 域名不能替代 |
| 服务器域名（仅原生替代） | 微信后台 request / uploadFile / downloadFile 配置 | 原生组件请求使用；开发工具和真机均开启域名校验 |
| 接待组与在线客服 | 渠道的接待设置与接待台 | 需要人工接待时，组内至少一名客服在线 |

### 前置准备

1. 准备自己的小程序 AppID 和开发者工具工程；创建独立自建 Web 入口，复制 HTTPS baseUrl、公开 key 和 entryId。
2. 下载独立小程序 SDK，导入解压根目录的 project.config.json，选择自己的 AppID，填写 config.js。默认首页是 pages/hosted-support/index；已有工程合并 hosted 页面、yunfu-sdk/hosted.js 与公开配置，保留 require 的相对路径。
3. 默认 web-view 必须将同一公网 HTTPS 主机配置为业务域名；仅在主动选择原生组件时使用 request、uploadFile、downloadFile 域名。两种域名不可替代，不关闭校验代替配置。
4. 默认首页完成宿主隐私同意后点击进入客服，核对同一入口的当前外观。需要原生替代时点击原生组件接入示例，先检查服务入口，再聊一聊；下方组件注册与 SDK 动作仅适用于该替代方案。

### 原生替代：只读入口检查

使用位置：`yunfu-sdk/examples/preflight.js` · CommonJS 模块 · 接入包 0.3.14

运行前：
- 复制整个 yunfu-sdk；传入 wx、baseUrl、key、entryId、userScope。

```javascript
const { YunfuMiniappClient, diagnoseMiniapp } = require('../index');

// options contains wx, baseUrl, key, entryId, userScope. This function never creates a visitor.
async function checkSupportEntry(options) {
  const local = diagnoseMiniapp(options);
  if (!local.localReady) return local;
  const client = new YunfuMiniappClient(options);
  try {
    await client.preflight();
    return { ...local, entryReachable: true };
  } finally {
    client.destroy();
  }
}
module.exports = { checkSupportEntry };
```

预期结果：调用 checkSupportEntry(options) 只检查本机配置和公开入口，不创建会话或调用 AI。

### 同步渠道聊天外观

默认 web-view 加载 /support?surface=channel，与网页渠道共用当前渲染，头像、标题、消息、输入区、语音入口及已启用功能随渠道更新；保存渠道后重新进入核对。原生 yunfu-chat 只同步基础皮肤与各自支持的功能，不承诺完整网页效果；完整复制 yunfu-sdk/，保留 presentation.js 与 assets/avatars/。

宿主 app.json 需要 darkmode: true；示例已附 theme.json，默认进入前页面适配系统明暗主题。仅原生替代方案预取公开外观并在点击聊一聊后创建会话。小程序原生客服窗口由微信绘制，无法套用此聊天皮肤。

iOS、Android、Harmony 与 Uniapp App 示例继续打开同一入口的 /support 页面，继承渠道聊天外观；Web 无 UI SDK 仅返回配置，宿主自绘界面需要自行映射，或使用现成嵌入组件。

### 隐私、登录与能力范围

宿主负责隐私保护指引和实际用户同意；默认 WebView 页的勾选框不替代宿主完整隐私授权。原生替代示例含 getPrivacySetting 与 agreePrivacyAuthorization 按钮，不覆盖全局隐私监听。getRandomValues 从基础库 2.15.0 提供且在微信插件中不支持，本交付采用源码组件。

userScope 只隔离本机会话，不认证会员；客户订单和跨设备历史需要独立服务端身份方案。原生 yunfu-voice 组件支持服务配置就绪后的实时语音；录音消息未提供。启用入口实时互动后，还须完成腾讯 TRTC、微信推拉流权限、隐私和真机验收。

### 统一填写公开入口配置

使用位置：`config.js` · 配置文件 · 接入包 0.3.14

运行前：
- 将文件放在小程序工程根目录，替换公开入口值。
- userScope 是本地隔离标识；账号切换时更换，不能用它认证微信会员。

```javascript
/* Replace these public entry values. Never paste AppSecret, session_key or admin API keys. */
module.exports = {
  baseUrl: 'https://support.example.com',
  testMode: false, // Enable explicitly for local testing; never for a release mini-program.
  publicKey: 'replace-with-public-key',
  entryId: 'replace-with-entry-id',
  userScope: 'guest', // Local partition only. Change on login/logout; not authenticated identity.
  visitorContext: { app: { name: '业务小程序', platform: 'wechat-miniapp', version: '1.0' } },
};
```

预期结果：页面与组件从同一 config.js 读取入口，密钥和 AppSecret 不进入前端。

### 原生替代：页面 JSON

使用位置：`pages/support/index.json` · 页面配置 · 接入包 0.3.14

运行前：
- 根目录已复制 yunfu-sdk，并在 app.json 注册 pages/support/index。

```json
{
  "usingComponents": { "yunfu-chat": "/yunfu-sdk/components/yunfu-chat/index" }
}
```

预期结果：微信开发工具能解析 yunfu-chat 原生组件；不是微信插件声明。

### 原生替代：页面 WXML

使用位置：`pages/support/index.wxml` · 页面文件 · 接入包 0.3.14

运行前：
- 与同包 index.js、index.wxss 和 config.js 一起复制。

```xml
<view class="setup">
  <view class="title">接入检查</view>
  <view class="hint">先在开发者工具选择自己的 AppID，再填写根目录 config.js。此处检查不会创建会话或调用 AI。</view>
  <view wx:for="{{checks}}" wx:key="id" class="check"><text>{{item.status === 'pass' ? '✓' : item.status === 'fail' ? '待修正' : '需核对'}} · {{item.message}}</text></view>
  <button bindtap="checkSetup" loading="{{checking}}" disabled="{{checking || !localReady}}">检查服务入口</button>
  <view class="hint">{{connectionStatus}}</view>
  <view wx:if="{{errorCode}}">错误码：{{errorCode}}</view>
  <view wx:if="{{needPrivacy}}">
    <view>图片、视频和文件选择前，请先阅读本小程序的隐私保护指引。</view>
    <button bindtap="openPrivacy">查看{{privacyName}}</button>
    <button open-type="agreePrivacyAuthorization" bindagreeprivacyauthorization="onPrivacyAgreed">我已阅读并同意</button>
  </view>
  <view wx:if="{{serviceState}}">当前接待状态：{{serviceState}}</view>
</view>
<yunfu-chat test-mode="{{testMode}}" wx:if="{{ready}}" base-url="{{baseUrl}}" public-key="{{publicKey}}" entry-id="{{entryId}}" user-scope="{{userScope}}" visitor-context="{{visitorContext}}" bind:statechange="onStateChange" bind:error="onSdkError" />
```

预期结果：显示入口检查及宿主隐私流程；检查通过后显示渠道聊天组件，语音仍受服务端开关约束。

### 原生替代：页面逻辑与清理

使用位置：`pages/support/index.js` · 页面文件 · 接入包 0.3.14

运行前：
- 使用上方同包 JSON/WXML，保留 ../../config 和 ../../yunfu-sdk 相对目录。

```javascript
/* global Page, wx */
// Native miniapp modules use CommonJS without a bundling step.
const config = require('../../config');
const { YunfuMiniappClient, diagnoseMiniapp } = require('../../yunfu-sdk/index');

const setupHints = {
  WX_DOMAIN_NOT_ALLOWED: '请在微信后台将 baseUrl 的主机加入 request 合法域名，并保持域名校验开启。附件还需单独配置 uploadFile 和 downloadFile。',
  WX_TLS_FAILED: '请核对公网 HTTPS 证书链及有效期，再使用体验版真机检查。',
  WX_PRIVACY_REQUIRED: '请先按宿主规则完成隐私授权，再重新检查；不要关闭全局隐私保护。',
  NETWORK_TIMEOUT: '请求超时，请检查网络后重试入口检查。此检查只读，不会创建会话。',
  NETWORK_UNCERTAIN: '网络结果未确认，请恢复网络后重试入口检查，不要据此重复发送业务消息。',
  CHANNEL_UNAVAILABLE: '请核对同一入口的公开 key、entryId 与启用状态；不要填写 AppID 或管理 API Key。',
};
Page({
  data: { ...config, checking: false, localReady: false, checks: [], ready: false, connectionStatus: '', errorCode: '', serviceState: '', needPrivacy: false, privacyName: '小程序隐私保护指引' },
  onLoad() {
    const report = diagnoseMiniapp({ ...config, key: config.publicKey, wx });
    this.setData({ localReady: report.localReady, checks: report.checks });
    // Host-owned privacy UI; the SDK never replaces an app's global privacy listener.
    if (typeof wx.getPrivacySetting === 'function') wx.getPrivacySetting({
      success: result => this.setData({ needPrivacy: result.needAuthorization, privacyName: result.privacyContractName || '小程序隐私保护指引' }),
      fail: () => this.setData({ connectionStatus: '隐私设置未读取成功；附件使用前请按宿主规则核对。' }),
    });
  },
  async checkSetup() {
    if (this.data.checking || !this.data.localReady) return;
    const generation = (this.checkGeneration || 0) + 1;
    this.checkGeneration = generation;
    this.setData({ checking: true, connectionStatus: '', errorCode: '' });
    let client;
    try {
      client = new YunfuMiniappClient({ ...config, key: config.publicKey, userScope: 'setup-check', wx });
      this.checkClient = client;
      await client.preflight(); // GET only; no visitor token, conversation, model or human dispatch.
      if (generation === this.checkGeneration)
        this.setData({ ready: true, connectionStatus: '已读取服务入口。请点击“聊一聊”，发送问题并在接待台核对实际回复。' });
    } catch (error) {
      if (generation === this.checkGeneration) this.setData({ errorCode: error.code || 'REQUEST_FAILED', connectionStatus: setupHints[error.code] || '入口检查未通过。核对公开参数与服务端入口状态，再按 README 的错误码说明排查。' });
    } finally {
      if (client) client.destroy();
      if (generation === this.checkGeneration) { this.checkClient = null; this.setData({ checking: false }); }
    }
  },
  openPrivacy() {
    if (typeof wx.openPrivacyContract === 'function') wx.openPrivacyContract({ fail: () => this.setData({ errorCode: 'WX_PRIVACY_REQUIRED' }) });
  },
  onPrivacyAgreed() { this.setData({ needPrivacy: false }); },
  onStateChange(event) {
    this.setData({ serviceState: event.detail.connected ? event.detail.state : 'not-connected' });
  },
  onSdkError(event) {
    // These bounded codes contain no visitor token, request body or customer text.
    this.setData({ errorCode: event.detail.code });
  },
  onUnload() {
    this.checkGeneration = (this.checkGeneration || 0) + 1;
    if (this.checkClient) this.checkClient.destroy();
    this.checkClient = null;
  },
});
```

预期结果：用户点击只读检查后才能打开接待；卸载会取消旧检查并清理实例。

### 检查首次打开

默认页面先显示隐私确认与进入客服按钮；无法加载时核对 web-view 使用资格、业务域名、HTTPS 和公开入口。原生替代页面使用检查入口与聊一聊。open-type="contact" 是另一条微信原生客服链路，请按对应教程配置。

### 原生替代：常见阻塞与处理

| 错误码 / 情况 | 先检查 |
| --- | --- |
| WX_DOMAIN_NOT_ALLOWED | 对应 request / uploadFile / downloadFile 合法域名，不用关闭校验替代 |
| WX_TLS_FAILED | 证书有效期、主机与信任链，分别验证 iOS / Android |
| WX_PRIVACY_REQUIRED / WX_MEDIA_PERMISSION_DENIED | 宿主隐私授权与相册/文件权限；取消选择不当成失败 |
| NETWORK_TIMEOUT / NETWORK_UNCERTAIN | 先刷新对账，再重试原 operation；不自动换 ID 重发 |
| 首次没有转人工目标 | 先发送客户诉求；需人工优先时在接待设置选择人工优先，忙时排队；未发首句直接 handoff 尚未提供 |

### 原生替代：怎样确认接入成功

| 操作 | 小程序中应看到 | 云蝠中应看到 |
| --- | --- | --- |
| 发送业务问题 | 实际 AI 回答，而非示例或初始化成功提示 | 同一入口的客户消息与 AI 回复 |
| 请求转人工 | 等待状态；接管后显示人工回复 | 进入正确的接待队列，客服接管后 AI 停止外发 |
| 取消选择文件，再选择并发送 | 取消不报成功；发送后可以预览 | 同一会话内的附件记录，其他访客不可读取 |
| 退出账号 A，再登录 B | 不展示 A 的历史或未完成请求 | 分别使用隔离会话；userScope 不作为身份认证 |
| 断网后恢复 | 保留待核对请求，刷新后决定是否重试 | 不因重试产生重复消息或重复业务操作 |

### 官方原始接入文档

先按云蝠指南完成入口、智能体和服务配置，再按下列官方原文配置宿主权限或供应商资源。外部文档说明对应平台能力，不代表云蝠已开放其中全部接口；腾讯 SecretKey、签名密钥和管理 API Key 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。

- [微信开放文档 · 小程序网络与合法域名](https://developers.weixin.qq.com/miniprogram/dev/framework/ability/network.html)：原生请求需配置 request、uploadFile、downloadFile 合法域名；WebView 另需业务域名，关闭校验不能代替正式配置。
- [微信开放文档 · 隐私授权开发指引](https://developers.weixin.qq.com/miniprogram/dev/framework/user-privacy/PrivacyAuthorize.html)：接入宿主隐私告知和同意流程；隐私同意、系统麦克风授权与实际收音分别验收。
- [微信开放文档 · wx.authorize 授权接口](https://developers.weixin.qq.com/miniprogram/dev/api/open-api/authorize/wx.authorize.html)：核对 scope.record 与拒绝后的处理；进入聊天页或点击普通按钮不等于已完成录音授权。
- [微信开放文档 · live-pusher 原生推流组件](https://developers.weixin.qq.com/miniprogram/dev/component/live-pusher.html)：核对原生推流组件、主体及类目权限；与腾讯 SDK 配置配套，在真机验证音频事件。
- [腾讯云 · 原生小程序快速接入](https://cloud.tencent.com/document/product/647/116548)：先核对企业主体、允许类目、推拉流权限、TRTC 套餐和 SDK 域名，再完成进房、发布音频与退房；开发工具不能代替真机。
- [腾讯云 · 实现 AI 对话](https://cloud.tencent.com/document/product/647/108901)：理解 RTC、识别、LLM、TTS、转录和打断的职责；具体参数与频率以对应接口的当前版本为准。
- [腾讯云 · 开始 AI 对话任务 · StartAIConversation](https://cloud.tencent.com/document/product/647/108514)：服务端适配时核对地域、SdkAppId、房间、目标用户与模型配置，保留 TaskId/RequestId；返回成功还需核对手机是否实际出声。
- [腾讯云 · 控制 AI 对话 · ControlAIConversation](https://cloud.tencent.com/document/product/647/109408)：核对供应商支持的播报和模型触发命令；仅供服务端适配参考，不可直接当作云蝠公开操作调用。
- [腾讯云 · 停止 AI 对话 · StopAIConversation](https://cloud.tencent.com/document/api/647/108513)：结束服务端 AI 对话任务并核对原 TaskId 的回收结果；退出客户端页面不应被当作云端任务已停止的证明。
- [腾讯云 · 高级权限控制](https://intl.cloud.tencent.com/zh/document/product/647/35157?lang=zh)：评估服务端 UserSig、PrivateMapKey 与房间隔离；通用平台表不证明小程序和 AI bot 已兼容，启用前须在实际应用核对入房。

继续阅读：[小程序生命周期与事件](#miniapp-events) · [小程序 API 与能力边界](#miniapp-api) · [与微信原生客服按钮的区别](#miniapp-native-contact)

实现依据（仓库内路径）：`sdk/wechat-miniapp/README.md`、`sdk/wechat-miniapp/example/pages/support/index.wxml`、`docs/MINIAPP-FIRST-CUSTOMER.md`

<a id="miniapp-events"></a>

## 小程序生命周期与事件

自绘界面时连接客户端状态与页面生命周期。

### 下载接入包

- [下载小程序 SDK 源码与示例](/downloads/yunfu-wechat-miniapp-sdk.zip) · [校验清单](/downloads/yunfu-wechat-miniapp-sdk.json)：默认 web-view 复用原版渠道页面，需业务域名；另含原生聊天与语音替代组件，按各自能力与权限完成真机验收。

### 订阅与显示

使用位置：`yunfu-sdk/examples/lifecycle.js` · CommonJS 模块 · 接入包 0.3.14

运行前：
- 用于自绘页面；现成 yunfu-chat 已管理自身生命周期。
- onShow/onHide/onUnload 分别转发给 controller，open 和 send 只从点击事件触发。

```javascript
const { YunfuMiniappClient } = require('../index');

// For a self-rendered page. Use the ready-made yunfu-chat component when no custom UI is needed.
function createSupportController(options, render) {
  const client = new YunfuMiniappClient(options);
  const unsubscribe = client.subscribe(render);
  return {
    async open() { client.setChatVisible(true); return client.connect(); },
    onShow() { client.onShow(); },
    onHide() { client.onHide(); },
    collapse() { client.setChatVisible(false); },
    send(text) { return client.sendText(text); },
    logout() {
      try { client.forgetSession(); }
      finally { try { unsubscribe(); } finally { client.destroy(); } }
    },
    destroy() { try { unsubscribe(); } finally { client.destroy(); } },
  };
}
module.exports = { createSupportController };
```

预期结果：首次 open 才连接；隐藏暂停轮询，卸载销毁，退出账号清理旧会话，不自动重放消息。

### 单实例约束

同一主机、key、entryId、userScope 已有存活实例时，新建会返回 SESSION_ALREADY_IN_USE。隐藏页面也占用实例；优先复用，或先 destroy 再创建。使用现成组件时，其内部管理生命周期，不要再为相同 scope 创建第二个客户端。

### 事件模型

当前 API 通过 subscribe(listener) 返回状态，取消订阅函数由 subscribe 返回；没有通用 on("message")、微信订阅消息或离线推送接口。前台恢复会补拉，首次历史不计为新未读。

### 官方原始接入文档

先按云蝠指南完成入口、智能体和服务配置，再按下列官方原文配置宿主权限或供应商资源。外部文档说明对应平台能力，不代表云蝠已开放其中全部接口；腾讯 SecretKey、签名密钥和管理 API Key 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。

- [微信开放文档 · 小程序网络与合法域名](https://developers.weixin.qq.com/miniprogram/dev/framework/ability/network.html)：原生请求需配置 request、uploadFile、downloadFile 合法域名；WebView 另需业务域名，关闭校验不能代替正式配置。
- [微信开放文档 · 隐私授权开发指引](https://developers.weixin.qq.com/miniprogram/dev/framework/user-privacy/PrivacyAuthorize.html)：接入宿主隐私告知和同意流程；隐私同意、系统麦克风授权与实际收音分别验收。
- [微信开放文档 · wx.authorize 授权接口](https://developers.weixin.qq.com/miniprogram/dev/api/open-api/authorize/wx.authorize.html)：核对 scope.record 与拒绝后的处理；进入聊天页或点击普通按钮不等于已完成录音授权。
- [微信开放文档 · live-pusher 原生推流组件](https://developers.weixin.qq.com/miniprogram/dev/component/live-pusher.html)：核对原生推流组件、主体及类目权限；与腾讯 SDK 配置配套，在真机验证音频事件。
- [腾讯云 · 原生小程序快速接入](https://cloud.tencent.com/document/product/647/116548)：先核对企业主体、允许类目、推拉流权限、TRTC 套餐和 SDK 域名，再完成进房、发布音频与退房；开发工具不能代替真机。
- [腾讯云 · 实现 AI 对话](https://cloud.tencent.com/document/product/647/108901)：理解 RTC、识别、LLM、TTS、转录和打断的职责；具体参数与频率以对应接口的当前版本为准。
- [腾讯云 · 开始 AI 对话任务 · StartAIConversation](https://cloud.tencent.com/document/product/647/108514)：服务端适配时核对地域、SdkAppId、房间、目标用户与模型配置，保留 TaskId/RequestId；返回成功还需核对手机是否实际出声。
- [腾讯云 · 控制 AI 对话 · ControlAIConversation](https://cloud.tencent.com/document/product/647/109408)：核对供应商支持的播报和模型触发命令；仅供服务端适配参考，不可直接当作云蝠公开操作调用。
- [腾讯云 · 停止 AI 对话 · StopAIConversation](https://cloud.tencent.com/document/api/647/108513)：结束服务端 AI 对话任务并核对原 TaskId 的回收结果；退出客户端页面不应被当作云端任务已停止的证明。
- [腾讯云 · 高级权限控制](https://intl.cloud.tencent.com/zh/document/product/647/35157?lang=zh)：评估服务端 UserSig、PrivateMapKey 与房间隔离；通用平台表不证明小程序和 AI bot 已兼容，启用前须在实际应用核对入房。

继续阅读：[生命周期与账号切换](#account-switch) · [消息、人工转接与历史](#messages) · [SDK 错误与待核对请求](#sdk-errors)

实现依据（仓库内路径）：`sdk/wechat-miniapp/index.d.ts`、`sdk/wechat-miniapp/components/yunfu-chat/index.js`

<a id="miniapp-api"></a>

## 小程序 API 与能力边界

复用消息、附件、知识与记忆 API；区别小程序文件路径和浏览器文件对象。

### 下载接入包

- [下载小程序 SDK 源码与示例](/downloads/yunfu-wechat-miniapp-sdk.zip) · [校验清单](/downloads/yunfu-wechat-miniapp-sdk.json)：默认 web-view 复用原版渠道页面，需业务域名；另含原生聊天与语音替代组件，按各自能力与权限完成真机验收。

### 初始化参数

| 参数 | 要求 |
| --- | --- |
| wx | 宿主微信 API 对象，必填 |
| baseUrl | 固定公网 HTTPS origin，不带路径和查询 |
| key / entryId | 自己的已启用入口参数，不能放 AppSecret / 管理密钥 |
| userScope | 可选；推荐每个业务账号独立，退出清理；不是认证凭据 |
| visitorContext | 可选说明资料，服务端清洗；不得据此宣称会员已认证 |
| pollInterval | 可选轮询间隔，由客户端限幅；后台暂停 |

### 消息与扩展接口

diagnoseMiniapp 为无网络本机检查；preflight 只读公开入口。connect、refresh、loadEarlier、sendText、handoff、end、restart、retryPending、discardPending、submitContact、rate、searchKnowledge、memory、changeMemory 与 Web 共用状态机。准确签名见包内 index.d.ts 及本指南的消息、附件章节。

### 文件差异

小程序 upload(filePath) 接收 wx 本地路径；download(mediaId) 返回鉴权下载后的临时文件路径。使用微信图片、视频或文档预览；这里没有 Web 的 releaseDownload()。

### AI 实时语音与在线接听

完整 SDK 包包含 yunfu-voice 原生组件。用户同意隐私和麦克风后进 TRTC 房间，进房成功才启动已发布智能体。客服仅能邀请当前前台在线客户，客户可接听或拒绝；不承诺离线微信来电。企业关闭语音后入口隐藏，服务端拒绝续租和回答并回收通话。腾讯媒体单独结算，AI 回答沿用现有模型与接待额度；公开访客不获得私有订单或 CRM 权限。

### 语音接通前核对

| 条件 | 确认方式 |
| --- | --- |
| 应用与入口 | 企业语音已开通；入口和已发布智能体均开启语音，服务时间有效 |
| 小程序权限 | 企业 AppID、推拉流标签、隐私指引、麦克风授权及 iOS/Android 真机 |
| 腾讯服务 | 独立 TRTC 应用、高级房间权限、AI bot 入房已实测、音色、回调 HTTPS 主机和安全服务端配置 |
| 费用与验收 | 腾讯 RTC/ASR/TTS 外部结算；AI 接待额度可用。自动控制测试不代替云端和音频验收 |

### 尚未接入

录音消息、视频通话、离线微信原生来电、微信 openid 认证、跨设备合并历史、模板 / 订阅消息未接入。当前小程序接入包的独立 yunfu-voice 组件支持配置就绪后的原生实时语音与在线邀请，仍需腾讯及真机验收。服务端来源仍为自建 Web 入口，请专门命名便于来源分析。

### 官方原始接入文档

先按云蝠指南完成入口、智能体和服务配置，再按下列官方原文配置宿主权限或供应商资源。外部文档说明对应平台能力，不代表云蝠已开放其中全部接口；腾讯 SecretKey、签名密钥和管理 API Key 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。

- [微信开放文档 · 小程序网络与合法域名](https://developers.weixin.qq.com/miniprogram/dev/framework/ability/network.html)：原生请求需配置 request、uploadFile、downloadFile 合法域名；WebView 另需业务域名，关闭校验不能代替正式配置。
- [微信开放文档 · 隐私授权开发指引](https://developers.weixin.qq.com/miniprogram/dev/framework/user-privacy/PrivacyAuthorize.html)：接入宿主隐私告知和同意流程；隐私同意、系统麦克风授权与实际收音分别验收。
- [微信开放文档 · wx.authorize 授权接口](https://developers.weixin.qq.com/miniprogram/dev/api/open-api/authorize/wx.authorize.html)：核对 scope.record 与拒绝后的处理；进入聊天页或点击普通按钮不等于已完成录音授权。
- [微信开放文档 · live-pusher 原生推流组件](https://developers.weixin.qq.com/miniprogram/dev/component/live-pusher.html)：核对原生推流组件、主体及类目权限；与腾讯 SDK 配置配套，在真机验证音频事件。
- [腾讯云 · 原生小程序快速接入](https://cloud.tencent.com/document/product/647/116548)：先核对企业主体、允许类目、推拉流权限、TRTC 套餐和 SDK 域名，再完成进房、发布音频与退房；开发工具不能代替真机。
- [腾讯云 · 实现 AI 对话](https://cloud.tencent.com/document/product/647/108901)：理解 RTC、识别、LLM、TTS、转录和打断的职责；具体参数与频率以对应接口的当前版本为准。
- [腾讯云 · 开始 AI 对话任务 · StartAIConversation](https://cloud.tencent.com/document/product/647/108514)：服务端适配时核对地域、SdkAppId、房间、目标用户与模型配置，保留 TaskId/RequestId；返回成功还需核对手机是否实际出声。
- [腾讯云 · 控制 AI 对话 · ControlAIConversation](https://cloud.tencent.com/document/product/647/109408)：核对供应商支持的播报和模型触发命令；仅供服务端适配参考，不可直接当作云蝠公开操作调用。
- [腾讯云 · 停止 AI 对话 · StopAIConversation](https://cloud.tencent.com/document/api/647/108513)：结束服务端 AI 对话任务并核对原 TaskId 的回收结果；退出客户端页面不应被当作云端任务已停止的证明。
- [腾讯云 · 高级权限控制](https://intl.cloud.tencent.com/zh/document/product/647/35157?lang=zh)：评估服务端 UserSig、PrivateMapKey 与房间隔离；通用平台表不证明小程序和 AI bot 已兼容，启用前须在实际应用核对入房。

继续阅读：[消息、人工转接与历史](#messages) · [附件与业务扩展](#media) · [小程序生命周期与事件](#miniapp-events) · [能力与交付状态](#capabilities)

实现依据（仓库内路径）：`sdk/wechat-miniapp/index.d.ts`、`sdk/wechat-miniapp/README.md`

<a id="miniapp-native-contact"></a>

## 与微信原生客服按钮的区别

原生 SDK 和 open-type="contact" 是两条独立链路。

### 微信客服消息接入：按角色完成配置

1. 开发者在自己的小程序中添加 open-type="contact" 按钮；已有按钮可以复用。先提交体验版，不用把管理端网址嵌入页面。
2. 小程序管理员在云蝠的小程序连接器中填写 AppID、AppSecret，绑定已发布智能体并保存。当前是密钥接入；未提供第三方平台扫码授权。
3. 复制本连接专用的公网 HTTPS 消息推送 URL。在微信后台配置同一 Token 与 EncodingAESKey，选择安全模式和 XML；先在云蝠保存密钥，再提交微信的 URL 验证。
4. 让接待组客服登录并切换在线。测试人员从体验版进入原生客服窗口，发送一条文本；只打开窗口不能证明消息接入成功。
5. 核对连接入站记录、接待台消息及手机实际回复。能接收但不能发送时，再排查稳定 access_token、权限、回复时限与发送失败记录。

### 按失败阶段定位

| 现象 | 先检查哪里 | 通过标准 |
| --- | --- | --- |
| URL 验证不通过 | 公网 HTTPS、专用回调 URL、相同 Token/AES Key、安全模式与 XML | 微信后台验证通过，凭据不出现在小程序代码里 |
| 点按钮后没有会话 | 按钮是否 open-type="contact"；是否真正发送文本；连接是否启用 | 云蝠收到同一小程序的文本入站记录 |
| 有入站，没有回复 | 智能体已发布、在线接待、官方权限及发送失败记录 | 手机实际收到对应回复 |
| 回复偶发失效 | 服务端稳定 access_token 的使用方式，避免其他系统强制刷新 | 检查发送结果后恢复收发，不盲目重发 |

### 先确定客户在哪里聊天

希望客服界面留在自己的小程序页面内，选择源码组件。希望进入微信原生客服窗口，选择原生客服消息连接器。两种方式都需要各自的配置与验收。

- [小程序内聊天：安装源码组件](#miniapp-install)
- [微信原生窗口：配置小程序连接器](#channel-wechat-mini)

### 选择哪一种

| 项目 | 云蝠源码 SDK | 微信原生客服消息 |
| --- | --- | --- |
| 界面 | 小程序内的 yunfu-chat 组件 | 微信原生客服窗口 |
| 渠道 | 独立自建 Web 入口 | 对应微信小程序连接器 |
| 凭据 | 公开 key / entryId + 访客 Bearer | 服务端 AppID / AppSecret / Token，安全模式 AES Key |
| 网络 | HTTPS request / upload / download | 平台回调和官方发送接口 |
| 边界 | 非已上架插件，无 openid 认证 | 当前文本与加密 XML；扫码授权、卡片和 session-from 分流未接通 |

### 微信原生客服的消息路径

1. **用户点击客服**：小程序的 contact 按钮打开微信客服窗口。
2. **微信推送消息**：公网回调验签、解密，校验 AppID 并去重。
3. **云蝠处理会话**：绑定智能体接待，或由有权限的人工客服接管。
4. **回复回到微信**：调用平台发送接口，再核对手机实际收到的文本。

### 原生客服接入检查

1. 管理员取得本小程序 AppID、AppSecret，确认客服消息权限；开发者在小程序放置 open-type="contact" 按钮。当前采用密钥接入。
2. 先准备回调 Token，并在微信消息推送设置中生成 EncodingAESKey。在云蝠对应小程序连接器中填写 AppID、AppSecret、Token、EncodingAESKey，绑定已发布智能体并保存连接；密钥只保存在服务端。
3. 复制已保存连接专属的公网 HTTPS 回调地址，填入微信消息推送配置；核对两端 Token 与 EncodingAESKey 一致，选择安全模式与 XML 后提交。不要替换其他在用应用的回调。
4. 完成平台 URL 校验与凭据检查，再用体验版或正式版发送真实文本。分别核对入站记录、平台发送结果和手机收到的回复。
5. 如需人工接待，先在接待台将至少一个客服账号设为在线，再验证转接、接管和人工回复。记录发送权限及窗口限制；握手成功不是完整收发成功。

### 最小客服入口

使用位置：`页面 WXML 片段` · 界面片段 · 接入包 0.3.14

运行前：
- 管理员先配置独立的微信小程序客服消息连接器并启用微信客服能力。

```xml
<!-- The bound WeChat mini-program must enable its customer-service callback. -->
<navigator url="/pages/hosted-support/index?native=1">微信客服</navigator>
<!-- Direct consultation stays available without sharing profile information. -->
<button open-type="contact">直接咨询</button>
```

预期结果：点击打开微信控制的客服窗口，不会打开 SDK 聊天、实时语音或套用渠道皮肤。

### 卡在哪一步，先检查什么

| 现象 | 优先检查 |
| --- | --- |
| URL 校验失败 | 公网 HTTPS 可达；URL 对应当前连接；两端 Token、EncodingAESKey、AppID 一致 |
| 校验通过但没有客户消息 | 发送的是否为当前 AppID 的文本；消息推送是否启用；云蝠连接与入口是否可用 |
| 消息入站但手机没有回复 | 平台发送回执、凭据有效性、出口 IP 白名单和客服发送窗口；平台接受后仍需手机核对 |
| 转人工后一直等待 | 服务时段、接待组、客服在线状态和实际接管记录；入队不代表已接管 |
| CRM、指定客服或卡片参数不生效 | 当前原生链路未接入 session-from 分流或卡片；不要将客户端字段作为可信身份 |

继续阅读：[小程序 SDK：安装与首条消息](#miniapp-install) · [微信小程序](#channel-wechat-mini) · [Webhook：订阅、验签与回执](#callbacks)

实现依据（仓库内路径）：`docs/WECHAT-MINIAPP-INTEGRATION.md`、`lib/developer-docs/integration-playbooks.ts`

<a id="server-auth"></a>

## 服务端认证与首次调用

业务系统通过操作网关访问已授权能力。

### 准备密钥

1. 在「开放平台 → 访问密钥」创建最小权限密钥，设置到期、限流与允许操作。只保存在你自己的服务端环境变量。
2. 先调用 GET /v1/capabilities，核对 tenantId、expiresAt 和 allowedOperations；该接口不要求 agents.read 权限。再从返回的授权列表中选择业务操作，核对所需参数与真实返回。
3. 写入前读取当前 revision，按接口字段构造请求，再附上稳定 Idempotency-Key。

### 配置自己的调用环境

YUNFU_BASE_URL 填密钥绑定的完整服务源站，例如 https://service.example.com，不带 /console、/api 或查询参数；OEM 域名必须与创建密钥时一致。本地仅使用 loopback HTTP。YUNFU_API_KEY 通过服务端密钥管理或环境变量注入，不贴进网页、URL、日志或聊天。

### 第一步：只读权限预检

使用位置：`终端只读检查` · 命令片段

运行前：
- 仅在服务端设置 YUNFU_BASE_URL 与 YUNFU_API_KEY；不要放入浏览器控制台。

```sh
curl --fail-with-body --show-error --max-time 15 --include "${YUNFU_BASE_URL:?Set your service origin}/v1/capabilities" \
  -H "Authorization: Bearer ${YUNFU_API_KEY:?Set your server API key}"
```

预期结果：成功返回当前企业的 allowedOperations；复制命令不建立连接，未授权操作不会自动开通。

### 读懂预检结果

| 字段 | 下一步 |
| --- | --- |
| tenantId | 确认是要接入的企业；不能用请求参数切换其他企业 |
| expiresAt / checkedAt | 毫秒时间戳；确认有效期并安排轮换，结果仅代表本次核验时刻 |
| allowedOperations | 密钥授权与当前账号权限的交集；空列表时先调整授权，不自动扩大权限 |
| X-Request-Id | 保留时间、HTTP 状态和请求编号供排查；不要保留认证头 |

### 第二步：验证一个真实业务请求

预检只验证当前凭据和权限，不执行模型、发消息、建工单或发布，也不代表资源、套餐、渠道或模型已就绪。选择 allowedOperations 中一个合适的只读接口，在「接口文档」补齐参数后再调用；写接口需另行授权和幂等键。预检共用每分钟限额，但不进入业务请求日志；实际 /v1/operations 调用再到请求日志核对。

### 不要混用协议

/v1/operations/{operationId} 使用企业 API Key；/api/* 后台路由使用登录会话，写入还要 Origin 及适用的主体范围。访客、评价、分享、电话和机器人回调有各自的凭据。不能把 API Key 直接用于任意 /api 路由。

### 查找字段与示例

「接口文档」包含已授权操作、真实路由、契约字段和 curl / Java / Go / PHP / Python 示例。OpenAPI 是索引与契约扩展，不是所有领域对象的完整 JSON Schema；不要据此生成严格 DTO 校验器。OAuth Client Credentials 和旧 /v1/conversations REST 别名未实现。

### 官方原始接入文档

先按云蝠指南完成入口、智能体和服务配置，再按下列官方原文配置宿主权限或供应商资源。外部文档说明对应平台能力，不代表云蝠已开放其中全部接口；腾讯 SecretKey、签名密钥和管理 API Key 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。

- [OpenAPI Initiative · OpenAPI Specification 3.1.0](https://spec.openapis.org/oas/v3.1.0)：理解本站 OpenAPI 文件的 schema、安全方案与导入格式；实际云蝠接口、字段和权限仍以本站接口参考为准。

继续阅读：[服务端 SDK、分页与失败恢复](#server-api-read) · [幂等、版本与错误处理](#server-errors) · [企业 SSO 与 MFA 身份打通](#enterprise-sso) · [Webhook：订阅、验签与回执](#callbacks) · [入口、身份与凭据](#credentials)

实现依据（仓库内路径）：`app/v1/operations/developer-gateway.ts`、`lib/developer-api/developer-operations.ts`、`lib/developer-docs/api-manual.ts`

<a id="enterprise-sso"></a>

## 企业 SSO 与 MFA 身份打通

对接客户 OIDC 身份系统，由客户完成 MFA，云蝠核验身份、企业范围与操作风险。

### 先选对认证方式

| 场景 | 协议与权限 |
| --- | --- |
| 管理员、员工和子账户登录 | OpenID Connect 1.0，Authorization Code + PKCE S256；客户 IdP 完成 MFA |
| 服务端业务接口与远程 MCP | API Key，绑定企业、创建账号、域名和允许操作；不是 OAuth Client Credentials |
| 网站与小程序访客 | 使用对应 SDK 访客凭据；本 SSO 不会自动认证匿名访客 |

### 一次登录怎样完成

1. **进入企业 SSO**：按管理员登记的企业标识进入 /api/identity-hub/login；云蝠创建一次性 state、nonce 与 PKCE 事务。
2. **客户完成 MFA**：浏览器跳转可信 IdP；由客户系统完成密码、OTP、硬件密钥等认证因素。
3. **回调核验**：服务端兑换 code 并验证签名、issuer、audience、nonce、acr、amr、auth_time 和策略版本；客户端传来的 MFA 标记不能代替证据。
4. **绑定已有账号**：按 issuer + subject 关联已登记的云蝠账号；不按同名邮箱自动合并，不自动提权或创建企业。
5. **按风险放行**：创建本人会话；每次请求检查企业、权限及 MFA 时效。写入、导出和凭据管理需要更近期认证。

### 客户与云蝠双方的准备

1. 客户 IdP 创建 OIDC Web 应用，登记精确回调 URI，并提供 issuer、clientId、客户端认证方式，以及经双方确认的 MFA acr / amr 含义。客户端 secret 仅配置在服务端。
2. 平台主管理员配置可信 OIDC 连接与企业标识；当前部署共用一个可信 issuer，不支持每家企业任意填写身份源。身份发现及相关端点须满足当前同源校验。
3. 企业管理员登记本人企业已有员工和子账户的外部 subject；不能仅凭邮箱自动关联。平台主管理员负责认证信任策略，更新需当前密码与 revision 校验。
4. 先在测试账号核对成功、拒绝、过期、停用、撤销绑定、跨企业和旧会话，再决定是否启用 required。开启前同时核对现有 API Key、CLI 与远程 MCP 依赖。

### 接口需求

| 路由 | 用途与认证 |
| --- | --- |
| GET /api/identity-hub/login | 浏览器企业 SSO 入口，enterprise 标识由管理员登记；reauth=1 请求重新认证 |
| GET /api/identity-hub/callback | IdP 回调，服务端验证一次性事务并创建会话 |
| GET /api/identity-hub/assurance | 本人登录会话读取当前认证状态与恢复入口，不提高权限 |
| GET / POST /api/identity-hub/policy | 企业管理员按权限读取本企业；仅平台主管理员可写策略，需当前密码与 revision |
| GET / POST /api/identity-hub/bindings | 本人管理会话维护授权范围的已有账号绑定；写入校验密码及 expectedSubject，解绑撤销相关会话 |

### 下载完整接口契约

进入「下载中心 → 企业 SSO / MFA OpenAPI」。该接口使用本人 Cookie 登录会话；写入还需同源 Origin 与服务端权限校验。API Key 不能调用这些 /api 管理路由。契约包含请求字段、错误响应与认证要求。

### 不同风险如何验证

| 风险 | 当前策略 |
| --- | --- |
| 普通业务读取 | required 模式验证可信 MFA 证据与有效期；普通时效配置为 300–28800 秒 |
| 写入、导出、凭据管理 | 需更近期 MFA，时效为 60–300 秒且不大于普通时效；过期返回 STEP_UP_REQUIRED |
| API Key / 远程 MCP | required 模式下拒绝机器调用、创建及轮换密钥；仍可用合格管理会话查看和撤销。管理员重新登录不能为 API Key 附加 MFA |

### 暂时无法接入 MFA

由平台主管理员明确选择 optional，沿用原有登录与权限控制；optional 不等于 MFA，也不自动变为只读。required 不会在 IdP 故障时自动降级。可由有权限的平台主管理员通过现有密码确认及审计流程恢复配置；目前没有双人审批或自动到期应急授权。

### 收到认证错误后怎么办

本人会话遇到 MFA_REQUIRED / STEP_UP_REQUIRED 时，经同源 loginUrl 重新认证，再由用户重新确认操作；不能自动重放写请求。API Key 收到 MFA_REQUIRED 时 loginUrl 为 null，应联系管理员核对接入方案，不能靠登录、换密钥或循环重试解除限制。远程 MCP 把同样的信息放在 error.data；普通权限 403 没有这些 MFA code。

### 当前范围

本能力适用于 SQLite / D1；PostgreSQL 的策略和绑定管理返回 501，不能声称已启用强制 MFA。没有本地 TOTP / WebAuthn 注册、SCIM 自动开通、SLO 或机器身份 MFA 例外。SAML 2.0、LDAP / AD、CAS 可由客户身份代理转换成 OIDC，未实现原生直连。真实 IdP、MFA 因素及浏览器兼容性仍需双方联调。

继续阅读：[服务端认证与首次调用](#server-auth) · [幂等、版本与错误处理](#server-errors) · [下载与更新记录](#downloads) · [入口、身份与凭据](#credentials)

实现依据（仓库内路径）：`docs/ENTERPRISE-MFA-SSO-INTEGRATION.md`、`docs/enterprise-mfa-sso.openapi.json`、`lib/identity/enterprise-assurance.ts`、`database/stores/identity/enterprise-assurance-access.ts`、`backend/services/identity/enterprise-sso-bindings.ts`

<a id="server-errors"></a>

## 幂等、版本与错误处理

先辨别协议和执行状态，再决定是否重试。

### 网关写入约定

POST /v1/operations 要求 Idempotency-Key，8–100 字符；同一业务操作重试沿用原编号与正文。响应重放窗口为 24 小时、有大小上限；未知结果不能自动重新执行。revision 是配置并发控制，不能用幂等键代替。

### 常见 HTTP 状态

| 状态 | 处理 |
| --- | --- |
| 400 / 413 / 415 / 422 | 检查字段、正文大小、Content-Type 与接口专属校验；不要原样循环重试 |
| 401 / 403 | 检查密钥到期、撤销、操作权限、所属范围及企业 MFA 策略；不要换企业或绕过校验 |
| MFA_REQUIRED / STEP_UP_REQUIRED | 本人会话按同源 loginUrl 重新认证后手动确认；API Key 的 MFA_REQUIRED 是机器接入受限，登录或轮换均无效 |
| 402 | 检查接待余额 / 套餐准入；调用前失败不等于业务成功 |
| 409 | 检查 revision 或未知执行状态，先读回对账 |
| 429 | 按 Retry-After 等待，保留原幂等键 |
| 网络超时 / 5xx | 结果可能未知，记录请求 ID 和读取状态；勿生成新键盲重试 |

### 响应格式不可一概而论

网关保留底层响应类型；下载、流式 NDJSON 与普通 JSON 分开解析，NDJSON 不是 SSE。访客客户端使用 YunfuError.code / status / retryAfter 和 pending；历史使用 before / limit，不能套用通用 page / pageSize。

### 排查信息

记录 X-Request-Id、operationId、时间、环境、HTTP 状态和脱敏响应；在请求日志核对计费主体和操作结果。不记录 API Key、visitor Bearer、原始敏感正文。

### 官方原始接入文档

先按云蝠指南完成入口、智能体和服务配置，再按下列官方原文配置宿主权限或供应商资源。外部文档说明对应平台能力，不代表云蝠已开放其中全部接口；腾讯 SecretKey、签名密钥和管理 API Key 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。

- [OpenAPI Initiative · OpenAPI Specification 3.1.0](https://spec.openapis.org/oas/v3.1.0)：理解本站 OpenAPI 文件的 schema、安全方案与导入格式；实际云蝠接口、字段和权限仍以本站接口参考为准。

继续阅读：[SDK 错误与待核对请求](#sdk-errors) · [服务端认证与首次调用](#server-auth) · [企业 SSO 与 MFA 身份打通](#enterprise-sso) · [接入常见问题](#troubleshooting)

实现依据（仓库内路径）：`app/v1/operations/developer-gateway.ts`、`lib/developer-docs/api-manual.ts`、`sdk/wechat-miniapp/index.d.ts`

<a id="server-api-read"></a>

## 服务端 SDK、分页与失败恢复

用当前服务端 SDK 先核对企业和授权，再完成一次只读调用；区分 HTTP、传输异常及业务结果。

### 运行示例前准备

从下载中心取得服务端开发客户端和只读示例，放在同一目录。示例是 JavaScript ES 模块，宿主需支持 fetch、Response、AbortSignal.any 与 AbortSignal.timeout；仅在受控服务端显式调用导出函数。先通过只读权限预检确认本人的企业编号，准备已授权的 agentId 与 agent-versions.read。示例不会自动创建或扩大密钥权限。

### 完整服务端只读示例

使用位置：`server-api-read-example.mjs` · 服务端模块示例

运行前：
- 从下载中心取得 developer-client.mjs，与本示例放在同一目录。
- 先确认自己的 tenantId、真实 agentId 及 agent-versions.read 授权；由受控服务端代码显式调用导出函数，不在浏览器运行。

```javascript
/** Server-only, read-only example. Import and call explicitly; loading this file performs no request. */
import {YunfuDeveloperClient, YunfuApiError} from './developer-client.mjs';

export async function readFirstAgentVersions({baseUrl,apiKey,agentId,expectedTenantId,fetch,signal,timeoutMs=15000}) {
  if(typeof agentId!=='string'||!agentId.trim())throw new Error('Provide your authorized agentId');
  if(typeof expectedTenantId!=='string'||!expectedTenantId.trim())throw new Error('Confirm expectedTenantId from your authorized preflight');
  const transport=fetch||globalThis.fetch;
  const guardedFetch=signal ? (url,options)=>transport(url,{...options,signal:options?.signal?AbortSignal.any([signal,options.signal]):signal}) : transport;
  const client=new YunfuDeveloperClient({baseUrl,apiKey,fetch:guardedFetch,timeoutMs});
  let stage='capabilities',requestId=null;
  try {
    if(signal?.aborted)return {outcome:'cancelled',stage};
    const grants=await client.capabilities();
    requestId=grants.requestId;
    if(grants.tenantId!==expectedTenantId)return {outcome:'tenant-mismatch',stage};
    if(signal?.aborted)return {outcome:'cancelled',stage};
    if(!grants.allowedOperations.includes('agent-versions.read'))return {outcome:'not-granted',stage};
    stage='read';requestId=null; // A preflight ID is not a business-request ID.
    // request() retains headers and response type. For a known JSON operation, json() is also available.
    const response=await client.request('agent-versions.read',{query:{agentId,page:0},signal});
    requestId=response.headers.get('x-request-id');
    const contentType=response.headers.get('content-type')||'';
    if(!contentType.includes('application/json')){
      await response.body?.cancel().catch(()=>{});
      return {outcome:'unexpected-content-type',stage,requestId};
    }
    const data=await response.json();
    if(!Array.isArray(data?.entries)||!Number.isSafeInteger(data.total)||!Number.isSafeInteger(data.page))
      return {outcome:'invalid-response',stage,requestId};
    return {outcome:'ok',requestId,data};
  } catch(error) {
    if(error instanceof YunfuApiError)return {
      outcome:'http-error',stage,status:error.status,requestId:error.requestId,retryAfter:error.retryAfter,
      ...(error.status===403&&error.body?.code==='MFA_REQUIRED'&&error.body.loginUrl===null?{code:'MFA_REQUIRED',loginUrl:null}:{}),
    };
    if(signal?.aborted||error?.name==='AbortError')return {outcome:'cancelled',stage,requestId};
    if(error?.name==='TimeoutError')return {outcome:'timeout',stage,requestId};
    return {outcome:'transport-or-response-error',stage,requestId};
  }
}

// In your authorized server job, pass environment-managed credentials and a real agentId:
// const result = await readFirstAgentVersions({baseUrl:process.env.YUNFU_BASE_URL,
//   apiKey:process.env.YUNFU_API_KEY,agentId:process.env.YUNFU_AGENT_ID,
//   expectedTenantId:process.env.YUNFU_TENANT_ID});
// Inspect result.outcome explicitly. Do not log credentials, full response bodies or customer data.
// This example performs at most one preflight and one GET. It does not retry, create, publish or bill a voice call.
```

预期结果：最多一次权限预检与一次只读 GET；按 outcome 区分权限、HTTP、取消/超时和响应类型，不自动重试或执行写入。

### 按 outcome 处理结果

ok 返回业务数据和可用的请求编号；not-granted / tenant-mismatch 停在预检，不发送业务读取。http-error 包含 HTTP 状态和可用的 requestId / retryAfter；MFA_REQUIRED 不通过登录或换密钥绕过。cancelled / timeout / transport-or-response-error 属于取消、超时或传输/解析问题，不伪装成 HTTP 错误。unexpected-content-type / invalid-response 不猜测字段。

request() 返回原生 Response，适合需要响应头、流式或下载的调用；json() 仅适用于确定返回 JSON 的操作。不要把服务端 YunfuApiError 与访客 SDK 的 YunfuError/pending 混为一套错误协议。示例不自动重试，也不把 GET 示例改成写入。

### HTTP 状态与处理方式

以下为常见状态，具体接口可能只返回其中部分；业务状态和 HTTP 状态需要分别核对。

有 X-Request-Id 时，由有权的管理员在请求日志核对；提前拒绝的请求可能没有编号，此时记录时间、操作路径和状态。/v1/capabilities 的编号不进入业务日志。错误正文按接口解析，不依赖错误文案自动重试。

| 状态 | 含义 | 处理方式 |
| --- | --- | --- |
| 400 | 参数错误 | 按当前操作检查字段、格式和固定参数；修正后再提交。 |
| 401 | 凭据失效 | 检查密钥是否过期、撤销或轮换，以及站点是否匹配。 |
| 402 | 余额或额度不足 | 核对余额、套餐和接待额度；恢复可用后再确认是否提交。 |
| 403 | 权限或来源不符 | 核对操作授权、账号权限和请求来源；不要关闭认证绕过。 |
| 404 | 资源不存在或不可见 | 核对路径、资源编号和所属企业。 |
| 405 | 请求方法不符 | 按该操作文档和 Allow 响应头使用 GET 或 POST。 |
| 408 | 读取请求超时 | 检查网络和正文上传；写入重试前核对原结果并保留原幂等键。 |
| 409 | 版本、幂等或状态冲突 | 先读回业务结果；有 Retry-After 时等待。修改配置先合并最新版本，结果未知不换键重做。 |
| 413 | 请求过大 | 按接口限制缩小请求或使用该业务提供的分批导入入口。 |
| 415 | 正文格式不支持 | 开放网关 POST 使用 Content-Type: application/json 和有效 JSON 正文。 |
| 422 | 业务条件不满足 | 按错误提示补齐配置或业务状态；不要重复提交相同无效请求。 |
| 429 | 调用限流 | 按 Retry-After 等待，降低调用频率；写入重试仍使用原幂等键。 |
| 503 | 依赖不可用 | 稍后核对服务状态；只读可有界重试，写入先确认原结果。 |

### 网关错误码

网关自身的拒绝（认证、授权、限流、幂等、格式）在 JSON 正文中返回稳定的 code，按 code 分支处理，不要解析 error 文案。没有 code 的错误由业务接口返回，按该接口说明处理。每次响应都带 X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset，可在收到 429 前主动降速。

| code | HTTP | 含义 | 处理方式 |
| --- | --- | --- | --- |
| INVALID_REQUEST | 400 | 请求参数、查询或正文不符合网关要求 | 按错误说明修正后再提交；不要原样重试。 |
| ACTION_MISMATCH | 400 | 正文 action 与所调用操作固定的 action 不一致 | 省略 action，或使用操作文档中的固定值。 |
| QUERY_MISMATCH | 400 | 查询参数试图覆盖操作的固定查询 | 删除该查询参数；需要其他分支时改用对应操作。 |
| IDEMPOTENCY_KEY_INVALID | 400 | 写请求缺少 Idempotency-Key 或格式无效 | 提供 8–100 位字母、数字、下划线、连字符、点或冒号。 |
| API_KEY_INVALID | 401 | 缺少 Bearer 密钥，或密钥不存在、已到期、已撤销 | 核对 Authorization 请求头与密钥有效期；必要时由管理员创建新密钥。 |
| API_KEY_OWNER_INACTIVE | 401 | 创建密钥的管理员账号已停用、移出企业或变更身份 | 由当前企业管理员重新创建密钥。 |
| API_KEY_ROTATED | 401 | 请求执行期间密钥被轮换 | 用新密钥读回业务结果后再决定是否重试。 |
| API_KEY_SITE_MISMATCH | 403 | 密钥不属于当前站点域名 | 使用创建密钥时的站点地址作为 YUNFU_BASE_URL。 |
| ORIGIN_NOT_ALLOWED | 403 | 请求携带了与站点不同源的 Origin | 从服务端调用并去掉浏览器 Origin；密钥不得在浏览器中使用。 |
| ACCOUNT_PERMISSION_DENIED | 403 | 密钥所属账号已不具备该操作所需权限 | 由企业管理员恢复账号权限，或改用其权限范围内的操作。 |
| TENANT_DISABLED | 403 | 密钥所属企业已停用 | 联系平台方恢复企业后再调用。 |
| OPERATION_NOT_GRANTED | 403 | 密钥未勾选该操作 | 调用 GET /v1/capabilities 核对 allowedOperations；需要时创建包含该操作的新密钥。反复调用未授权操作会触发请求防护。 |
| OPERATION_NOT_FOUND | 404 | 操作 ID 不存在 | 按接口参考核对操作 ID 的拼写与大小写。 |
| METHOD_NOT_ALLOWED | 405 | HTTP 方法与操作不符 | 按 Allow 响应头使用 GET 或 POST。 |
| REQUEST_TIMEOUT | 408 | 读取请求正文超时或被取消 | 检查网络后用原幂等键重试。 |
| IDEMPOTENCY_KEY_REUSED | 409 | 同一幂等键被用于不同的操作、查询或正文 | 重试保持原请求完全一致；新的业务提交使用新键。 |
| REQUEST_IN_PROGRESS | 409 | 同一幂等键的原请求仍在执行 | 按 Retry-After 等待后用原键重试，或在调用记录中按 requestId 核对。 |
| REQUEST_OUTCOME_UNKNOWN | 409 | 原请求中断，执行结果未知 | 先读取业务数据确认是否生效；确认未生效后才用新键重新提交。 |
| REPLAY_UNAVAILABLE | 409 | 原请求已完成，但响应超过缓存上限或已过 24 小时 | 原请求不会再次执行；通过业务读取操作获取结果。 |
| ORIGINAL_KEY_ROTATED | 409 | 原请求由轮换前的密钥发起，不重放旧回执 | 用当前密钥读回业务结果，不换键强行重做。 |
| PAYLOAD_TOO_LARGE | 413 | 请求正文超过该操作的大小上限 | 缩小正文，或使用该业务的分批导入操作。 |
| UNSUPPORTED_MEDIA_TYPE | 415 | POST 未使用 application/json | 设置 Content-Type: application/json 并发送 JSON 正文。 |
| RATE_LIMITED | 429 | 超过密钥的每分钟调用限额 | 按 Retry-After 等待到下一分钟窗口；可用 X-RateLimit-Remaining 提前降速。 |
| API_BUSY | 429 | 超过短时突发或并发上限（也可能以 503 返回） | 降低并发，按 Retry-After 退避；写入用原幂等键重试。 |
| REQUEST_BLOCKED | 429 | 账号因高频、重复越权或连续协议错误被临时封禁 | 停止调用直到 blockedUntil；修正调用方后再恢复，换密钥不能解除。 |
| MFA_REQUIRED | 403 | 企业强制 MFA，当前不允许 API Key 机器接入 | 联系企业管理员确认接入方案；重新登录或轮换密钥无效。 |
| SERVICE_UNAVAILABLE | 503 | 操作处理器暂不可用 | 稍后重试；写入用原幂等键。 |
| INTERNAL_ERROR | 503 | 服务内部异常，正文含排查编号 reference | 只读可有界重试；写入先核对业务结果，并向支持提供 reference。 |

### 按接口选择分页方式

不要为所有接口统一添加 page/pageSize。下面的操作先要求出现在当前密钥的 allowedOperations 中；日志入口则使用后台登录会话。保持每页的筛选与排序，游标只能使用服务端实际返回值。

| 场景 | 读取入口 | 参数与返回 | 何时结束 |
| --- | --- | --- | --- |
| 智能体版本 | agent-versions.read?agentId=YOUR_AGENT_ID&page=0 | page 从 0 开始；固定每页 30 条。读取 entries / total / page，不能自行加入 pageSize 改变大小。 | page × 30 + entries.length ≥ total 时结束；legacy 是兼容历史列表，单独处理。 |
| 文本会话记录 | conversations.read?page=1&pageSize=20 | page 从 1 开始，pageSize 为 1–100；读取 conversations / total / page / pageSize。 | page × pageSize ≥ total 时结束。每页 asOf 不是跨页事务快照；保持原筛选与排序。 |
| 后台请求日志 | /api/developer-platform?view=requests | 仅本人有权的后台会话可读；不是 /v1/operations 操作。每页最多 50 条，读取 requests 与 next。 | next 为 null 时结束；否则把 next.before 与 next.beforeId 一起原样带入下一页。 |

### 幂等冲突和失败恢复

先看 HTTP 状态、可用的 requestId/state 和实际业务状态；不要依赖错误文案字符串作自动重试判断。幂等键允许 8–100 位字母、数字、下划线、连字符、点或冒号。

| 场景 | 含义 | 恢复方式 |
| --- | --- | --- |
| 同一幂等键改了操作、查询或正文 | 409；幂等键在同一个 API Key 记录下跨操作共享，不是每个接口各自独立。 | 先核对原请求。重试必须保持同一操作、查询、正文与键；另一笔已确认业务提交才用另一键。 |
| 密钥已轮换 | 密钥轮换后，旧回执的密钥版本与当前不同时返回 409。 | 用当前获准凭据查询业务并由管理员核对原日志，不以换密钥或换键强行重复执行。 |
| 请求仍在执行或结果未知 | 409 可含 requestId / state，并给 Retry-After: 2；state 可能为 running 或 unknown。 | 等待后读回业务和原请求日志，不把 409 当作执行失败，也不换新键盲重做。 |
| 已完成但不能重放 | 回执完整正文最多缓存 256000 字节、窗口 24 小时；超限、过期或无缓存时不能重放。 | 查询业务结果；缓存过期不表示业务已撤销，也不授权再次执行。Idempotency-Replayed: true 仅表示返回原缓存。 |
| 业务 revision 冲突 | 业务接口也可能返回 409，与网关幂等冲突不同；revision 不是幂等键。 | 先重读并合并他人变更。确认原业务没有完成、形成新的提交内容后，才由用户确认新的逻辑提交与新键。 |
| 429、超时或断流 | 429 按 Retry-After 处理；网络异常、HTTP 状态与业务完成状态是三回事。 | 只读调用可做有界重试；写入先核对原结果。SDK 不自动重试写入，客户端取消也不保证服务端已回滚。 |

### 请求编号与响应类型

业务网关通常在登记请求后返回 X-Request-Id；方法错误、鉴权失败、参数拒绝或限流可能在登记前发生，不能假定每个业务错误都有编号。/v1/capabilities 独立返回编号但不进入业务请求日志。

普通 JSON、文件、SSE 与 NDJSON 按 Content-Type 分开读取；HTTP 2xx/202 或 api.request.completed 只表示对应 HTTP 处理结果，不代替异步任务、电话或外部投递的最终成功。

在本人有权的“开放平台 → 请求日志”记录时间、operationId、状态、请求编号和脱敏错误。该日志的后台接口不能用 API Key 调用。不要记录认证头、完整票据或客户正文。

继续阅读：[服务端认证与首次调用](#server-auth) · [幂等、版本与错误处理](#server-errors) · [Webhook：订阅、验签与回执](#callbacks) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`sdk/developer-client.mjs`、`sdk/server-api-read-example.mjs`、`app/v1/operations/developer-gateway.ts`、`backend/services/developer-api/developer-capabilities.ts`、`app/api/agent-versions/route.ts`、`database/stores/conversations/conversation-records.ts`、`database/stores/developer-store.ts`

<a id="callbacks"></a>

## Webhook：订阅、验签与回执

不同回调协议分别接入，不使用一个通用签名函数猜测所有协议。

### 订阅流程

1. 在开放平台 Webhook 选择当前支持的事件及范围，填写 HTTPS 接收地址。将该订阅产生的签名密钥只放接收端。
2. 保留请求原始正文，按对应协议的准确 Header、时间窗和签名算法校验；先核对协议再解析 JSON。
3. 验签后持久化事件及唯一标识，原子去重后处理；重复投递不能重复创建业务对象。
4. 通过投递尝试与业务记录分别核对接收、处理及最终结果；轮换密钥后按界面要求重新确认启用。

### 三类协议

| 来源 | 查阅位置 | 不可混用 |
| --- | --- | --- |
| 平台 / 业务事件订阅 | X-Yunfu-Event-Id / X-Yunfu-Delivery-Id / X-Yunfu-Timestamp / X-Yunfu-Attempt / X-Yunfu-Signature | sha256= + hex(HMAC-SHA256(timestamp.raw_body))；至少一次、不保序，自动投递最多 5 次含首次 |
| 通知投递 | X-Notification-Id；配置 HMAC 才附 X-Notification-Timestamp / X-Notification-Signature | sha256= + hex(HMAC-SHA256(timestamp.raw_body))；没有自动 5 次重试 |
| 通信网关入站 | x-app-event-id / x-app-timestamp / x-app-signature | HMAC-SHA256(bindingId.eventId.timestamp.raw_body)，64 位十六进制、不带 sha256= |

### 验签实现

签名原文必须使用原始正文，不能先解析再序列化。时间戳使用 Unix 秒；业务事件和通信回调校验 ±300 秒窗口。业务回调示例见 examples/verify-business-callback.mjs；微信 XML、LINE、电话等仍按各自真实路由契约验签。/v1/webhooks/events 未实现，不作为订阅入口。

### 回执不是业务完成

接收端 2xx 只确认收到投递。把事件入队或通知发出也不能直接标为工单解决、退款完成或电话已结束。需要读取真实业务状态；未核对保持待跟进。

继续阅读：[业务回调接入：验签、去重与故障恢复](#callback-receiver) · [API 性能与稳定接入](#api-performance) · [服务端认证与首次调用](#server-auth) · [幂等、版本与错误处理](#server-errors) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`docs/OPEN-API-CALLBACKS.md`、`lib/developer-api/business-callback-contract.ts`、`lib/developer-docs/api-route-notes.ts`

<a id="callback-receiver"></a>

## 业务回调接入：验签、去重与故障恢复

从订阅到持久收件箱的完整接入路径；明确回执、重试和业务处理的边界。

### 准备与接入

1. 先在 API 平台读取真实事件和订阅；按实际需求给服务端密钥授予 callbacks.read，以及必要的 save / toggle / test 等操作。API Key 调用者须为企业管理员本人，并同时具备 applications、agent、service 权限；后台登录会话管理要求 applications 和 agent，具体事件另查对应权限。
2. 使用 callbacks.save 保存公开 HTTPS 443 接收地址、非空 events 和 eventScope（self 或 tenant，默认 self）。新订阅停用；一次性 secret 放入接收端密钥存储，不放前端、日志或代码库。
3. 下载接收、验签、收件箱三个文件并保持同目录；Node.js 24 下在服务启动时显式打开持久收件箱一次，POST 路由在 JSON 中间件之前把原始 Request 交给 receiveBusinessCallback。
4. 配置固定的 inboxScope、tenantId 和允许的 actorId；企业事件范围使用可信配置中的 actorIds 白名单，不能从本次未验证正文复制 actorId 作为预期值。接收路径由自己定义，平台没有通用 /v1/webhooks/events 入站接口。
5. 读取当前 revision，再用 callbacks.toggle 启用，callbacks.test 发送一次真实 webhook.test；从 callbacks.read 核对投递和 delivery 查询的逐次尝试，最后查询自己的持久收件箱。测试回调属于真实外发，代码导入与阅读文档不会自动发送。

### API Key 的操作入口

| 操作 | 参数与结果 | 注意 |
| --- | --- | --- |
| GET /v1/operations/callbacks.read | subscriptions、deliveries、events；?delivery=投递ID 返回 attempts | 只读不推进队列；列表最多返回最近100条投递。 |
| POST /v1/operations/callbacks.save | name、endpoint、events、eventScope；更新另传 id、revision | 每人最多5个订阅；首次或传入非空 endpoint（含相同地址）均轮换并返回 secret；更新省略 endpoint 才保留原密钥。 |
| POST /v1/operations/callbacks.toggle | id、revision、enabled | 每次操作后重读最新 revision；不要猜测版本号。 |
| POST /v1/operations/callbacks.test | id、revision → eventId | 真实外发；每人每分钟最多10次。 |
| POST /v1/operations/callbacks.dispatch | {} → queued | 提交投递唤醒请求，每分钟最多10次；后台按当前授权统一处理，queued 不等于 delivered。 |
| POST /v1/operations/callbacks.retry | id、revision、deliveryId | 只允许未改配置的 dead 记录，累计少于10次；人工操作后仍需核对。 |
| POST /v1/operations/callbacks.rotate / callbacks.delete | id、revision | 轮换会停用，重新部署密钥并确认启用；删除不可恢复。 |

### 写入与幂等

所有 /v1/operations 写请求使用服务端 Bearer、application/json 和稳定的 Idempotency-Key。网关按操作补齐 action，显式传入时必须匹配。一个业务尝试保持同一标识与相同请求；超时先查记录，不用新标识重复测试、轮换或重发。后台 /api/business-callbacks 使用登录会话，是另一种认证协议。

### 接收与快速回执

使用位置：`business-callback-receiver.mjs` · 服务端接收模块

运行前：
- Node.js 24；与 verify-business-callback.mjs 放在同一目录。
- 在 JSON 中间件之前调用；secret、tenantId、actorId 或 actorIds 和 inboxScope 由服务端可信配置提供。

```javascript
/** Server-only Webhook receiver. Importing this module opens no server or connection. */
import { createHash } from 'node:crypto';
import { verifyBusinessCallback } from './verify-business-callback.mjs';

const MAX_BYTES = 65536;
class BodyError extends Error {
  constructor(status) { super('CALLBACK_BODY'); this.status = status; }
}
async function readBody(request) {
  if (Number(request.headers.get('content-length')) > MAX_BYTES) throw new BodyError(413);
  if (!request.body) throw new BodyError(400);
  const reader = request.body.getReader();
  const chunks = [];
  let size = 0;
  try {
    for (;;) {
      const {done, value} = await reader.read();
      if (done) break;
      size += value.byteLength;
      if (size > MAX_BYTES) throw new BodyError(413);
      chunks.push(Buffer.from(value));
    }
    return Buffer.concat(chunks, size);
  } catch (error) {
    void reader.cancel().catch(() => {});
    throw error;
  } finally { reader.releaseLock(); }
}
const reply = (status, body) => Response.json(body, {
  status, headers: {'Cache-Control':'no-store', ...(status === 503 ? {'Retry-After':'30'} : {})},
});

/**
 * Call from an explicitly configured POST route BEFORE JSON middleware.
 * persist must atomically insert a durable inbox row with its unique deduplication
 * key and return inserted / duplicate / conflict. Never use a process-local Set.
 * inboxScope is a fixed, server-owned integration ID; do not read it from headers.
 * actorIds is an optional trusted allowlist for tenant-scope subscriptions.
 * Configure body-read deadlines at the HTTP server/proxy; no business work here.
 */
export async function receiveBusinessCallback({request, secret, tenantId, actorId, actorIds, inboxScope, persist}) {
  if (!secret || !tenantId || (!actorId && !actorIds?.length) || !inboxScope || typeof persist !== 'function')
    throw new Error('CALLBACK_CONFIGURATION_REQUIRED');
  if (request.method !== 'POST') return new Response(null, {status:405, headers:{Allow:'POST'}});
  if (request.headers.get('content-type')?.split(';')[0].trim().toLowerCase() !== 'application/json')
    return reply(415, {error:'JSON_REQUIRED'});
  let rawBody;
  try { rawBody = await readBody(request); }
  catch (error) { return reply(error instanceof BodyError ? error.status : 400, {error:'INVALID_BODY'}); }
  let event;
  try { event = verifyBusinessCallback({secret, headers:request.headers, rawBody, tenantId, actorId, actorIds}); }
  catch { return reply(400, {error:'INVALID_CALLBACK'}); }
  const bodyHash = createHash('sha256').update(rawBody).digest('hex');
  try {
    const outcome = await persist({inboxScope, eventId:event.id, bodyHash, event});
    if (outcome === 'conflict') return reply(409, {error:'EVENT_BODY_CONFLICT'});
    if (outcome !== 'inserted' && outcome !== 'duplicate') return reply(503, {error:'INBOX_UNAVAILABLE'});
    // This acknowledges durable receipt only. A separate worker handles business work.
    return reply(200, {received:true, duplicate:outcome === 'duplicate'});
  } catch { return reply(503, {error:'INBOX_UNAVAILABLE'}); }
}
```

预期结果：只有持久收件箱确认插入或重复后返回 200；冲突返回 409，存储故障返回 503；不执行业务副作用。

### 持久化去重适配器

使用位置：`business-callback-inbox-postgres.mjs` · PostgreSQL 持久化适配器

运行前：
- 使用 pg 驱动；传入专用 Pool，配置 PostgreSQL URL、TLS 和独立 schema。
- 启动时 await openBusinessCallbackInbox(pool)，把 inbox.persist 传给接收模块；退出时 await inbox.close()。

```javascript
/** PostgreSQL inbox. Pass a dedicated pg Pool with its TLS and schema configured by the host. */
export async function openBusinessCallbackInbox(pool) {
  if (!pool || typeof pool.query !== 'function' || typeof pool.end !== 'function')
    throw new Error('POSTGRES_INBOX_POOL_REQUIRED');
  try {
    await pool.query(`CREATE TABLE IF NOT EXISTS yunfu_callback_inbox (
      integration TEXT NOT NULL, tenant TEXT NOT NULL, event_id TEXT NOT NULL,
      body_hash TEXT NOT NULL, payload TEXT NOT NULL, received_at BIGINT NOT NULL,
      state TEXT NOT NULL DEFAULT 'pending', PRIMARY KEY(integration, tenant, event_id)
    )`);
  } catch (error) { await pool.end(); throw error; }
  return {
    // Unique insert includes the pending work payload; 2xx always follows persistence.
    async persist({inboxScope, eventId, bodyHash, event}) {
      const result = await pool.query(`INSERT INTO yunfu_callback_inbox
        (integration,tenant,event_id,body_hash,payload,received_at) VALUES($1,$2,$3,$4,$5,$6)
        ON CONFLICT(integration,tenant,event_id) DO NOTHING`,
        [inboxScope,event.tenantId,eventId,bodyHash,JSON.stringify(event),Date.now()]);
      if (result.rowCount === 1) return 'inserted';
      const prior = await pool.query('SELECT body_hash FROM yunfu_callback_inbox WHERE integration=$1 AND tenant=$2 AND event_id=$3', [inboxScope,event.tenantId,eventId]);
      return prior.rows[0]?.body_hash === bodyHash ? 'duplicate' : 'conflict';
    },
    close() { return pool.end(); },
  };
}
```

预期结果：同一集成、企业、事件只生成一条待处理记录；跨重启保留去重，业务处理和保留期由宿主另外实现。

### 接收后如何处理

示例仅持久保存 pending 事件，不启动业务工作进程，也不承诺业务恰好执行一次。宿主需另行实现领取、租约、重试与完成标记；向外部业务写入时使用其幂等键或事务约束，结果未知先核对。读取旧事件不能仅靠到达顺序；按 sourceId/taskId 和 revision 判断新旧。

inboxScope 应在同一集成的密钥轮换和重复部署间保持稳定；多租户、多个集成分别隔离。单机 SQLite 文件需要持久卷、文件权限和备份；多实例使用共享数据库的原子唯一写入，不能各开一份文件或用内存 Set。数据库示例不自动删除记录；保留期须覆盖自动与人工重试及业务审计要求。

宿主 HTTP 服务器应配置正文读取超时和连接上限。接收示例最多读取65536字节，先验签再解析，成功持久化后立即返回200；耗时业务放到独立工作进程。数据库出错返回503，不提前确认收到。

### 状态与排查

| 观察到的情况 | 优先检查 | 恢复方式 |
| --- | --- | --- |
| 验签失败 / 400 | 原始字节、sha256= 前缀、Unix秒时间戳、±300秒时钟差、当前 secret | 修正接收端；不要重新序列化正文再计算签名。 |
| 409 EVENT_BODY_CONFLICT | 同一集成/企业/事件编号对应不同原始正文 | 保留原记录并告警，人工核查；不覆盖、不重复执行业务。 |
| 503 INBOX_UNAVAILABLE | 持久文件权限、容量、锁竞争或共享数据库连接 | 恢复存储后由平台重试；200必须在持久化成功后返回。 |
| retry / 网络超时 | 接收方可能已持久保存，但回执丢失 | 依靠事件ID和正文摘要去重，重复同正文返回200。 |
| dead | 最多5次自动尝试耗尽，或发送中租约过期且次数耗尽 | 修正故障后仅对允许的记录人工 retry，累计上限10次。 |
| cancelled | 订阅停用/版本变化、账号epoch/权限、企业状态 | 修复配置并重新确认启用；旧事件不会自动重放到新订阅。 |

### 时限和标识

单次投递总超时8秒，租约60秒。失败间隔30秒、2分钟、10分钟、1小时，最多5次含首次；实际执行时间还取决于调度与积压，不承诺秒级送达。至少一次、不保序。重试复用 Event-Id 和 Delivery-Id，刷新 Timestamp / Signature / Attempt；这些投递头本身不在正文签名范围内，去重以验签后的正文事件编号为准。接收方的 Retry-After 当前不调整平台固定重试表。

2xx只代表接收方确认收到，不代表退款、工单、构建或通话完成。api.request.completed 表示 API HTTP 处理结果；业务完成读取对应业务状态或对应已实现事件。错误诊断只记录事件/投递编号、状态和时间，避免记录密钥或敏感正文。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端 SDK、分页与失败恢复](#server-api-read) · [幂等、版本与错误处理](#server-errors) · [API 性能与稳定接入](#api-performance)

实现依据（仓库内路径）：`sdk/business-callback-receiver.mjs`、`sdk/business-callback-inbox-postgres.mjs`、`examples/verify-business-callback.mjs`、`backend/services/developer-api/callback-dispatch.ts`、`database/stores/callback-store.ts`、`backend/services/developer-api/callback-settings.ts`、`lib/developer-api/developer-operations.ts`

<a id="api-performance"></a>

## API 性能与稳定接入

按实际响应类型、限流、分页和回调语义组织调用，避免轮询与重试放大。

### 调用路径建议

1. 服务端初始化时先做 capabilities 只读预检，业务请求仍会重新校验授权；预检不代替后续权限检查，也不要每次业务调用前重复拉取完整目录。
2. 列表按对应接口的分页契约读取，只有用户翻页或后台任务需要时才取下一页；请求日志使用成对 before / beforeId 游标，不通过不断增加偏移量翻页。
3. 复用宿主 HTTP 连接池，设置有限并发和请求超时；根据429及 Retry-After 降低并发，避免同时重试全部请求。取消已不需要的读取，不把客户端取消当成业务撤销。
4. SSE / NDJSON 按原响应类型逐块读取，下载按字节处理，不等完整响应后才显示首条结果，也不把所有响应都交给 json()。
5. 写请求超时保留原 Idempotency-Key，先查询真实业务记录；网关仅对有界已完成响应重放，unknown、running、超限正文均不能靠换标识重做。
6. 异步任务优先使用已实现回调，配合低频有界状态核对；回调接收只验签并持久入队，避免等待模型、邮件或下游业务完成后才回执。

### 如何验证性能

| 指标 | 口径 | 诊断 |
| --- | --- | --- |
| 首字节 / 首事件延迟 | 分别记录HTTP响应头、首条流式事件和最终完成时间 | 连接建立、鉴权、业务处理和下游模型分别排查。 |
| 成功请求延迟 p50 / p95 | 区分操作、响应体量、并发和数据规模 | 请求日志 duration 包含流式结束，不等于模型首字延迟；不能只看平均值。 |
| 429 / 5xx / 超时率 | 包含失败与被限流请求，不从样本中删去 | 先降并发并核对 Retry-After；不要用提高限额掩盖错误。 |
| 回调积压与最老等待时间 | 按 pending / retry / sending / dead 区分 | 确认调度在工作，再查接收端持久存储与回执耗时。 |

### 异步与批次调用

SDK 的 batchJson(items, { concurrency: 2, signal }) 接受1–50项，单批并发1–4；同一客户端跨批次最多4项正在执行、100项未完成。返回顺序与输入一致，每项独立成功或失败。JSON正文读完才释放并发额度。

批次中的每项仍是独立HTTP请求，不是服务端批量事务。需要减少请求次数时，优先使用业务原生批量接口，例如 insights.conversations.import 一次提交1–50条 records，整体正文最多150000字节。不能用通用批次绕过逐项权限、计费或幂等。

写入项必须使用各自独立且稳定的 Idempotency-Key。429或503会按 Retry-After 暂缓同一客户端后续批次项，最长60秒；失败项不自动重试。普通 request/json 和流式调用仍需宿主自行控制并发。

### 批次读取示例

使用位置：`api-batch-example.mjs` · 有界批次示例

运行前：
- 与最新版 developer-client.mjs 放在同一目录，传入真实智能体编号。
- 仅在受控服务端显式调用；示例导入时不发起请求。

```javascript
import { YunfuDeveloperClient } from './developer-client.mjs';

/** Import is inert. Call only from your authorized server; no secret is embedded. */
export async function readAgentVersionsBatch({ baseUrl, apiKey, agentIds, signal }) {
  if (!Array.isArray(agentIds) || !agentIds.length || agentIds.length > 50 ||
      agentIds.some(id => typeof id !== 'string' || !id.trim())) throw Error('Provide 1–50 real agent IDs');
  const client = new YunfuDeveloperClient({ baseUrl, apiKey });
  const grants = await client.capabilities();
  if (!grants.allowedOperations.includes('agent-versions.read')) throw Error('Operation not authorized');
  const results = await client.batchJson(agentIds.map(agentId => ({
    operation: 'agent-versions.read', query: { agentId },
  })), { concurrency: 2, signal });
  return results.map((result, index) => ({ agentId: agentIds[index], ...result }));
}

// Each item remains a separate HTTP request. Use native records-based imports
// when reducing request count is required. Failed items are not retried here.
// Reuse a client in a long-lived service so concurrent batches share its limits.
```

预期结果：逐项返回成功或失败，最多50项、默认并发2；不自动重试失败项。

### 过载保护

操作网关保留每密钥分钟配额，并增加共享数据库的秒级突发上限：每密钥8次、每企业24次、每环境96次。单个网页服务进程另限制正在执行的操作：每密钥4个、每企业12个、合计64个；流式请求持续占位直到结束或取消。

超出限制在执行业务前返回429或503及 Retry-After，不接受后再丢弃。秒级预算跨进程共享；正在执行数量是单进程保护，不应当作整个集群的总并发承诺。

### 回调后台分批投递

事件与业务变化仍在同一事务持久保存。网页和构建入口只合并唤醒后台队列；每个环境同一时刻由一个持有有效租约的消费者发送，每次HTTP回调仍保持一个签名事件。

每轮最多50条、最多20秒启动新投递，已经领取的请求仍受8秒超时保护；逐条发送间隔至少100毫秒。到期积压通过持久续调继续处理，丢失唤醒由周期扫描恢复；没有后台执行器时记录会等待，不会伪装成投递成功。

默认不合并或丢弃业务事件，不把整个队列一次放进内存。失败沿用退避和有限重试；接收方应验签、持久去重入队后快速返回2xx，把耗时业务留给自己的后台任务。

### 本轮优化范围

请求日志深分页按现有复合索引直接定位游标；只读网关响应不再建立文本重放副本，写响应超过256000字节后及时释放缓存；回调列表独立读取并发执行。密钥、企业、当前权限和调用时重新授权仍实时检查，新增过载保护，写入幂等边界保持不变。

性能数据只能对应具体测试条件。离线SQLite或模拟传输结果不等于生产端到端吞吐；正式压测需使用隔离企业、合成数据、明确并发与停止条件，不能把语音/模型调用或真实客户业务作为无约束压力源。

继续阅读：[服务端 SDK、分页与失败恢复](#server-api-read) · [业务回调接入：验签、去重与故障恢复](#callback-receiver) · [幂等、版本与错误处理](#server-errors)

实现依据（仓库内路径）：`database/stores/developer-store.ts`、`app/v1/operations/developer-gateway.ts`、`lib/developer-api/developer-replay-capture.ts`、`database/stores/callback-store.ts`、`backend/services/developer-api/callback-settings.ts`

<a id="voice"></a>

## 语音接入与消息 SDK 的边界

语音使用已有独立接入文档与权限链路。

### 接入入口

进入「开放平台 → 语音接入」查看当前协议、鉴权、语音资源、代码示例与诊断。浏览器真实语音需要 HTTPS、用户交互与麦克风权限；各端容器不能直接借用浏览器已通过的验收。

### 当前消息包

Web 无 UI 消息内核的 realtimeVoice / voiceMessage 为 false。小程序 voiceMessage 为 true，支持最长60秒私有录音消息，自动转写使用已授权文件 ASR 与语音额度；录音需要宿主隐私声明及麦克风授权。小程序另有 yunfu-voice RTC 组件，需腾讯与真机验收。接入包 0.3.0 提供 H5 完整语音嵌入，以及 iOS/Android、Harmony、Uniapp 的前台语音宿主流程；复用渠道引擎，不是独立原生媒体 SDK，平台编译与真机待验收。所有语音继续受企业、入口、已发布智能体及额度限制。

### 验收维度

单独核验设备收音、外放回声、打断、前后台、连接恢复、计费和挂断回执。首包返回或模型调用成功不等于通话质量合格。

### 官方原始接入文档

先按云蝠指南完成入口、智能体和服务配置，再按下列官方原文配置宿主权限或供应商资源。外部文档说明对应平台能力，不代表云蝠已开放其中全部接口；腾讯 SecretKey、签名密钥和管理 API Key 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。

- [腾讯云 · 原生小程序快速接入](https://cloud.tencent.com/document/product/647/116548)：先核对企业主体、允许类目、推拉流权限、TRTC 套餐和 SDK 域名，再完成进房、发布音频与退房；开发工具不能代替真机。
- [腾讯云 · 实现 AI 对话](https://cloud.tencent.com/document/product/647/108901)：理解 RTC、识别、LLM、TTS、转录和打断的职责；具体参数与频率以对应接口的当前版本为准。
- [腾讯云 · 开始 AI 对话任务 · StartAIConversation](https://cloud.tencent.com/document/product/647/108514)：服务端适配时核对地域、SdkAppId、房间、目标用户与模型配置，保留 TaskId/RequestId；返回成功还需核对手机是否实际出声。
- [腾讯云 · 控制 AI 对话 · ControlAIConversation](https://cloud.tencent.com/document/product/647/109408)：核对供应商支持的播报和模型触发命令；仅供服务端适配参考，不可直接当作云蝠公开操作调用。
- [腾讯云 · 停止 AI 对话 · StopAIConversation](https://cloud.tencent.com/document/api/647/108513)：结束服务端 AI 对话任务并核对原 TaskId 的回收结果；退出客户端页面不应被当作云端任务已停止的证明。
- [腾讯云 · 高级权限控制](https://intl.cloud.tencent.com/zh/document/product/647/35157?lang=zh)：评估服务端 UserSig、PrivateMapKey 与房间隔离；通用平台表不证明小程序和 AI bot 已兼容，启用前须在实际应用核对入房。

继续阅读：[ESP32 语音智能体固件接入](#esp32) · [能力与交付状态](#capabilities) · [隐私告知与权限申请](#privacy) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`docs/voice-sdk.md`、`lib/developer-docs/voice-integration.ts`

<a id="esp32"></a>

## ESP32 语音智能体固件接入

使用 C SDK 在 ESP32-S3 上接入语音智能体，处理唤醒、外放插话和弱网恢复。

### SDK 与开发环境

以 ESP32-S3 和 ESP-IDF v5.5.2 为例。将头文件加入已有固件工程，再按开发板配置 I²S 麦克风和扬声器、引脚、增益和回声消除。下方是源码和接入示例，整机固件由你的工程编译并烧录。

- [云蝠智能 · 下载 ESP32 C SDK](/api/voice-sdk?file=yunfu-esp32-voice.h)：头文件包含音频缓存、二进制封帧和 HTTPS 连接辅助。
- [云蝠智能 · 下载离线文档](/api/voice-sdk?file=esp32-voice.md)：保留接入步骤、代码、联调和故障诊断。
- [Espressif · ESP-IDF v5.5.2 安装与烧录](https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/get-started/index.html)：核对工具链、串口与开发板配置。
- [Espressif · WebSocket 客户端组件](https://components.espressif.com/components/espressif/esp_websocket_client)：将组件加入项目，并提交 dependencies.lock 固定工程解析到的版本。

1. 已有工程若缺 WebSocket 客户端，执行 idf.py add-dependency "espressif/esp_websocket_client"。为接入组件声明 esp_http_client、esp_timer 依赖，使用原生 TLS 示例时加入 esp-tls。
2. 执行 idf.py set-target esp32s3。配置 Wi-Fi、根证书包和 I²S，再执行 idf.py build。
3. 用对应板卡的串口执行 idf.py -p PORT flash monitor。首次联调分别确认收音、喇叭播放和联网。

### 唤醒、取票与连接

1. 设备接入 Wi-Fi 后可在后台调用 yf_voice_broker_client(&cfg, true) 预热取票服务。唤醒即亮灯并开始收音，已完成的预热句柄可以复用，未完成则由本次唤醒的网络任务直接取票。
2. 业务服务持有具备 voice.start 权限的 API Key，使用已发布智能体为设备调用 POST /v1/operations/voice.start，mediaProtocol 填 volc-dialogue。设备只收到对应会话的短期票据和返回的媒体地址。相同请求结果未知时保留幂等键核对。
3. 按回执指定的 WSS URL 连接，用 Authorization: Bearer 传入临时票据。保留 TLS 证书校验。连接打开后按顺序连发 1、100 两条独立二进制消息。50 确认连接，收到匹配当前会话的 150 后才发送缓存音频。启动写入失败时关闭连接，结果未知先核对会话。

### ESP32-S3 原生 TLS 示例

原生 esp-tls 客户端读完整个取票响应后，若使用 HTTP/1.1、连接允许复用，且返回的 WSS 主机、端口和 TLS 身份策略一致，可接管同一个句柄。用回执的路径和查询参数发送新的 WebSocket Upgrade，只带媒体票据，校验 101 和 Sec-WebSocket-Accept 后再启动会话。使用 esp_http_client、连接已关闭或目标不同，沿用独立 WSS。

冷连接示例预算为 3 秒。确认 0x8006 后 5 秒内同一链路立即返回原错误，Wi-Fi 或目标变化时清空 link。

使用位置：`ticket_transport.c` · 固件片段

运行前：
- 链接 esp-tls 和 esp_timer，配置可信根证书。
- 每个网络和 HTTPS 目标单独初始化 link，由网络任务独占。

```c
#define YF_VOICE_USE_ESP_TLS
#include "yunfu-esp32-voice.h"

// One zero-initialized link per Wi-Fi connection and HTTPS endpoint.
// cfg is your CA-verified, blocking client configuration. *tls must start as NULL.
static esp_err_t connect_ticket_service(yf_voice_tls_link *link, const char *host,
                                        const esp_tls_cfg_t *cfg, esp_tls_t **tls) {
    return yf_voice_tls_connect(link, host, 443, cfg, 3000, tls);
}

// Call after reading the ticket response. Parse media_host/port from its validated wss:// URL.
// Both requests use the same TLS identity and trust settings. *media_tls starts as NULL.
static esp_err_t connect_media(yf_voice_tls_link *media_link, const char *ticket_host, int ticket_port,
                               esp_tls_t **ticket_tls, bool http1_reusable, const char *media_host,
                               int media_port, const esp_tls_cfg_t *cfg, esp_tls_t **media_tls) {
    if (!media_tls || *media_tls) return ESP_ERR_INVALID_ARG;
    *media_tls = yf_voice_tls_take_for_wss(ticket_tls, ticket_host, ticket_port,
                                           media_host, media_port, http1_reusable);
    if (*media_tls) return ESP_OK;
    return yf_voice_tls_connect(media_link, media_host, media_port, cfg, 3000, media_tls);
}
```

预期结果：复用成功后由媒体任务独占并最终销毁句柄。冷连接时取票任务仍负责清理原句柄。Upgrade 失败时关闭该连接；已发送 StartSession 而结果未知时先核对会话。取票 POST 结果未知时沿用原幂等键核对。

### 收音、缓存与媒体发送

使用 16 kHz 单声道 PCM16 小端音频。每帧 20 ms（320 个样本，640 字节）。32 帧占 20 KiB，可容纳 640 ms。256 帧占 160 KiB，可容纳 5.12 秒。模块有 PSRAM 时可在唤醒前分配。开口后保留音节和句中停顿，缓存紧张时只回收开口前确认的非人声。

使用位置：`media_uplink.c` · 固件片段

运行前：
- 传入已建立的 WebSocket 句柄和当前 session_id。
- 使用兼容二进制协议的默认 PCM 格式。只有 150 声明能力时才启用板端 VAD 提示。

```c
#include "yunfu-esp32-voice.h"
#include "esp_timer.h"
#include "esp_websocket_client.h"

typedef struct {
    esp_websocket_client_handle_t ws;
    uint8_t packet[16 + 256 + sizeof(yf_voice_frame)];
    size_t prefix;
    const char *session_id;
    yf_voice_activity (*detect_edge)(const int16_t *pcm); // Optional board VAD, advanced by samples.
    uint8_t control[16 + 256 + 64];
} uplink;

static int write_start_frame(void *ws, const uint8_t *frame, size_t length) {
    return esp_websocket_client_send_bin((esp_websocket_client_handle_t)ws, (const char *)frame,
                                         (int)length, pdMS_TO_TICKS(1000));
}

static bool on_media_open(uplink *tx, const char *session_id) {
    tx->session_id = session_id;
    tx->prefix = yf_voice_pcm_prefix(tx->packet, sizeof(tx->packet), session_id);
    return tx->prefix && yf_voice_start_dialogue(tx->control, sizeof(tx->control), session_id,
                                                 write_start_frame, tx->ws);
}

static yf_voice_send_result send_pcm(void *arg, const int16_t *pcm) {
    uplink *tx = (uplink *)arg;
    if (!tx->prefix) return YF_SEND_UNKNOWN;
    memcpy(tx->packet + tx->prefix, pcm, sizeof(yf_voice_frame));
    int size = (int)(tx->prefix + sizeof(yf_voice_frame));
    int sent = esp_websocket_client_send_bin(tx->ws, (const char *)tx->packet,
                                               size, pdMS_TO_TICKS(20));
    if (sent != size) return YF_SEND_UNKNOWN;
    if (!tx->detect_edge) return YF_SENT;
    yf_voice_activity edge = tx->detect_edge(pcm);
    if (edge == YF_ACTIVITY_NONE) return YF_SENT;
    size_t n = yf_voice_activity_packet(tx->control, sizeof(tx->control), tx->session_id, edge);
    if (!n) return YF_SEND_UNKNOWN;
    sent = esp_websocket_client_send_bin(tx->ws, (const char *)tx->control, (int)n, pdMS_TO_TICKS(20));
    return sent == (int)n ? YF_SENT : YF_SEND_UNKNOWN;
}

// At wake: yf_voice_wake(&input, storage, frame_capacity);
// Each 20 ms: yf_voice_capture(&input, pcm);
// With device VAD, use yf_voice_capture_with_vad(&input, pcm, confirmed_quiet_for_this_frame);
// Keep the admitted session_id alive until teardown. Zero-initialize tx for every connection.
// Use the returned WSS URL with the default raw PCM format.
// After WSS opens, call on_media_open(&tx, session_id) once from the media task.
// On failure close this transport; reconcile an uncertain StartSession before retrying.
// On validated 150: enable detect_edge only if yunfu_input_activity is true. Then yf_voice_ready(&input);
// On ready and each 20 ms tick (including silence): yf_voice_pump(&input, esp_timer_get_time(), send_pcm, &tx);
```

预期结果：媒体就绪后按帧发送，跟不上时显式判断回压或断线。已提交结果未知的帧不自动重放。

### 播放、打断与回执

1. 收到 yunfu.audio.started 后，先用 yf_voice_playback_start(&out, generation, rate) 打开本轮播放，队列和 DMA 回调带上这一代编号。WebSocket 分片按完整消息重组，收到 352 后将有效 PCM 写入现有环形队列，并调用 yf_voice_playback_receive 登记样本。队列已满时分批写入；已丢弃音频则调用 yf_voice_playback_discard。使用 16 kHz 播放时可协商 output_sample_rate=16000。
2. 在每个 DMA 补给周期调用 yf_voice_playback_allow_dma(&out, generation, queued, capacity, now_ms, underrun)，允许后再从原队列提交。queued 和 capacity 都用单声道样本数，不含已提交给 DMA 的样本。now_ms 为单调毫秒时钟，每次真实耗尽仅标记一次 underrun。首播目标 20 ms，耗尽后每次加 20 ms，上限 80 ms 或环形队列容量。连续播放每满一秒降低一级。未攒满也会在目标时限后放行。
3. 收到本轮正常结束事件时调用 yf_voice_playback_end，立即放行短尾音。yf_voice_playback_consume 只登记 I²S 实际播出的原始样本，等待或填充静音不计入回执。
4. 收到 yunfu.interrupted 时调用 yf_voice_playback_discard，清空 interrupted_generation 及更早的队列和 DMA。延迟到达的旧代播放回调按代号忽略。
5. 实际播放完成并且音频连续时，用事件 9000 发送 yunfu.playback.complete，写入当前 generation、实际 playedMs、telephone-media-clock、continuous:true 和 final:true。收到末包、DMA 入队或播放被提前清除时不可确认播完。
6. 断线清理旧连接的输入、播放和 VAD 状态。票据只消费一次。按回执能力恢复或核对、结束原会话后再明确开始新会话。

### 外放时插话

1. 采音侧用对齐的扬声器参考做回声消除，并独立检测用户开口。网络任务在对应 PCM 成功发出后再转发本地判停，扬声器降音由采音侧触发。
2. 每次连接都重新读取 150 的 yunfu_scoped_interrupt。只有它和当前 yunfu.audio.started 的 interruptible 都为 true，固件才可主动降音和按代打断。其余情况继续上传 PCM，收到 yunfu.interrupted 后按 interrupted_generation 清理旧音频。
3. 固件自行判定普通插话时，先降低旧播报音量并持续收音。确认是用户插话且不足 3 秒，在用户说完时停掉旧播报。持续满 3 秒仍在说话时停播并继续收音。只有“嗯”等附和或扬声器回声时恢复原音量。新回复只走同一个播放器。
4. 使用 yf_voice_interrupt_packet 发当前 generation 和真实停播截点。先从 I²S 读取实际已播样本并编码，再调用 yf_voice_playback_discard。截点未知时传 NULL，只按代次打断。普通播完使用 yf_voice_playback_complete_packet。旧代和异步 DMA 回调按 generation 丢弃。

### 弱网恢复

在三段式智能体中启用「音频断续保护」。一句话中途断流后，网关会等待同一输入轨道恢复。固件保留真实采音顺序，避免用补零制造句末。

| 设备收到什么 | 固件怎么处理 |
| --- | --- |
| 上行暂时写不进去 | 确认整帧尚未提交时返回 YF_WOULD_BLOCK，SDK 会保留该帧并按顺序补发。部分写入或结果未知时返回 YF_SEND_UNKNOWN。进入 YF_INPUT_LOST 后丢弃本句缓存，提示用户重说。 |
| 事件 9000 · yunfu.input.flow | 读取 input_flow.id、sequence 和 paused，同一流忽略重复或较旧序号。paused 为 true 时暂停上传，收到更新的 false 后从新采音恢复并重置 VAD。暂停期的积压音频不补发。 |
| 事件 9000 · yunfu.input.unconfirmed | 只请用户重说受影响的那句话。保留已确认轮次，避免用已识别的半句话触发业务操作。 |
| Wi-Fi 断开或连接失去响应 | 响应标准 WebSocket Ping。二进制网关每 5 秒探测，连续 15 秒未收到 Pong 或上行二进制消息时释放连接。断开时清理本地收音、待播队列和 DMA。 |
| 恢复原会话 | 从 voice.start 回执读取 connectionPolicy。resumeSupported 为 true 且仍在 reconnectWindowMs 内时，保留 compatibility.url 的媒体参数，追加 resume=1，将 reconnectToken 作为 Authorization 请求头的 Bearer 凭据重连。重发事件 1 和 100，核对本次会话的 150 后再上传新音频。无法恢复时由业务服务用 voice.read 核对原会话，再决定是否结束并重新取票。 |

### 真机验收

1. 在同一连接连续对话三轮。分别记录唤醒到事件 150、用户说完到扬声器播出正文第一个字的时间。用同一板卡和网络对比，唤醒提示音与垫词单独记录。
2. 播放中分别说一声“嗯”、一句不到 3 秒的“改到周六”，再试一句超过 3 秒的话。确认附和后能接着播，有效插话时只有一路回复。记录用户开口、旧声实际停止及本次 generation 的已播样本数。
3. 说“约周五……改到周六”时，在两段之间让上行暂停约半秒，然后恢复。确认完整语句只触发一次回复，或收到未确认提示后重说。再断开 Wi-Fi 验证恢复窗口内外两种情况，核对会话编号、旧音频是否重播及有无重复取票。

### 联调与排错

| 现象 | 核对方式 |
| --- | --- |
| 0x8006 / select() timeout | 记录时区、域名、解析 IP 和失败阶段。同一 Wi-Fi 下用电脑验证 443。同步核对平台维护窗口。 |
| HTTP 401 / 403 | 检查业务服务权限、票据有效期、来源和会话匹配。 |
| 已连接却丢开口 | 分别计时唤醒、取票、WSS 升级和事件 150。检查缓存容量、实际 PCM 规格和 YF_INPUT_LOST。 |
| 唤醒后首句慢 | 分别记录唤醒、取票完成、WSS 升级完成、事件 150、首个 352 和扬声器首声。注明媒体是否复用 TLS。扬声器为 24 kHz 时可协商 output_sample_rate=24000，上行保持 16 kHz。 |
| 首包已到但听到晚 | 分开记录事件 352、PCM 入队、I²S 实际开始播放。核对播放队列和 DAC 采样率。 |
| 打断后出现上一轮声音 | 按 generation 清理 DMA 和待播队列。连续测试两轮、插话、断线和 Wi-Fi 切换。 |

继续阅读：[语音接入与消息 SDK 的边界](#voice) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`sdk/yunfu-esp32-voice.h`

<a id="sdk-errors"></a>

## SDK 错误与待核对请求

网络失败时保留真实状态，避免重复消息和重复业务执行。

### 排查表

| 现象 | 处理 |
| --- | --- |
| SESSION_ALREADY_IN_USE | 同 scope 已有实例，复用或先销毁，不创建竞争客户端 |
| storageError / 本地存储不可用 | 停止发送并提示存储权限；不可丢失幂等记录后继续 |
| 401 / 会话过期 | 提示重新开始；不得换身份自动重放旧消息 |
| 403 / 入口或来源被拒绝 | 核对入口启用、公开 key、entryId 与来源限制 |
| 429 | 按错误 retryAfter 退避，保留待核对请求 |
| 网络断开但 pending 仍存在 | refresh() 读取对账；用户确认后 retryPending 使用原请求 |
| 验证码 / 真人验证要求 | 无 UI SDK 没有验证码界面，转现有完整网页处理 |

### 重试步骤

1. 向用户显示“结果待核对”，不要直接宣布失败或成功。
2. refresh() 读取会话；按消息 ID 与待核对状态确认是否已收到并处理。
3. 需要重试时调用 retryPending(action)，沿用原请求标识；不要另一次 sendText 重发同一请求。
4. 用户明确放弃本地重试时 discardPending(action)；说明这不会撤销服务端已收到的工作。

继续阅读：[消息、人工转接与历史](#messages) · [生命周期与账号切换](#account-switch) · [幂等、版本与错误处理](#server-errors)

实现依据（仓库内路径）：`sdk/wechat-miniapp/index.js`、`sdk/wechat-miniapp/index.d.ts`

<a id="troubleshooting"></a>

## 接入常见问题

按配置、网络、身份和业务回执逐层定位。

### 问题与检查

| 问题 | 先检查 |
| --- | --- |
| 只有页面，没有回复 | 入口是否启用，智能体是否发布、资源是否可用，实际请求是否被接受 |
| Web SDK 提示不同源 | 必须相同 HTTPS origin；异域站点改用生成的 widget / iframe |
| 小程序开发工具可用，手机不可用 | 正式 request / upload / download 域名、证书、基础库、实际 wx API |
| App 页面被拒绝 | 专用渠道是否适合无 Referer；不要删除原网站白名单或伪造头 |
| 切账号仍看到旧聊天 | 旧实例是否 forgetSession + destroy，原生页面是否销毁，scope 是否更新 |
| “转人工”后仍在等待 | 人工组、服务时间、在线客服和实际接管状态；请求入队不是接管完成 |
| 附件不能预览 | 服务端类型/大小、访客范围、宿主文件能力；不泄露令牌给外部 URL |
| 扫码授权 / 推送 / openid 不可用 | 检查该端能力表，不把供应商功能当作云蝠已实现功能 |

### 提交诊断材料

提供平台及版本、入口 ID、复现时间、脱敏错误码 / 请求 ID、实际步骤和预期结果。不要发送 API Key、AppSecret、访客令牌或客户完整敏感信息。

继续阅读：[SDK 错误与待核对请求](#sdk-errors) · [联调与上线验收清单](#acceptance) · [能力与交付状态](#capabilities)

实现依据（仓库内路径）：`sdk/client-kit/README.md`、`sdk/wechat-miniapp/README.md`

<a id="acceptance"></a>

## 联调与上线验收清单

每个入口、平台和业务流程分别留存结果。

### 验收项目

1. 基础：点击前无连接；合法 HTTPS、入口启用、智能体已发布；发送与真实 AI 回答成功。
2. 人工：真实入队、接管、人工回复到达，AI 外发停止；无人在线与超时保持正确状态。
3. 可靠性：断网、未知响应、原请求重试、重复事件、前后台恢复和关闭后的迟到响应。
4. 隔离：A 账号退出后 B 看不到 A 的历史；不同企业、入口、设备共享场景独立核验。
5. 扩展：附件、历史分页、公开知识、留资同意、评价与记忆控制；未支持项明确标未实现。
6. 业务：读取持久回执再确认工单/预约等结果；模型调用成功、消息被接受和业务解决分开记录。
7. 设备：宿主编译、真机键盘、安全区、返回、文件取消、权限拒绝；每端记录版本与截图。

### 发布与回滚

使用现有构建和发布流程。源码示例、隔离测试、复制接入代码不能替代生产发布；应用代码与数据库、上传和审计独立管理。上线后仍需以真实服务记录验证接待结果。

继续阅读：[快速入门：完成第一次接待](#first-conversation) · [接入常见问题](#troubleshooting) · [下载与更新记录](#downloads)

实现依据（仓库内路径）：`sdk/client-kit/README.md`、`sdk/wechat-miniapp/README.md`

<a id="downloads"></a>

## 下载与更新记录

固定下载地址随应用发布更新；源码版本和真实接入状态分开核对。

### 下载接入包

- [下载 Web 客户端与示例](/downloads/yunfu-web-integration-kit.zip) · [校验清单](/downloads/yunfu-web-integration-kit.json)：含原版渠道 iframe 示例及无 UI 客户端。复用完整渠道外观请选择 web/voice-example.html 或渠道嵌入代码；无 UI 客户端需自行绘制界面。
- [下载 iOS 源码示例](/downloads/yunfu-ios-integration-kit.zip) · [校验清单](/downloads/yunfu-ios-integration-kit.json)：WKWebView Swift 容器示例，加入现有 Xcode 工程编译；不含预编译 framework。
- [下载 Android 源码示例](/downloads/yunfu-android-integration-kit.zip) · [校验清单](/downloads/yunfu-android-integration-kit.json)：WebView Kotlin 容器和 Manifest 合并片段，需宿主工程编译；不含 AAR。
- [下载鸿蒙源码示例](/downloads/yunfu-harmony-integration-kit.zip) · [校验清单](/downloads/yunfu-harmony-integration-kit.json)：ArkWeb API 12+ 页面和权限片段，需 DevEco 宿主工程编译；不含 HAR。
- [下载 Uniapp 源码示例](/downloads/yunfu-uniapp-integration-kit.zip) · [校验清单](/downloads/yunfu-uniapp-integration-kit.json)：App-vue 容器与 Vue2 / Vue3 的 H5、微信示例默认加载当前原版渠道。原生文本为替代方案，按目标配置并完成真机验收。
- [下载小程序 SDK 源码与示例](/downloads/yunfu-wechat-miniapp-sdk.zip) · [校验清单](/downloads/yunfu-wechat-miniapp-sdk.json)：默认 web-view 复用原版渠道页面，需业务域名；另含原生聊天与语音替代组件，按各自能力与权限完成真机验收。

### 下载接入包

- [客户端合集接入包](/downloads/yunfu-client-integration-kit.zip) · [校验清单](/downloads/yunfu-client-integration-kit.json)：Web 客户端和 iOS、Android、鸿蒙、Uniapp 宿主源码示例。

### 下载包内容

客户端包包含 Web ESM 与声明、iOS / Android / Harmony / Uniapp 宿主示例和 README。小程序包包含原生组件、客户端 API、类型声明与示例骨架。下载链接在文档页顶部；文件清单和摘要随固定包的 JSON 元数据提供。

### 本地源码更新记录

| 日期 | 变更 | 边界 |
| --- | --- | --- |
| 2026-10-19 | 补齐客户端前台语音接入、原生小程序 RTC、渠道外观与官方原始接入文档 | 本地源码与固定接入包已更新；宿主编译、真实音频和生产发布分别验收 |
| 2026-10-17 | 按平台整理快速入门、生命周期、API、排错及离线文档 | 文档内容对应本地源码；不表示生产已发布 |
| 2026-10-17 | Web 无 UI 客户端与四端容器源码接入包 | 原生宿主编译、真机和生产收发待各端验收 |
| 2026-10-17 | 小程序原生源码组件及既有访客服务衔接 | 当时不包含实时语音；当前可选 RTC 组件见小程序指南，可信微信身份仍未接入 |

### 升级建议

先核对自己下载包的清单和对应文档；在测试入口更新，复验账号隔离、待核对请求和附件。保留宿主已有签名、路由、权限与业务配置，不整套覆盖宿主工程。接口完整字段仍以当前接口文档为准。

### 官方原始接入文档

先按云蝠指南完成入口、智能体和服务配置，再按下列官方原文配置宿主权限或供应商资源。外部文档说明对应平台能力，不代表云蝠已开放其中全部接口；腾讯 SecretKey、签名密钥和管理 API Key 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。

- [OpenAPI Initiative · OpenAPI Specification 3.1.0](https://spec.openapis.org/oas/v3.1.0)：理解本站 OpenAPI 文件的 schema、安全方案与导入格式；实际云蝠接口、字段和权限仍以本站接口参考为准。

继续阅读：[能力与交付状态](#capabilities) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`scripts/client-sdk-package.mjs`、`scripts/miniapp-sdk-package.mjs`

<a id="ios-install"></a>

## iOS：快速接入

WKWebView 源码示例，需加入自己的宿主工程编译。

### 下载接入包

- [下载 iOS 源码示例](/downloads/yunfu-ios-integration-kit.zip) · [校验清单](/downloads/yunfu-ios-integration-kit.json)：WKWebView Swift 容器示例，加入现有 Xcode 工程编译；不含预编译 framework。

### 开始前准备

1. 在“渠道 → 自建渠道 → 服务入口”创建专用 Web 入口，启用入口并绑定已发布智能体。需要渠道管理权限；没有入口时请企业管理员协助。
2. 将 Swift 文件加入最低 iOS 15 的现有 Xcode 工程，合并 Info.plist.fragment.xml 中的麦克风用途说明，使用宿主自己的签名和 Bundle ID。没有预编译 framework 或 CocoaPods 包。

### 从哪里取得入口参数

| 参数 | 填写内容 | 获取位置 |
| --- | --- | --- |
| origin | 部署客服的公网 HTTPS 主机，不带 /support、路径或查询参数 | 从“服务入口 → 皮肤与代码”的入口链接提取协议和主机 |
| key / publicKey | 同一入口的公开 UUID key | 从该入口生成的链接或代码复制 key；Android 字段名为 publicKey |
| entryId | 同一入口的 ID | 从该入口生成的链接或代码复制 entryId，不填写智能体 ID |

### 客户端只填公开参数

管理 API Key、AppSecret 和登录 token 不得放入 App 源码或入口链接。公开 key 不是管理授权；本地会话编号也不代表可信会员身份。

- [入口参数与访客身份详解](#credentials)

### 安装与配置

1. 下载本页客户端接入包，将 ios/YunfuSupportViewController.swift 及准备要求中的配套文件合并到宿主工程，不覆盖原有业务配置。
2. 填入 HTTPS origin、公开 key（UUID）和 entryId；在用户点击客服后创建并 present 控制器。使用非持久化 WKWebsiteDataStore，不添加 ATS 明文例外。

### 宿主接入示例

使用位置：`ios/usage.swift` · 宿主调用文件 · 接入包 0.3.15

运行前：
- iOS15+ target 同时加入 YunfuSupportViewController.swift 和麦克风用途说明。
- 由宿主配置产生 HTTPS URL、公开 UUID key 和 entryId，保留函数返回的控制器。

```swift
import UIKit

// Add YunfuSupportViewController.swift and microphone Info.plist settings to this same target.
@available(iOS 15.0, *)
@MainActor
func openYunfuSupport(from host: UIViewController, origin: URL,
                      publicKey: UUID, entryId: String) -> YunfuSupportViewController {
    let support = YunfuSupportViewController(origin: origin, publicKey: publicKey, entryId: entryId)
    host.present(support, animated: true)
    return support // Retain it; call closeForAccountChange() before logout/account switch.
}
// Call from the customer's support button, using validated public entry values.
// Starting the page does not start recording. The customer starts voice inside the channel UI.
```

预期结果：从客服按钮调用 openYunfuSupport；退出账号前调用控制器 closeForAccountChange。需 Xcode 编译与真机验收。

### 实际接待范围

容器承载现有 /support 页面：当前读取最近 100 条消息，尚未接线显式转人工按钮与更早历史翻页。人工接待沿服务端路由进入。页面能打开不代表宿主、文件与真实接待已验收。

### 本平台能力边界

用户开始语音后，仅对当前入口主框架的可信 HTTPS 麦克风请求显示授权；摄像头拒绝。使用渠道现有 Web 语音链路，需同步更新 /support；没有 APNs、后台通话、CallKit 或附件原生保存桥。

### 怎样确认接入成功

1. 从自己的 App 入口发送一条带唯一标记的测试问题，确认收到回复，并在接待台找到同一企业、入口和会话。仅页面打开或编译成功不能代替这一步。
2. 真机验收首次允许/拒绝录音、AI 出声与打断、挂断释放、后台/锁屏/电话中断、耳机、账号切换、安全区、键盘和文件选择。
3. 退出 A 账号后用 B 账号重新进入，确认 B 看不到 A 的内容；挂断或离开页面后确认录音指示消失。

### 没有成功时先检查

| 现象 | 下一步 |
| --- | --- |
| 页面打不开 / 连接被拒绝 | 先核对 HTTPS 证书、origin 与同一入口的 key / entryId，再检查入口是否启用及来源限制；不要关闭安全校验绕过问题。 |
| 页面打开但没有回复 | 检查入口接待方案是否绑定已发布智能体、模型是否可用；在接待台按测试标记查找会话，确认是否已转人工。 |
| 文字可用，但无法语音 | 检查企业和入口是否开启语音、系统录音权限与网页授权是否都满足；由用户主动点击开始，分别确认实际收音、AI 出声和挂断释放。 |

### 继续接入与配置

- [生命周期、权限与排错](#ios-lifecycle)
- [入口参数与访客身份](#credentials)
- [当前平台能力与限制](#capabilities)
- [上线验收清单](#acceptance)

### 官方原始接入文档

先按云蝠指南完成入口、智能体和服务配置，再按下列官方原文配置宿主权限或供应商资源。外部文档说明对应平台能力，不代表云蝠已开放其中全部接口；腾讯 SecretKey、签名密钥和管理 API Key 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。

- [Apple · NSMicrophoneUsageDescription](https://developer.apple.com/documentation/bundleresources/information-property-list/nsmicrophoneusagedescription)：将真实录音用途写入宿主 Info.plist；只复制 Swift 容器不足以完成权限接入。
- [Apple · WKUIDelegate 媒体采集权限](https://developer.apple.com/documentation/webkit/wkuidelegate/webview%28_%3Arequestmediacapturepermissionfor%3Ainitiatedbyframe%3Atype%3Adecisionhandler%3A%29)：按可信 origin、frame 与媒体类型处理网页请求；系统录音权限和网页媒体授权需要分别处理。

继续阅读：[iOS：生命周期、权限与排错](#ios-lifecycle) · [能力与交付状态](#capabilities) · [网站 / H5 嵌入](#web-embed)

实现依据（仓库内路径）：`sdk/client-kit/ios/YunfuSupportViewController.swift`、`sdk/client-kit/README.md`

<a id="ios-lifecycle"></a>

## iOS：生命周期、权限与排错

核对账号切换、权限拒绝和容器能力。

### 下载接入包

- [下载 iOS 源码示例](/downloads/yunfu-ios-integration-kit.zip) · [校验清单](/downloads/yunfu-ios-integration-kit.json)：WKWebView Swift 容器示例，加入现有 Xcode 工程编译；不含预编译 framework。

### 生命周期

复用当前页面；进入后台、离开页面或音频中断时停止语音与麦克风，返回后由用户重新开始。退出登录先 closeForAccountChange()，再从导航栈移除；临时网页数据不承诺关闭后的历史续接。

### 权限与功能边界

用户开始语音后，仅对当前入口主框架的可信 HTTPS 麦克风请求显示授权；摄像头拒绝。使用渠道现有 Web 语音链路，需同步更新 /support；没有 APNs、后台通话、CallKit 或附件原生保存桥。

### 连接被拒绝时

核对 HTTPS、key、entryId 与入口启用状态；网站渠道的 Referer 限制可能不适用于原生容器。为 App 创建专用入口评估策略，不伪造来源、不关闭旧网站的来源限制。

### 最小回归

1. 真机验收首次允许/拒绝录音、AI 出声与打断、挂断释放、后台/锁屏/电话中断、耳机、账号切换、安全区、键盘和文件选择。
2. A 账号聊天后退出，B 看不到 A 的历史；关闭后旧回调不再触发。
3. 接收真实 AI 与人工回复；网络未知时保留待核对，不自动重复提交。

### 官方原始接入文档

先按云蝠指南完成入口、智能体和服务配置，再按下列官方原文配置宿主权限或供应商资源。外部文档说明对应平台能力，不代表云蝠已开放其中全部接口；腾讯 SecretKey、签名密钥和管理 API Key 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。

- [Apple · NSMicrophoneUsageDescription](https://developer.apple.com/documentation/bundleresources/information-property-list/nsmicrophoneusagedescription)：将真实录音用途写入宿主 Info.plist；只复制 Swift 容器不足以完成权限接入。
- [Apple · WKUIDelegate 媒体采集权限](https://developer.apple.com/documentation/webkit/wkuidelegate/webview%28_%3Arequestmediacapturepermissionfor%3Ainitiatedbyframe%3Atype%3Adecisionhandler%3A%29)：按可信 origin、frame 与媒体类型处理网页请求；系统录音权限和网页媒体授权需要分别处理。

继续阅读：[iOS：快速接入](#ios-install) · [生命周期与账号切换](#account-switch) · [SDK 错误与待核对请求](#sdk-errors)

实现依据（仓库内路径）：`sdk/client-kit/ios/YunfuSupportViewController.swift`、`sdk/client-kit/README.md`

<a id="android-install"></a>

## Android：快速接入

WebView 源码示例，需加入自己的宿主工程编译。

### 下载接入包

- [下载 Android 源码示例](/downloads/yunfu-android-integration-kit.zip) · [校验清单](/downloads/yunfu-android-integration-kit.json)：WebView Kotlin 容器和 Manifest 合并片段，需宿主工程编译；不含 AAR。

### 开始前准备

1. 在“渠道 → 自建渠道 → 服务入口”创建专用 Web 入口，启用入口并绑定已发布智能体。需要渠道管理权限；没有入口时请企业管理员协助。
2. 将 Kotlin 文件加入最低 API 23 的现有 Android 工程，修改包名并合并 Manifest 片段。使用更新版支持 WebRTC/AudioWorklet 的 System WebView；不是已发行 AAR 或 Maven 依赖。

### 从哪里取得入口参数

| 参数 | 填写内容 | 获取位置 |
| --- | --- | --- |
| origin | 部署客服的公网 HTTPS 主机，不带 /support、路径或查询参数 | 从“服务入口 → 皮肤与代码”的入口链接提取协议和主机 |
| key / publicKey | 同一入口的公开 UUID key | 从该入口生成的链接或代码复制 key；Android 字段名为 publicKey |
| entryId | 同一入口的 ID | 从该入口生成的链接或代码复制 entryId，不填写智能体 ID |

### 客户端只填公开参数

管理 API Key、AppSecret 和登录 token 不得放入 App 源码或入口链接。公开 key 不是管理授权；本地会话编号也不代表可信会员身份。

- [入口参数与访客身份详解](#credentials)

### 安装与配置

1. 下载本页客户端接入包，将 android/YunfuSupportActivity.kt 及准备要求中的配套文件合并到宿主工程，不覆盖原有业务配置。
2. 替换 origin、publicKey、entryId；合并 INTERNET、RECORD_AUDIO、MODIFY_AUDIO_SETTINGS 和 exported=false 的 Activity。只在用户点击后启动，保留 HTTPS 与 SSL 默认拒绝行为。

### 宿主接入示例

使用位置：`android/usage.kt` · 宿主调用文件 · 接入包 0.3.15

运行前：
- 修改示例 Activity 的公开参数，合并 Manifest，并将 package 改为宿主实际包名。

```kotlin
package your.app.support

import android.app.Activity
import android.content.Intent
import android.os.Build

// Configure the three public entry constants in YunfuSupportActivity and merge the Manifest.
fun openYunfuSupport(host: Activity) {
    require(Build.VERSION.SDK_INT >= Build.VERSION_CODES.M)
    host.startActivity(Intent(host, YunfuSupportActivity::class.java))
}
// Call from a support button, never from Application startup.
// The account-switch flow must close all hosted support Activities before replacing the account.
```

预期结果：按钮进入可信客服页；开始语音才申请录音。账号切换须关闭旧 Activity，仍需 Android 工程编译。

### 实际接待范围

容器承载现有 /support 页面：当前读取最近 100 条消息，尚未接线显式转人工按钮与更早历史翻页。人工接待沿服务端路由进入。页面能打开不代表宿主、文件与真实接待已验收。

### 本平台能力边界

开始语音时申请系统录音权限，仅向当前可信来源授予 AUDIO_CAPTURE，拒绝摄像头和未知资源。使用渠道 Web 语音，需同步更新 /support。无后台通话、ConnectionService、厂商推送或附件原生保存桥。

### 怎样确认接入成功

1. 从自己的 App 入口发送一条带唯一标记的测试问题，确认收到回复，并在接待台找到同一企业、入口和会话。仅页面打开或编译成功不能代替这一步。
2. 真机验收允许/拒绝录音、授权中退出、AI 出声与打断、挂断释放、前后台/锁屏/电话中断、耳机、弱网、旋转和账号切换。
3. 退出 A 账号后用 B 账号重新进入，确认 B 看不到 A 的内容；挂断或离开页面后确认录音指示消失。

### 没有成功时先检查

| 现象 | 下一步 |
| --- | --- |
| 页面打不开 / 连接被拒绝 | 先核对 HTTPS 证书、origin 与同一入口的 key / entryId，再检查入口是否启用及来源限制；不要关闭安全校验绕过问题。 |
| 页面打开但没有回复 | 检查入口接待方案是否绑定已发布智能体、模型是否可用；在接待台按测试标记查找会话，确认是否已转人工。 |
| 文字可用，但无法语音 | 检查企业和入口是否开启语音、系统录音权限与网页授权是否都满足；由用户主动点击开始，分别确认实际收音、AI 出声和挂断释放。 |

### 继续接入与配置

- [生命周期、权限与排错](#android-lifecycle)
- [入口参数与访客身份](#credentials)
- [当前平台能力与限制](#capabilities)
- [上线验收清单](#acceptance)

### 官方原始接入文档

先按云蝠指南完成入口、智能体和服务配置，再按下列官方原文配置宿主权限或供应商资源。外部文档说明对应平台能力，不代表云蝠已开放其中全部接口；腾讯 SecretKey、签名密钥和管理 API Key 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。

- [Android Developers · 请求运行时权限](https://developer.android.com/training/permissions/requesting)：声明并请求 RECORD_AUDIO；处理拒绝、永久拒绝及恢复，不把权限请求回调当作全部获准。
- [Android Developers · WebView PermissionRequest](https://developer.android.com/reference/android/webkit/PermissionRequest)：在 UI 线程仅授予当前可信来源的音频资源，处理取消请求；不直接 grant(getResources()) 放行未知媒体权限。

继续阅读：[Android：生命周期、权限与排错](#android-lifecycle) · [能力与交付状态](#capabilities) · [网站 / H5 嵌入](#web-embed)

实现依据（仓库内路径）：`sdk/client-kit/android/YunfuSupportActivity.kt`、`sdk/client-kit/README.md`

<a id="android-lifecycle"></a>

## Android：生命周期、权限与排错

核对账号切换、权限拒绝和容器能力。

### 下载接入包

- [下载 Android 源码示例](/downloads/yunfu-android-integration-kit.zip) · [校验清单](/downloads/yunfu-android-integration-kit.json)：WebView Kotlin 容器和 Manifest 合并片段，需宿主工程编译；不含 AAR。

### 生命周期

切后台取消待授权请求并挂断，回前台保留文字、不自动开麦。退出登录先 finish 所有客服 Activity，再更换宿主账号；不恢复旧账号的 WebView、回调或 savedInstanceState。

### 权限与功能边界

开始语音时申请系统录音权限，仅向当前可信来源授予 AUDIO_CAPTURE，拒绝摄像头和未知资源。使用渠道 Web 语音，需同步更新 /support。无后台通话、ConnectionService、厂商推送或附件原生保存桥。

### 连接被拒绝时

核对 HTTPS、key、entryId 与入口启用状态；网站渠道的 Referer 限制可能不适用于原生容器。为 App 创建专用入口评估策略，不伪造来源、不关闭旧网站的来源限制。

### 最小回归

1. 真机验收允许/拒绝录音、授权中退出、AI 出声与打断、挂断释放、前后台/锁屏/电话中断、耳机、弱网、旋转和账号切换。
2. A 账号聊天后退出，B 看不到 A 的历史；关闭后旧回调不再触发。
3. 接收真实 AI 与人工回复；网络未知时保留待核对，不自动重复提交。

### 官方原始接入文档

先按云蝠指南完成入口、智能体和服务配置，再按下列官方原文配置宿主权限或供应商资源。外部文档说明对应平台能力，不代表云蝠已开放其中全部接口；腾讯 SecretKey、签名密钥和管理 API Key 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。

- [Android Developers · 请求运行时权限](https://developer.android.com/training/permissions/requesting)：声明并请求 RECORD_AUDIO；处理拒绝、永久拒绝及恢复，不把权限请求回调当作全部获准。
- [Android Developers · WebView PermissionRequest](https://developer.android.com/reference/android/webkit/PermissionRequest)：在 UI 线程仅授予当前可信来源的音频资源，处理取消请求；不直接 grant(getResources()) 放行未知媒体权限。

继续阅读：[Android：快速接入](#android-install) · [生命周期与账号切换](#account-switch) · [SDK 错误与待核对请求](#sdk-errors)

实现依据（仓库内路径）：`sdk/client-kit/android/YunfuSupportActivity.kt`、`sdk/client-kit/README.md`

<a id="harmony-install"></a>

## Harmony 鸿蒙：快速接入

ArkWeb 源码示例，需加入自己的宿主工程编译。

### 下载接入包

- [下载鸿蒙源码示例](/downloads/yunfu-harmony-integration-kit.zip) · [校验清单](/downloads/yunfu-harmony-integration-kit.json)：ArkWeb API 12+ 页面和权限片段，需 DevEco 宿主工程编译；不含 HAR。

### 开始前准备

1. 在“渠道 → 自建渠道 → 服务入口”创建专用 Web 入口，启用入口并绑定已发布智能体。需要渠道管理权限；没有入口时请企业管理员协助。
2. 使用 DevEco / ArkWeb API12+ 工程，复制页面与 voice-permission-policy.ts；合并 INTERNET、MICROPHONE 及字符串资源片段，将 Ability 名改为宿主实际值。尚未发行 HAR。

### 从哪里取得入口参数

| 参数 | 填写内容 | 获取位置 |
| --- | --- | --- |
| origin | 部署客服的公网 HTTPS 主机，不带 /support、路径或查询参数 | 从“服务入口 → 皮肤与代码”的入口链接提取协议和主机 |
| key / publicKey | 同一入口的公开 UUID key | 从该入口生成的链接或代码复制 key；Android 字段名为 publicKey |
| entryId | 同一入口的 ID | 从该入口生成的链接或代码复制 entryId，不填写智能体 ID |

### 客户端只填公开参数

管理 API Key、AppSecret 和登录 token 不得放入 App 源码或入口链接。公开 key 不是管理授权；本地会话编号也不代表可信会员身份。

- [入口参数与访客身份详解](#credentials)

### 安装与配置

1. 下载本页客户端接入包，将 harmony/YunfuSupport.ets 及准备要求中的配套文件合并到宿主工程，不覆盖原有业务配置。
2. 替换 HTTPS origin、公开 key 和 entryId，在用户点击后进入页面。网页请求语音时核对当前入口与精确来源，再申请系统麦克风；只 grant AUDIO_CAPTURE。

### 宿主接入示例

使用位置：`harmony/YunfuSupport.ets` · ArkTS 页面文件 · 接入包 0.3.15

运行前：
- 同目录加入 voice-permission-policy.ts，合并权限和字符串片段。
- 替换真实 Ability 名和公开参数，在 DevEco 页面列表注册；本示例按 API12+ 编写。

```typescript
import { webview } from '@kit.ArkWeb';
import { util } from '@kit.ArkTS';
import { abilityAccessCtrl, common } from '@kit.AbilityKit';
import { HostedAudioPermission, AudioPermissionRequest } from './voice-permission-policy';

// Explicit adapter keeps ArkTS nominal class/interface compatibility.
class ArkWebAudioRequest implements AudioPermissionRequest {
  private value: PermissionRequest;
  constructor(value: PermissionRequest) { this.value = value; }
  getOrigin(): string { return this.value.getOrigin(); }
  getAccessibleResource(): string[] { return this.value.getAccessibleResource(); }
  grant(resources: string[]): void { this.value.grant(resources); }
  deny(): void { this.value.deny(); }
}

// ArkWeb API 12+ source example. Register this page in the host route table.
// A new page instance creates a new isolated visitor. Remove the page before account changes.
@Entry
@Component
struct YunfuSupport {
  private controller: webview.WebviewController = new webview.WebviewController();
  private attached: boolean = false;
  private clientSession: string = util.generateRandomUUID().toLowerCase();
  private origin: string = 'https://YOUR_CUSTOMER_SERVICE_ORIGIN';
  private key: string = 'YOUR_PUBLIC_KEY';
  private entryId: string = 'YOUR_ENTRY_ID';
  private audioPermission: HostedAudioPermission | undefined = undefined;
  @State private supportUrl: string = '';

  aboutToAppear(): void {
    if (!/^https:\/\/[a-z0-9.-]+(:[0-9]{1,5})?$/.test(this.origin) ||
        !/^[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(this.key) ||
        !/^[-a-zA-Z0-9_]{1,100}$/.test(this.entryId)) {
      throw new Error('Configure a published HTTPS support entry first');
    }
    this.supportUrl = this.origin + '/support?key=' + encodeURIComponent(this.key) +
      '&entryId=' + encodeURIComponent(this.entryId) + '&surface=channel&clientSession=' + this.clientSession;
    this.audioPermission = new HostedAudioPermission(this.origin, this.supportUrl,
      ProtectedResourceType.AUDIO_CAPTURE, async (): Promise<boolean> => {
        const context = getContext(this) as common.UIAbilityContext;
        const result = await abilityAccessCtrl.createAtManager().requestPermissionsFromUser(
          context, ['ohos.permission.MICROPHONE']);
        return result.authResults.length === 1 && result.authResults[0] === 0;
      });
  }
  private stopVoice(): void {
    if (this.attached) {
      this.controller.runJavaScript("window.dispatchEvent(new Event('yunfu:native-voice-stop'));")
        .catch(() => {});
    }
  }
  onPageHide(): void {
    this.audioPermission?.setForeground(false);
    this.stopVoice();
    if (this.attached) this.controller.onInactive();
  }
  onPageShow(): void {
    this.audioPermission?.setForeground(true);
    if (this.attached) this.controller.onActive();
    // Never reopen the microphone merely because the page became visible.
  }
  aboutToDisappear(): void {
    this.audioPermission?.dispose();
    this.stopVoice();
    if (this.attached) this.controller.stop();
    this.attached = false;
  }

  build() {
    Column() {
      if (this.supportUrl) {
        Web({ src: this.supportUrl, controller: this.controller })
          .onControllerAttached(() => { this.attached = true; })
          .javaScriptAccess(true)
          .domStorageAccess(true)
          .fileAccess(false)
          .mixedMode(MixedMode.None)
          .onPageBegin((event) => { this.audioPermission?.navigate(event?.url || ''); })
          .onOverrideUrlLoading((request: WebResourceRequest) => {
            return request.getRequestUrl() !== this.supportUrl;
          })
          .onLoadIntercept((event) => {
            return !event || event.data.getRequestUrl() !== this.supportUrl;
          })
          .onPermissionRequest((event) => {
            if (!event) return;
            if (!this.audioPermission) { event.request.deny(); return; }
            this.audioPermission.request(new ArkWebAudioRequest(event.request)).catch(() => {});
          })
          .width('100%')
          .height('100%')
      }
    }.width('100%').height('100%')
  }
}
```

预期结果：用户主动进入后显示渠道 UI；仅可信来源音频可申请授权，退出清理。完整原生编译和真机音频另行验收。

### 实际接待范围

容器承载现有 /support 页面：当前读取最近 100 条消息，尚未接线显式转人工按钮与更早历史翻页。人工接待沿服务端路由进入。页面能打开不代表宿主、文件与真实接待已验收。

### 本平台能力边界

提供前台网页语音授权流程，仍需 DevEco 编译和真机音频验收。API12 不使用 stopMicrophone；onInactive/停止加载不能代替停麦。文件选择、原生下载、后台通话和推送未接入。

### 怎样确认接入成功

1. 从自己的 App 入口发送一条带唯一标记的测试问题，确认收到回复，并在接待台找到同一企业、入口和会话。仅页面打开或编译成功不能代替这一步。
2. 验收实际允许/拒绝录音、授权中退出、AI 出声与打断、后台/锁屏释放、耳机、重拨及账号隔离。
3. 退出 A 账号后用 B 账号重新进入，确认 B 看不到 A 的内容；挂断或离开页面后确认录音指示消失。

### 没有成功时先检查

| 现象 | 下一步 |
| --- | --- |
| 页面打不开 / 连接被拒绝 | 先核对 HTTPS 证书、origin 与同一入口的 key / entryId，再检查入口是否启用及来源限制；不要关闭安全校验绕过问题。 |
| 页面打开但没有回复 | 检查入口接待方案是否绑定已发布智能体、模型是否可用；在接待台按测试标记查找会话，确认是否已转人工。 |
| 文字可用，但无法语音 | 检查企业和入口是否开启语音、系统录音权限与网页授权是否都满足；由用户主动点击开始，分别确认实际收音、AI 出声和挂断释放。 |

### 继续接入与配置

- [生命周期、权限与排错](#harmony-lifecycle)
- [入口参数与访客身份](#credentials)
- [当前平台能力与限制](#capabilities)
- [上线验收清单](#acceptance)

### 官方原始接入文档

先按云蝠指南完成入口、智能体和服务配置，再按下列官方原文配置宿主权限或供应商资源。外部文档说明对应平台能力，不代表云蝠已开放其中全部接口；腾讯 SecretKey、签名密钥和管理 API Key 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。

- [OpenHarmony · ArkWeb onPermissionRequest](https://github.com/openharmony/docs/blob/master/en/application-dev/reference/apis-arkweb/arkts-basic-components-web-events.md#onpermissionrequest9)：核对网页音频授权事件与 grant/deny；文档主干会更新，本包 API12+ 示例仍须用目标 SDK 编译并真机验收。
- [OpenHarmony · 声明应用权限 · 5.0 Release](https://github.com/openharmony/docs/blob/OpenHarmony-5.0.0-Release/zh-cn/application-dev/security/AccessToken/declare-permissions.md)：合并 MICROPHONE、用途字符串与实际 Ability 的 usedScene；清单声明不能代替运行时授权。

继续阅读：[Harmony 鸿蒙：生命周期、权限与排错](#harmony-lifecycle) · [能力与交付状态](#capabilities) · [网站 / H5 嵌入](#web-embed)

实现依据（仓库内路径）：`sdk/client-kit/harmony/YunfuSupport.ets`、`sdk/client-kit/README.md`

<a id="harmony-lifecycle"></a>

## Harmony 鸿蒙：生命周期、权限与排错

核对账号切换、权限拒绝和容器能力。

### 下载接入包

- [下载鸿蒙源码示例](/downloads/yunfu-harmony-integration-kit.zip) · [校验清单](/downloads/yunfu-harmony-integration-kit.json)：ArkWeb API 12+ 页面和权限片段，需 DevEco 宿主工程编译；不含 HAR。

### 生命周期

隐藏、导航和退出时作废待授权请求并停止网页语音；回前台不自动开麦。退出登录移除实例，重新进入生成随机 clientSession；该编号不认证会员。

### 权限与功能边界

提供前台网页语音授权流程，仍需 DevEco 编译和真机音频验收。API12 不使用 stopMicrophone；onInactive/停止加载不能代替停麦。文件选择、原生下载、后台通话和推送未接入。

### 连接被拒绝时

核对 HTTPS、key、entryId 与入口启用状态；网站渠道的 Referer 限制可能不适用于原生容器。为 App 创建专用入口评估策略，不伪造来源、不关闭旧网站的来源限制。

### 最小回归

1. 验收实际允许/拒绝录音、授权中退出、AI 出声与打断、后台/锁屏释放、耳机、重拨及账号隔离。
2. A 账号聊天后退出，B 看不到 A 的历史；关闭后旧回调不再触发。
3. 接收真实 AI 与人工回复；网络未知时保留待核对，不自动重复提交。

### 官方原始接入文档

先按云蝠指南完成入口、智能体和服务配置，再按下列官方原文配置宿主权限或供应商资源。外部文档说明对应平台能力，不代表云蝠已开放其中全部接口；腾讯 SecretKey、签名密钥和管理 API Key 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。

- [OpenHarmony · ArkWeb onPermissionRequest](https://github.com/openharmony/docs/blob/master/en/application-dev/reference/apis-arkweb/arkts-basic-components-web-events.md#onpermissionrequest9)：核对网页音频授权事件与 grant/deny；文档主干会更新，本包 API12+ 示例仍须用目标 SDK 编译并真机验收。
- [OpenHarmony · 声明应用权限 · 5.0 Release](https://github.com/openharmony/docs/blob/OpenHarmony-5.0.0-Release/zh-cn/application-dev/security/AccessToken/declare-permissions.md)：合并 MICROPHONE、用途字符串与实际 Ability 的 usedScene；清单声明不能代替运行时授权。

继续阅读：[Harmony 鸿蒙：快速接入](#harmony-install) · [生命周期与账号切换](#account-switch) · [SDK 错误与待核对请求](#sdk-errors)

实现依据（仓库内路径）：`sdk/client-kit/harmony/YunfuSupport.ets`、`sdk/client-kit/README.md`

<a id="uniapp-install"></a>

## Uniapp：快速接入

App-vue 网页容器 源码示例，需加入自己的宿主工程编译。

### 下载接入包

- [下载 Uniapp 源码示例](/downloads/yunfu-uniapp-integration-kit.zip) · [校验清单](/downloads/yunfu-uniapp-integration-kit.json)：App-vue 容器与 Vue2 / Vue3 的 H5、微信示例默认加载当前原版渠道。原生文本为替代方案，按目标配置并完成真机验收。

### 先选择编译目标，再下载示例

| 目标 | 接入方案 | 开始位置与验收边界 |
| --- | --- | --- |
| App-vue · Android / iOS | 本页 uniapp/ HTML5+ 容器，加载现有 /support 聊天与前台语音 | 按下方步骤合并到宿主工程；需 HBuilderX、自定义基座和真机验收 |
| H5 · Vue 2 / Vue 3 | uniapp-text/ 默认原版渠道页面，与 JS 嵌入共用渲染 | 打开 Uni-app 微信小程序 / H5 指南；HTTPS 宿主与入口来源许可，不调用 plus |
| MP-WEIXIN · Vue 2 / Vue 3 | uniapp-text/ 默认 web-view 原版渠道；显式 native 为原生文本替代 | 配置 AppID 与业务域名，编译后以体验版真机验收；request 域名不能替代业务域名 |
| nvue / uni-app x / App-Harmony | 当前 App-vue 容器和 H5 / 微信文本构建未覆盖 | 不要直接套用本页源码；需按目标宿主另行适配和验收 |

### 开始前准备

1. 在“渠道 → 自建渠道 → 服务入口”创建专用 Web 入口，启用入口并绑定已发布智能体。需要渠道管理权限；没有入口时请企业管理员协助。
2. 仅 App-vue：将 support.vue 改名为 pages/support/index.vue，config.js、usage.js、support-session.js、voice-access.js 放同目录；合并 pages.fragment.json 与 manifest.fragment.json，不覆盖宿主文件。H5 / 微信文本接入见“Uni-app：微信小程序与 H5 文本客服”，本页容器不用于这两个目标。

### 从哪里取得入口参数

| 参数 | 填写内容 | 获取位置 |
| --- | --- | --- |
| origin | 部署客服的公网 HTTPS 主机，不带 /support、路径或查询参数 | 从“服务入口 → 皮肤与代码”的入口链接提取协议和主机 |
| key / publicKey | 同一入口的公开 UUID key | 从该入口生成的链接或代码复制 key；Android 字段名为 publicKey |
| entryId | 同一入口的 ID | 从该入口生成的链接或代码复制 entryId，不填写智能体 ID |

### 客户端只填公开参数

管理 API Key、AppSecret 和登录 token 不得放入 App 源码或入口链接。公开 key 不是管理授权；本地会话编号也不代表可信会员身份。

- [入口参数与访客身份详解](#credentials)

### 安装与配置

1. 下载本页客户端接入包，将 uniapp/support.vue 及准备要求中的配套文件合并到宿主工程，不覆盖原有业务配置。
2. 填写 config.js 的 origin、key、entryId，宿主登录且完成隐私流程后调用 prepareSupportAccount(随机 UUID)。用户点击时 await openSupport() 或 openSupport(true)，捕获错误；先检查入口是否开启语音，再处理 Android 系统权限。iOS 保留网页 WebKit 提示。需指定自定义基座验收。

### 第一步：填写公开配置

使用位置：`pages/support/config.js` · 配置文件 · 接入包 0.3.15

运行前：
- 替换 HTTPS origin、公开 key、entryId；不放 AppSecret 或管理密钥。

```javascript
// Only public channel values. Never place an API secret, AppSecret or account token here.
export const supportConfig = {
  origin: 'https://YOUR_CUSTOMER_SERVICE_ORIGIN',
  key: 'YOUR_PUBLIC_KEY',
  entryId: 'YOUR_ENTRY_ID',
};
export const supportRoute = '/pages/support/index';
export function readSupportConfig() {
  const { origin, key, entryId } = supportConfig;
  if (typeof origin !== 'string' || !/^https:\/\/[a-z0-9.-]+(:[0-9]{1,5})?$/.test(origin) ||
      !/^[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(key || '') ||
      !/^[-a-zA-Z0-9_]{1,100}$/.test(entryId || '') || entryId === 'YOUR_ENTRY_ID')
    throw Error('CONFIGURE_ENTRY_FIRST');
  return { origin, key, entryId };
}
```

预期结果：打开前验证配置，配置错误显示可定位的说明。

### 第二步：合并页面路由

使用位置：`pages.json（合并片段）` · 路由片段 · 接入包 0.3.15

运行前：
- 把 support.vue 重命名为 pages/support/index.vue；所有 helper 放在同目录。
- 仅合并 pages 数组中的新页面，不覆盖宿主 pages.json。

```json
{
  "pages": [
    {
      "path": "pages/support/index",
      "style": {
        "navigationBarTitleText": "在线客服",
        "enablePullDownRefresh": false
      }
    }
  ]
}
```

预期结果：保留原生导航栏和返回入口；禁用无意义的下拉刷新。

### 第三步：合并宿主权限并重新制作基座

| 位置 | 需要合并的内容 | 核对方法 |
| --- | --- | --- |
| manifest.json → app-plus.distribute.android.permissions | 合并 manifest.fragment.json 的 INTERNET、RECORD_AUDIO、MODIFY_AUDIO_SETTINGS；保留原有权限 | 重新制作包含这些配置的自定义基座；真机首次开始语音时检查系统录音提示 |
| manifest.json → app-plus.distribute.ios.privacyDescription | 填写 NSMicrophoneUsageDescription，说明用户主动语音咨询的用途 | 使用更新后的基座；网页点击开始后检查 WebKit / getUserMedia 提示和实际收音 |
| 远端客服页与宿主 | 保留 plusrequire:none、固定 HTTPS 地址和原生返回入口；渠道及企业须开启语音 | 系统权限只是一层：还要分别验证网页授权、用户开始、AI 出声和挂断停麦 |

### 第四步：接入业务按钮

1. 宿主完成登录与隐私同意后提供随机 UUID；不要使用手机号、会员 ID 或 token。仅隔离本地会话，不代表可信会员认证。
2. 从 pages/support/usage.js 导入 prepareSupportAccount、openSupport、beforeLogout；用户点击客服时 await openSupport(false)。传 true 会在页面加载前核对语音入口和 Android 系统权限，之后仍由用户在网页点击开始，不自动拨号。
3. 调用端用 try/catch 展示失败说明；Promise 成功仅表示页面导航成功，接待、AI 回复、语音收音需在页面内分别确认。
4. 登出前调用 beforeLogout() 关闭旧客服内容，并为下次登录创建新 UUID。旧客服页在栈顶时下次打开会替换它；若其上还有宿主页面，旧页失效并保留到正常返回。不要清理宿主全局存储。

### 宿主接入示例

使用位置：`uniapp/usage.js` · 模块文件 · 接入包 0.3.15

运行前：
- 仅 App-vue：复制 support.vue、config、usage、session/voice helper，合并 manifest 和 pages 片段。
- 宿主登录后先提供新的随机 UUID；不要在 App 启动时自动调用 openSupport。

```javascript
import { setSupportSession, clearSupportSession, readSupportSession, onSupportSessionEnd } from './support-session.js';
import { readSupportConfig, supportRoute } from './config.js';
let opening = null;

// Call after host login/privacy consent. Reuse this random UUID until logout/account switch.
// This isolates local history; it does not authenticate a business member.
export function prepareSupportAccount(opaqueRandomUuid) {
  setSupportSession(opaqueRandomUuid);
}
// await from a click handler and catch errors. Importing this module makes no requests.
export function openSupport(voice = false) {
  try {
    if (typeof plus === 'undefined') throw Error('APP_VUE_REQUIRED');
    readSupportConfig();
    const scope = readSupportSession();
    if (opening) return opening.promise;
    const pages = getCurrentPages();
    const supportPages = pages.filter(page => '/' + page.route === supportRoute);
    const isClosed = page => (page.$vm || page).disposed === true;
    if (supportPages.some(page => !isClosed(page)))
      throw Error('SUPPORT_ALREADY_OPEN'); // Do not pop an unrelated page above support.
    // Replace a closed support page only when it is on top; never remove other host pages.
    const replaceClosedTop = supportPages.length && pages[pages.length - 1] === supportPages[supportPages.length - 1];
    const request = { promise: null };
    opening = request;
    request.promise = new Promise((resolve, reject) => {
      let settled = false;
      let unsubscribe = () => {};
      const finish = error => {
        if (settled) return;
        settled = true; unsubscribe();
        if (opening === request) opening = null;
        if (error) reject(Error(error)); else resolve();
      };
      unsubscribe = onSupportSessionEnd(() => finish('SUPPORT_SESSION_CHANGED'));
      try {
        uni[replaceClosedTop ? 'redirectTo' : 'navigateTo']({
          url: supportRoute + '?session=' + encodeURIComponent(scope) + (voice ? '&voice=1' : ''),
          success() {
            try {
              if (readSupportSession() !== scope) throw Error('SUPPORT_SESSION_CHANGED');
              finish(); // Navigation only; not a connection or voice-success receipt.
            } catch { finish('SUPPORT_SESSION_CHANGED'); }
          },
          fail() { finish('SUPPORT_NAVIGATION_FAILED'); },
        });
      } catch { finish('SUPPORT_NAVIGATION_FAILED'); }
    });
    return request.promise;
  } catch (error) { return Promise.reject(error); }
}
export function beforeLogout() {
  clearSupportSession(); // Close old content without navigating away from an unrelated page.
}
```

预期结果：点击时 await openSupport(true) 并捕获错误；重复打开去重，后台不重拨，退出前 beforeLogout。WebView 媒体仍须指定基座验收。

### 实际接待范围

容器承载现有 /support 页面：当前读取最近 100 条消息，尚未接线显式转人工按钮与更早历史翻页。人工接待沿服务端路由进入。页面能打开不代表宿主、文件与真实接待已验收。

### 本平台能力边界

保持 plusrequire:none 与固定导航。DCloud 公共 API 不提供逐来源媒体授权 hook；系统权限不等于 WebView 授权成功。不能使用 App 不支持的 uni.authorize(scope.record)。失败保留文字，必要时接宿主原生插件。

### 怎样确认接入成功

1. 从自己的 App 入口发送一条带唯一标记的测试问题，确认收到回复，并在接待台找到同一企业、入口和会话。仅页面打开或编译成功不能代替这一步。
2. 在指定基座验收 Android/iOS 的首次授权、拒绝与设置恢复、网页实际收音和 AI 出声、授权中离开、后台/锁屏释放、耳机、导航及账号切换。
3. 退出 A 账号后用 B 账号重新进入，确认 B 看不到 A 的内容；挂断或离开页面后确认录音指示消失。

### 没有成功时先检查

| 现象 | 下一步 |
| --- | --- |
| 页面打不开 / 连接被拒绝 | 先核对 HTTPS 证书、origin 与同一入口的 key / entryId，再检查入口是否启用及来源限制；不要关闭安全校验绕过问题。 |
| 页面打开但没有回复 | 检查入口接待方案是否绑定已发布智能体、模型是否可用；在接待台按测试标记查找会话，确认是否已转人工。 |
| 文字可用，但无法语音 | 检查企业和入口是否开启语音、系统录音权限与网页授权是否都满足；由用户主动点击开始，分别确认实际收音、AI 出声和挂断释放。 |

### 继续接入与配置

- [生命周期、权限与排错](#uniapp-lifecycle)
- [微信小程序 / H5 文本完整接入](#uniapp-text)
- [入口参数与访客身份](#credentials)
- [当前平台能力与限制](#capabilities)
- [上线验收清单](#acceptance)

### 官方原始接入文档

先按云蝠指南完成入口、智能体和服务配置，再按下列官方原文配置宿主权限或供应商资源。外部文档说明对应平台能力，不代表云蝠已开放其中全部接口；腾讯 SecretKey、签名密钥和管理 API Key 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。

- [DCloud · uni-app web-view 组件](https://uniapp.dcloud.net.cn/component/web-view)：区分 App-vue、H5 iframe 和微信目标；不同内核不能复用同一套原生权限假设。
- [DCloud · manifest.json 配置](https://uniapp.dcloud.net.cn/tutorial/app-manifest.html)：合并 Android 录音权限和 iOS 麦克风用途说明，并重新制作实际使用的自定义基座。
- [DCloud · plus.android.requestPermissions](https://www.html5plus.org/doc/zh_cn/android.html#plus.android.requestPermissions)：分别检查 granted、deniedPresent、deniedAlways；系统授权成功不等于远端 WebView 已收音，需基座验收。

继续阅读：[Uniapp：生命周期、权限与排错](#uniapp-lifecycle) · [能力与交付状态](#capabilities) · [网站 / H5 嵌入](#web-embed)

实现依据（仓库内路径）：`sdk/client-kit/uniapp/support.vue`、`sdk/client-kit/README.md`

<a id="uniapp-lifecycle"></a>

## Uniapp：生命周期、权限与排错

核对账号切换、权限拒绝和容器能力。

### 下载接入包

- [下载 Uniapp 源码示例](/downloads/yunfu-uniapp-integration-kit.zip) · [校验清单](/downloads/yunfu-uniapp-integration-kit.json)：App-vue 容器与 Vue2 / Vue3 的 H5、微信示例默认加载当前原版渠道。原生文本为替代方案，按目标配置并完成真机验收。

### 生命周期

同一登录期复用 UUID，重复初始化不会关闭咨询；切换账号必须更换 UUID。退出 beforeLogout() 幂等关闭旧内容并作废旧授权，不擅自弹出其他业务页。pause/onHide 停语音，resume 不重拨，卸载移除页面订阅。不可只修改客户名称。

### 权限与功能边界

保持 plusrequire:none 与固定导航。DCloud 公共 API 不提供逐来源媒体授权 hook；系统权限不等于 WebView 授权成功。不能使用 App 不支持的 uni.authorize(scope.record)。失败保留文字，必要时接宿主原生插件。

### 按这个顺序切换账号

1. A 登录并完成隐私流程后生成随机 UUID，调用 prepareSupportAccount；同一登录期复用，不随每次打开客服更换。
2. A 退出前调用 beforeLogout()，停止旧语音、关闭旧网页内容并作废旧授权回调。旧客服页在栈顶时重新打开会被替换；其他宿主页面不会被弹走，旧客服页会失效并等待正常返回。
3. B 登录后用不同 UUID 调用 prepareSupportAccount，再由 B 点击打开。不得只修改昵称、手机号或 URL 标签来复用 A 的页面。
4. 分别检查 B 的消息列表、后台接待记录和迟到回复。UUID 仅隔离本地会话，不是可信会员认证；退出不会删除服务端历史或审计。

### 错误处理与恢复

| 错误 / 场景 | 处理方式 |
| --- | --- |
| CONFIGURE_ENTRY_FIRST | 检查 config.js：只填 HTTPS origin、公开 UUID key 与入口 ID，不填完整聊天 URL |
| SUPPORT_SESSION_REQUIRED / SUPPORT_SESSION_CHANGED | 先登录初始化；旧账号页关闭内容，返回后重新进入 |
| APP_VUE_REQUIRED / SUPPORT_ALREADY_OPEN | 选择正确编译目标；已有客服页时由宿主决定导航，不自动弹走其他页面 |
| SUPPORT_NAVIGATION_FAILED | 检查 pages.json 与页面栈；失败后可由用户再次点击 |
| 加载失败或 15 秒超时 | 页面提供重新加载；只重载页面，不自动重发客户消息或重拨 |
| 麦克风拒绝 / 永久拒绝 | 继续文字咨询；由用户到系统设置授权，回前台不自动开麦 |

### 在目标真机逐项验收

| 操作 | 通过条件 |
| --- | --- |
| 先初始化账号，不点击客服；再连续点击客服按钮 | 初始化无客服请求和录音提示；点击后仅打开一个客服页面，不出现重复会话页 |
| 通过文字入口发送一条带唯一标记的问题 | 页面收到真实回复，后台记录归属正确企业、入口和会话；导航成功或 loaded 事件不能代替此结果 |
| 首次开始语音并允许录音 | 系统与网页授权分别满足，实际收音、AI 出声及打断正常；挂断后录音指示消失 |
| 拒绝录音、永久拒绝、到设置恢复授权 | 拒绝后仍可文字咨询，不循环弹窗；恢复后由用户主动重试，回前台不自动开麦 |
| 授权弹窗期间离开；通话时切后台、锁屏、返回或关闭页面 | 旧授权不会恢复已关闭内容；麦克风与连接停止，返回后需再次点击开始 |
| A 聊天后退出，再以 B 登录；等待旧回复到达 | B 看不到 A 的消息，旧回调不更新 B 页面；后台保留各自会话记录 |
| 断网后恢复并手动重新加载；切换耳机，弹出键盘及返回 | 失败可见、无自动重发或重拨；内容与返回入口可用；扬声器和目标耳机能实际收听 |

### 当前没有包含的能力

App-vue 交付是宿主源码片段，不是已编译的 App、插件或已完成真机验收的基座。当前没有可信会员身份交换、跨设备历史同步、离线未读、消息推送、后台通话、CallKit / ConnectionService 或原生听筒切换。网页文件选择与下载仍需目标设备验证，不能从无 UI SDK 的能力推断此容器已具备。

### 接入验收记录

按 Android / iOS 分别记录 HBuilderX / Vue 版本、自定义基座、系统与 WebView 版本、入口、测试时间、客服会话编号以及每项通过 / 失败 / 未测。不要把密钥写进日志。静态示例、控制测试和编译通过不等于真实接待或真机语音已接通。

### 连接被拒绝时

核对 HTTPS、key、entryId 与入口启用状态；网站渠道的 Referer 限制可能不适用于原生容器。为 App 创建专用入口评估策略，不伪造来源、不关闭旧网站的来源限制。

### 最小回归

1. 在指定基座验收 Android/iOS 的首次授权、拒绝与设置恢复、网页实际收音和 AI 出声、授权中离开、后台/锁屏释放、耳机、导航及账号切换。
2. A 账号聊天后退出，B 看不到 A 的历史；关闭后旧回调不再触发。
3. 接收真实 AI 与人工回复；网络未知时保留待核对，不自动重复提交。

### 官方原始接入文档

先按云蝠指南完成入口、智能体和服务配置，再按下列官方原文配置宿主权限或供应商资源。外部文档说明对应平台能力，不代表云蝠已开放其中全部接口；腾讯 SecretKey、签名密钥和管理 API Key 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。

- [DCloud · uni-app web-view 组件](https://uniapp.dcloud.net.cn/component/web-view)：区分 App-vue、H5 iframe 和微信目标；不同内核不能复用同一套原生权限假设。
- [DCloud · manifest.json 配置](https://uniapp.dcloud.net.cn/tutorial/app-manifest.html)：合并 Android 录音权限和 iOS 麦克风用途说明，并重新制作实际使用的自定义基座。
- [DCloud · plus.android.requestPermissions](https://www.html5plus.org/doc/zh_cn/android.html#plus.android.requestPermissions)：分别检查 granted、deniedPresent、deniedAlways；系统授权成功不等于远端 WebView 已收音，需基座验收。

继续阅读：[Uniapp：快速接入](#uniapp-install) · [生命周期与账号切换](#account-switch) · [SDK 错误与待核对请求](#sdk-errors)

实现依据（仓库内路径）：`sdk/client-kit/uniapp/support.vue`、`sdk/client-kit/README.md`

<a id="uniapp-text"></a>

## Uni-app：微信小程序与 H5 客服

Vue2 / Vue3 客服接入、客户资料传递与手机号授权；可视化选择字段并核对客户与智能体变量。

### 下载接入包

- [下载 Uniapp 文本客服源码示例](/downloads/yunfu-uniapp-text-integration-kit.zip) · [校验清单](/downloads/yunfu-uniapp-text-integration-kit.json)：Vue 2 / Vue 3 默认复用原版渠道页面，含可选原生文本替代；按目标编译并验收。

### 下载与运行

1. 下载中心选择“Uni-app 微信小程序 / H5 文本示例”，解压进入 uniapp-text/。README 含完整发布步骤；默认 renderer: channel 直接打开原版客服页面，微信使用 web-view、H5 使用 iframe。
2. 使用 Node 20.19+（推荐 22 LTS）。Vue3 在工程根目录用 pnpm 11 执行 pnpm install --frozen-lockfile；Vue2 进入 vue2/ 执行 npm ci。两套依赖各自锁定，不混装。
3. Vue3 在根目录运行 pnpm run build:mp-weixin / build:h5；Vue2 在 vue2/ 运行 npm run build:mp-weixin / build:h5。Vue2 输出固定在 dist/build/vue2/ 下，Vue3 在 dist/build/ 下。构建不会自动发布或调用模型。
4. 现有工程复制组件、support helper、sdk、static/yunfu-avatars 与 config，合并路由及 App 生命周期，不覆盖宿主文件；自包含 SDK 已在包内。兼容 Vue2 / Vue3；默认原版渠道界面，不能使用 WebView 时显式改为 renderer: native。原生文本方案不含语音和附件；不适用于 nvue、uni-app x。

### Vue2 快速接入与旧包升级

1. 如果组件中看到 <script setup> 或 defineProps，说明拿到的是旧版 Vue3 示例。请重新下载 Uni-app 接入包或 Uni-app 微信小程序 / H5 文本示例；新版使用 export default Options API，同一组件兼容 Vue2 和 Vue3，不需要 Composition API。
2. 在解压后的 uniapp-text/vue2/ 目录依次运行 npm ci、npm run build:h5、npm run build:mp-weixin；可先阅读该目录的 README。微信开发者工具导入 dist/build/vue2/mp-weixin，H5 使用 dist/build/vue2/h5。
3. 接入现有 Vue2 项目时同时复制组件、support/、sdk/、static/yunfu-avatars/ 和 config.js，按下文合并页面路由、App 前后台事件；保留宿主的 main.js、manifest.json 和依赖，不要仅复制旧版 Vue3 组件或覆盖宿主配置。
4. 若重新下载后仍看到 script setup，检查浏览器缓存及解压目录，确认文件来自刚下载的包；旧包不会自动更新。可在下载中心核对文件摘要。构建通过后仍需自己的公开入口及真机联调。

### 与 JS 嵌入使用同一界面

1. 默认 renderer: channel，由 YunfuChannel 打开 /support?surface=channel。消息、输入区、头像、主题和可用功能直接使用 JS 嵌入相同页面，渠道保存后重新进入即可读取配置。原版界面加载前须同意隐私说明并点击进入客服。
2. H5 合并 style.h5.navigationStyle: custom 与 titleNView: false（兼容 Vue2），避免额外标题挤占聊天高度；进入前页面随系统明暗主题，进入后使用渠道主题。窗口关闭和缩放由宿主管理，原版整页模式不重复展示；微信原生导航栏、键盘及不同内核的字体渲染需要真机核对，不能用同浏览器像素结果替代所有设备验收。
3. 无法满足 WebView 业务域名或平台要求时，显式使用 renderer: native。该方案同步标题、头像、欢迎语、推荐问题、品牌色与主题，但只是原生文本替代，不能声明与网页所有功能和像素完全一致。
4. 升级时一并替换组件、support/、sdk/ 与 static/，保留公开参数和宿主 Vue 版本；合并 transformPx:false 前核对宿主其他页面。两种模式互斥，不会在页面加载失败后自动改用另一种身份连接。

### 选择宿主 Vue 版本

| 宿主 | 组件与构建 | 保留宿主设置 |
| --- | --- | --- |
| Vue2 | 共用 Options API 组件；附带 Vue 2.6.14 + DCloud Vue CLI / webpack 锁定构建链，位于 vue2/。不需要 composition-api 插件。 | 已有工程保留自己的 package.json、路由、App 生命周期及 manifest 的 Vue 版本。不要覆盖为示例根目录的 Vue3 依赖。 |
| Vue3 | 同一组件；根目录继续使用 Vue 3.4.21 + DCloud Vite 构建链。 | 保留现有 Vue3 配置；不能用 Vue2 的 webpack 配置替换 Vite。 |
| 共用源码 | main.js 使用 VUE3 条件编译；销毁分别响应 beforeDestroy / beforeUnmount，页面离开也清理。 | HBuilderX 中按宿主 Vue 版本导入组件；所用 IDE、基座和真机仍需单独验收。不适用于 nvue / uni-app x。 |

### 双版本启动入口（新工程）

使用位置：`src/main.js` · 完整源文件 · 接入包 0.3.15

运行前：
- 新工程按 VUE3 条件编译选择启动入口；已有宿主只合并必要配置，不覆盖自己的 main.js。

```javascript
import App from './App.vue';
// #ifndef VUE3
import Vue from 'vue';
Vue.config.productionTip = false;
App.mpType = 'app';
const app = new Vue({ ...App });
app.$mount();
// #endif
// #ifdef VUE3
import { createSSRApp } from 'vue';
export function createApp() { return { app: createSSRApp(App) }; }
// #endif
```

预期结果：Vue2 使用 new Vue，Vue3 使用 createSSRApp；分别使用对应锁定构建链。

### 第一步：入口配置

使用位置：`src/config.js` · 完整源文件 · 接入包 0.3.15

运行前：
- 从 uniapp-text 接入包复制相关 SDK、support helper 和组件；按 README 填写公开参数。

```javascript
// Only public locator values. Never put AppSecret, administrator or Open API keys here.
import { normalizeOrigin, assertTestEnvironment } from './sdk/yunfu-miniapp-client.mjs';
export const supportConfig = Object.freeze({
  baseUrl: 'https://chat.ccgpt.net',
  testMode: false, // Set true for HTTP/localhost testing; restore false before release.
  key: 'YOUR_PUBLIC_KEY_UUID',
  entryId: 'YOUR_ENTRY_ID',
  renderer: 'channel', // Original channel page. Use 'native' only for the alternate text UI.
});

export function validateSupportConfig(config) {
  const uuid = /^[a-f\d]{8}-[a-f\d]{4}-[1-5][a-f\d]{3}-[89ab][a-f\d]{3}-[a-f\d]{12}$/i;
  // #ifdef MP-WEIXIN
  if (typeof wx !== 'undefined') assertTestEnvironment(config?.testMode, wx);
  // #endif
  const origin = normalizeOrigin(config?.baseUrl, config?.testMode === true);
  const validOrigin = !!origin && !/example\.com(?::\d+)?$/.test(origin);
  if (!validOrigin || !uuid.test(config.key || '') ||
      !/^[-\w]{1,100}$/.test(config.entryId || '') || config.entryId === 'YOUR_ENTRY_ID') {
    throw Object.assign(new Error('CONFIGURE_ENTRY_FIRST'), { code: 'CONFIGURE_ENTRY_FIRST' });
  }
}
```

预期结果：合并到 Vue2 或 Vue3 宿主后分别编译 H5 与 MP-WEIXIN；真机收发、身份隔离和平台发布分别验收。

### 参数与身份

| 字段 | 来源与含义 |
| --- | --- |
| baseUrl | 默认 https://chat.ccgpt.net；私有部署填写客服服务的公开 HTTPS origin，不含路径或查询串 |
| key / entryId | 自建渠道公开 key（UUID）及其实际启用的入口 ID；不是企业 API Key 或 AppSecret |
| renderer | channel：原版页面（默认）；native：原生文本替代方案 |
| userScope | 安全随机本地隔离串，同登录期稳定、换账号更换；不传手机号、会员ID或登录凭据 |
| mp-weixin.appid / manifest.appid | 分别填写宿主微信 AppID / DCloud 应用标识，不与渠道公开 key 混用 |

### 客户资料：字段与接入流程

1. **选择字段**：在上方入口配置中勾选姓名、公司、手机号、邮箱，复制资料示例到宿主。
2. **取得同意**：姓名由用户填写；手机号由用户点击授权。企业与邮箱可由宿主传入。
3. **关联客户**：native 模式连接或保存资料后关联当前访客；核对客户档案及智能体变量。

自动关联适用于 renderer: native 的 YunfuTextChat、原生微信和 Web 文字 SDK。将获同意的资料传给 config.visitorContext.customer 或组件 customer 属性，连接时即可建立当前访客的未核实客户档案；已连接后使用 identifyCustomer(customer, true)。不需要先发送消息或开启手动留资。

智能体在变量中选择“客户资料”及表内 profile 字段；自定义变量名按实际配置。资料不是指令或会员认证，不按手机号或宿主 id 合并客户，不开放其他账号历史；人工维护、解绑和重新关联优先，自动档案只补空字段。

默认 renderer: channel 使用独立 WebView 会话。进入前的手机号授权记录仅供回访，当前包不会把它自动关联到网页聊天或注入网页智能体变量。需要此关联时显式使用 native；不要把个人资料或访客令牌拼进 URL。

| 传递字段 | 客户来源字段 | 默认智能体变量 |
| --- | --- | --- |
| customer.name · 姓名 / 昵称 | profile.name | {{customer_name}} |
| customer.company · 公司名称 | profile.company | {{customer_company}} |
| customer.phone · 手机号 | profile.phone | {{customer_phone}} |
| customer.email · 邮箱 | profile.email | {{customer_email}} |

### 微信手机号与姓名

1. 在管理后台配置并启用对应“微信小程序客服”应用，再到入口的“留资引导 → 微信一键授权”绑定；启用联系电话收集。AppID 必须与当前宿主匹配，微信取号权限及可能费用由该小程序承担。
2. native 组件“更多 → 联系资料”提供昵称、公司、电话和已启用的邮箱字段。微信昵称使用 input type="nickname"，不代表真实姓名；真实姓名、公司及邮箱由用户填写或宿主按同意范围传入。
3. 按钮使用 open-type="getPhoneNumber" 和 @getphonenumber；取得 event.detail.code 后调用下方示例。后端负责取号，AppSecret 不进入小程序。拒绝授权可以继续咨询或手动填写。
4. 手机号换取失败需要用户重新授权，不重复消费旧 code。资料保存结果未知时使用 retryPending("profile") 重试原请求；换账号先 forget，再换随机 userScope。

使用位置：`yunfu-sdk/examples/customer-profile.js` · 授权回调示例 · 接入包 0.3.14

运行前：
- 用于 renderer: native 或自绘 SDK 页面，client 必须是同一聊天实例。
- 宿主完成隐私流程；profile 仅包含获同意的 name/company/email；current 回调检查页面、同意状态及账号是否仍有效。

```javascript
// Call from @getphonenumber after the host privacy flow. Pass the current chat client.
async function onPhoneAuthorized(client, event, profile, consent, current) {
  if (consent !== true || !current()) throw Error('CONSENT_REQUIRED');
  if (!client.getState().connected) await client.connect();
  if (!current()) throw Error('CLIENT_CHANGED');
  // An uncertain save retries its original request without consuming another phone code.
  if (client.getState().pending.some(item => item.action === 'profile'))
    return client.retryPending('profile');
  const code = event && event.detail && event.detail.code;
  if (!code) throw Error('PHONE_AUTHORIZATION_DECLINED');
  const phone = await client.getWechatPhoneNumber(code, true);
  if (!current()) throw Error('CLIENT_CHANGED');
  return client.identifyCustomer({ ...profile, phone }, true, current);
}
module.exports = { onPhoneAuthorized };
```

预期结果：用户点击 getPhoneNumber 后传入事件；保存确认后当前访客关联客户，后续消息带入智能体变量。未知保存结果仅重试 profile；拒绝授权可继续咨询。

### 第二步：合并页面路由

使用位置：`src/pages.json` · 完整源文件 · 接入包 0.3.15

运行前：
- 从 uniapp-text 接入包复制相关 SDK、support helper 和组件；按 README 填写公开参数。

```json
{
  "pages": [
    {
      "path": "pages/support/index",
      "style": {
        "navigationBarTitleText": "在线客服",
        "enablePullDownRefresh": false,
        "h5": {
          "navigationStyle": "custom",
          "titleNView": false
        }
      }
    }
  ],
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarBackgroundColor": "#ffffff"
  }
}
```

预期结果：合并到 Vue2 或 Vue3 宿主后分别编译 H5 与 MP-WEIXIN；真机收发、身份隔离和平台发布分别验收。

### 第三步：局部组件注册与页面生命周期

使用位置：`src/pages/support/index.vue` · 完整源文件 · 接入包 0.3.15

运行前：
- 从 uniapp-text 接入包复制相关 SDK、support helper 和组件；按 README 填写公开参数。

```html
<template>
  <view>
    <YunfuChannel v-if="scope && !identityError && supportConfig.renderer !== 'native'" :key="scope" ref="chat" :config="supportConfig" :user-scope="scope" :visible="visible"><template v-slot:account><button class="yf-account-action" :disabled="resetting" @click="resetIdentity">退出访客身份</button></template></YunfuChannel>
    <YunfuTextChat v-if="scope && !identityError && supportConfig.renderer === 'native'" :key="scope" ref="chat" :config="supportConfig" :user-scope="scope" :visible="visible"><template v-slot:account><button class="yf-account-action" :disabled="resetting || !scope || !!identityError" @click="resetIdentity">退出访客身份</button></template></YunfuTextChat>
    <text v-if="identityError" class="yf-host-error">{{ identityError }}。请恢复存储后重新进入；未创建新身份。</text>
  </view>
</template>
<script>
// Options API local registration works in both Vue2 and Vue3 Uni-app hosts.
import YunfuChannel from '../../components/YunfuChannel.vue';
import YunfuTextChat from '../../components/YunfuTextChat.vue';
import { supportConfig } from '../../config.js';
import { getAnonymousScope, removeAnonymousScope } from '../../support/session.js';
import { safeError } from '../../support/session.js';
const lifetimes = new WeakMap();
export default {
  components: { YunfuTextChat, YunfuChannel },
  data() { return { supportConfig, scope: '', visible: false, identityError: '', resetting: false }; },
  // Vue2 H5 dispatches onLoad from a framework created mixin, before user created.
  beforeCreate() { lifetimes.set(this, { generation: 0, alive: true }); },
  onLoad() { void this.loadIdentity(); },
  onShow() { this.visible = true; },
  onHide() { this.visible = false; },
  onUnload() { this.disposePage(); },
  beforeDestroy() { this.disposePage(); },
  beforeUnmount() { this.disposePage(); },
  methods: {
    async loadIdentity() {
      const state = lifetimes.get(this);
      if (!state || !state.alive) return;
      const current = ++state.generation;
      const valid = () => state.alive && state.generation === current;
      try { const next = await getAnonymousScope(undefined, undefined, valid); if (valid()) this.scope = next; }
      catch (error) { if (valid()) this.identityError = safeError(error).code; }
    },
    disposePage() {
      const state = lifetimes.get(this);
      if (!state || !state.alive) return;
      state.alive = false; state.generation += 1;
      if (this.$refs.chat) this.$refs.chat.close();
    },
    resetIdentity() {
      const state = lifetimes.get(this), requestedAt = state.generation;
      let settled = false;
      uni.showModal({ title: '退出访客身份', content: '将清除此设备上的客服续接凭据。服务器历史不会被删除；待确认请求也不会因此取消。是否继续？',
        success: async result => {
          if (settled) return;
          settled = true;
          if (!result.confirm || this.resetting || !state.alive || !this.visible || state.generation !== requestedAt) return;
          this.resetting = true;
          try {
            // Forget before changing accounts; next login must use a new opaque scope.
            if (this.$refs.chat) this.$refs.chat.forget();
            removeAnonymousScope();
            this.scope = '';
            await this.loadIdentity();
          } catch (error) { if (state.alive) { this.identityError = safeError(error).code; this.scope = ''; } }
          finally { if (state.alive) this.resetting = false; }
        } });
    },
  },
};
</script>

<style scoped>.yf-host-error { display: block; padding: 16px; color: #9a3412; }.yf-account-action { margin:0; font-size:12px; line-height:1.5; padding:7px 10px; border-radius:8px; background:var(--yf-surface,#fff); color:var(--yf-muted,#69788f); }.yf-account-action::after { border:0; }</style>
```

预期结果：合并到 Vue2 或 Vue3 宿主后分别编译 H5 与 MP-WEIXIN；真机收发、身份隔离和平台发布分别验收。

### 第四步：合并 App 前后台事件

使用位置：`src/App.vue` · 完整源文件 · 接入包 0.3.15

运行前：
- 从 uniapp-text 接入包复制相关 SDK、support helper 和组件；按 README 填写公开参数。

```html
<script>
import { setAppVisible } from './support/session.js';
export default {
  onShow() { setAppVisible(true); },
  onHide() { setAppVisible(false); },
};
</script>
```

预期结果：合并到 Vue2 或 Vue3 宿主后分别编译 H5 与 MP-WEIXIN；真机收发、身份隔离和平台发布分别验收。

### 微信与 H5 域名配置

| 目标 | 必须配置 | 发布与验收 |
| --- | --- | --- |
| 微信原版渠道 | 具备 web-view 使用资格，并在微信后台配置 baseUrl 业务域名；嵌套页面按微信规则配置。request 域名不能替代业务域名。 | 真实 AppID、有效 HTTPS 证书、域名校验开启；分别编译 Vue2 / Vue3 的 mp-weixin 输出，微信体验版和真机验收。 |
| H5 原版渠道 | 宿主页面必须 HTTPS，渠道允许该宿主来源；iframe 的麦克风许可还受服务器 Permissions-Policy 与浏览器限制。 | 部署对应 H5 输出，默认路径 /yunfu-text/。检查加载、主题、键盘、关闭和账号切换；页面加载事件不等于真实接待成功。 |
| native 原生文本 | 微信配置 request 合法域名；H5 页面与 baseUrl 必须 HTTPS 同源。仅此模式使用独立消息 SDK。 | 无法使用 WebView 时主动选择，绝不自动降级；先编译再验证消息、转人工、历史与幂等恢复。 |

### 原版页面的身份与生命周期

按 baseUrl、key、entryId 与 userScope 保存随机 clientSession；这只是匿名续接标识，不是会员认证。公开参数不授予管理权限，不在 URL 放置 API Key 或登录凭据。

隐藏、卸载、切换账号或配置时移除旧网页。返回后由客户再次进入，不自动重新打开或恢复麦克风。账号退出先调用 forget 并卸载，再更换 scope；不会删除服务器历史。

下列 SDK 方法、文本收发和错误码专用于 renderer: native；原版页面由当前网页界面管理，目前尚未接线显式转人工按钮和更早历史翻页。

### 原生文本：身份、会话与历史

公开参数仅定位入口，服务端签发的访客 token 由 SDK 保管，不写到 URL 或日志。userScope 不是微信会员认证、openid 绑定或跨设备历史找回；当前包不包含可信会员 SSO。

小程序本地存储续接，H5 使用 sessionStorage；同标签页刷新可恢复，关闭标签页、清存储或跨设备不保证恢复。卸载 destroy 保留续接；退出必须先 forget 再换随机 scope 并通过 Vue key 重建组件。清理失败时阻止新身份进入。

connect 读取最近记录，loadEarlier 根据 hasMore/before 加载更早消息；refresh 合并记录。结束咨询要等服务端 closed 后 restart。清客户端凭据不会删除服务器历史，也不会取消已经送达的消息。

### 原生文本：收发与转人工

1. 页面自动预检并加载渠道外观，更多中的检查入口也只 preflight；完成宿主隐私同意后点击开始咨询，调用 connect。示例勾选框不能代替宿主和微信完整隐私流程。
2. subscribe 监听状态，sendText 发送最多 2000 字。组件渲染纯文本，不执行 v-html；发送中禁用重复提交。AI / 人工回复必须根据服务端消息实际确认。
3. 已有 activeConversationId 后才 handoff；没有会话先发第一条问题。waiting 仅为人工排队，human 才接管；接待台必须实际回复并在客户端看到 service 消息。
4. 断网/超时保留 pending。先 refresh 核对，再由用户确认 retryPending，沿用原请求编号，不能直接再次 sendText 相同内容。

### 原生文本：生命周期与错误恢复

| 场景 | 处理 |
| --- | --- |
| 页面 / 应用 / H5文档可见性 | 三者同时可见才轮询。H5使用manageVisibility:false由宿主管理；隐藏路由不能被标签页恢复事件唤醒。 |
| 卸载 / 账号切换 | 取消请求、订阅、轮询和监听；先隔离迟到回调。账号切换另清理续接凭据，不自动终止服务器会话。 |
| WX_DOMAIN_NOT_ALLOWED / WX_TLS_FAILED / WX_PRIVACY_REQUIRED | 分别核对微信request域名、证书链和宿主隐私授权。 |
| SAME_HTTPS_ORIGIN_REQUIRED | 按H5同源规则部署；不绕过检查。 |
| NETWORK_TIMEOUT / NETWORK_UNCERTAIN / PENDING_REQUEST_EXISTS | 先核对原请求，再幂等重试；不循环自动重发。 |
| NO_ACTIVE_CONVERSATION / RESTART_NOT_READY | 先发咨询；重新开始必须等待closed且无其他待确认请求。 |
| SESSION_STORAGE_UNAVAILABLE / SECURE_RANDOM_UNAVAILABLE | 恢复存储或安全随机能力，失败时阻止身份混用；不使用Math.random降级。 |

### 联调与验收步骤

1. 首先核对原版模式的业务域名、显式进入、隐藏后关闭、切账号不串历史，并与同入口 JS 嵌入比对头像、品牌色、消息和输入区。原生文本按以下 SDK 动作另行验收。创建专用测试入口并设置可用智能体/人工组；按宿主 Vue 版本完成 H5 / MP-WEIXIN 编译后分别安装微信体验版与同源HTTPS站点。真实发消息可能计费，遵循测试预算。
2. 入口只读检查→开始咨询→发送唯一测试文本→接待台找到同一会话编号和实际回复；再跑3轮，验证客户/AI/人工角色。
3. 准备超过一页历史，验证更早记录、刷新后不丢失；转人工看到waiting，再由客服接管回复，核对human与service消息。
4. 断网或丢响应后先核对再重试，确认只生成一条业务消息；切后台与路由隐藏不新发轮询，恢复沿用同会话。
5. A账号退出后切B，延迟A的响应与回旧页，确认B不显示A历史；测试结束closed及重新开始，新旧记录可区分。
6. 微信保持域名校验，在iOS/Android真机与体验版核对；H5在Safari/Chrome核对HTTPS、路由、键盘、刷新续接。记录版本、包摘要、时间、入口ID、会话编号和实际结果，不记录密钥。
7. 编译、真机接待、平台审核和正式发布分别留证。示例没有预置真实账户，不提供虚构的通话/会话记录；管理员完成实际发布。

### 官方原始接入文档

先按云蝠指南完成入口、智能体和服务配置，再按下列官方原文配置宿主权限或供应商资源。外部文档说明对应平台能力，不代表云蝠已开放其中全部接口；腾讯 SecretKey、签名密钥和管理 API Key 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。

- [DCloud · CLI 创建与构建](https://uniapp.dcloud.net.cn/quickstart-cli.html)：核对 Vue2 Vue CLI / webpack 与 Vue3 Vite 的不同构建入口、编译目标和输出目录；编译不等于平台发布。
- [DCloud · web-view 原版网页承载](https://uniapp.dcloud.net.cn/component/web-view.html)：核对微信业务域名、全屏展示及宿主导航；原版页面和原生文本模式使用不同域名类别。
- [DCloud · 页面与生命周期](https://uniapp.dcloud.net.cn/tutorial/page.html)：合并页面与应用事件，防止隐藏路由继续轮询。
- [DCloud · 小程序开发注意事项](https://uniapp.dcloud.net.cn/tutorial/miniprogram-subject.html)：区分 Vue 组件与原生微信组件注册，核对目标能力。
- [微信开放文档 · 小程序网络与合法域名](https://developers.weixin.qq.com/miniprogram/dev/framework/ability/network.html)：原生请求需配置 request、uploadFile、downloadFile 合法域名；WebView 另需业务域名，关闭校验不能代替正式配置。

继续阅读：[Uniapp：快速接入](#uniapp-install) · [小程序生命周期与事件](#miniapp-events) · [无 UI Web 客户端快速接入](#web-client) · [入口、身份与凭据](#credentials) · [下载与更新记录](#downloads)

实现依据（仓库内路径）：`sdk/client-kit/uniapp-text/README.md`、`sdk/client-kit/uniapp-text/src/components/YunfuChannel.vue`、`sdk/client-kit/uniapp-text/src/components/YunfuTextChat.vue`、`sdk/client-kit/uniapp-text/src/support/session.js`

<a id="channel-taobao-flash"></a>

## 淘宝闪购

需商家授权及平台消息协议；订单权限不代表客服权限。

### 支持状态

资料筹备，尚无可用收发适配器

需商家授权及平台消息协议；订单权限不代表客服权限。

### 准备资料

店铺主体、获批服务商应用与消息权限。

### 接入流程

1. 先取得自有应用正式协议与授权，当前不要展示为已接通。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

取得自有应用的正式协议与授权后实现适配器，再完成真实收发验收。当前不能从本系统收发该平台消息。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="channel-xiaohongshu"></a>

## 小红书

已提供资料筹备；三方客服消息推送、授权和发送需独立实现。

### 支持状态

资料筹备，尚无可用收发适配器

已提供资料筹备；三方客服消息推送、授权和发送需独立实现。

### 准备资料

专业号及 third_im 准入；绑定页、授权回调与消息地址分别配置。

### 接入流程

1. 先取得自有应用正式协议与授权，当前不要展示为已接通。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

取得自有应用的正式协议与授权后实现适配器，再完成真实收发验收。当前不能从本系统收发该平台消息。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="channel-bilibili"></a>

## Bilibili

尚未提供 Bilibili 私信适配器。

### 支持状态

资料筹备，尚无可用收发适配器

尚未提供 Bilibili 私信适配器。

### 准备资料

具备平台三方客服权限的账号和应用。

### 接入流程

1. 先取得自有应用正式协议与授权，当前不要展示为已接通。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

取得自有应用的正式协议与授权后实现适配器，再完成真实收发验收。当前不能从本系统收发该平台消息。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="channel-wechat-shop"></a>

## 微信小店

小店订单与客服消息尚未接通；不能复用公众号凭据替代授权。

### 支持状态

资料筹备，尚无可用收发适配器

小店订单与客服消息尚未接通；不能复用公众号凭据替代授权。

### 准备资料

店铺管理员与独立店铺授权。

### 接入流程

1. 先取得自有应用正式协议与授权，当前不要展示为已接通。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

取得自有应用的正式协议与授权后实现适配器，再完成真实收发验收。当前不能从本系统收发该平台消息。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="channel-meituan-flash"></a>

## 美团闪购

闪购和外卖协议分开接入；当前没有闪购消息连接器。

### 支持状态

资料筹备，尚无可用收发适配器

闪购和外卖协议分开接入；当前没有闪购消息连接器。

### 准备资料

对应业态的商户授权与客服消息权限。

### 接入流程

1. 先取得自有应用正式协议与授权，当前不要展示为已接通。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

取得自有应用的正式协议与授权后实现适配器，再完成真实收发验收。当前不能从本系统收发该平台消息。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="channel-wechat-mini"></a>

## 微信小程序

原生文本、加密 XML 回调；尚不支持扫码授权、卡片与 session-from 分流。

### 支持状态

已实现连接器，待自有账号联调

原生文本、加密 XML 回调；尚不支持扫码授权、卡片与 session-from 分流。

### 准备资料

管理员、AppID、AppSecret、客服按钮、Token；安全模式另需 AES Key。

### 接入流程

1. 进入对应渠道 / 业务模块，核对权限、配置和真实接口契约。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

分别核对凭据、真实入站、平台接受回复；验证重复事件不重复回复、转人工停止 AI、撤权与账号隔离。空回调和保存配置不算接通。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="channel-wechat-kf"></a>

## 微信客服

API 管理的客服账号文本收发；人工服务状态限制 AI 发送。

### 支持状态

已实现连接器，待自有账号联调

API 管理的客服账号文本收发；人工服务状态限制 AI 发送。

### 准备资料

企业 ID、客服账号、获准应用 Secret 与加密回调。

### 接入流程

1. 进入对应渠道 / 业务模块，核对权限、配置和真实接口契约。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

分别核对凭据、真实入站、平台接受回复；验证重复事件不重复回复、转人工停止 AI、撤权与账号隔离。空回调和保存配置不算接通。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="channel-wechat-mp"></a>

## 微信公众号

公众号文本收发与 XML 回调；媒体消息尚未接通。

### 支持状态

已实现连接器，待自有账号联调

公众号文本收发与 XML 回调；媒体消息尚未接通。

### 准备资料

公众号 AppID、Secret、客服权限和回调 Token。

### 接入流程

1. 进入对应渠道 / 业务模块，核对权限、配置和真实接口契约。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

分别核对凭据、真实入站、平台接受回复；验证重复事件不重复回复、转人工停止 AI、撤权与账号隔离。空回调和保存配置不算接通。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="channel-wecom"></a>

## 企业微信

已有内部智能机器人 API 文本链路；客户联系与员工应用需另行接入。

### 支持状态

已实现连接器，待自有账号联调

已有内部智能机器人 API 文本链路；客户联系与员工应用需另行接入。

### 准备资料

智能机器人 API 模式 Token、AES Key；外部接待另用微信客服。

### 接入流程

1. 进入对应渠道 / 业务模块，核对权限、配置和真实接口契约。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

分别核对凭据、真实入站、平台接受回复；验证重复事件不重复回复、转人工停止 AI、撤权与账号隔离。空回调和保存配置不算接通。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="channel-douyin"></a>

## 抖音企业号

私信连接器保持暂停，先核验当前准入与获批协议。

### 支持状态

资料筹备，尚无可用收发适配器

私信连接器保持暂停，先核验当前准入与获批协议。

### 准备资料

企业号认证、存量权限核对及独立消息授权。

### 接入流程

1. 先取得自有应用正式协议与授权，当前不要展示为已接通。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

取得自有应用的正式协议与授权后实现适配器，再完成真实收发验收。当前不能从本系统收发该平台消息。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="channel-baidu"></a>

## 百度营销

尚未提供百度营销原生消息适配器。

### 支持状态

资料筹备，尚无可用收发适配器

尚未提供百度营销原生消息适配器。

### 准备资料

营销账号及获批消息接入方案。

### 接入流程

1. 先取得自有应用正式协议与授权，当前不要展示为已接通。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

取得自有应用的正式协议与授权后实现适配器，再完成真实收发验收。当前不能从本系统收发该平台消息。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="channel-twitter"></a>

## X / Twitter

尚未提供 X 私信适配器；旧文档不能证明当前 API 套餐可用。

### 支持状态

资料筹备，尚无可用收发适配器

尚未提供 X 私信适配器；旧文档不能证明当前 API 套餐可用。

### 准备资料

当前开发者套餐、应用审核和私信权限。

### 接入流程

1. 先取得自有应用正式协议与授权，当前不要展示为已接通。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

取得自有应用的正式协议与授权后实现适配器，再完成真实收发验收。当前不能从本系统收发该平台消息。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="channel-whatsapp"></a>

## WhatsApp

Cloud API 原生文本收发；模板消息未提供。

### 支持状态

已实现连接器，待自有账号联调

Cloud API 原生文本收发；模板消息未提供。

### 准备资料

Business 号码 ID、Graph 版本、令牌、App Secret、Verify Token。

### 接入流程

1. 进入对应渠道 / 业务模块，核对权限、配置和真实接口契约。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

分别核对凭据、真实入站、平台接受回复；验证重复事件不重复回复、转人工停止 AI、撤权与账号隔离。空回调和保存配置不算接通。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="channel-facebook"></a>

## Facebook

已有准备表单，尚未实现主页私信或评论连接器。

### 支持状态

资料筹备，尚无可用收发适配器

已有准备表单，尚未实现主页私信或评论连接器。

### 准备资料

Page 管理权限、获批应用与对应消息权限；不照搬人工 7 天窗口给 AI。

### 接入流程

1. 先取得自有应用正式协议与授权，当前不要展示为已接通。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

取得自有应用的正式协议与授权后实现适配器，再完成真实收发验收。当前不能从本系统收发该平台消息。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="channel-instagram"></a>

## Instagram

已有准备表单；两种登录方案的令牌和权限不能混用。

### 支持状态

资料筹备，尚无可用收发适配器

已有准备表单；两种登录方案的令牌和权限不能混用。

### 准备资料

专业账号及匹配 Instagram Login 或 Facebook Login 的授权。

### 接入流程

1. 先取得自有应用正式协议与授权，当前不要展示为已接通。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

取得自有应用的正式协议与授权后实现适配器，再完成真实收发验收。当前不能从本系统收发该平台消息。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="channel-line"></a>

## LINE

官方账号单聊文本、签名校验与幂等 Push 回复；群聊、媒体及 Reply Token 不在当前范围。

### 支持状态

已实现连接器，待自有账号联调

官方账号单聊文本、签名校验与幂等 Push 回复；群聊、媒体及 Reply Token 不在当前范围。

### 准备资料

Messaging API、Bot User ID、Channel Secret、Access Token；Push 消耗账号额度。

### 接入流程

1. 进入对应渠道 / 业务模块，核对权限、配置和真实接口契约。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

分别核对凭据、真实入站、平台接受回复；验证重复事件不重复回复、转人工停止 AI、撤权与账号隔离。空回调和保存配置不算接通。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="channel-discord"></a>

## Discord

已有 /ask 指令与交互回复；并非任意频道消息监听。

### 支持状态

已实现连接器，待自有账号联调

已有 /ask 指令与交互回复；并非任意频道消息监听。

### 准备资料

应用 ID、公钥、Bot Token、Interactions URL。

### 接入流程

1. 进入对应渠道 / 业务模块，核对权限、配置和真实接口契约。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

分别核对凭据、真实入站、平台接受回复；验证重复事件不重复回复、转人工停止 AI、撤权与账号隔离。空回调和保存配置不算接通。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="channel-google-play"></a>

## Google Play

应用评价回复尚未实现；评价不能当成即时会话。

### 支持状态

资料筹备，尚无可用收发适配器

应用评价回复尚未实现；评价不能当成即时会话。

### 准备资料

应用开发者权限与评价接口授权。

### 接入流程

1. 先取得自有应用正式协议与授权，当前不要展示为已接通。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

取得自有应用的正式协议与授权后实现适配器，再完成真实收发验收。当前不能从本系统收发该平台消息。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="channel-app-store"></a>

## App Store

应用评价同步和回复尚未实现。

### 支持状态

资料筹备，尚无可用收发适配器

应用评价同步和回复尚未实现。

### 准备资料

App Store Connect 账号、应用访问权限和 API 凭据。

### 接入流程

1. 先取得自有应用正式协议与授权，当前不要展示为已接通。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

取得自有应用的正式协议与授权后实现适配器，再完成真实收发验收。当前不能从本系统收发该平台消息。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="channel-dingtalk"></a>

## 钉钉

已有应用机器人 HTTP 回调，使用会话内临时地址回复。

### 支持状态

已实现连接器，待自有账号联调

已有应用机器人 HTTP 回调，使用会话内临时地址回复。

### 准备资料

AppKey、App Secret、Robot Code、HTTP 回调及应用可见范围。

### 接入流程

1. 进入对应渠道 / 业务模块，核对权限、配置和真实接口契约。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

分别核对凭据、真实入站、平台接受回复；验证重复事件不重复回复、转人工停止 AI、撤权与账号隔离。空回调和保存配置不算接通。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="channel-feishu"></a>

## 飞书

已有应用机器人消息事件与文本回复；需正确的会话权限。

### 支持状态

已实现连接器，待自有账号联调

已有应用机器人消息事件与文本回复；需正确的会话权限。

### 准备资料

App ID、Secret、Verification Token、订阅事件和应用发布。

### 接入流程

1. 进入对应渠道 / 业务模块，核对权限、配置和真实接口契约。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

分别核对凭据、真实入站、平台接受回复；验证重复事件不重复回复、转人工停止 AI、撤权与账号隔离。空回调和保存配置不算接通。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="channel-youzan"></a>

## 有赞

订单和客服两类授权尚未实现原生适配。

### 支持状态

资料筹备，尚无可用收发适配器

订单和客服两类授权尚未实现原生适配。

### 准备资料

店铺授权及对应订单、客服接口权限。

### 接入流程

1. 先取得自有应用正式协议与授权，当前不要展示为已接通。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

取得自有应用的正式协议与授权后实现适配器，再完成真实收发验收。当前不能从本系统收发该平台消息。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="channel-weimob"></a>

## 微盟

尚未提供微盟消息连接器。

### 支持状态

资料筹备，尚无可用收发适配器

尚未提供微盟消息连接器。

### 准备资料

商户应用、店铺与对应消息权限。

### 接入流程

1. 先取得自有应用正式协议与授权，当前不要展示为已接通。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

取得自有应用的正式协议与授权后实现适配器，再完成真实收发验收。当前不能从本系统收发该平台消息。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="channel-popo"></a>

## POPO

尚未提供 POPO 消息连接器。

### 支持状态

资料筹备，尚无可用收发适配器

尚未提供 POPO 消息连接器。

### 准备资料

企业应用及消息推送、回复接口授权。

### 接入流程

1. 先取得自有应用正式协议与授权，当前不要展示为已接通。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

取得自有应用的正式协议与授权后实现适配器，再完成真实收发验收。当前不能从本系统收发该平台消息。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="channel-email"></a>

## 邮件

系统通知邮件不等于邮件客服；入站线程、附件与坐席回复尚未接通。

### 支持状态

资料筹备，尚无可用收发适配器

系统通知邮件不等于邮件客服；入站线程、附件与坐席回复尚未接通。

### 准备资料

专用客服邮箱、转发规则、发件域名与线程关联协议。

### 接入流程

1. 先取得自有应用正式协议与授权，当前不要展示为已接通。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

取得自有应用的正式协议与授权后实现适配器，再完成真实收发验收。当前不能从本系统收发该平台消息。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="module-web"></a>

## Web / H5

使用现有网页入口、嵌入代码和来源记录；新增同源无 UI 消息客户端。

### 下载接入包

- [下载 Web 客户端与示例](/downloads/yunfu-web-integration-kit.zip) · [校验清单](/downloads/yunfu-web-integration-kit.json)：含原版渠道 iframe 示例及无 UI 客户端。复用完整渠道外观请选择 web/voice-example.html 或渠道嵌入代码；无 UI 客户端需自行绘制界面。

### 支持状态

现有网页 / 容器接入

使用现有网页入口、嵌入代码和来源记录；新增同源无 UI 消息客户端。

### 准备资料

已发布智能体、公开 HTTPS 地址和获准嵌入域名；由用户点击展开。

### 接入流程

1. 进入对应渠道 / 业务模块，核对权限、配置和真实接口契约。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

验证访客发送、AI 回复、人工接管、关闭展开及手机键盘；跨访客不能串会话。

### 具体平台接入文档

- [网站 / H5 嵌入](#web-embed)
- [Web 消息 SDK](#web-client)

### 关联开放操作

channels.saveEntry、channels.saveEntryEmbed；方法、请求字段及返回结构见现有接口文档。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="module-app-sdk"></a>

## iOS / Android / Harmony / Uniapp

提供四端 WebView 容器源码示例与接入包，复用现有接待服务；尚未发行四端原生消息 SDK。

### 下载接入包

- [下载 iOS 源码示例](/downloads/yunfu-ios-integration-kit.zip) · [校验清单](/downloads/yunfu-ios-integration-kit.json)：WKWebView Swift 容器示例，加入现有 Xcode 工程编译；不含预编译 framework。
- [下载 Android 源码示例](/downloads/yunfu-android-integration-kit.zip) · [校验清单](/downloads/yunfu-android-integration-kit.json)：WebView Kotlin 容器和 Manifest 合并片段，需宿主工程编译；不含 AAR。
- [下载鸿蒙源码示例](/downloads/yunfu-harmony-integration-kit.zip) · [校验清单](/downloads/yunfu-harmony-integration-kit.json)：ArkWeb API 12+ 页面和权限片段，需 DevEco 宿主工程编译；不含 HAR。
- [下载 Uniapp 源码示例](/downloads/yunfu-uniapp-integration-kit.zip) · [校验清单](/downloads/yunfu-uniapp-integration-kit.json)：App-vue 容器与 Vue2 / Vue3 的 H5、微信示例默认加载当前原版渠道。原生文本为替代方案，按目标配置并完成真机验收。

### 支持状态

现有网页 / 容器接入

提供四端 WebView 容器源码示例与接入包，复用现有接待服务；尚未发行四端原生消息 SDK。

### 准备资料

宿主包名、云蝠公开 HTTPS 入口与宿主开发工程；按本包对应平台示例集成。

### 接入流程

1. 进入对应渠道 / 业务模块，核对权限、配置和真实接口契约。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

逐端验证登录身份、键盘、安全区、返回和前后台恢复；原生推送另行接入。

### 具体平台接入文档

- [iOS 快速接入](#ios-install)
- [Android 快速接入](#android-install)
- [Harmony 鸿蒙 快速接入](#harmony-install)
- [Uniapp 快速接入](#uniapp-install)

### 关联开放操作

channels.saveEntry；方法、请求字段及返回结构见现有接口文档。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="module-miniapp-sdk"></a>

## 微信小程序原生 SDK

提供 wx 原生聊天组件：AI、人工、历史、图片文件、知识、留资与评价；不是已上架插件。服务配置就绪后支持原生实时语音与在线邀请；微信身份认证未提供。

### 下载接入包

- [下载小程序 SDK 源码与示例](/downloads/yunfu-wechat-miniapp-sdk.zip) · [校验清单](/downloads/yunfu-wechat-miniapp-sdk.json)：默认 web-view 复用原版渠道页面，需业务域名；另含原生聊天与语音替代组件，按各自能力与权限完成真机验收。

### 支持状态

源码 SDK，待宿主验收

提供 wx 原生聊天组件：AI、人工、历史、图片文件、知识、留资与评价；不是已上架插件。服务配置就绪后支持原生实时语音与在线邀请；微信身份认证未提供。

### 准备资料

启用的自建 Web 入口、公开 key/entryId、微信合法域名与宿主小程序。语音还需企业 AppID 推拉流权限、企业/入口/智能体语音、服务端 TRTC 配置与清理任务。

### 接入流程

1. 进入对应渠道 / 业务模块，核对权限、配置和真实接口契约。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

按 SDK 包内清单验证真机收发、人工接待、前后台、未知结果重试、账号切换与附件；离线测试不能代替真机验收。

### 具体平台接入文档

- [小程序源码组件接入](#miniapp-install)
- [小程序功能与 API](#miniapp-api)

### 官方原始接入文档

先按云蝠指南完成入口、智能体和服务配置，再按下列官方原文配置宿主权限或供应商资源。外部文档说明对应平台能力，不代表云蝠已开放其中全部接口；腾讯 SecretKey、签名密钥和管理 API Key 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。

- [微信开放文档 · 小程序网络与合法域名](https://developers.weixin.qq.com/miniprogram/dev/framework/ability/network.html)：原生请求需配置 request、uploadFile、downloadFile 合法域名；WebView 另需业务域名，关闭校验不能代替正式配置。
- [微信开放文档 · 隐私授权开发指引](https://developers.weixin.qq.com/miniprogram/dev/framework/user-privacy/PrivacyAuthorize.html)：接入宿主隐私告知和同意流程；隐私同意、系统麦克风授权与实际收音分别验收。
- [微信开放文档 · wx.authorize 授权接口](https://developers.weixin.qq.com/miniprogram/dev/api/open-api/authorize/wx.authorize.html)：核对 scope.record 与拒绝后的处理；进入聊天页或点击普通按钮不等于已完成录音授权。
- [微信开放文档 · live-pusher 原生推流组件](https://developers.weixin.qq.com/miniprogram/dev/component/live-pusher.html)：核对原生推流组件、主体及类目权限；与腾讯 SDK 配置配套，在真机验证音频事件。
- [腾讯云 · 原生小程序快速接入](https://cloud.tencent.com/document/product/647/116548)：先核对企业主体、允许类目、推拉流权限、TRTC 套餐和 SDK 域名，再完成进房、发布音频与退房；开发工具不能代替真机。
- [腾讯云 · 实现 AI 对话](https://cloud.tencent.com/document/product/647/108901)：理解 RTC、识别、LLM、TTS、转录和打断的职责；具体参数与频率以对应接口的当前版本为准。
- [腾讯云 · 开始 AI 对话任务 · StartAIConversation](https://cloud.tencent.com/document/product/647/108514)：服务端适配时核对地域、SdkAppId、房间、目标用户与模型配置，保留 TaskId/RequestId；返回成功还需核对手机是否实际出声。
- [腾讯云 · 控制 AI 对话 · ControlAIConversation](https://cloud.tencent.com/document/product/647/109408)：核对供应商支持的播报和模型触发命令；仅供服务端适配参考，不可直接当作云蝠公开操作调用。
- [腾讯云 · 停止 AI 对话 · StopAIConversation](https://cloud.tencent.com/document/api/647/108513)：结束服务端 AI 对话任务并核对原 TaskId 的回收结果；退出客户端页面不应被当作云端任务已停止的证明。
- [腾讯云 · 高级权限控制](https://intl.cloud.tencent.com/zh/document/product/647/35157?lang=zh)：评估服务端 UserSig、PrivateMapKey 与房间隔离；通用平台表不证明小程序和 AI bot 已兼容，启用前须在实际应用核对入房。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="module-crm"></a>

## CRM / 客户资料

使用云蝠已登记的服务端操作，遵循本系统的接口地址、鉴权和签名协议。

### 支持状态

已有受控 API，按权限使用

使用云蝠已登记的服务端操作，遵循本系统的接口地址、鉴权和签名协议。

### 准备资料

客户字段映射、企业客户 ID、最小权限服务端密钥。

### 接入流程

1. 进入对应渠道 / 业务模块，核对权限、配置和真实接口契约。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

使用稳定幂等键保存客户，回读核对；同名客户不合并，不把前端访客资料当成身份认证。

### 关联开放操作

customers.read、customers.save、customers.crmFollowup；方法、请求字段及返回结构见现有接口文档。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="module-tickets"></a>

## 工单 / 接待转人工

使用云蝠已登记的服务端操作，遵循本系统的接口地址、鉴权和签名协议。

### 支持状态

已有受控 API，按权限使用

使用云蝠已登记的服务端操作，遵循本系统的接口地址、鉴权和签名协议。

### 准备资料

会话 ID、客服组、工单字段与负责人权限。

### 接入流程

1. 进入对应渠道 / 业务模块，核对权限、配置和真实接口契约。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

重复创建请求只生成一单，核对负责人和状态；建单成功不等于问题解决。

### 关联开放操作

desk.read、desk.createTicket、desk.transferTicket、desk.handoff；方法、请求字段及返回结构见现有接口文档。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="module-knowledge"></a>

## 知识库

使用云蝠已登记的服务端操作，遵循本系统的接口地址、鉴权和签名协议。

### 支持状态

已有受控 API，按权限使用

使用云蝠已登记的服务端操作，遵循本系统的接口地址、鉴权和签名协议。

### 准备资料

知识权限、真实数据源、索引及待发布版本。

### 接入流程

1. 进入对应渠道 / 业务模块，核对权限、配置和真实接口契约。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

先同步、检索和问答回归，再人工发布；源同步成功不代表回答准确。

### 关联开放操作

knowledge-sources.sync、knowledge.retrieve、knowledge.publish；方法、请求字段及返回结构见现有接口文档。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="module-ai-agent"></a>

## AI Agent / 工具

使用云蝠已登记的服务端操作，遵循本系统的接口地址、鉴权和签名协议。

### 支持状态

已有受控 API，按权限使用

使用云蝠已登记的服务端操作，遵循本系统的接口地址、鉴权和签名协议。

### 准备资料

获准业务接口、字段映射与工具权限。

### 接入流程

1. 进入对应渠道 / 业务模块，核对权限、配置和真实接口契约。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

验证必填补问、工具失败、审批和执行回执；不自动确认业务完成。

### 关联开放操作

tools.save、tools.test、workflows.check、workflows.run；方法、请求字段及返回结构见现有接口文档。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="module-call"></a>

## 呼叫 / 外呼任务

使用云蝠已登记的服务端操作，遵循本系统的接口地址、鉴权和签名协议。

### 支持状态

已有受控 API，按权限使用

使用云蝠已登记的服务端操作，遵循本系统的接口地址、鉴权和签名协议。

### 准备资料

实际 SIP/媒体桥、号码权限及已发布语音智能体。

### 接入流程

1. 进入对应渠道 / 业务模块，核对权限、配置和真实接口契约。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

用授权测试号码验证媒体、打断、转人工、结束与记录；保存任务不触发拨号。

### 关联开放操作

voice.start、voice.realtime-transport、outbound-batches.save、outbound-batches.read；方法、请求字段及返回结构见现有接口文档。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="module-records"></a>

## 会话记录 / 数据回传

使用云蝠已登记的服务端操作，遵循本系统的接口地址、鉴权和签名协议。

### 支持状态

已有受控 API，按权限使用

使用云蝠已登记的服务端操作，遵循本系统的接口地址、鉴权和签名协议。

### 准备资料

服务记录权限、时间范围与分页游标。

### 接入流程

1. 进入对应渠道 / 业务模块，核对权限、配置和真实接口契约。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

核对时间范围、企业隔离、下一页与附件授权；导出不遗漏或重复记录。

### 关联开放操作

conversations.read、voice-records.read、phone-records.export；方法、请求字段及返回结构见现有接口文档。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="module-callbacks"></a>

## 业务事件 / Webhook

使用云蝠已登记的服务端操作，遵循本系统的接口地址、鉴权和签名协议。

### 支持状态

已有受控 API，按权限使用

使用云蝠已登记的服务端操作，遵循本系统的接口地址、鉴权和签名协议。

### 准备资料

公网 HTTPS 接收服务、事件订阅和回调签名密钥。

### 接入流程

1. 进入对应渠道 / 业务模块，核对权限、配置和真实接口契约。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

按本系统签名协议验签、时间校验和持久去重；先落盘再应答，核对重试与未知结果。

### 关联开放操作

callbacks.save、callbacks.test；方法、请求字段及返回结构见现有接口文档。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="module-quality"></a>

## 智能质检

现有总结分析不等于完整第三方质检 API；外部数据导入与质检结果导出需单独实现。

### 支持状态

资料筹备，尚无可用收发适配器

现有总结分析不等于完整第三方质检 API；外部数据导入与质检结果导出需单独实现。

### 准备资料

明确自有业务协议、所需权限和验收数据。

### 接入流程

1. 先取得自有应用正式协议与授权，当前不要展示为已接通。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

完成相应接口与真实业务验证前保持未接通。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="module-staff"></a>

## 员工 / 组织 / 单点登录

后台已有组织管理；面向外部系统的员工同步和 iframe 单点登录协议尚未提供。

### 支持状态

资料筹备，尚无可用收发适配器

后台已有组织管理；面向外部系统的员工同步和 iframe 单点登录协议尚未提供。

### 准备资料

明确自有业务协议、所需权限和验收数据。

### 接入流程

1. 先取得自有应用正式协议与授权，当前不要展示为已接通。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

完成相应接口与真实业务验证前保持未接通。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`

<a id="module-sms"></a>

## 短信

通知和注册短信不等于批量营销短信接口；模板审批、签名、退订与回执需独立接入。

### 支持状态

资料筹备，尚无可用收发适配器

通知和注册短信不等于批量营销短信接口；模板审批、签名、退订与回执需独立接入。

### 准备资料

明确自有业务协议、所需权限和验收数据。

### 接入流程

1. 先取得自有应用正式协议与授权，当前不要展示为已接通。
2. 按对应平台的凭据和来源规则配置，不复用其他平台的 AppSecret 或签名。
3. 保存后分别验证真实入站、响应和业务结果；错误保留原始状态以便核对。

### 验收要求

完成相应接口与真实业务验证前保持未接通。

继续阅读：[Webhook：订阅、验签与回执](#callbacks) · [服务端认证与首次调用](#server-auth) · [联调与上线验收清单](#acceptance)

实现依据（仓库内路径）：`lib/developer-docs/integration-playbooks.ts`
