# 实时语音（选接）

微信小游戏实时语音能力用于在游戏内创建语音房间，并让同一房间内的用户进行实时语音通话；了解详情可查看《微信开放文档 - 实时语音》 (opens new window)说明。

# 准备事项

# 申请开通能力

使用该能力前，请先登录《微信公众平台》 (opens new window)后台，进入“功能 > 游戏能力地图 > 运营能力 > 特色能力”，申请开通实时语音能力，否则接口将无权限调用。

# 完善用户隐私保护指引

管理员需登录《微信公众平台》 (opens new window)后台，进入“账号设置 > 基本设置 > 服务内容声明”，完善《用户隐私保护指引》，填写并披露麦克风权限使用说明；若游戏需要使用视频房间（roomType 为 video），还需要同时填写并披露摄像头权限使用说明。若未完成相关权限配置，小游戏将无权调用微信实时语音能力，此时调用 sdkInstance.joinVoiceChat(options) 接口将会直接触发 fail 回调。

# 配置服务接口地址

实时语音入房前需要向SDK服务端获取签名，请在SDK初始化时配置 requests.voiceChat 服务接口地址，详见前文《初始化》章节说明。

# 处理用户授权结果

微信实时语音能力需要使用麦克风权限；当 roomType 为 video 时，还需要使用摄像头权限。SDK已在 sdkInstance.joinVoiceChat(options) 接口内部完成请求授权操作，若用户授权失败或拒绝授权，将触发 fail 回调，请游戏客户端根据业务场景处理失败情况。

例如：当用户拒绝授权时，fail 回调返回的 error.code 为 reject，游戏可根据该状态码展示符合自身UI风格的授权引导，并在引导页中提供“去开启”按钮；用户点击按钮后，可调用 sdkInstance.openSetting(options) 接口（详见前文《用户设置》章节说明）打开用户设置界面，引导用户重新开启麦克风或摄像头权限。

# 加入实时语音房间

# 接口说明

用于加入（创建）实时语音房间。

sdkInstance.joinVoiceChat(options);

最低基础库版本要求

当用户的客户端基础库版本低于 2.7.0 时，调用 sdkInstance.joinVoiceChat(options) 接口将中断用户当前操作并弹出升级提示，不会报错！

# 参数说明

参数说明如下表所示：

选项	类型	必填	默认值	说明
roomType	string	否	voice	房间类型 `voice` - 音频房间，用于语音通话 `video` - 视频房间
groupId	string	是	--	实时语音房间唯一标识，同一个房间必须传相同 `groupId`
mute	object	否	--	入房时的静音设置
mute.microphone	boolean	否	false	是否静音麦克风
mute.speaker	boolean	否	false	是否静音扬声器
forceCellularNetwork	boolean	否	false	开启后，加入实时语音房间时会同时使用Wi-Fi和蜂窝网络两种网络模式，以保证实时通话体验
success	function	否	--	加入成功的回调函数
fail	function	否	--	加入失败的回调函数
complete	function	否	--	加入完成的回调函数，成功或失败均会调用

# 返回值说明

选项	类型	说明
code	number	响应状态码，为 `0` 时表示加入成功，其他非 `0` 状态码均表示加入失败
data	object	加入成功时返回相应的操作结果，失败时返回 `null`
data.openIdList	string[]	在此通话中的成员 `openId` 名单
message	string	加入成功或失败时的相应描述信息

# 示例代码

注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！

// 当用户的客户端基础库版本低于 2.7.0 时，调用此接口将中断用户当前操作并弹出升级提示，不会报错！
sdkInstance.joinVoiceChat({
  roomType: "voice",
  groupId: "room_10001_123",
  mute: {
    microphone: false,
    speaker: false
  },
  success: function(response) {
    console.log(response.data.openIdList);
  },
  fail: function(error) {
    // 用户拒绝授权
    if (error.code == "reject") {
      // 用户拒绝授权时，游戏可根据自身UI风格展示授权引导，并在引导页中提供“去开启”按钮
      // 用户点击按钮后，可调用 sdkInstance.openSetting(options) 接口打开用户设置界面，引导用户重新开启麦克风或摄像头权限
    }
    // 其他情况
    else {
      sdkInstance.modal.message(error.message);
    }
  },
  complete: function(result) {
    // do something here...
  }
});

# 退出实时语音房间

# 接口说明

用于退出（销毁）实时语音房间。

sdkInstance.exitVoiceChat(options);

最低基础库版本要求

当用户的客户端基础库版本低于 2.7.0 时，调用 sdkInstance.exitVoiceChat(options) 接口将中断用户当前操作并弹出升级提示，不会报错！

# 参数说明

参数说明如下表所示：

