帮你快速理解、总结文档立即下载
文档中心>物联网开发平台>通用功能（应用端）>微信通话>设备呼叫小程序

设备呼叫小程序

最近更新时间：2026-09-20 16:47:02
我的收藏

本页目录：

TWeCall 是腾讯云物联网开发平台提供的设备与微信小程序之间的双向音视频通话能力。设备端一键呼叫后，微信通过「服务通知」强提醒用户，点击即可进入通话，达到微信原生通话体验。
本文将介绍小程序端如何接入 TWeCall（微信通话），实现接听设备端发起的音视频呼叫，帮助您快速完成设备呼叫微信场景的小程序端接入。

前提条件

已完成 集成与登录 文档中的登录功能，小程序成功登录。
已在物联网开发平台完成 TWeCall 服务激活与小程序授权，详见 开通微信通话服务。
已完成小程序的硬件设备接入并获取 model_id：在小程序管理后台的设置 > 基本设置 > 服务类目中添加「工具 > 设备管理」类目，然后在功能 > 硬件设备中添加设备，审核通过后平台在设备管理列表分配 model_id。详细流程请参见 开通服务 的 小程序申请硬件能力 章节及微信官方 硬件设备接入指引。

接入流程

小程序端接入分为以下四步：
1. 绑定设备到家庭：设备须先归属某个家庭，才能对该设备发起呼叫。
2. 接入 wmpf-voip 插件：通话接听页由微信官方 wmpf-voip 插件承载。
3. 注册 VoIP 通话权限：为指定设备完成微信侧授权，授权后设备才能呼叫当前用户。
4. 查询与管理授权状态：查询设备已授权的用户，或注销设备的 VoIP 通话权限。

接入步骤

步骤 1：绑定设备到家庭

用户使用 TWeCall 前，需要先把设备绑定到家庭中。绑定凭证为设备绑定签名（deviceBindSignature），由设备配网流程或设备机身二维码提供，详细绑定流程请参见 设备绑定。
const plugin = requirePlugin('tx-iot-sdk');
const engine = plugin.TXIoTEngine.getInstance();
const familyManager = engine.getFamilyManager();
const deviceManager = engine.getDeviceManager();

// 1. 获取家庭列表；首次使用可先通过 createFamily 创建家庭
const families = await familyManager.getFamilyList();
const familyId = families[0]?.familyId;

// 2. 使用设备绑定签名将设备绑定到家庭
// deviceBindSignature 由设备配网流程或扫描设备机身二维码获取
const deviceBindSignature = 'YOUR_DEVICE_BIND_SIGNATURE';
const deviceInfo = await deviceManager.bindDevice(familyId, deviceBindSignature);
绑定成功后，设备会出现在 getDeviceList 的返回结果中。相关接口说明请参见 getFamilyList, createFamily, bindDevice。

步骤 2：接入 wmpf-voip 插件

接听 UI 由微信官方 wmpf-voip 插件（AppID：wxf830863afde621eb）的通话页承载，宿主小程序需在 app.json 中声明插件：
{
  "plugins": {
    "wmpf-voip": {
      "version": "latest",
      "provider": "wxf830863afde621eb"
    }
  }
}
在小程序启动时（如 App 的 onLaunch 中）对插件进行初始化：
const wmpfVoip = requirePlugin('wmpf-voip').default;

// 接听页 UI 定制（按需配置）
wmpfVoip.setUIConfig({
  // ...
});

// 通话结束后跳转的宿主小程序页面路径
wmpfVoip.setVoipEndPagePath({
  url: '/pages/call-end/call-end',
  key: 'Call',
});

// 监听通话事件
wmpfVoip.onVoipEvent((event) => {
  console.log(event.eventName, event);
});

步骤 3：注册微信 VoIP 通话权限

设备只能呼叫已完成微信 VoIP 授权的用户。注册流程分为三个子步骤，需依次完成。

3.1 获取授权票据

调用 requestVoIPSnTicket 获取设备的 SN 与 snTicket（授权票据）：
const deviceManager = engine.getDeviceManager();

// deviceId：设备标识，productId / deviceName 为物联网开发平台上的产品 ID 与设备名称
const deviceId = { productId: 'YOUR_PRODUCT_ID', deviceName: 'YOUR_DEVICE_NAME' };
// modelId：微信公众平台「设备接入」分配的 model_id
const modelId = 'YOUR_MODEL_ID';
// appId：当前宿主小程序的 AppID
const appId = 'YOUR_MINIPROGRAM_APPID';

