分类： 音视频通话+摄像头（for 硬件）

微信小程序音视频通话+摄像头（for 硬件）

接入流程和常见问题也可参考微信小程序音视频通话（for 硬件） 使用手册

1. 产品介绍

1.1 微信小程序 Voip

借助微信小程序音视频通话插件，硬件开发者可以通过微信小程序硬件框架(WMPF)、Linux SDK 接入、云云接入三种方式实现智能设备和手机微信端的一对一音视频通话，满足实时触达场景，提升通话体验。

下图为手机端的示意图，授权弹窗、通话提醒、通话界面为微信提供的统一界面，硬件微信小程序接入微信 VOIP 通话插件后，可实现上述功能。

适用于校园话机、门禁机、智能门锁、智慧中控屏、智能电视、智能摄像头、智能音箱、智慧养老等多种设备和场景，支持硬件设备和手机端双向通话，实现通话强提醒。

1.2 微信小程序摄像头

借助微信小程序音视频通话插件里的摄像头能力，开发者能够快速的将摄像头类产品接入微信小程序生态(云对云的方式），用户查看摄像头流媒体也更加方便，培养用户微信小程序观看摄像头的习惯。

针对摄像头涉及的功能，分成组件必选、组件可选、自定义等部分。

类型 模块 功能点 描述
组件必选 播放器 播放 播放、暂停
组件必选 播放器 画面缩放 放大、缩小
组件必选 播放器 音量 音量、静音
组件必选 播放器 屏幕 小屏、全屏
组件必选 对讲 设备呼叫手机 VoIP功能
组件可选 播放器 清晰度 开发者传入
组件可选 对讲 手机呼叫设备 呼叫、挂断
自定义（举例） 轮盘 方向控制 一般用来控制摄像头转动
自定义（举例） 增值服务 云存储
自定义（举例） 增值服务 AI服务

微信小程序界面：

全屏界面：

2. 设备要求

目前支持安卓系统、Linux 系统、RTOS 系统的设备。每台设备只能绑定一个微信小程序，只能和一个微信小程序进行通话。

目前支持 「设备直连」和「云对云」 两种接入模式：

  • 设备直连：支持安卓和 Linux 设备。由设备端直接向微信后台发送并接受音视频流和信令，与用户手机微信内的微信小程序进行通话。
  • 云对云：支持无法满足设备直连硬件需要的低功耗 Linux、RTOS 等系统设备。设备端仅进行设备验证，由开发者后台（服务端）向微信后台转发音视频流和信令，与用户手机微信内的微信小程序进行通话。

2.1 设备直连（安卓）

安卓系统设备端运行微信小程序硬件框架(WMPF)，WMPF 内运行开发者微信小程序，直接与用户手机微信内的微信小程序进行通话；

设备应满足下列基本要求：

  • 具有音视频能力（麦克风、摄像头等硬件设备）；
  • 满足微信小程序设备认证的设备要求；
  • 满足安卓微信小程序硬件框架运行要求
    • 系统版本：建议安卓 7.1 及以上版本
    • CPU：至少四核 2GHz，视频通话对 CPU 有更高要求
    • 内存：至少 2GB RAM + 8GB ROM
  • 建议使用微信小程序硬件框架 v2.1.0 及以上版本。

2.2 设备直连（Linux）

Linux 系统设备端调用 微信小程序音视频通话 SDK (Linux)，直接与用户手机微信内的微信小程序进行通话。

设备应满足下列基本要求：

  • 具有音视频能力（麦克风、摄像头等硬件设备）；
  • 满足微信小程序设备认证的设备要求；
  • 满足运行 微信小程序音视频通话 SDK (Linux) 的设备要求。

2.3 云对云

目前支持部分低功耗 Linux、RTOS 等系统的设备。设备端进行设备验证，经由开发者后台中转，与用户手机微信内的微信小程序进行通话。

设备应满足下列基本要求：

  • HTTPS 通信能力
  • 存储能力
  • 音(视)频能力

3. 开发前准备

以下几个环节可以同时进行，涉及到多个平台侧的审核流程，请提前预留时间。

3.1 【仅安卓直连设备】接入微信硬件平台

注册微信终端合作平台和微信开放平台账号、登记设备信息等环节均涉及平台审核，请提早准备。

参考文档指引，完成「微信终端合作平台 (wecooper)」企业主体账号注册、移动应用绑定和硬件注册的流程。

本步骤主要是将设备接入微信的设备体系，完成设备与 APP，以及 APP 与微信小程序之间的关联。

  • 为避免混淆，移动应用的 appId 一般被称为 hostAppId；
  • 每一台硬件设备都需要使用 hostAppId 身份调用 addDevice 接口完成注册，才可以使用 安卓 WMPF。

3.2 设备接入和申请设备能力

此环节涉及平台审核，请提早准备。

微信小程序想要使用音视频通话能力能力，需要在微信小程序管理平台申请开通「微信小程序音视频能力」设备能力。详见「设备接入」文档和微信小程序音视频通话（for 硬件） 使用手册中的流程指引，并关注《硬件 VoIP 审核验证要求》。

完成接入后，开发者可获得由平台分配的 model_id。model_id 对应一种设备类型，是调用微信小程序设备能力相关接口的重要凭证。

获取 model_id 后，开发者可以调用获取设备票据接口获取 snTicket，用于后续的设备验证流程。

3.3 接入 VOIP 插件

微信小程序音视频通话的主要功能通过「VOIP 通话」这一微信小程序插件（appId: wxf830863afde621eb）提供。

在微信小程序管理后台完成「微信小程序音视频能力」申请并通过后，微信小程序可以直接使用 VOIP 通话插件，无需额外申请。

如果开发者想要提前进行调试，可以手动进行申请：登录「微信小程序管理后台」——「设置」——「第三方设置」——「插件管理」，点击「添加插件」，搜索并添加「VOIP 通话」插件。

4. 设备端开发

  • 安卓设备端需要运行一个开发者提供的安卓应用，用来进行设备注册、运行微信小程序进行 VOIP 通话。请参考《开发设备端应用（安卓）》
  • Linux 设备端需要集成 微信小程序音视频通话 SDK (Linux)
  • RTOS 设备端需要集成 SDK 用于进行呼叫。

5. 微信小程序开发

开发者需要开发（或使用现有）微信小程序，接入「VOIP 通话」插件，实现拨打和接听音视频通话的能力。

  • 与安卓设备通话时，开发者需要使用同一个微信小程序，既运行在安卓设备端（设备发起或接听通话），也运行在手机端微信客户端（手机用户发起或接听通话）。
  • 与 Linux 设备通话时，设备端运行「微信小程序音视频通话 SDK (Linux)」，手机端微信客户端内运行微信小程序（手机用户发起或接听通话）。
  • 与 RTOS 设备通话时，设备端的 SDK 用于发起呼叫，服务端的 SDK 用于通过过程中的视频流转，手机端微信客户端内运行微信小程序（手机用户发起或接听通话）。

5.1 核心流程

至少使用微信客户端 8.0.30 及以上版本，建议使用当前最新版本。

微信小程序开发主要有以下环节，请参考各环节的文档：

  1. 接入「VOIP 通话」插件：参考插件文档在微信小程序中引入插件；
  2. 设备呼叫手机微信：
  • 需要用户在手机微信端先对设备进行授权，请参考 《用户授权》；
  • 适用于已注册并且用户授权过的设备发起通话，用户在手机微信内接听，请参考《设备呼叫手机微信》；
  1. 手机微信呼叫设备：适用于用户在手机微信内发起通话，已注册并且用户授权过的设备接听，请参考《手机微信呼叫设备(安卓)》和《手机微信呼叫设备(Linux)》；
  2. 性能与体验优化：请参考《性能与体验优化》。

通话相关异常，请参考《通话异常排查指南》

5.2 调试说明

VoIP 通话流程暂不支持在微信开发者工具进行调试，请使用真机进行。

5.2.1 设备端使用「开发版/体验版微信小程序」

安卓设备端可指定使用「开发版/体验版微信小程序」进行调试。请参考《开发设备端应用（安卓）》「3.2 运行开发版/体验版微信小程序」。

5.2.2 使用开发版/体验版微信小程序接听通话

接听方收到消息推送点击接听后，默认打开的是正式版的微信小程序。

在开发阶段，建议在调用 wmpfVoip.initByCaller 时额外传入 miniprogramState 参数指定打开开发版/体验版微信小程序。

const result = await wmpfVoip.initByCaller({
  // 其他参数省略
  miniprogramState: 'developer', // formal/正式版（默认）；trial/体验版；developer/开发版
})

使用微信小程序音视频通话 SDK (Linux)时，可以在初始化时设置 wxa_flavor 指定使用开发版/体验版接听通话。

注意：

  • 接听方为手机微信时，应提前扫微信开发者工具生成的开发版二维码下载开发版。
  • 接听方为运行 WMPF 的设备时，应提前按照 5.2.1 的步骤下载开发版。
  • 正式上线时应注意切换为正式版，可以使用 wx.getAccountInfoSync 接口判断当前的微信小程序版本。

6. 服务端开发

RTOS 设备使用云对云方案时，需要进行服务端开发。设备直连（Linux、Android）无需服务端开发。

7. 常见问题

请参考《常见问题（FAQ）》

VoIP 通话插件

本插件主要用于提供「微信小程序音视频通话（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. 更新日志

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

initByCaller(Object req)

本接口为异步接口，返回 Promise 对象。

发起通话并获取通话房间号。调用此接口后，会创建 VoIP 房间，并且向接听方推送接听提醒。

建议先阅读接口介绍。

参数

Object req

属性 类型 默认值 必填 说明 最低版本
roomType string 是 通话类型。voice: 音频通话；video: 视频通话
caller Object 是 拨打方信息
caller.id string 是 拨打方 id，参考 businessType 的说明
caller.name string 否 显示的拨打方名字。设备端发起通话时无效
caller.cameraStatus number 0 否 是否启用摄像头。0: 开启；1: 关闭
listener Object 是 接听方信息
listener.id string 是 接听方 id，参考 businessType 的说明
listener.name string 否 显示的接听方名字。
listener.cameraStatus number 0 否 是否启用摄像头。0: 开启；1: 关闭
businessType number 0 否 业务类型。详见 businessType 的说明
voipToken string 否 拨打票据，部分情况下必填，参考 businessType 的说明
miniprogramState string formal 否 接听方点击通知时打开的微信小程序类型。
取值：formal: 正式版; trial: 体验版; developer: 开发版。
2.1.8 起，正式版微信小程序只能拨打给正式版，设置这一字段无效。
customQuery string 否 接听方点击通知打开微信小程序时，会作为 query 拼接到插件页面路径后，格式如 a=1&b=2。可在接听端微信小程序内通过 getPluginOnloadOptions 或 getPluginEnterOptions 接口获取到
timeLimit number 否 最大通话时长，需为 > 0 的数字 2.3.8

返回值

由于历史原因，本接口调用失败可能会抛出异常（一般是参数错误），也可能会返回 isSuccess: false（一般是后台错误）。

接口成功返回后，仍需要使用 isSuccess 字段判断调用是否最终成功。

Object

接口调用成功时，返回如下

属性 类型 说明 最低版本
isSuccess boolean 是否调用成功，此时为 true
roomId string 本次通话的房间号 2.4.0
groupId string 与 roomId 相同
chargeType string 计费方式。取值：duration: 时长计费；license: license 计费 2.3.8

调用失败时，接口返回如下：

属性 类型 说明 最低版本
isSuccess boolean 是否调用成功，此时为 false
error object 错误对象，已废弃。{ err_code: string, errMsg: string }
errCode number 错误码，取值参考错误码文档
errMsg string 错误信息
errObj VoipError 错误对象 2.4.0

关于 businessType

不同 businessType 对应的部分参数含义不同，参数获取的具体方式请参考对应业务的文档。

businessType 业务类型 caller.id listener.id voipToken
1 硬件设备呼叫手机微信 设备 SN 微信用户 openId 使用设备认证 SDK注册的设备传入 deviceToken.
使用 WMPF 注册的设备不能有这个字段（插件 2.3.0 支持）
2 手机微信呼叫硬件设备 微信用户 openId 设备 SN 从设备获取的 pushToken
  • 发起通话前，需要在提前让 openId 对应的用户在微信客户端的微信小程序内进行授权，具体流程请参见授权文档；
  • 传入 id 为 设备 SN 时，name 会强制使用用户授权时的「deviceName」+「modelId 对应设备型号」，不使用开发者传入的 name。
  • 本接口 businessType=2 仅支持安卓 WMPF，呼叫 Linux 设备请使用 callDevice。
  • 本接口 businessType=2 不支持 license 计费，手机微信呼叫安卓 WMPF 建议使用 callWMPF。

示例代码

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

try {
  const { isSuccess } = await wmpfVoip.initByCaller({
    caller: {
      id: '拨打方 Id',
      name: '拨打方名字',
    },
    listener: {
      id: '接听方 Id',
      name: '接听方名字',
    },
    roomType: 'video',
    businessType: 1,
    voipToken: 'xxxx*****xxxx',
    miniprogramState: 'developer', // 开发阶段建议使用开发版
  })

  if (isSuccess /* && 当前不在插件页面 */) {
    wx.redirectTo({
      url: wmpfVoip.CALL_PAGE_PATH,
    })
  } else {
    wx.showToast({
      title: '呼叫失败',
      icon: 'error',
    })
  }
} catch (e) {
  wx.showToast({
    title: '呼叫失败',
    icon: 'error',
  })
}

发起通话接口介绍

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

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 参数仍予以保留。

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

callWMPF(Object req)

本接口为异步接口，返回 Promise 对象。

需插件 2.4.0 版本开始支持

从手机客户端的微信小程序呼叫运行安卓 WMPF 的设备。调用此接口后，会创建 VoIP 房间，并且向设备推送 WMPF pushMsg 提醒。详情参考《手机微信呼叫设备(安卓)》。

本接口只能在微信客户端内使用，不可在 WMPF 内使用。建议先阅读接口介绍。

参数

Object req

属性 类型 默认值 必填 说明 最低版本
roomType string 是 通话类型。voice: 音频通话；video: 视频通话
sn string 是 接听方设备 SN
modelId string 是 接听方设备 modelId
pushToken string 是 从设备获取的 pushToken
nickName string 是 设备端显示的微信用户名称
deviceName string 否 微信端显示的设备名称 2.4.1
chargeType string ‘license’ 否 计费方式。duration: 时长计费；license：license 计费
timeLimit number 否 最大通话时长，需为 > 0 的数字
enableCallerCamera boolean true 否 拨打方是否启用摄像头。
enableListenerCamera boolean true 否 接听方是否启用摄像头。
envVersion string ‘release’ 否 接听方打开的微信小程序类型。
取值：release: 正式版; trial: 体验版; develop: 开发版。
正式版微信小程序只能拨打给正式版，设置这一字段无效。
customQuery string 否 接听方打开微信小程序时，会作为 query 拼接到插件页面路径后，格式如 a=1&b=2。可在接听端微信小程序内通过 getPluginOnloadOptions 或 getPluginEnterOptions 接口获取到

返回值

本接口调用失败会抛出异常。

Object

接口调用成功时，返回如下：

属性 类型 说明 最低版本
roomId string 本次通话的房间号

示例代码

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

try {
  const { roomId } = await wmpfVoip.callWMPF({
    roomType: 'video',
    sn: '设备 SN',
    modelId: '设备 modelId',
    nickName: '设备端显示的微信用户名称',
    pushToken: 'xxxx*****xxxx',
  })

  if (/* 当前不在插件页面 */) {
    wx.redirectTo({
      url: wmpfVoip.CALL_PAGE_PATH,
    })
  }
} catch (e) {
  console.error('callWMPF failed:', e)
  wx.showToast({
    title: '呼叫失败',
    icon: 'error',
  })
}

callDevice(Object req)

本接口为异步接口，返回 Promise 对象。

需插件 2.4.0 版本开始支持

从手机客户端的微信小程序呼叫 Linux 设备、RTOS 设备。调用此接口后，会创建 VoIP 房间。开发者应自行向设备端推送通话提醒。详情参考《手机微信呼叫设备(Linux 直连)》。

本接口只能在微信客户端内使用，不可在 WMPF 内使用。建议先阅读接口介绍。

参数

Object req

属性 类型 默认值 必填 说明 最低版本
roomType string 是 通话类型。voice: 音频通话；video: 视频通话
sn string 是 接听方设备 SN
modelId string 是 接听方设备 modelId
chargeType string ‘license’ 否 计费方式。duration: 时长计费；license：license 计费
timeLimit number 否 最大通话时长，需为 > 0 的数字
enableCallerCamera boolean true 否 拨打方是否启用摄像头
enableListenerCamera boolean true 否 接听方是否启用摄像头
nickName string 否 设备端显示的微信用户名称，仅记录
deviceName string 否 微信端显示的设备名称 2.4.1
isCloud boolean false 否 如果是呼叫 RTOS 设备，设置为 true 以触发消息回调
payload string 否 呼叫 RTOS 时，可以带 payload 到回调消息中
encodeVideoFixedLength number 0 否 编码的长边值，可取 320、480、640
encodeVideoRotation number 0 否 编码的视频旋转方向。1: 发出正向流. 2: 保持发出旋转流
encodeVideoRatio number 0 否 视频的比例, 宽/高*100
encodeVideoMaxFPS number 0 否 视频的最大 FPS, 8-15

返回值

本接口调用失败会抛出异常。

Object

接口调用成功时，返回如下：

属性 类型 说明 最低版本
roomId string 本次通话的房间号

示例代码

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

try {
  const { roomId } = await wmpfVoip.callDevice({
    roomType: 'video',
    sn: '设备 SN',
    modelId: '设备 modelId',
    nickName: '设备端显示的微信用户名称',
  })

  if (/* 当前不在插件页面 */) {
    wx.redirectTo({
      url: wmpfVoip.CALL_PAGE_PATH,
    })
  }
} catch (e) {
  console.error('callDevice failed:', e)
  wx.showToast({
    title: '呼叫失败',
    icon: 'error',
  })
}

获取插件入口参数

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

从插件页面进入微信小程序时，微信小程序本身无法直接通过wx.getEnterOptionsSync 获取启动参数，故提供本接口。

注意：当微信小程序在前台时被客户端 reLaunch（例如手机微信来电提醒打开微信小程序，或 WMPF launchMiniProgram 接口打开微信小程序），这种情况下并不算「进入微信小程序」，getPluginEnterOptions 无法获取最新的 query，需要通过 getPluginOnloadOptions 获取。

参数

无

返回值

Object

启动参数。与插件调用wx.getEnterOptionsSync返回值一致。

示例代码

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

const query = wmpfVoip.getPluginEnterOptions()

获取插件 onload 选项

微信小程序插件 2.2.3 版本开始支持

获取微信小程序插件通话页面打开(onLoad)时页面路径中的参数。

注意：获取参数时，如果微信小程序插件通话页面onLoad还没有触发，可能取到的不是最新的值。建议在 callPageOnShow 事件后调用。

参数

无

返回值

Object

微信小程序插件页面 onLoad 生命周期的 query 参数

示例代码

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

let query = {}

wmpfVoip.onVoipEvent((event) => {
  if (event.eventName === 'callPageOnShow') {
    query = wmpfVoip.getPluginOnloadOptions()
  }
})

微信小程序VoIP事件监听函数

功能描述

监听 VoIP 通话相关事件。事件绑定需要在通话开始前完成。

注意：不要在 onLoad、onShow 等生命周期内绑定事件，可能会因为生命周期多次调用而重复绑定。

参数

function listener

事件监听函数

回调参数

Object event
属性 类型 说明 最低版本
eventName string 事件名称。请参考后文描述。
roomId string 通话房间号。除 bindContact、callPageOnShow 事件外提供 2.4.0
groupId string 与 roomId 相同
data Object 某个事件额外的参数。不同事件的字段不同，请参考后文描述

返回值

function

取消监听函数，调用后取消监听事件。该函数无参数，无返回值。

事件描述

1. startVoip

通话开始。

2. abortVoip

通话异常中断。

data 参数

属性 类型 说明
keepTime number 通话时长
status string 异常说明，取值参见后文
error Object 错误对象
error.errMsg Object 错误信息

status 取值

status 描述
abortByListener 通话因本端异常中断（接听方触发）
abortByCaller 通话因本端异常中断（拨打方触发）
unknown 通话因对端异常中断

常见 errMsg

  • room status is abort：status=unknown，接收到对端通话异常时触发，需要根据 roomId 关联对端触发的 abortVoip 事件判断真正的异常原因。
  • listener waitOtherToJoin timeout：status=abortByListener，接听方加入房间后，拨打方一直未成功加入（可能是网络慢等原因）或异常退出，接听方等待 20s 超时后触发。此时建议分析接听方的情况来排查。
  • call interrupted due to close passive float ball：用户将微信小程序切后台后，会展示微信小程序浮窗，用户通过浮窗关闭微信小程序时触发。
  • in comming call：微信小程序通话被其他来电打断时触发。
  • call interrupted due to native reason：一般是由于通话过程中一段时间未收到数据包（一般是网络原因），被踢出房间中断通话。

3. hangOnVoip

通话被接听（仅接听方触发）。

4. cancelVoip

通话未接通，拨打方取消通话。

data 参数

属性 类型 说明
status string 取消原因说明，取值参见后文

status 取值

status 描述
manual 用户点击界面挂断按钮取消通话。（仅拨打方）
unloadCallPage 插件页面被销毁导致取消通话。（仅拨打方）
forceFromApp 微信小程序调用 forceHangUpVoip 取消通话。（仅拨打方）
other 拨打方取消通话。（仅接听方）

5. rejectVoip

通话未接通，接听方拒接。

data 参数

属性 类型 说明
status string 拒接原因说明，取值参见后文

status 取值

status 描述
manual 用户点击界面挂断按钮拒接通话（仅接听方）
unloadCallPage 插件页面被销毁导致拒接通话（仅接听方）
forceFromApp 微信小程序调用 forceHangUpVoip 拒接通话（仅接听方）
other 接听方拒接（仅拨打方）

6. hangUpVoip

通话已接通，拨打方/接听方挂断通话。

data 参数

属性 类型 说明
keepTime number 通话时长
status string 挂断方说明，取值参见后文
origin string 挂断原因说明，取值参见后文

status 取值

status 描述
endByListener 接听方挂断
endByCaller 拨打方挂断

origin 取值

为了保持向下兼容，hangUpVoip 事件额外使用 origin 字段提供具体的挂断原因信息。

origin 描述
manual 用户点击界面挂断按钮挂断通话（仅挂断方）
unloadCallPage 插件页面被销毁导致挂断通话（仅挂断方）
forceFromApp 微信小程序调用 forceHangUpVoip 导致挂断通话（仅挂断方）
other 对方挂断通话
timeLimit 超过最大通话时长

7. endVoip

通话结束。

data 参数

属性 类型 说明
keepTime number 通话时长
callerName string 拨打方名字
listenerName string 接听方名字
roomType string 房间类型
isCaller boolean 是否是拨打方
businessType number 业务类型

8. busy

通话未接通，接听方占线（仅拨打方触发）。

9. calling

通话过程中, 双方都会每秒触发一次。

data 参数

属性 类型 说明
keepTime number 通话时长

10. timeout

通话超时未接听。

11. joinedRoomByCaller

拨打方加入房间成功（仅拨打方触发）。

12. joinFailCaller

拨打方加入房间失败（仅拨打方触发）。

data 参数

属性 类型 说明
errMsg string 错误消息
message string 由于向下兼容原因，某些情况下 data 是一个 Error 对象

13. joinFailListener

接听方加入房间失败（仅接听方触发）。

data 参数

属性 类型 说明
errMsg string 错误消息
message string 由于向下兼容原因，某些情况下 data 是一个 Error 对象

14. finishVoip

通话完成。返回本次通话结算使用的实际时长。

需从后台获取最终时间后触发，触发时机晚于 endVoip。

data 参数

属性 类型 说明
keepTime number 结算用通话时长

15. callPageOnShow

微信小程序插件通话页面 onShow。

16. showCustomBox

用户点击通话页面自定义按钮，展示自定义组件。

data 参数

属性 类型 说明
callerId string 拨打方 Id
listenerId string 接听方 Id

17. hideCustomBox

用户隐藏自定义组件。

data 参数

属性 类型 说明
callerId string 拨打方 Id
listenerId string 接听方 Id

示例代码

const wmpfVoip = requirePlugin('wmpf-voip').default
const offVoipEvent = wmpfVoip.onVoipEvent(event => {
  console.info(`onVoipEvent`, event)
})

// 需要取消监听时调用
offVoipEvent()