# 群聊能力（选接）

群聊能力是抖音为小游戏开发者提供的私域运营解决方案，玩家可在游戏内一键加入开发者的抖音群聊，开发者也可实时查询群状态以调整加群策略。了解更多内容请阅读抖音小游戏官方文档《粉丝群聊能力》 (opens new window)。

# 核心优势

一键快捷加群：开发者创建了抖音群聊，但在游戏内只能提供二维码或群号，转化有限；接入后玩家在游戏内点击即可加入群聊，无需跳出游戏。
群状态实时监控：可实时查询群人数、是否满员、是否封禁，据此动态调整加群策略（如满员时自动切换到二群）。

# 示例介绍

用户官方群入口	用户加入群聊	群内固定复访入口

# 接入流程介绍

注意，群聊与群标签是两个相互独立的能力，需在抖音开放平台分别开通与配置，技术上互不依赖，可以只接入其中一个。业务上通常先接入群聊，再接入群标签，群标签的接入说明请查看《群标签能力》章节。

# 开通群聊能力

# 绑定抖音号

使用需要绑定的抖音号，在抖音首页搜索页点击左上角「扫一扫」，扫描页面中的二维码即可完成绑定。绑定完成后，平台将获得以下权限：

获取你创建的公开群信息；
应用可通过你的抖音账号创建公开群；
应用可通过你的抖音账号推广你的公开群。

注意，绑定规则如下，请在绑定前确认好用于绑定的抖音号：

平台根据绑定抖音号的粉丝数判断能创建的群聊数量；
不支持对抖音号进行解绑、换绑；
绑定后的能力有效期为 150 天，到期后需再次绑定；有效期外开发者无法再新建群聊，游戏玩家也将无法申请入群。

# 创建群聊并设置展示

绑定完成后，进入「官方群管理」，点击「新建群聊」新建并获得对应的群 ID，群主默认为绑定的抖音号用户。

绑定完成后，按照「个人主页」-「设置」-「抖音创作者中心」-「主播中心」-「直播服务」-「更多」-「公开群」路径将群展示在个人主页，将群聊设置为展示。

完成以上设置后，即可在游戏内接入加群入口：玩家点击入口时调用 sdkInstance.joinGroup(options) 并传入群 ID，抖音会拉起加群面板，玩家确认后即可加入群聊。

公告弹窗内的加群入口	聊天频道内的加群入口

# 配置群管理员ID

查询群聊信息接口需要以建群用户（群主）在当前游戏中的 openId 作为查询依据，该值由 SDK 自行从渠道配置中读取，无需接入方传入，但需提前在 SDK 开放平台后台完成配置。

请登录《SDK开放平台》 (opens new window)后台，进入「打包中心」-「选择游戏」-「渠道配置」-「基本参数配置」，填写并保存「群管理员ID」。

SDK 会在查询群聊信息接口被调用时向渠道配置服务请求该配置，因此务必确保已在 SDK 初始化参数中填写 requests.config 渠道配置服务接口地址，并将该地址添加至抖音的服务器域名白名单中，详情请查看《准备工作》与《初始化》章节。

注意，未配置群管理员ID，或未填写渠道配置服务接口地址时，调用查询群聊信息接口将返回「缺失群聊配置」、404 或其它失败信息。

# API接入

Step 1：在游戏内展示加群入口前，接入「查询群聊信息」API 能力，根据群状态决定引导玩家加入哪个群；
Step 2：在加群按钮的点击事件中，接入「加入群聊」API 能力。

# API说明

# 查询群聊信息

# 接口说明

用于查询开发者在抖音开放平台创建的群聊信息（2.4.0 版本新增）（查询到的群聊信息列表只局限在通过游戏创建的群聊或开发者在抖音开放平台创建的群聊信息，其他渠道创建的群聊信息不会返回），包括群名称、群头像、现有人数、最大人数、群状态等，便于游戏内做加群逻辑优化，如群已满员时引导玩家加入二群。

sdkInstance.checkGroupInfo(options);

最低基础库版本要求

当用户的客户端基础库版本低于 2.70.0 时，调用 sdkInstance.checkGroupInfo(options) 接口将直接触发失败回调函数，并在正式版环境下于控制台输出错误提示（非正式版环境下，以弹窗形式展示）！

