JoyInside 接入手册

主题

H. RTC 协议参考 ​

面向 JRTC 链路的协议参考：实时交互时序、鉴权 Token 获取、房间初始化、上下行事件一览及 SDK 使用文档。

协议边界：本附录说明 JoyInside 侧 HTTP 接口与业务事件，时序图展示进房、音视频交互及退房流程；SDK 具体调用与媒体配置请参考 H.5 SDK 使用文档 。

H.1 链路与实时交互时序 ​

接入步骤总览 ​

步骤操作参考
1. 准备接入凭证准备 AccessKey、签名所需的密钥及 vendorId；密钥仅用于服务端签名，不下发到应用端4.1 签名算法
2. 获取鉴权 Token调用 /auth/getToken，获取后续房间初始化请求使用的 accessTokenH.2 环境、鉴权与 Token
3. 初始化房间携带 accessToken 调用 /device/rtc/registerAndGetRoom，获取房间信息和 RTC 鉴权参数H.3 初始化房间
4. SDK 进入房间准备 SDK 所需参数，调用 JRTCEngine.joinRoom(...)，等待 onJoinRoomSuccess 回调确认进房成功H.5 SDK 使用文档
5. 开启实时交互配置语音对话，发布与订阅音视频，收发业务事件并展示文本或播放语音H.4 业务事件协议

实时交互时序 ​

参与方功能模块
App应用端
JRTC SDK客户端 SDK
JoyInside 服务Token 鉴权、房间初始化、业务事件收发

进房接口：JRTCEngine.joinRoom(connection, authInfo, configInfo, options)，参数依次为房间连接、鉴权信息、房间配置和媒体选项。

H.2 环境、鉴权与 Token ​

环境JoyInside API 域名
生产https://api.joyinside.com
预发https://uat-api.joyinside.com

H.2.1 V2 签名算法 ​

签名算法及示例参考 4.1 Token 鉴权-签名算法。

H.2.2 获取鉴权 Token ​

参考 4.1 Token 鉴权-获取访问令牌，本链路使用 vendorId 获取鉴权 Token，其中 accessToken 即访问令牌，用于后续 RTC 房间初始化请求。

getToken 接口：

项值
URLhttps://api.joyinside.com/auth/getToken
方式POST
作用用签名获取 Token

请求参数：

Body

字段必选说明
accessKeyId是AccessKey
accessTimestamp是13 位毫秒时间戳（与服务端时间误差 ≤5min）
accessNonce是随机数（防重放）
accessVersion是固定 V2
accessSign是签名，参见 4.1 Token 鉴权-签名算法
vendorId是厂商唯一标识，RTC 房间初始化前使用 vendorId 获取鉴权 Token

请求示例

完整请求示例（点击展开）
shell
curl --location 'https://api.joyinside.com/auth/getToken' \
--header 'Content-Type: application/json' \
--data '{
    "accessVersion": "V2",
    "accessTimestamp": "1791948159496",
    "accessNonce": "{本次请求随机数}",
    "accessKeyId": "{AccessKey}",
    "accessSign": "{签名结果}",
    "vendorId": "{vendorId}"
}'

示例中的时间戳、随机数和签名需在每次请求时重新生成。

响应参数：

字段说明
accessToken访问令牌，有效期 8 小时
expireIn访问令牌剩余有效时间（秒）
refreshToken刷新令牌，有效期 7 天
refreshExpireIn刷新令牌剩余有效时间（秒）
code状态码
msg状态信息

响应示例

完整响应示例（点击展开）
json
{
  "accessToken": "ehuc2065edbru==",
  "expireIn": 7200,
  "refreshToken": "cjekcnlsjfekncejh==",
  "refreshExpireIn": 604800,
  "code": 0,
  "msg": ""
}

accessToken 用于 JoyInside 前置接口鉴权，rtcToken 用于 JRTC 进房，两者不可互换。

H.3 初始化房间 ​

registerAndGetRoom 接口：

项值
URLhttps://api.joyinside.com/device/rtc/registerAndGetRoom
方式POST
作用初始化房间，获取房间信息及进房凭证

请求参数：

Body

字段类型必选说明
vendorIdstring是厂商唯一标识
productIdstring是产品唯一标识
deviceIdstring是厂商保证唯一的设备标识，建议设备 SN
typestring是固定 PHYSICAL_ROBOT，生产设备
namestring是设备名称
requestIdstring是每次重新建连生成新的 UUID，用于追踪本次连接
sessionIdstring是短期记忆/对话上下文标识，可在一次建连中新设，也可跨建连复用
uidstring是用户唯一标识，不超过 128 字节
rtcTypeinteger是固定 1，JRTC
modeinteger是固定 1，JoyAI Interaction 服务

请求示例

完整请求示例（点击展开）
json
{
  "vendorId": "{vendorId}",
  "productId": "{productId}",
  "deviceId": "{设备SN}",
  "type": "PHYSICAL_ROBOT",
  "name": "RTC设备",
  "requestId": "{本次建连UUID}",
  "sessionId": "{会话ID}",
  "uid": "{用户ID}",
  "rtcType": 1,
  "mode": 1
}

响应参数：

字段类型说明
statestring响应结果，成功示例为 SUCCESS
codestring响应结果码，成功示例为 0000
msgstring错误信息
dataobject响应数据，按原始 JSON 示例整理
data.botIdstringJoyInside 设备 ID
data.roomIdstringRTC 房间 ID
data.rtcTokenstringRTC 进房 Token
data.noncestringRTC 生成房间的随机数
data.timestampstringRTC 生成房间的时间戳

响应示例

完整响应示例（点击展开）
json
{
  "state": "SUCCESS",
  "code": "0000",
  "msg": null,
  "data": {
    "botId": "{botId}",
    "roomId": "{roomId}",
    "rtcToken": "{rtcToken}",
    "nonce": "{nonce}",
    "timestamp": 1791948159496
  }
}

H.4 业务事件协议 ​

H.4.1 上下行事件一览表 ​

上行事件（设备端 → 云端） ​

事件名contentType触发时机协议明细
CLIENT_VOICE_CHAT_UPDATEEVENT建连后发一次，配置音频/音色/角色B.4.2

下行事件（云端 → 设备端） ​

事件名contentType触发时机协议明细
CFG_BOT_EVENTEVENT建连成功后下发默认配置B.4.1
SERVER_VOICE_CHAT_UPDATEDEVENT配置更新成功响应B.4.2
ASRASR语音识别结果B.4.3
EMPTY_CONTENTEVENT未识别到有效输入（拒识）B.4.5
COMPLETEEVENT当轮对话完成B.4.5
TTS_SENTENCE_STARTEVENT音频字幕（先于 TTS 下发）B.4.6
TTS_COMPLETEEVENTTTS 音频全部下发完成B.4.6
CALL_AGENT_INTERRUPTEDEVENT打断事件（端侧需清空播放队列）B.4.7
USER_AUDIT_FAILEVENT审核命中B.4.11

H.5 SDK 使用文档 ​

请根据项目的平台需求，选择对应的 SDK 使用文档。

平台参考文档
AndroidAndroid SDK 使用文档
iOSiOS SDK 使用文档

下一步 ​