第 3 章 JoyInside 接入预览

本章面向初次接触 JoyInside 的外部合作方，提供最简的端到端接入流程介绍。
JoyInside 目前主要协同外部合作方，聚焦语音通道链路业务场景解决方案落地，非语音通道链接（如设备联网配网、重置控制、在线时长等实时状态检测、OTA升级等）相关开放能力暂无资源支持。
阅读本章后，您将完成两项核心目标：在运营平台完成可对话智能体配置，并通过设备端体验 Demo 验证完整语音对话链路（用户语音输入→云端识别应答→设备语音播放输出）。

3.1 JoyInside 接入全景

完成 JoyInside 接入仅包含两大核心工作：云端运营平台配置智能体（自定义智能体人设、配置业务能力）、设备端对接语音通信链路（实现设备收音、播音能力），两项工作全部落地即完成整体接入。

下文先梳理整体业务架构，再分阶段分步实操。

接入全景图

模块能力说明

模块	能力
JoyInside 智能体管理平台	搭智能体的地方:配人设、选技能、注册设备,网址 https://joy-inside.jd.com/index
智能体	设备的「大脑」:你说什么它决定怎么回。人设 + 技能决定它的性格和能力
ASR(语音识别)	设备的「耳朵」:把你说的语音转成文字,还带 VAD(判断你什么时候说完)
TTS(语音合成)	设备的「嘴巴」:把回复文字转成语音,设备才能播放出来
WebSocket 语音链路	耳朵—大脑—嘴巴之间的高速通道:设备音频实时上传、回复实时下发

接入两个阶段

智能体平台配置、设备端开发对接分属产品 / 运营、研发两类角色，可独立完成、分层验证，出现异常可单独定位排查，降低跨环节联调成本：

阶段	谁来做	做什么	完成标志
① 智能体搭建并验证	运营 / 产品	在平台搭好智能体,用预览调试验证能对话	预览调试里听见智能体回复
② 体验设备端接入	研发	用 Demo 体验设备端,走通语音链路	设备听见云端回复的声音

下文 3.2 章节讲解第一阶段智能体平台配置，3.3 章节讲解第二阶段设备端开发对接，两节全部完成即实现完整接入闭环。

3.2 智能体搭建并验证

本节完成第一阶段——在运营平台完成智能体配置并通过预览调试验证。零代码,运营 / 产品可独立完成。每步末尾标注「关键产出」,为下一环节必需。

step1 注册企业(获取 vendorId)

操作	要点
登录注册	打开 https://joy-inside.jd.com,用京东 APP / 微信扫码登录个人京东账号(暂不支持企业账号)
提交企业信息	按照实际企业主体名称填写即可,提交申请后待审核通过,进入工作区首页
关键产出	vendorId(进入 `个人信息 > 企业信息` 获取企业 ID)

📋 查看注册企业截图(vendorId 获取位置)

step2 创建产品型号

操作	要点
型号	自定义产品型号名称
产品品类	即一类产品的统称,不确定时可选「通用」
型号描述	描述产品型号的主要能力和属性

📋 查看创建产品型号截图

step3 创建应用 + 选择系统技能(获取 appId)

操作	要点
新建应用	进入 `应用管理 > 新建应用`;接入类型选「语音智能体接入」(推荐)
选产品型号	选择 step2 创建的型号
预选技能	至少勾选「闲聊」系统技能(最小闭环用它即可)
关键产出	appId(应用卡片下方即应用 ID)

📋 查看创建应用截图(appId 获取位置)

系统技能是预置标准能力(如闲聊、天气查询等),勾选即用。自定义技能(A2A 第三方智能体)是进阶能力,跑通最小闭环后再看运营平台高级功能。

step4 注册一台测试设备(获取 botId)

操作	要点
新建设备	进入 `设备管理 > 新建`;类型选「虚拟设备」(测试阶段只能选虚拟设备)
填写 SN 编码	SN 是制造商为每个产品分配的唯一标识,建议作为 deviceId
所属应用	选择 step3 创建的应用
关键产出	botId(设备 ID 列的内容,后续 WS 建联必需)

📋 查看注册测试设备截图(botId 获取位置)

测试设备注册无需申请,运营平台可直接创建。量产是单设备维度——每台设备开机配网后单独注册,见第 10 章 §10.1。

