主题
第 8 章 小程序接入方案
小程序是 JoyInside 接入的「可选增强场景」，不是独立的接入方式。设备端语音接入（第二部分）是前置条件，小程序用于扩展用户交互面：配网、设备绑定、角色管理、聊天记录、在线设备管理。
本章讲小程序接入方案与适配策略；接口协议明细见 A。
8.1 小程序定位
⚠️ JoyInside 不提供小程序，需客户自行对接 C 端开放接口。
- JoyInside 提供的是小程序对接所需的 HTTP 接口（设备注册、音色、角色、绑定、聊天、在线设备管理），见 A
8.2 接入前置：Token 鉴权与设备注册
小程序对接 JoyInside 分两步：先获取 token 鉴权，再完成设备注册拿到 botId 后才能调用后续接口。
第一步：Token 鉴权获取 — 详见 4.1 Token 鉴权 的 token 获取流程。
验证请求合法、未被篡改，签名通过后服务端签发 accessToken（临时凭证），后续调用接口 header 携带即可。
第二步：设备注册 — 详见 4.2 设备注册与绑定 的注册接口（/device/register）。
设备注册与语音侧共用同一套注册流程（见 4.2）。注册拿到 botId 后，小程序即可用它调用角色管理、绑定、聊天等接口。此处不重复，详见第 4 章。
8.3 小程序业务能力
8.3.1 角色管理
我们提供 自定义角色、设备专属称呼 两个大模块。
自 2026 年 8 月起主推自定义角色，新接入优先走这条链路。AI 角色管理接口明细见 A.4。
8.3.1.1 自定义角色对接
平台已预置一批默认角色可供选用，作为自定义角色的基座。
查看默认角色列表截图（运营平台 > 默认角色）
自定义角色 = 客户企业基于一个默认角色自建，可改角色名 + 换音色，是新接入的推荐方案。
前提：设备已配网、已注册拿到设备身份（botId）。
对接四步走（选 → 建 → 绑 → 生效）：
第一步：选一个默认角色当基座 调 「默认角色列表」接口，从返回列表里挑一个默认角色，作为自定义角色的基座。
第二步：基于它创建/编辑自定义角色 用第一步选中的默认角色，调 「创建」接口 建一个自定义角色，改角色名、可选自定义音色（音色从 「查询企业音色列表」接口 拿，把 timbreId 填进去即可）；后续要改就调 「编辑」接口。
第三步：给设备绑定自定义角色 ⭐ 调 「绑定」接口，把第二步的自定义角色绑到设备上（roleType = CUSTOM）。
第四步：重连 WS 让它生效 绑定后必须让设备断开并重连 WebSocket，自定义音色 + 名称才会生效（这一步最容易漏）。
关键要点：
| 要点 | 说明 |
|---|---|
| 必须基于默认角色 | 自定义角色必须基于一个默认角色来建 |
| 自定义音色优先 | 想换嗓音就指定自定义音色，它会优先于系统默认音色；不传则沿用系统默认音色 |
| 绑定后必须重连 WS | 绑定后必须重连 WS 才生效（这一步最容易漏） |
举例：某儿童手表想打造"小鹰"这个 IP 形象——挑一个合适的默认角色当基座，建一个名为"小鹰"、换上定制嗓音的自定义角色，绑到设备即可。
8.3.1.2 用户昵称和设备称呼（独立于角色）
适用于「角色统一，但每个用户想给设备起专属名字」的场景，比如同一款"小鹰"手表，A 用户想叫它"小鹰"、B 用户想叫它"团团"。
它和角色名称的关系：
角色名称 ==（被覆盖为）== 接口设置的设备称呼| 维度 | 说明 |
|---|---|
| 角色名称 | 属于企业 + 用户维度（一批设备共用），通过上下文的 extInfo.agentName（自定义角色名称） 注入大模型，客户企业只需要绑定自定义角色即可 |
| 设备称呼 | 属于用户 + 设备维度（每个用户各自不同），由「修改用户昵称和设备称呼」接口设置；上下文侧对话时调「查询用户昵称和设备称呼」接口（按 botId + uid）动态拿到并覆盖角色名称 |
对接三步走：
第一步：设置设备称呼 调 「修改用户昵称和设备称呼」接口，传 botId + uid + userNickname + equipmentName，给这台设备起个用户专属名字。
第二步：对话时读取设备称呼 上下文侧在对话时调 「查询用户昵称和设备称呼」接口（按 botId + uid），动态拿到刚才设置的设备称呼。
第三步：占位符生效 只要运营平台人设里写了 ${agentName!"默认名称"} 占位符，设备称呼就会覆盖角色名称并生效。
❗ 使用前提（关键）：运营平台的全局人设（agentProfile）里，引用名字处必须写成占位符
${agentName!"默认名称"}，否则调接口对关联设备完全无效。💡 昵称修改后需在下次建连后的上下文中才能生效。
8.3.1.3 常见问题 FAQ
Q1：自定义音色从哪来？ 先调「查询企业音色列表」接口，拿到本企业可用音色（每个音色含 timbreId + 音色名称），选一个把 timbreId 填到自定义角色即可。音色资源的申请/开通请联系 JoyInside 团队。
Q2：改了角色/音色多久生效？ 不是自动生效——必须让设备断开并重连 WebSocket 后才生效。
Q3："最多 10 个自定义角色"按什么算？ 按 同一企业（vendorId）+ 同一用户（userId） 这个维度算。不同企业、不同用户各自独立计数。
Q4：换角色后，之前的聊天记忆还在吗？ 记忆挂在用户 uid 上，只要 uid 不变，换角色不影响历史记忆；uid 变了记忆会跟着变。
Q5：一台设备能同时绑多个角色吗？ 一台设备同一时刻绑定一个生效角色。要换形象就重新绑定并重连 WS。
Q6：角色名称和"设备称呼"有啥区别？该用哪个？ 角色名称是企业/用户维度的统一名字（一批设备共用）；设备称呼是用户维度的专属名字（每个用户各自不同）。想让不同用户给同一款设备起不同名字，就用「修改用户昵称和设备称呼」接口，它会覆盖角色名称——前提是运营平台人设里带 ${agentName!"默认名称"} 占位符。
Q7：设了设备称呼后，"你是谁"到底回答哪个名字？ 调了「修改用户昵称和设备称呼」接口就回答设备称呼；没调就回答角色名称。两者名字来源不同：角色名称走上下文的 extInfo.agentName，设备称呼则由上下文侧调「查询用户昵称和设备称呼」接口（按 botId+uid）动态拿到并注入人设，从而覆盖角色名称。
Q8：提示词中配置的 ${agentName!"默认名称"} 和 ${extInfo.agentName!"默认名称"} 有啥区别？ 代表的名字不同：${agentName!"默认名称"} 代表设备称呼，${extInfo.agentName!"默认名称"} 代表角色名称。（!"默认名称" 表示取不到值时回退显示引号里的默认名称。）
8.3.2 聊天管理
提供获取设备的聊天报告与历史对话能力。
对接前先想清楚——要不要精确到「人」：只有**设备已绑定用户（uid）**后，才能拿到该用户维度的聊天数据。
接口明细见 A.7 聊天记录与报告。
8.3.2.1 对接核心内容
前置准备，先明确业务使用场景：
| 业务诉求 | 怎么做 |
|---|---|
| 只看某台设备说了什么 | 按设备维度（botId）查即可，数据不区分用户 |
| 精确到某个人做用户画像 | 必须先做「设备 ↔ 用户」绑定（绑 uid），之后数据才归到该用户 |
精确到人时，先把 uid 绑定到 botId，绑定后该设备对话即归属到这个用户，产生长期记忆与聊天报告；绑定、查询绑定、解绑等能力均见 A.6 用户绑定。
对接四步走（注册 → 绑定 → 重连 → 查询），照着做即可：
第一步：确认设备已注册 设备完成注册、拿到设备身份 botId（前置条件，见 4.2 设备注册与绑定）。
第二步：绑定用户 调 「绑定用户」接口，把用户 uid 绑到 botId 上，之后该设备的对话就归属到这个用户。
第三步：设备重连 WS（关键！否则不生效） 让设备断开并重连 WebSocket，重连后的对话才会归到该 uid；重连前的仍按无用户处理。
第四步：按用户维度查记录/报告 之后即可按 uid 查询该用户的 聊天报告 和 聊天记录。
关键要点：
- 绑定后必须重连 WS：重连前的对话仍按无用户处理（详见 FAQ Q3）。
- uid 要真实且唯一：≤128 字节，勿多设备共用固定
uid（详见 FAQ Q4）。 - 换人需先解绑再绑定：一台设备同一时刻只归属一个用户，换人时须先解绑当前
uid，再绑定新uid。
8.3.2.2 常见问题 FAQ
Q1：不绑用户能拿到聊天记录吗？ 能，按设备维度（botId）查即可，只是不区分具体用户。
Q2：做用户画像必须绑用户吗？ 是。必须先把 uid 绑到 botId，之后对话才归属到该用户。
Q3：刚绑上用户，记录马上归到用户维度吗？ 不会。必须让设备断开并重连 WS，重连后的对话才归到该 uid；重连前的仍按无用户处理。
Q4：一台设备换了使用者，数据会串吗？ 不会。一台设备同一时刻只归属一个用户，换人时须先解绑当前 uid，再绑定新 uid，新对话即归新用户。切勿多设备共用固定 uid。
Q5：能查多久以前的记录？ 近 90 天，更早的无法查询，建议定期拉取归档。
Q6：聊天报告和聊天记录啥区别？ 记录是逐条原始对话；报告是平台生成的汇总洞察，更适合直接做画像。
Q7：解绑用户会有什么影响？ 解绑会断开该设备与用户的关联，影响长期记忆和按人员维度的聊天报告，请谨慎操作。
8.3.3 插播管理
具备向在线设备主动下发一句话并播报功能
适用于运营触达、消息提醒等场景。接口明细见 A.8 在线设备管理与插播。
前提：目标设备当前在线。
8.3.3.1 对接核心内容
插播只能推给当前在线的设备。所以业务流程是「先查在线、再插播」。
对接四步走（查在线 → 选设备 → 插播 → 播出），照着做即可：
第一步：查在线设备 调 「查询在线设备」接口，按 用户(uid) + 企业(vendorId) 查出该用户名下当前在线的设备。
第二步：选定目标设备 从返回结果里选一台在线设备（拿到它的 botId）。若没有在线设备，本次无法插播——可改走其它触达方式，或等设备上线再试。
第三步：给设备插播一句话 ⭐ 调 「插播一句话」接口，向目标设备下发文本，并选择播放策略（决定"什么时候播"）。
第四步：设备播出 设备收到后把这句话播报出来。
8.3.3.2 常见问题 FAQ
Q1：设备不在线还能插播吗？ 不能。插播只对在线设备生效。设备离线时应改用其它触达方式（如小程序推送），或等设备上线后再下发。
Q2：一个用户有多台设备，插播会发给哪台？ 先查在线设备列表，由业务侧选定目标设备（botId）后下发。可按需要给某一台或多台分别插播。
Q3：「强制打断」和「等待空闲」怎么选？ 紧急、需立刻让用户听到的（如闹钟）用强制打断；不紧急的运营/关怀提醒用等待空闲，避免打断用户当前对话。
Q4：插播的内容可以很长吗？ 不建议。插播定位是「短句即时触达」，文本有长度上限（≤500 字符），长内容体验差也可能被拒。
Q5：查到设备在线，插播就一定成功吗？ 不一定。在线状态是查询那一刻的快照，设备可能随即下线或忙碌，需根据下发结果做失败处理与重试策略。
Q6：用户会觉得被打扰吗？ 可能。主动下发要克制频率、挑合适时机、选合适策略，并遵循业务的触达规则，避免过度打扰。
Q7：插播内容会做内容安全审核吗？ 会。下发文本同样经过内容安全，避免下发不当内容。
Q8：为什么查不到用户的在线设备？ 查在线设备按 uid 维度，uid 必须与用户真实绑定一致，否则查不到正确设备。
下一步
- 小程序接口明细：读 A HTTP API 参考 —— 7 类接口完整字段
- Token 鉴权：读 4.1 Token 鉴权 —— token 获取流程（第一步）
- 设备注册：读 4.2 设备注册与绑定 —— botId 注册流程（第二步）
- uid 规则：读 4.3 重要参数介绍 —— uid ≤128 字节约束
- 小程序决策：回 2.6 小程序接入决策 —— 是否需要小程序