微信VoIP通话

中文

English

中文

English

业务前置说明 ​

微信 VoIP 通话涉及小程序、业务服务端、探鸽云平台、设备端四方交互。在开通小程序 VoIP 权限后，需先明确各平台能力边界，再分别完成业务服务端、小程序端、设备端的对接开发

整体业务流程 ​

完整通话生命周期流程统一如下：

  1. 小程序完成设备来电呼入权限申请、用户授权绑定；
  2. 任意一端（小程序/设备）发起通话呼叫；
  3. 被叫未接听、处于振铃阶段时，主叫可中止本次呼叫；
  4. 被叫收到来电后，支持接听或拒接处理；
  5. 双方接听成功后，进入同一RTC通话房间，建立双向音视频对讲链路；
  6. 通话过程中任意一端可挂断，终止本次通话会话、释放媒体与房间资源。

各平台能力与开发分工 ​

微信平台能力 ​

  1. 提供官方 VoIP 通话插件，支撑小程序快速集成设备对讲、来电振铃、通话页面能力；
  2. 提供设备VoIP授权、呼叫回调、前台通话状态管理等基础能力。

探鸽云平台能力 ​

  1. 提供标准 RTC 音视频传输通道，支撑双向实时流收发；
  2. 提供 RTC 命令信令通道，透传接通、挂断等控制指令；
  3. 提供设备侧标准接口：来电拒接、进房通话、关键帧请求、媒体订阅等能力；
  4. 统一维护 cmdw=0x2000（接通）、cmdw=0x2001（挂断）信令机制。

业务服务端（自行开发） ​

所有业务层呼叫状态透传、设备联动、业务逻辑均由自研服务端实现，具体能力如下：

  1. 对外提供接口，接收微信平台呼叫相关回调通知；
  2. 维护与设备端的长连接通道，作为业务信令中转链路；
  3. 向下透传小程序侧业务指令：发起呼叫、中止呼叫；
  4. 接收设备侧拒接、状态回调，同步推送至小程序端；
  5. 管理呼叫生命周期：振铃、待接听、通话中、已挂断、已中止。

开发指引：集成业务服务端

设备端（自行开发） ​

  1. 集成探鸽云 RTC SDK，完成 SDK 初始化、启动、连接管理；
  2. 实现音视频采集、编码与 RTC 流发送/接收能力；
  3. 主动发起呼叫、调用 TiRtcWhipConnect 加入对讲房间；
  4. 来电状态处理：未接通时拒接呼叫、振铃阶段中止呼叫；
  5. 通话态处理：接听建立媒体链路、主动挂断终止通话、释放资源；
  6. 监听 on_command 信令，同步接通、挂断、异常结束状态。

开发指引：集成设备端

小程序端（自行开发） ​

  1. 集成微信官方 VoIP 通话插件，实现来电振铃、通话页面、音视频通话基础能力；
  2. 完成小程序登录，获取用户 openid，引导用户完成设备来电权限授权，并将用户 - 设备授权关系上报至业务服务端绑定存储；
  3. 发起呼叫时调用业务服务端接口发起通话请求；被叫尚未接听、处于振铃阶段可再次调用服务端接口，下发中止呼叫指令，终止本次呼叫流程。

开发指引：集成微信小程序

场景一：小程序主动呼叫设备 ​

小程序呼叫设备 — 时序概览

呼叫发起阶段 ​

  1. 小程序发起呼叫
    • 基于微信小程序官方 VoIP 插件能力发起通话，接口规范参考：微信官方文档。
  2. 小程序主动中止呼叫（被叫未接听前）
    • 小程序调用自研业务服务端中止呼叫接口，由业务服务端下发中止呼叫指令至设备端，该信令转发逻辑需要业务方自主开发实现。
  3. 设备端拒接来电
    • 设备收到呼叫请求后如需拒接，通过探鸽云 SDK 调用服务请求接口： TiRtcServiceRequest("/v1/wxvoip/reject", ...) 向小程序推送拒接通知。
    • 入参 hangup_reason 字段值参考 微信VoIP通话命令 取值遵循微信 VoIP 通话信令规范：忙线 = 5、用户主动拒接 = 7；
    • 注意：本接口用于来电未接通前拒接场景，不可与通话中挂断信令（cmdw=0x2001）混用。