const { sn, snTicket } = await deviceManager.requestVoIPSnTicket(deviceId, modelId, appId);

3.2 拉起微信授权弹窗

使用上一步获取的票据调用 wx.requestDeviceVoIP，拉起微信侧授权弹窗。该接口为微信原生 API，必须由宿主小程序在小程序上下文调用（插件上下文无此 API）：
wx.requestDeviceVoIP({
  sn,
  snTicket,  // 第 3.1 步获取，5 分钟内有效
  modelId,
  deviceName: "设备名称",  // 授权弹窗中显示的设备名，不超过 13 个字符
  success(res) {
    console.log('requestDeviceVoIP success:', res);
    // 授权成功，继续执行第 3.3 步完成授权登记
  },
  fail(err) {
    // errCode 10001 表示用户此前已授权，可视为成功
    console.error('requestDeviceVoIP fail:', err);
  },
});
注意：
用户拒绝过授权后，再次调用 wx.requestDeviceVoIP 不再弹窗，须引导用户到小程序设置页手动开启。
用户删除小程序后重新打开，授权状态会失效，需要重新执行本步骤。查询设备的授权状态参见步骤4中的 查询小程序已授权的设备。

3.3 添加到设备的联系人列表中

微信侧授权成功后，调用 registerVoIPNotificationForDevice 将当前用户的微信 OpenID 添加到设备的联系人列表中，完成授权闭环：
// wxOpenId：当前用户的微信 OpenID
const wxOpenId = 'USER_WX_OPENID';

await deviceManager.registerVoIPNotificationForDevice(deviceId, modelId, appId, wxOpenId);
授权登记成功后，设备端即可发起呼叫，呼叫到达时微信会弹出「服务通知」提醒用户接听。

步骤 4：查询与管理授权状态

查询设备联系人列表

调用 getAuthorizedVoIPUserList 获取允许呼叫对应设备的微信用户 OpenID 列表，设备端 SDK 不允许呼叫联系人列表以外的用户：
const openIds = await deviceManager.getAuthorizedVoIPUserList(deviceId);
const isInContactList = openIds.includes(wxOpenId);

查询微信授权的设备列表

调用 wx.getDeviceVoIPList 获取哪些设备允许通过微信 VoIP 呼叫当前用户。小程序被删除后再重新打开，已授权的设备会被清空。通过判断设备是否在本列表中，决定是否要重新执行步骤3。
const wxAny = wx as any;
if (typeof wxAny.getDeviceVoIPList === 'function') {
  wxAny.getDeviceVoIPList({
    success: (res: { list?: any[] }) => {
      // 判断 res.list 中是否包含目标设备的 sn (sn 由 productId + deviceName 组成)
    },
    fail: (err: { errMsg?: string }) => {
      console.warn('[device] wx.getDeviceVoIPList fail:', err && err.errMsg);
    },
  });
}

从设备联系人列表中移除

当用户不想再接收来自设备的呼叫时，调用 unregisterVoIPNotificationForDevice 将自己从设备联系人列表中移除，移除后设备再呼叫该用户时不会触发微信提醒：
await deviceManager.unregisterVoIPNotificationForDevice(deviceId, modelId, appId, wxOpenId);

常见问题

model_id 在哪里查看？

在小程序管理后台的功能 > 硬件设备 > 设备管理列表中查看。设备需先通过微信审核（约1-3天），审核通过后平台才会分配 model_id。

授权弹窗没有弹出？

检查 snTicket 是否在5分钟有效期内，过期需重新调用 requestVoIPSnTicket。
用户此前拒绝过授权的，微信不再自动弹窗，须引导用户到小程序设置页手动开启。
fail 回调中 errCode 为 10001 表示用户已授权，属于成功场景，可直接进入授权登记。

设备呼叫后用户收不到提醒？

确认用户已完成步骤3的授权登记，可通过 getAuthorizedVoIPUserList 校验。
确认用户未删除过小程序；删除后重新打开授权状态会失效，需重新注册。

相关文档

TXIoTDeviceManager：设备绑定、VoIP 授权等接口的完整说明。
设备端接入：设备侧呼叫微信的对接流程。
集成与登录：小程序 SDK 集成与登录。
中国站