如何对接虚拟数字人开放平台的通用WebSocket服务_虚拟数字人(DVH)-阿里云帮助中心

本文档向您介绍如何对接虚拟数字人开放平台的通用WebSocket服务，适用于互动数字人这类需要通过WebSocket来持续传输语音流数据的产品服务。

建立WebSocket连接

开发者可以通过js、java、python等支持标准websocket协议的语言作为WebSocket客户端与虚拟数字人开放平台WebSocket服务端进行连接。

1. URL与鉴权

wss://avatar-im.console.aliyun.com/ws?t=${token}&tenant=${tenantId}&app=${appId}

参数解释：
  - token通过StartInstance返回值中的Token获取（非Channel中的Token）
  - tenantId通过虚拟数字人开放平台的应用中的开发者信息获取（同调用StartInstance中的tenantId）
  - appId通过虚拟数字人开放平台的应用中的开发者信息获取（同调用StartInstance中的appId）

2. 连接建立成功与断开

在客户端成功与ws建立连接之后，服务端在收到异常信息时可能会主动断开与客户端的连接，此时会在断开连接之前给客户端下发一个连接断开消息，通知客户端连接被断开以及断开的原因。

建连断开消息协议：
   消息内容：2{"reason":"CONNECTION_TIMEOUT"}
      2表示是连接断开消息，2后面的JSON为断开原因，具体有：
          {"reason":"CONNECTION_TIMEOUT"}    //会话超时连接断开
          {"reason":"CONNECTION_KICK_OUT"}   //连接踢除断开
          {"reason":"HEARTBEAT_TIMEOUT"}     //心跳超时连接断开
          {"reason":"SERVER_CONNECTION_CLOSED"} //服务器异常引起的连接断开
   消息格式：Text类型的DataFrame（字符串，编码：UTF-8）

重要

在收到服务端下发的连接断开消息之后，WebSocket将会自动断开，此时客户端可以重新发起建立连接（如果需要的话）；另外如果客户端在收到连接断开消息之后，WebSocket没有自动断开，此时客户端可以主动进行连接断开（可能由于网络问题无法立即断开）。

3. 发送心跳包（可选）

客户端在与服务端成功建立连接之后可以通过周期性的发送心跳包来维持与服务端之间的连接，如果客户端本身会持续发送消息（如互动数字人会需要持续发送音频包），那么就不需要周期性再发送心跳包。如果客户端长时间没有发送任何消息或者心跳包，服务端会主动断开客户端的连接，此时客户端会收到一条消息内容为2{"reason":"HEARTBEAT_TIMEOUT"}的消息，然后连接会被强制断开。

心跳包消息协议：
   消息内容：3
   消息格式：Text类型的DataFrame（字符串，编码：UTF-8）

服务端在收到客户端发送的心跳包之后会主动给客户端发送一条心跳包回执消息。

心跳包回执消息协议：
   消息内容：4
   消息格式：Text类型的DataFrame（字符串，编码：UTF-8）

重要

心跳包发送间隔建议设置为30s发送一次，服务端最长60s收不到客户端发送的消息就会主动断开客户端的连接，客户端发送业务消息和心跳消息都会认为发送了消息，从而不会被主动断开。

4. 发送&接收业务消息

说明

业务消息指的是不同于建连、断开、心跳、心跳回执这类系统消息，是代表有业务意义的消息，如互动数字人的语音流消息，以及互动数字人返回的ASR文本消息。

消息格式：

业务消息协议：
   消息内容：
   5{
      "messageId": "<messageId>", // 必传，消息id，需要保证唯一，可以直接生成16位随机数
      "receiverId": "<receiverId>", // 必传，固定值，不同产品功能对应值不同，请结合具体产品功能接入方案传递
      "content": {
        // JSON格式，不同产品功能对应值不同，请结合具体产品功能接入方案传递
      }
    }
   消息格式：Text类型的DataFrame（字符串，编码：UTF-8）

说明

具体消息内容是5后面的文本，格式根据不同的产品能力会有不同的要求，具体请参考对应产品能力的接入文档获取，messageId是统一要求，必填，且需要唯一，可使用时间戳+随机数方式生成。

接收方在收到发送方的消息之后需要发送一个回执给到接收方，如：客户端发送消息给服务端，服务端收到消息则会立即给客户端发送一条回执消息；同理，服务端发送消息给客户端，客户端收到消息之后也需要立即发送一条回执消息（该回执消息需要在处理消息之前立即发送，避免服务端误判客户端没有收到消息而导致重复发送该条消息）。回执消息格式：

业务消息协议：
   消息内容：6{"messageId":"msg_1659937198426_687"}
   消息格式：Text类型的DataFrame（字符串，编码：UTF-8）

回执消息会带上对应消息的messageId，发送方可以根据是否收到回执消息才判断接收方是否成功接收到消息，如一定时间内未收到回执（如3s），发送方可重新发送该消息（保持messageId不变）。