step5 预览调试验证(第一阶段完成标志)

这是零代码的验证,确认「智能体搭对了、能对话」再写设备端代码。

操作:

在应用配置详情右侧点击「开始测试」,建立 WebSocket 链路
调试窗支持语音输入和文本输入两种方式
上行音频 / 文本与下行音频 / 文本下方各有「详情」按钮,点击可查看完整事件详情
走的是真实语音 WS 链路(ASR→智能体→TTS),可播放 TTS 音频回复

📋 查看预览调试窗截图(开始测试 + 语音/文本输入 + 上下行详情)

第一阶段验收:

☑ 对话回复符合人设(确认智能体配置无误)
☑ 下行事件符合预期(收到 ASR 识别结果、收到 TTS 音频)

测试开场白不播放? 预览调试默认不收音。调试工具左边有「录音按钮」,开启后收到音才会播放开场白(端到端模式,语音入语音出)。

第一阶段完成,你手里应该有:vendorId + appId + botId + 预览调试能正常对话。把这四样交给研发,进入 3.3。

3.3 体验设备端接入

本节完成第二阶段——基于多语言 Demo 修改鉴权凭证,完成设备端与云端语音链路的联调。Demo 为 JoyInside 接入实现示例,可阅读源码理解交互规范,仅修改配置参数即可快速联调,内置 test.pcm 标准测试音频用于本地验证。

step1 选一个 Demo + 填凭证

下载 Demo(官网各语言下载页):

语言	下载地址	配置文件	环境要求
Python(推荐)	joyinside-python-dev.zip	`config.py`	Python 3.8+
Java	joyinside-java-dev.zip	`AppConfig.java`	Java 1.8+
C++	joyinside-cpp-dev.zip(含签名计算 / websocket client / usage 三个子包)	见 README	—
Android	joyinside-android-demo.zip	`AppConfig.java`	Android SDK 36+

获取凭证:

AccessKey / SecretKey:登录 https://joy-inside.jd.com,在 开发者中心 > API密钥 页面获取
vendorId:进入 个人信息,获取 3.2 step1 注册企业 ID
appId:进入 应用管理,目标应用 ID
botId:3.2 step4 注册设备后,设备管理页面「ID」列

填入配置文件(以 Python 为例):

python

# config.py
ACCESS_KEY = "你的 AccessKey"
ACCESS_KEY_SECRET = "你的 SecretKey"
VENDOR_ID = "你的企业 ID"
APP_ID = "你的应用 ID"
BOT_ID = "你的设备 ID"  # 3.2 step4 拿到的 botId

step2 签名 + getToken(Demo 已实现,直接调用)

Demo 已实现 HMAC-MD5 V2 签名算法,无需自己手写。直接运行 Demo 的 get_token() 即可。

签名原理(key 小写升序 → key=value 拼接 → HMAC-MD5)与算法明细见 4.1 Token 鉴权,本章不展开。

Demo 跑通后:accessToken 打印出来即成功。跑不通?看 9.1 建联失败类。

step3 建 WebSocket + 发 CLIENT_VOICE_CHAT_UPDATE 配置音频参数

建联 URL(Demo 已封装):

wss://ws.joyinside.com/soulmate/voiceChat/v1
  ?botId={botId}
  &sessionId={botId + uuid}     # 建议每次建连新生成
  &requestId={uuid}              # 一次 WS 建连唯一标识

Header:

Authorization: Bearer {accessToken}

建联后立即发 CLIENT_VOICE_CHAT_UPDATE 配置音频格式:

完整事件 JSON(点击展开)

json

{
  "mid": "f70e8955-8b39-4ae8-bba1-2bea4aa6c50b",
  "contentType": "EVENT",
  "content": {
    "eventType": "CLIENT_VOICE_CHAT_UPDATE",
    "eventData": {
      "audio": {
        "binary": true,
        "input": {
          "codec": "pcm",
          "sampleRate": "16000"
        },
        "output": {
          "codec": "opus",
          "sampleRate": "16000",
          "frameSizeMs": "40"
        }
      }
    }
  }
}

关键字段(最小闭环用这些就够,完整字段表见附录 B.3 事件协议明细):