选项	类型	必填	默认值	说明
success	function	否	--	退出成功的回调函数
fail	function	否	--	退出失败的回调函数
complete	function	否	--	退出完成的回调函数，成功或失败均会调用

# 返回值说明

选项	类型	说明
code	number	响应状态码，为 `0` 时表示退出成功，其他非 `0` 状态码均表示退出失败
data	object / null	退出成功时返回相应的操作结果，失败时返回 `null`
message	string	退出成功或失败时的相应描述信息

# 示例代码

注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！

// 当用户的客户端基础库版本低于 2.7.0 时，调用此接口将中断用户当前操作并弹出升级提示，不会报错！
sdkInstance.exitVoiceChat({
  success: function(response) {
    console.log(response);
  },
  fail: function(error) {
    console.log(error);
  },
  complete: function(result) {
    // do something here...
  }
});

# 更新实时语音静音设置

# 接口说明

用于更新实时语音静音设置。

sdkInstance.changeVoiceChatMuteSettings(options);

最低基础库版本要求

当用户的客户端基础库版本低于 2.7.0 时，调用 sdkInstance.changeVoiceChatMuteSettings(options) 接口将中断用户当前操作并弹出升级提示，不会报错！

# 参数说明

参数说明如下表所示：

选项	类型	必填	默认值	说明
mute	object	是	--	静音设置
mute.microphone	boolean	否	false	是否静音麦克风
mute.speaker	boolean	否	false	是否静音扬声器
success	function	否	--	更新成功的回调函数
fail	function	否	--	更新失败的回调函数
complete	function	否	--	更新完成的回调函数，成功或失败均会调用

# 返回值说明

选项	类型	说明
code	number	响应状态码，为 `0` 时表示更新成功，其他非 `0` 状态码均表示更新失败
data	object / null	更新成功时返回相应的操作结果，失败时返回 `null`
message	string	更新成功或失败时的相应描述信息

# 示例代码

注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！

// 当用户的客户端基础库版本低于 2.7.0 时，调用此接口将中断用户当前操作并弹出升级提示，不会报错！
sdkInstance.changeVoiceChatMuteSettings({
  mute: {
    microphone: true,
    speaker: false
  },
  success: function(response) {
    console.log(response);
  },
  fail: function(error) {
    console.log(error);
  },
  complete: function(result) {
    // do something here...
  }
});

# 监听成员在线状态变化事件

# 接口说明

用于监听实时语音成员在线状态变化事件。

sdkInstance.onVoiceChatMembersChanged(listener);
sdkInstance.offVoiceChatMembersChanged(listener?);

# 参数说明

参数说明如下表所示：

选项	类型	必填	默认值	说明
listener	function	见说明	--	实时语音成员在线状态变化事件监听函数；调用 `onVoiceChatMembersChanged` 时必填，调用 `offVoiceChatMembersChanged` 时可不传，不传时取消所有监听

# 返回值说明

选项	类型	说明
code	number	响应状态码，为 `0` 时表示事件触发成功，其他非 `0` 状态码均表示事件触发失败
data	object / null	事件触发成功时返回实时语音事件数据，失败时返回 `null`
data.openIdList	string[]	还在实时语音通话中的成员 `openId` 名单
message	string	事件触发时的相应描述信息

# 取消监听

sdkInstance.offVoiceChatMembersChanged(listener?) 用于取消监听实时语音成员在线状态变化事件；若传入 listener，则取消对应的监听函数；若不传入 listener，则取消所有通过 sdkInstance.onVoiceChatMembersChanged(listener) 注册的监听函数。

# 示例代码

注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！

// 定义事件回调函数
const listener = function(response) {
  // code 非 0 时表示监听失败，例如用户基础库版本暂不支持此监听
  if (response.code !== 0) {
    return;
  }

  console.log(response.data.openIdList); // 返回还在实时语音通话中的成员 openId 名单
};

// 监听实时语音成员在线状态变化事件
sdkInstance.onVoiceChatMembersChanged(listener);
// 取消监听实时语音成员在线状态变化事件
sdkInstance.offVoiceChatMembersChanged(listener);
// 取消所有监听
sdkInstance.offVoiceChatMembersChanged();

# 监听成员通话状态变化事件

# 接口说明

用于监听实时语音成员通话状态变化事件。

sdkInstance.onVoiceChatSpeakersChanged(listener);
sdkInstance.offVoiceChatSpeakersChanged(listener?);

# 参数说明

参数说明如下表所示：

选项	类型	必填	默认值	说明
listener	function	见说明	--	实时语音成员通话状态变化事件监听函数；调用 `onVoiceChatSpeakersChanged` 时必填，调用 `offVoiceChatSpeakersChanged` 时可不传，不传时取消所有监听

# 返回值说明

