# 用户授权设备

设备和用户间如果要进行通话，需要用户在手机微信端先对设备进行授权。

# 1. 请求授权

用户授权前，需要从开发者的后台通过获取设备票据 接口拿到设备票据 snTicket。

拿到 snTicket 后，需要在小程序内调用 wx.requestDeviceVoIP 请用户进行授权。

需要基础库 >= 2.27.3 支持。设备组 >= 2.30.4 支持。

wx.requestDeviceVoIP({
  sn: 'xxxxxx', // 向用户发起通话的设备 sn（需要与设备注册时一致）
  snTicket: 'xxxxxx', // 获取的 snTicket
  modelId: 'xxxxxx', // 「设备接入」从微信公众平台获取的 model_id
  deviceName: 'xxx', // 设备名称，用于授权时显示给用户
  success(res) {
    console.log(`requestDeviceVoIP success:`, res)
  },
  fail(err) {
    console.error(`requestDeviceVoIP fail:`, err)
  },
})

注意：

• 如果用户拒绝授权或在设置页中取消授权，再次调用 requestDeviceVoIP 不会出现授权弹框。开发者应引导用户在设置页中手动开启。
• 授权框中「设备名字」= 「deviceName」 + 「modelId 对应设备型号」。如「devcieName」为「iot」，modelId 对应设备型号是「校园电话」，最终名字为「iot校园电话」

# 2. 处理授权失效的情况

用户在授权成功后，下列操作可能导致授权失效：

• 清空授权：在最近使用中删除小程序，用户的授权记录会被清空。
• 取消授权：用户同意授权后，小程序设置页面中会出现「语音、视频通话提醒」模块，点击进入后用户可以管理已授权的设备，并可以取消授权。（需要微信客户端 >= 8.0.30 支持）

为了保证用户能够正常使用音视频通话能力，开发者需要处理授权失效的情况。 在发起通话前，建议开发者通过第 4 节所述方式检查授权状态。并在必要时提醒用户重新授权：

• 清空授权：可以直接调用 requestDeviceVoIP 请用户进行重新授权。
• 取消授权/用户拒绝授权：再次调用 requestDeviceVoIP 不会出现授权弹框。开发者应引导用户在设置页中手动开启授权开关。

# 3. 批量授权

如果需要批量授权，可以创建设备组。在用户授权和设备进行音视频通话时，可以批量授权给一个设备组，而无需对每台设备重复授权。

例如，在校园电话场景下，同一所学校可能有很多台话机。可以将同一所学校的设备加入到一个设备组，并使用 wx.requestDeviceVoIP 对整个设备组进行授权。

注意：对于设备组，deviceName 显示为创建设备组时指定的名称，授权时暂不允许自定义。

需要基础库 >= 2.30.4 支持。

wx.requestDeviceVoIP({
  isGroup: true,
  groupId: '设备组 ID',
  success(res) {
    console.log(res)
  },
  fail(res) {
    console.log(res)
  }
})

# 4. 授权状态查询

# 4.1 当前用户授权的设备（组）

查询当前登录的用户同意/拒绝或取消授权了哪些设备（组）。

在手机微信端小程序内调用 wx.getDeviceVoIPList，可用于在手机端发起通话前检查授权状态。

需要基础库 >= 2.30.3 支持。设备组 >= 2.30.4 支持。

// 小程序基础库接口
wx.getDeviceVoIPList({
  success(res) {
    console.log('[getDeviceVoIPList]', res.list)
    // [{sn: 'xxx', model_id: 'xxx', status: 0}]
    // status: 0/未授权；1/已授权
  }
})

• 设备组只有 groupId 字段，sn 和 model_id 为 undefined。

# 4.2 当前设备是否被授权

根据用户 openId，查询指定用户是否授权设备（组）。

由插件提供 getIotBindContactList 接口，一般在设备端使用，可用于在设备端发起通话前（如联系人页面）检查授权状态。

const wmpfVoip = requirePlugin('wmpf-voip').default

// VOIP 插件接口
wmpfVoip.getIotBindContactList({
  sn: "设备sn",
  model_id: "申请的modelid",
  openid_list: ["openid_1", "openid_2"], // 传入需要验证的openid列表
}).then((res) => {
  console.log(`[getIotBindContactList]:`, res.contact_list)
  // [{sn: 'xxx', model_id: 'xxx', status: 0}]
  // status: 0/未授权；1/已授权
})