字段	必选	取值	说明
`audio.binary`	否	true / false	true=二进制传输(推荐),false=base64 文本
`audio.input.codec`	是	pcm / opus	上行音频格式,默认 pcm
`audio.input.sampleRate`	是	16000 / 24000 / 32000	采样率,默认 16k
`audio.output.codec`	是	mp3 / pcm / opus	下行 TTS 格式,默认 mp3
`audio.output.sampleRate`	否	16000 等	默认 16k
`audio.output.frameSizeMs`	否	pcm: 60-120 / opus: 60 / mp3 不支持	TTS 帧长,opus 只能设 60,mp3 不可切分

⚠ CLIENT_VOICE_CHAT_UPDATE 每连接只发一次,否则对话被打断。一定要收到 SERVER_VOICE_CHAT_UPDATED(更新语音对话配置成功)事件才算配置成功。

step4 发音频 → 收 ASR → 收 TTS → 播放(第二阶段完成标志)

设备端一轮对话的完整时序:

发音频(用 Demo 自带 test.pcm):

发音频代码示例(Python,点击展开)

python

# 流式上传音频,每帧 ≤300ms(PCM)或 ≤480字节(Opus)
# 间隔 = 音频时长,均匀发送,否则回复延时异常
with open(PCM_FILE_PATH, 'rb') as f:
    while True:
        data = f.read(BYTES_PER_FRAME)
        if not data:
            break
        audio_base64 = base64.b64encode(data).decode('utf-8')
        params = {
            "mid": str(uuid.uuid4()),
            "contentType": "AUDIO",
            "content": {
                "audioBase64": audio_base64,
                "index": index
            }
        }
        ws.send(json.dumps(params))
        time.sleep(FRAME_MS / 1000)

播放 TTS 音频:收到 contentType: TTS 的事件后,解码 audioBase64 播放。

第二阶段验收:

☑ WebSocket 建联成功(收到 SERVER_VOICE_CHAT_UPDATED)
☑ 上传音频后收到 ASR 识别结果
☑ 收到 TTS 音频并能播放
☑ 听见云端回复的声音 ⭐ —— 第二阶段完成,接入就绪

3.4 跑不通?分层定位

接入分两阶段的优势在于:异常发生时可快速定位至具体阶段。按现象对照跳转:

现象	哪个阶段失败	跳转
预览调试都不通(语音/文本都没回复)	第一阶段(智能体搭建)	3.2 step1-5 检查应用/技能/设备配置
预览调试通,但 Demo getToken 失败	第二阶段(设备端·签名)	9.1 鉴权失败 1001-1006
getToken 成功,但 WS 建联失败	第二阶段(设备端·建联)	9.1 建联失败 400 TLS / 408 CRLF
WS 建联通,但发音频没回复	第二阶段(设备端·音频)	9.2 设备不说话/答非所问
有回复但 TTS 打不断	第二阶段(设备端·打断)	9.3 打断失效 TTS 打不断

下一步

接入完成后,可进一步:

理解协议细节:读第 4 章语音对话协议 —— 了解签名机制与事件处理逻辑的设计依据
适配硬件:读第 5 章设备端适配 —— 三种交互模式(全双工/按键/半双工)的声学要求
扩展业务场景:读第 6 章业务场景接入 —— 指令与控制、媒体资源、魔法打印、视觉对话
联调排错:读第 9 章故障排查 —— 按故障现象定位解决方案

第 3 章 JoyInside 接入预览 ​

3.1 JoyInside 接入全景 ​

接入全景图 ​

模块能力说明 ​

接入两个阶段 ​

3.2 智能体搭建并验证 ​

step1 注册企业(获取 vendorId) ​

step2 创建产品型号 ​

step3 创建应用 + 选择系统技能(获取 appId) ​

step4 注册一台测试设备(获取 botId) ​

step5 预览调试验证(第一阶段完成标志) ​

3.3 体验设备端接入 ​

step1 选一个 Demo + 填凭证 ​

step2 签名 + getToken(Demo 已实现,直接调用) ​

step3 建 WebSocket + 发 CLIENT_VOICE_CHAT_UPDATE 配置音频参数 ​

step4 发音频 → 收 ASR → 收 TTS → 播放(第二阶段完成标志) ​

3.4 跑不通?分层定位 ​

下一步 ​