常见呼叫失败原因

设备呼叫小程序, 业务服务端调用微信 /wxa/business/iot/voip/call 失败

确认设备是否提交微信审核通过。否则，不能呼叫正式版。可以呼叫体验版小程序，

错误码参考: 微信 微信VoIP插件错误码

以官方文档为准，但其错误码不全。

这是我们收集的一些错误码，供参考

后台返回错误码

errCode	描述
1	roomId 错误
2	设备 deviceId 错误
3	voip_id 错误
4	voipToken 错误（刷脸模式）
5	生成微信VoIP通话房间错误
7	openId 错误
8	openId 未授权（刷脸模式）
9	openId 未授权设备（硬件模式），或不是 userId 联系人（刷脸模式）
12	小程序音视频能力审核未完成，正式版中暂时无法使用
13	硬件设备拨打微信，voipToken 错误
14	微信拨打硬件设备，voipToken 错误
15	欠费
17	voipToken 对应 modelId 错误
19	openId 与小程序 appId 不匹配（同一用户在不同小程序的 openId 不同）
20	openId 无效
22	传入的 chargeType 非法
23	当前设备 license 已过期
24	当前设备未激活 license
31	设备未审核，不能呼叫正式版
-202	开发者服务器收到回调消息没有正常回复
61007	服务端模式下小程序授权问题
10008	一般是 sn_ticket 过期

微信回调接口返回 errcode != 0 是否会结束通话

不会。

只要呼叫发起接口调用成功并进入微信侧振铃流程，微信服务器回调接口返回 errcode != 0 不会直接结束这次通话。

部分较早的微信文档中有“若 errcode 非 0 则不会响铃、通话取消”的描述，当前实际行为不遵循该规则。

两个微信用户同时呼叫同一个设备冲突

微信平台不支持多个用户同时呼叫同一个设备。两个微信用户呼叫同一个设备时，呼叫会相互干扰，可能出现以下现象：

CASE 1：设备在振铃期间收到第二个呼叫

1. A 用户呼叫设备，设备振铃中；
2. B 用户呼叫设备，设备拒接；
3. 之后设备接听 A 用户的呼叫，但无法接通。

CASE 2：设备在通话期间拒接第二个呼叫

1. A 用户呼叫设备，设备接听，通话正常进行；
2. B 用户呼叫设备，设备拒接；
3. 之后 A 用户的通话会中断。

CASE 3：设备在通话期间忽略第二个呼叫

1. A 用户呼叫设备，设备接听，通话正常进行；
2. B 用户呼叫设备，设备忽略该呼叫，B 用户保持振铃且不进行操作；
3. 设备收到 B 用户的呼叫通知约 30 秒后，A 用户的通话中断。

可以在发起呼叫前检查设备是否空闲。建议根据业务接口设计选择以下方案之一：

• 方案一（推荐）：小程序调用业务服务端的“发起呼叫”接口；业务服务端先查询设备状态，仅在设备空闲时继续发起呼叫，否则向小程序返回设备忙。
• 方案二：小程序先调用业务服务端提供的“设备是否空闲”接口；该接口由业务服务端代理调用 GET /v1/device/wxvoip-call-status。确认空闲后，小程序再请求业务服务端发起呼叫。

/v1/device/wxvoip-call-status 是需要 TGV1 应用凭证鉴权的服务端 API。小程序不能直接调用该接口，也不能保存 access_id、secret_key 等服务端凭证。

业务服务端还可以按 device_id 对发起呼叫请求做短时间串行化或分布式互斥，进一步缩小并发竞争窗口。这是一项可选的增强措施。

上述方案存在以下局限：

• 只要两个呼叫都已经发起，两个小程序同时处于振铃中，后续就会产生冲突，即使发起呼叫时设备确实处于空闲状态。
• 通话状态的上报和清理存在延迟，既无法百分之百避免同时发起呼叫，也可能在短时间内将空闲设备误判为通话中。
• 状态查询与实际发起呼叫不是原子操作，并发请求仍可能同时查询到设备空闲。

我们推荐上述方案, 是因为它们可以解决大多数的冲突场景。 理论上需要判断设备是否正在被小程序呼叫来制止小程序发起呼叫，但维护设备是否正在被小程序呼叫可能引入更多的问题。

如何让设备收到正向的下行视频流，而不是旋转了 90 度的？

要让设备收到 0° 正向下行视频流，需要微信侧编码 0° 流，并由设备侧选择订阅该流。微信版本须高于 8.0.54，VoIP 插件版本须不低于 2.4.5，前端小程序建议增加版本判断逻辑。不同呼叫方向的微信侧配置入口不同，详细说明请参考微信官方文档：VoIP 视频流指南。

小程序呼叫设备

小程序调用微信 VoIP 插件的 callDevice 时，将 encodeVideoRotation 设置为 1：

const { roomId } = await plugin.callDevice({
  roomType: 'video',
  sn: deviceId,
  modelId,
  encodeVideoRotation: 1,
});

设备呼叫小程序

业务服务端调用微信 POST /wxa/business/iot/voip/call 发起呼叫时，通过 query 将 encodeVideoRotation 设置为 1：

POST https://api.weixin.qq.com/wxa/business/iot/voip/call?access_token=<ACCESS_TOKEN>

{
  ..., // 其他字段
  "query": "encodeVideoRotation=1"
}

收到 join_voip_room 后签发设备通话凭证

无论谁发起呼叫，业务服务端收到微信 join_voip_room 通知后，在调用 POST /v1/token/wxvoip 签发 peer_id 和 token 时，在请求参数中增加 down_video_rotation：

{
  ..., // 其他字段
  "down_video_rotation": 1
}