发起通话 – 微信小程序开发指南

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',
  })
}