分类： VoIP 通话插件

插件提供设备端和微信用户直接通话的能力。

1. 选择接口

开发者请根据场景选择不同的通话接口。

1.1 安卓 WMPF 设备呼叫手机微信

使用 initByCaller 接口，businessType 传 1。

1.2 Linux 设备呼叫手机微信

Linux 设备不运行微信小程序插件，请使用微信小程序音视频通话 SDK (Linux 设备)。

1.3 手机微信呼叫安卓 WMPF 设备

• 推荐：使用 callWMPF 接口。需插件 2.4.0 开始支持。若使用 license 计费，必须使用本接口。
• 使用 initByCaller 接口，businessType 传 2。此方式不支持 license 计费。

1.4 手机微信呼叫 Linux 设备

使用 callDevice 接口。需插件 2.4.0 开始支持。

请注意：呼叫 Linux 设备时，微信不进行消息推送，需要开发者自行将设备端加入房间所需参数（如 roomId 等）从微信端推送到设备端。

2. 使用前必读

2.1 进入通话页面

发起通话的几个接口既可以在微信小程序页面调用，也可以在插件页面调用。但是最终通话流程必须在插件页面才能进行。

• 如果发起通话时在微信小程序页面，接口调用成功后，开发者需要手动跳转到插件页面，插件页面加载完成后进入通话流程。
• 如果发起通话时在插件页面，接口调用成功后就会直接进入通话流程。此时请勿重复进行页面跳转，否则当前通话会被中断。
• 不建议页面栈内存在多个插件页面实例。

// 发起通话成功后，仅在当前不是插件页面的情况下需进行跳转。
wx.redirectTo({
  // 此处只需要传入 path 即可，如果开发者有其他参数需要传递给<a href="https://weixin-xiaochengxu-kaifa.yuannext.com">微信小程序</a>，也可以自行拼接 query，并通过插件 getPluginOnloadOptions 接口获取。
  url: wmpfVoip.CALL_PAGE_PATH,
  // 插件 2.3.9 开始支持 CALL_PAGE_PATH, 低版本请传入 'plugin-private://wxf830863afde621eb/pages/call-page-plugin/call-page-plugin',
})

2.2 最大通话时长

为了降低开发者的开发成本，插件提供了限制最大通话时长的能力。最大通话时长应为 > 0 的数字。

通话时长从 startVoip 事件开始计时，超时后通话自动结束并弹 toast 提示用户，同时触发 hangUpVoip 事件，origin 为 'timeLimit'。

2.3 groupId 与 roomId

在插件 2.4.0 以下版本中，通话房间 ID 被称为 groupId，这个名字比较容易与设备组的 ID 产生混淆，因此从 2.4.0 开始，房间号统一更名为 roomId，但为保持向下兼容，groupId 参数仍予以保留。

二者除名字不同外，无其他差异。

本插件主要用于提供「微信小程序音视频通话（for 硬件）」的部分基础能力和统一的通话界面。完整的接入流程和开发指南请参考相关文档。

插件接入可参考：微信小程序示例代码

1. 微信小程序引入插件

关于微信小程序插件详细说明请参考微信小程序使用插件文档

在「微信小程序管理后台」添加插件后，使用者还需要在微信小程序的 app.json 中声明本插件。可以在主包引入，也可以在分包引入。

// 主包引入
{
  "plugins": {
    "wmpf-voip": {
      "version": "latest", // latest 表示自动使用最新版本。也可使用具体版本，如 2.3.8
      "provider": "wxf830863afde621eb"
    }
  }
}

// 分包引入
{
  "subpackages": [
    {
      "root": "xxxx",
      "pages": [],
      "plugins": {
        "wmpf-voip": {
          "version": "latest", // latest 表示自动使用最新版本。也可使用具体版本，如 2.3.8
          "provider": "wxf830863afde621eb"
        }
      }
    }
  ]
}

完成声明后，可以在微信小程序中来确认是否引入成功

const wmpfVoip = requirePlugin('wmpf-voip').default
console.log(wmpfVoip) // 有结果即表示引入插件成功

2. 插件接口

从功能上，插件提供的接口可以分为以下几类

2.1 发起通话

发起通话的过程中，插件主要负责通话房间创建、发送接听提醒和通话页面的展示。可以在微信小程序页面或插件页面调用initByCaller 发起通话。

2.2 结束通话

通常情况下，通话结束需要用户点击操作。某些场景下，微信小程序也可以调用 forceHangUpVoip 主动结束当前通话。

非用户点击结束通话可能有以下场景：

• 用户操作硬件设备的某些按钮结束通话。例如，设备有单独的话机听筒时，用户挂断听筒。
• 用户通话时长超过限制。建议使用 initByCaller 的 timeLimit 参数。插件低版本也可以根据 calling 事件的 keepTime 字段计算通话时长。

2.3 通话事件

开发者可以通过 onVoipEvent 绑定通话事件的监听，以便更好地分析通话过程。

2.4 自定义设置

插件提供下列接口对通话过程和界面进行设置

• setCustomBtnText：自定义接听页面按钮。
• setVoipEndPagePath：设置插件功能执行完成后的跳转页面路径。
• setUIConfig：设置插件通话界面。

2.5 授权查询

在微信客户端内，可以使用wx.getDeviceVoIPList查询当前登录的用户同意或拒绝授权了哪些设备。

在硬件端，可以通过插件getIotBindContactList接口查询用户是否授权某台设备。

推荐开发者在微信用户授权设备时，即 wx.requestDeviceVoIP 回调 success 后，在后台存储 SN 与 openId。在设备端联系人页面中，配合 getIotBindContactList 接口进行授权验证。

2.6 页面参数

微信小程序可以通过插件getPluginEnterOptions获取从插件页面进入微信小程序时的启动参数。

如果微信小程序在前台时进入插件页面，则需要使用getPluginOnloadOptions获取插件通话页面 onLoad 时页面路径中的参数。

3. 更新日志

请参考《微信小程序音视频通话插件更新日志》