通话中通用规则（双向呼叫共用） ​

通话中 — 媒体与挂断

媒体流传输约定 ​

通话接通后，基于现有 RTC 连接按照《实时收发音视频》文档传输音视频数据。

  • 音频流：stream_id = 0
  • 视频流：stream_id = 1

接通判定与实现逻辑 ​

设备调用 TiRtcWhipConnect 加入 RTC 房间成功后，会收到信令 cmdw=0x2000，代表双方对讲建立成功。振铃阶段即为待接听状态。

  1. 设备作为被叫（小程序主叫） 设备收到 call_incoming 后调用 TiRtcWhipConnect 加入 RTC 房间，连接成功后收到 cmdw=0x2000，双方对讲建立成功。
  2. 设备作为主叫（呼叫小程序） 设备收到服务端下发的 call_incoming 后调用 TiRtcWhipConnect 加入 RTC 房间，连接成功后收到 cmdw=0x2000 双方对讲建立成功；此时房间已由微信侧建立，直接进入对讲状态。

挂断流程规范 ​

  1. 设备端主动挂断 设备端通过命令通道TiRtcSendCommand下发挂断信令:（cmdw=0x2001）通知小程序结束通话。
  2. 小程序端主动挂断 设备监听（on_command）回调，接收小程序下发的挂断信令（cmdw=0x2001）执行通话释放、房间退出逻辑。

场景二：设备主动呼叫小程序 ​

设备呼叫小程序 — 时序概览

接通流程 ​

  1. 设备调用业务服务端 POST /v1/voip/device/call，服务端内部调微信 iot/voip/call 发起呼叫；
  2. 小程序振铃，用户接听后微信服务器回调 join_voip_room；
  3. 业务服务端处理回调后通过下行通道推送 call_incoming 至设备；
  4. 设备收到后调用 TiRtcWhipConnect 加入 RTC 房间，连接成功后收到 cmdw=0x2000 进入对讲状态；此时房间已由微信侧建立，直接开始音视频对讲；
  5. 设备监听 on_command 指令回调，用于接收对端挂断信令（cmdw=0x2001）；用户未接听前，小程序持续来电振铃。

中止呼叫（设备主动取消呼叫） ​

设备需调用自研逻辑向业务服务端上报呼叫中止请求，由服务端推送取消来电通知给小程序，小程序停止振铃，本次呼叫结束。

补充通用约束说明 ​

  1. 接通前：仅支持「中止呼叫、来电拒接」；接通后仅支持双向挂断，两类场景接口、信令不可混用；
  2. 所有跨端信令转发（呼叫、中止呼叫）依赖业务服务端透传，探鸽云仅提供设备侧 SDK 信令上报与下发能力；
  3. 两种呼叫场景共用同一套音视频流规则、接通 / 挂断信令，仅呼叫发起、来电拒接阶段业务流程存在差异；
  4. 主叫方可在 payload 中传入自定义字段（如 wxa_from 标识主叫方、call_id 标识唯一呼叫），微信与探鸽云全程透传、不做解析。设备端据此区分来电是小程序发起还是设备回铃。

参考实现 ​

tirtc-server-example 是基于本文档及探鸽云 SDK 开发的开源参考项目，完整演示了微信 VoIP 通话的四方交互实现，可作为自研开发的起点：

模块说明
voip-server业务服务端（Go）：对接微信回调、调用探鸽云 Token 接口、MQTT 设备下行通道
device-sim-c / device-sim-py设备端模拟器（C / Python）：WHIP 建连、信令收发、G.711a 音频推流
weixin-mini-program微信小程序：VoIP 插件集成、设备授权绑定、通话页面
user-server / device-server用户与设备管理服务（Go）：登录、绑定、MQTT 凭证签发

设备与业务服务端之间通过 MQTT 长连接通信，ClientID 为 sn_{device_id}，主要 Topic：

TopicQoS说明
device/sn_{device_id}/cmd1指令通道：call_incoming（来电通知，设备需回复 ACK）
device/sn_{device_id}/notify1通知通道：call_cancel（取消呼叫）、callers_update（授权变更）

项目完整覆盖了本文档描述的两种呼叫场景（小程序主叫 / 设备主叫）、来电拒接、通话中挂断、音频收发等流程，可直接运行和调试。

微信VoIP通话

Copyright © 2025