选项	类型	说明
code	number	响应状态码，为 `0` 时表示事件触发成功，其他非 `0` 状态码均表示事件触发失败
data	object / null	事件触发成功时返回实时语音事件数据，失败时返回 `null`
data.openIdList	string[]	还在实时语音通话中的成员 `openId` 名单
message	string	事件触发时的相应描述信息

# 取消监听

sdkInstance.offVoiceChatSpeakersChanged(listener?) 用于取消监听实时语音成员通话状态变化事件；若传入 listener，则取消对应的监听函数；若不传入 listener，则取消所有通过 sdkInstance.onVoiceChatSpeakersChanged(listener) 注册的监听函数。

# 示例代码

注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！

// 定义事件回调函数
const listener = function(response) {
  // code 非 0 时表示监听失败，例如用户基础库版本暂不支持此监听
  if (response.code !== 0) {
    return;
  }

  console.log(response.data.openIdList); // 返回还在实时语音通话中的成员 openId 名单
};

// 监听实时语音成员通话状态变化事件
sdkInstance.onVoiceChatSpeakersChanged(listener);
// 取消监听实时语音成员通话状态变化事件
sdkInstance.offVoiceChatSpeakersChanged(listener);
// 取消所有监听
sdkInstance.offVoiceChatSpeakersChanged();

# 监听通话中断事件

# 接口说明

用于监听实时语音通话中断事件。

sdkInstance.onVoiceChatInterrupted(listener);
sdkInstance.offVoiceChatInterrupted(listener?);

# 参数说明

参数说明如下表所示：

选项	类型	必填	默认值	说明
listener	function	见说明	--	实时语音通话中断事件监听函数；调用 `onVoiceChatInterrupted` 时必填，调用 `offVoiceChatInterrupted` 时可不传，不传时取消所有监听

# 返回值说明

选项	类型	说明
code	number	响应状态码，为 `0` 时表示事件触发成功，其他非 `0` 状态码均表示事件触发失败
data	object / null	事件触发成功时返回实时语音事件数据，失败时返回 `null`
message	string	事件触发时的相应描述信息

# 取消监听

sdkInstance.offVoiceChatInterrupted(listener?) 用于取消监听实时语音通话中断事件；若传入 listener，则取消对应的监听函数；若不传入 listener，则取消所有通过 sdkInstance.onVoiceChatInterrupted(listener) 注册的监听函数。

# 示例代码

注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！

// 定义事件回调函数
const listener = function(response) {
  // code 非 0 时表示监听失败，例如用户基础库版本暂不支持此监听
  if (response.code !== 0) {
    return;
  }

  console.log(response.data); // 返回相应实时语音事件数据
};

// 监听实时语音通话中断事件
sdkInstance.onVoiceChatInterrupted(listener);
// 取消监听实时语音通话中断事件
sdkInstance.offVoiceChatInterrupted(listener);
// 取消所有监听
sdkInstance.offVoiceChatInterrupted();

# 监听房间状态变化事件

# 接口说明

用于监听实时语音房间状态变化事件。

sdkInstance.onVoiceChatStateChanged(listener);
sdkInstance.offVoiceChatStateChanged(listener?);

# 参数说明

参数说明如下表所示：

选项	类型	必填	默认值	说明
listener	function	见说明	--	实时语音房间状态变化事件监听函数；调用 `onVoiceChatStateChanged` 时必填，调用 `offVoiceChatStateChanged` 时可不传，不传时取消所有监听

# 返回值说明

选项	类型	说明
code	number	响应状态码，为 `0` 时表示事件触发成功，其他非 `0` 状态码均表示事件触发失败
data	object	事件触发成功时返回实时语音事件数据，失败时返回 `null`
data.code	number	实时语音房间状态事件码
data.data	object	实时语音房间状态附加信息
message	string	事件触发时的相应描述信息

# 取消监听

sdkInstance.offVoiceChatStateChanged(listener?) 用于取消监听实时语音房间状态变化事件；若传入 listener，则取消对应的监听函数；若不传入 listener，则取消所有通过 sdkInstance.onVoiceChatStateChanged(listener) 注册的监听函数。

# 示例代码

注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！

// 定义事件回调函数
const listener = function(response) {
  // code 非 0 时表示监听失败，例如用户基础库版本暂不支持此监听
  if (response.code !== 0) {
    return;
  }

  console.log(response.data.code); // 返回实时语音房间状态事件码
  console.log(response.data.data); // 返回实时语音房间状态附加信息
};

// 监听实时语音房间状态变化事件
sdkInstance.onVoiceChatStateChanged(listener);
// 取消监听实时语音房间状态变化事件
sdkInstance.offVoiceChatStateChanged(listener);
// 取消所有监听
sdkInstance.offVoiceChatStateChanged();

← 游戏圈（选接）视频号（选接） →