场景接入
设备如何接入微信音视频通话？
了解设备、业务服务和微信小程序的分工，分开验证授权、呼叫提醒和媒体通话，避免把演示成功当成正式接入完成。
先回答：需要设备、小程序和业务服务一起接入
设备接入微信音视频通话，通常要通过微信硬件设备相关能力，由小程序承接用户授权与通话入口，再由业务服务协调用户、设备和呼叫关系。它不是给设备填入一个微信号就能拨打。本文以探鸽的微信 VoIP 方案与开源示例说明接入思路，正式开通条件以微信当前要求为准。
先分清体验与自己的产品上线
使用现成演示时，按照演示的绑定和授权步骤验证交互即可。自己的产品上线则要核对小程序与硬件设备相关能力、设备型号配置、服务域名和回调等条件。示例文档要求用已开通 IoT VoIP 能力的正式小程序验证完整流程，不能把测试号的运行结果当成完整验收。
三部分分别负责什么？
设备负责联网、呼叫动作和音视频采集播放；小程序负责用户身份、授权以及接听界面；业务服务维护用户与设备关系，处理呼叫事件与状态。使用 Ti RTC 时，它承担设备侧实时音视频连接与传输中的相应工作。小程序、业务服务和设备固件仍需要按照同一套业务流程配合。
按什么顺序联调？
建议先让设备在线并完成绑定，再确认目标微信用户已经授权。之后验证设备发起呼叫、用户收到提醒、接听后双向有声，以及双方都能结束通话。有视频能力时，再检查画面方向与比例。把每一步分开记录，可以判断问题发生在授权、消息通知还是媒体阶段。
收不到提醒和接通后无声，应分开排查
没有提醒时，先核对目标用户、授权关系、设备状态与业务事件日志；已经接通但无声时，重点检查两端采集、音频格式、媒体接收与播放。不要通过反复重新绑定来处理所有问题。拒接、取消、超时和断网，也都需要让两端回到一致状态，避免设备一直显示通话中。
能否保证任何时候都收到来电？
指南不应承诺所有手机、网络和微信状态下都能必达。建议用目标用户常见的手机、微信版本和网络验证通知及接听表现，并为设备离线、未授权、呼叫失败提供清楚反馈。正式发布所需能力和审核按微信当前官方说明执行，不在这里承诺审批时长。
最小联调：先跑通小程序呼叫设备
以下步骤按当前 ThingConnect 参考实现整理。先确认小程序已配置 wmpf-voip 插件，用户登录并绑定设备，设备正式 MQTT 在线；再完成能力上报和微信授权。普通设备绑定与微信通话授权是不同步骤。
设备启动后调用 POST /v1/device/profile，上报真实音频采样率、声道、编码及是否支持视频。视频设备还需核对屏幕尺寸与下行画面配置，媒体能力变化后重新上报。
小程序通过 wx.login 与业务登录接口建立微信用户身份，再用 wx.getDeviceVoIPList 同步微信侧已有授权。
首次授权前设置设备名称，获取 sn-ticket，调用 wx.requestDeviceVoIP；成功后调用 report-auth，把同一设备名称和授权结果同步到服务端。
小程序调用插件 callDevice。服务端收到微信回调后，向设备 cmd 主题下发 call_incoming；设备先回 ACK，再按本地状态决定接听或拒接。
接听时完整传递本次 peer_id 和 token 给 TiRtcWhipConnect。确认连接回调和本实现要求的接通事件，再启动媒体并验证两个方向的声音。
媒体配置应填什么，哪些不能直接照抄？
audio_rate 和 audio_channels 要匹配设备接收语音的实际格式；up_video_mt、down_video_mt 分别表示上下行视频能力；no_video=true 表示按纯音频处理。不能因为示例 JSON 填了 640×480 就把无屏设备也配置成同样能力。
需要下行 MJPEG 适配屏幕时，fit_screen 用于等比缩小且不裁剪，fill_screen 用于填满屏幕并可能裁剪；后者要求有效的偶数屏幕尺寸。画面缩放与旋转是不同配置。先跑通纯音频，再按目标硬件增加视频，能减少首次联调的变量。
设备主动呼叫微信，与接听有什么不同？
先通过 GET /v1/voip/device/contacts 读取当前有效微信联系人，再向 POST /v1/voip/device/call 发起呼叫。HTTP 返回成功只说明请求被接收，之后仍需等待 MQTT call_incoming，使用该次会话的连接信息继续建连。微信联系人与设备互呼联系人是两套数据，不能混用。
授权状态不一致时怎样处理？
wx.getDeviceVoIPList 中存在设备且 status=1：按已授权处理，并核对服务端记录。
设备仍在列表但提醒已关闭：引导用户在小程序设置的“语音、视频通话提醒”中开启，不能假定再次调用接口一定弹出授权框。
查询接口失败：状态是未知，不要直接删除现有授权或显示“用户已取消”。
收到 callers_update：重新拉取联系人；刷新失败保留上次缓存，刷新成功再替换。
把结束通话也纳入首次验收
至少分别测试用户取消等待、设备拒接、无人接听超时、任意一方挂断和断网。结束后确认媒体停止、连接释放、界面返回可操作状态；马上发起第二次呼叫，检查旧房间迟到消息不会结束新会话。错误码 9 只能说明微信授权不可用，不能推断用户主动取消。
按三个阶段定位“呼叫没有接通”
下面以 ThingConnect 当前参考实现为例，不代表所有微信音视频 SDK 都使用相同接口。第一阶段是业务呼叫与 MQTT 来电；第二阶段是设备使用本次 peer_id 与 token 建立媒体连接；第三阶段是收到接通确认后启动媒体。分别记录这三个阶段，可以避免把业务接口成功当作通话成功。
TiRtcWhipConnect 返回 0 只表示请求已提交；连接回调 error == 0 表示连接成功。当前 C 参考实现随后等待 0x2000，再启动本地媒体。应按这套实现的状态和事件处理，不要在提交请求后就把界面改成“通话中”。
设备在线，为什么仍收不到微信来电？
先检查设备是否完成正式 MQTT 上线，再确认已经上报 POST /v1/device/profile。当前示例把媒体能力上报作为收到 call_incoming 的前提。还要检查微信用户的授权关系及小程序侧结果。仅看到网页上的在线标记，不能证明微信授权、能力上报和来电消息都已完成。
已经接听但没有声音，先检查什么？
先核对是否收到接通确认，再分别检查上行采集与编码、下行接收与播放。Linux C 示例的默认播放 sink 不等于已经接入真实扬声器，移植时需要实现播放链路。采样率、声道和编码格式应与上报及实际媒体一致。测试时只开一个方向，确认后再交换方向，避免把两个问题混在一起。
取消和挂断有哪些容易遗漏的情况？
当前示例中，设备在未进入媒体房间时结束本地外呼等待，不保证微信端立即停止振铃。已经建立通话后，结束处理需要覆盖业务层 call_cancel 和媒体层 0x2001；不能只监听其中一个。还要核对消息属于当前房间，避免旧会话迟到的结束通知关闭新通话。
遇到凭证错误，先检查完整性
文档记录了连接字符串在固定长度缓冲区中被截断的情况。遇到 -40012 等服务端错误时，可检查 peer_id 和 token 在解析、缓存、传递时是否完整，以及是否属于本次会话；不能仅凭错误码就认定一定是截断或一定是服务端故障。日志记录长度与错误阶段即可，不输出完整凭证。
下一步：先验证场景，再做正式集成
门铃、看护和穿戴设备的共同需求是联系到合适的人，但发起方式、接听权限和失败后的处理可能不同。先写清“谁发起、谁接听、无人接听怎么办”，再对照集成文档实现。微信通话也不能仅凭普通音视频体验成功或领取 RTC ID 就视为自动开通。
资料核对：2026 年 11 月 7 日。本文提供接入思路；接口、板卡支持与平台条件请以所链接文档的当前版本为准。
视频参考：开发板与微信语音通话
探鸽智能提供了开发板微信语音通话的演示入口。观看时可结合上文区分呼叫、接听与媒体建立；正式接入仍需核对设备能力、授权关系和当前接口文档。