注意，该接口目前仅支持抖音及抖音极速版，其他宿主 APP 暂不支持，可以使用 sdkInstance.system.appName 判断宿主，详细枚举值可查看 appName 参数说明 (opens new window)。

# 调用时机

建议在游戏内展示加群入口之前调用，根据返回的群状态决定加群入口展示哪一个群。

# 参数说明

参数说明如下表所示：

选项	类型	必填	默认值	说明
sessionFrom	string	否	""	抖音预留字段，暂无实际作用
extraInfo	string	否	""	抖音预留字段，暂无实际作用
success	function	否	--	接口调用成功的回调函数
fail	function	否	--	接口调用失败的回调函数
complete	function	否	--	接口调用完成的回调函数，成功或失败均会调用

注意，该接口需要以建群用户（群主）在当前游戏中的 openId 作为查询依据，该值由 SDK 自行从渠道配置中读取，无需接入方传入，但需提前在SDK开放平台后台完成配置，详情请查看上文《配置群管理员ID》章节。

# 返回值说明

注意

返回值格式：JSON 格式。

选项	类型	说明
code	string / number	响应状态码，为 `0` 时表示接口调用成功，其他非 `0` 状态码均表示接口调用失败
data	object	接口调用成功时返回群聊信息数据，失败时返回 `null`
data.groupInfoList	object[]	群聊信息对象数组，无群聊时为空数组，见下文 `groupInfoList` 数据结构说明
message	string	接口调用成功或失败时的相应描述信息

# groupInfoList 数据结构

选项	类型	说明
groupInfoList[n].id	string	群 ID，可用于「加入群聊」接口的 `groupId` 参数
groupInfoList[n].avatarUrl	string	群头像
groupInfoList[n].name	string	群名称
groupInfoList[n].description	string	群描述
groupInfoList[n].count	number	群现有人数
groupInfoList[n].maxCount	number	群最大支持进入人数
groupInfoList[n].tags	string[]	群标签，如活跃群、群主近期发言
groupInfoList[n].limits	string[]	群门槛，如“无要求”、“万粉”等
groupInfoList[n].status	string	群状态： `Normal` - 正常 `Ban` - 封禁 `Full` - 已满

# 示例代码

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

// 当用户的客户端基础库版本低于 2.70.0 时，调用此接口将直接触发失败回调函数，并在正式版环境下于控制台输出错误提示（非正式版环境下，以弹窗形式展示）！
sdkInstance.checkGroupInfo({
  success: function(response) {
    // 获取所有群列表
    const groupInfoList = response.data.groupInfoList;

    // 过滤出状态正常且未满员的群
    const availableGroups = groupInfoList.filter(function(item) {
      return item.status === "Normal" && item.count < item.maxCount;
    });

    // 没有可加入的群时，隐藏游戏内的加群入口
    if (availableGroups.length === 0) {
      return console.log("暂无可加入的群聊");
    }

    // 取第一个可用的群作为加群入口，展示群头像、群名称或人数等信息
    const targetGroup = availableGroups[0];

    console.log("群ID：", targetGroup.id);
    console.log("群头像：", targetGroup.avatarUrl);
    console.log("群名称：", targetGroup.name);
    console.log("群人数：", targetGroup.count + "/" + targetGroup.maxCount);

    // 展示游戏内的加群入口弹窗，注意：这是一段伪代码，具体由开发者自行实现
    showGroupEntryModal(targetGroup);
  },
  fail: function(error) {
    console.log(error);
  },
  complete: function(result) {
    // do something here...
  }
});

# 加入群聊

# 接口说明

用于在游戏内引导玩家加入指定的群聊（2.4.0 版本新增），调用后由抖音拉起加群面板，玩家确认后即可完成加群。

sdkInstance.joinGroup(options);

最低基础库版本要求

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

注意，该接口目前仅支持抖音及抖音极速版，其他宿主 APP 暂不支持，可以使用 sdkInstance.system.appName 判断宿主，详细枚举值可查看 appName 参数说明 (opens new window)。另，该接口必须由玩家点击触发，不能放在网络请求、定时器等异步回调中调用，否则调用会失败。