创造沉浸式游戏内聊天体验：与腾讯RTC GME的快速集成

场景概述

即时通讯是游戏中的常见需求，即时聊天已成为多人游戏中必不可少的功能。游戏平台本身涉及多种群体类型、自定义消息类型（如游戏道具赠送和交易）、全球访问等复杂需求。本文档整理了在构建游戏内聊天过程中常见需求的实现方法，以及可能的问题和考虑事项，帮助开发者快速了解业务并实现其需求。

应用产品

聊天

基本集成指南

使用密钥计算 UserSig

在聊天账户系统中，用户登录所需的密码由服务器使用聊天提供的密钥计算。有关更多信息，请参见 生成 UserSig。 在开发阶段，为避免客户端开发受阻，您还可以在 控制台 中计算UserSig，如下所示：

配置管理员账户

管理游戏内即时通讯可能需要管理员向游戏发送电子邮件公告、管理临时组队消息等，这可以通过 聊天服务器 API 来完成。要调用这些 API，您需要创建一个聊天管理员账户。 默认情况下，聊天提供了一个 UserID 为 administrator 的账户。您还可以根据需要创建多个管理员账户。请注意，最多可以创建五个管理员账户。

配置回调地址并启用回调

为了实现游戏内组队等需求，您可以使用 Webhook 事件，在某些场景中，聊天后端会调用业务后端。您只需提供一个 HTTP API，并在控制台的 Webhook 配置 模块中进行配置，如下所示：

集成客户端 SDK

完成准备工作后，您需要将聊天客户端 SDK 集成到您的项目中。您可以根据需要选择不同的集成选项。有关详细说明，请参见 TUIKit 介绍。

以下描述了要集成到游戏中的常见聊天功能，并提供了实现代码的最佳实践。

场景特定实现

用户资料

常见用户资料

存储在游戏业务中的常见用户资料可分为基本信息资料和其他信息资料。

资料存储

游戏业务有大量用户，存储海量用户数据非常困难。聊天通过其用户资料托管能力提供了一整套资料解决方案。以下比较了将用户资料存储在聊天和业务后台之间的差异。

除了资料存储和读写能力外，聊天由于其用户资料托管服务还具有以下优势：

1. 聊天提供远程灾难恢复、跨区域部署和自动扩展能力。这样，您完全可以摆脱复杂的处理流程，例如服务器停机、多副本主从复制和容量扩展。

2. 聊天提供行业内常用的业务处理流程，您无需担心用户资料的业务逻辑。

3. 聊天提供专业的运营流程和团队，确保每年 99.99% 的服务质量，帮助您提供以稳定性著称的服务。

4. 聊天提供易于使用的服务 API 和易于访问的指南，整个过程提供优质服务。

聊天用户资料存储方法

聊天存储方案包括用户资料存储和读写能力。以下描述了聊天如何存储用户资料、好友资料和扩展数据。所有数据都以Key-Value 格式存储。Key 为String 类型，仅支持大小写字母、数字和下划线。Value 支持以下类型：

用户资料：用户资料包括标准字段和自定义字段。有关自定义字段的信息，请参见扩展数据部分。当前聊天支持的标准字段详见 标准资料字段。

好友资料：好友资料包括标准和自定义好友字段。聊天的联系人列表最多支持 3000 个好友。标准好友字段描述如下：

有关更多信息，请参见 标准好友字段.

自定义资料：要申请自定义资料字段，应用管理员可以登录 聊天控制台，找到您的应用并进入功能配置。提交申请后，自定义资料字段将在五分钟内生效。

有关用户资料管理的更多信息，请参见 资料管理。

有关关系链自定义资料管理的更多信息，请参见 自定义好友字段。

聊天用户资料存储限制

服务功能限制

数据存储：每个字符串或缓冲区不能超过 500 字节。

自定义字段：自定义字段的关键字必须由英文字母组成，长度不得超过 8 字节。自定义字段的值不得超过 500 字节。

好友关系链：每个用户最多可以拥有 3000 个好友。

与 API 相关的限制

账户管理：每次最多可以导入 100 个用户名，每次请求最多可以查询 500 个用户的状态。

其他调用频率：每秒最多 200 次。

有关使用限制的更多信息，请参见 使用限制。

电子邮件系统

如今，电子邮件系统几乎是游戏中的必备功能。电子邮件可以包含文本消息，还可以包含游戏道具和奖励的附件。电子邮件可以发送给单个用户，也可以作为群发邮件发送以发放活动奖励。以下描述了如何实现电子邮件系统功能，从玩家接收电子邮件、电子邮件列表、电子邮件未读计数、向所有成员发送电子邮件以及电子邮件有效期等多个方面。

电子邮件接收和发送

玩家接收电子邮件：当系统电子邮件成功发送并且玩家在线时，玩家可以正确接收系统电子邮件。玩家可以通过获取电子邮件对话的消息列表来获取历史或最新电子邮件。他们还可以添加或删除监听器，以接收所有类型的新消息（包括文本、自定义和富媒体消息）。以下是 Unity 的示例代码：

// 配置消息接收事件监听器
TencentIMSDK.AddRecvNewMsgCallback((List<Message> messages, string user_data)=>{
foreach(Message message in messages)
{
  foreach (Elem elem in message.message_elem_array)
  {
    // 有下一个元素
    if (elem.elem_type == TIMElemType.kTIMElem_Text)
    {
       string text = elem.text_elem_content;
    }
  }
}
})
// 监听 `RecvNewMsgCallback` 回调以接收消息
// 要停止接收消息，可以调用 `RemoveRecvNewMsgCallback` 移除监听器。这一步是可选的，可以根据需要执行。

有关更多信息，请参见 Unity - 接收消息。

系统发送电子邮件：系统可以通过不同的服务器 API 向用户发送系统电子邮件，具体如下：

注意：

推送给所有用户仅适用于终极版。要使用此功能，您需要 购买终极版，然后转到控制台，选择功能配置 > 登录和消息 > 推送给所有用户，并启用该功能。

以下是发送普通消息到群组的基本请求示例：

{
    "GroupId": "@TGS#2C5SZEAEF",
    "Random": 8912345, // 随机数。如果两条消息的随机数在五分钟内相同，则视为同一消息。
    "MsgBody": [ // 消息主体，由元素数组组成。有关详细信息，请参见字段描述。
        {
            "MsgType": "TIMTextElem", // 文本
            "MsgContent":{
            "Text": "红包"
            }
        },
        {
            "MsgType": "TIMCustomElem", // 自定义
            "MsgContent":{
            "Data": "消息",
            "Desc": "通知",
            "Ext": "url",
            "Sound":"dingdong.aiff"
            }
        }
    ],
}

MsgBody（消息主体）是一个消息数组。您可以将文本和自定义消息添加到其中。

电子邮件列表

历史电子邮件列表的存储相当于消息的存储。它由历史一对一消息的存储和历史群组消息的存储组成。由于群聊至少需要两个用户，因此您可以创建一个包含管理员指定的账户和接收电子邮件的用户的群组进行存储。

注意：

对于免费版和专业版，存储期限为七天。对于终极版，存储期限为 30 天。专业版和终极版允许您延长存储期限。您可以登录 控制台 修改相关配置。延长历史消息的存储期限是收费增值服务。有关更多信息，请参见 增值服务定价。

当网络正常时，将拉取最新的云数据；当异常时，SDK 将返回本地存储的历史消息。支持分页拉取。以下是 Unity 拉取历史电子邮件列表的示例代码：

// 拉取历史一对一消息
// 将 `msg_getmsglist_param_last_msg` 设置为 `null` 以进行第一次拉取
// `msg_getmsglist_param_last_msg` 可以是返回的消息列表中的最后一条消息，用于第二次拉取。
var get_message_list_param = new MsgGetMsgListParam
{
    msg_getmsglist_param_last_msg = LastMessage
};
TIMResult res = TencentIMSDK.MsgGetMsgList(conv_id, TIMConvType.kTIMConv_C2C, get_message_list_param, (int code, string desc, string user_data) => {
// 处理回调逻辑
});

有关如何拉取历史消息的更多信息，请参见 历史消息 - Unity。

未读电子邮件计数

用户-系统电子邮件的记录相当于聊天中的对话。聊天提供对话未读计数功能，以提醒用户他们尚未阅读的消息。当用户点击对话并返回对话列表时，未读消息计数被清除。以下是 Unity 的示例代码：

// 获取总未读计数
TIMResult res = TencentIMSDK.ConvGetTotalUnreadMessageCount((int code, string desc, GetTotalUnreadNumberResult unread, string user_data)=>{
 // 处理异步逻辑
});

// 未读计数变化通知
TencentIMSDK.SetConvTotalUnreadMessageCountChangedCallback((int total_unread_count, string user_data)=>{
 // 处理回调逻辑
});

// 清除所有对话的未读计数
TIMResult res = TencentIMSDK.MsgMarkAllMessageAsRead((int code, string desc, string user_data)=>{
 // 处理异步逻辑
});

有关更多信息，请参见 Unity - 对话未读计数。

向所有成员发送电子邮件

向所有成员发送电子邮件是指向游戏中的所有玩家发送电子邮件消息。聊天在服务器端提供向所有成员推送的功能。以下是示例代码：

https://console.tim.qq.com/v4/all_member_push/im_push?usersig=xxx&identifier=admin&sdkappid=88888888&random=99999999&contenttype=json

以下是基本请求的示例：

{
    "From_Account": "admin",
    "MsgRandom": 56512,
    "MsgLifeTime": 120, // 离线存储 120 秒（两分钟）
    "MsgBody":[
        {
        "MsgType": "TIMTextElem",
        "MsgContent":{
            "Text": "嗨，美女"
            }
        }
    ]
}

MsgLifeTime（单位：秒）的设置允许您指定离线存储期限，以便即使某些用户不在线，他们也能在指定的离线存储期限内收到消息。最大期限为 604800 秒（七天）。默认值为 0，表示不进行离线存储。

有关更多信息，请参见 向所有用户推送。

电子邮件有效期

历史电子邮件的存储期限如下：对于免费版和专业版，存储期限为七天。对于终极版，存储期限为 30 天。专业版和终极版允许您延长存储期限。此外，在服务器端发送消息时，可以设置MsgLifeTime来指定消息的离线存储期限（最长七天）。如果MsgLifeTime为0，则表示仅发送给在线用户，不进行离线存储。有关更多信息，请参见 这里。

临时组队

临时组队在在线多人游戏中至关重要。以下描述了临时组队场景以及后台和队员如何获取组队信息。

基于团队的场景

基于团队的场景包括创建团队、离开临时团队、成为团队领导、邀请他人加入团队和解散团队。以下是一些代码示例，解释不同场景的实现。

• 在游戏开始前创建团队：当第一个玩家进入游戏时，服务器会自动创建一个组，并可以指定组成员的最大人数。如果请求指定了组的所有者或组成员，则在创建组时会自动将指定的组所有者或组成员添加到组中。以下是示例请求 URL：

https://console.tim.qq.com/v4/group_open_http_svc/create_group?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json

以下是基本请求示例：

{
  "Owner_Account": "leckie", // 组所有者的 UserId（可选）
  "Type": "Public", // 群组类型：私有、公开、聊天室、音视频聊天室或社区
  "Name": "测试组", // 群组名称（必填）
  "MaxMemberCount":5 // 最大组成员数（可选）
}

注意：

一个应用最多支持 100,000 个群组。对于额外的群组，您需要支付一定费用，具体请参见 定价。 有关服务器端创建组的更多信息，请参见 创建群组。

• 添加组成员：如果新的玩家在群聊创建后进入游戏，则需要将新玩家添加到现有群组中。以下是示例请求 URL：

https://console.tim.qq.com/v4/group_open_http_svc/add_group_member?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json

以下是请求示例：

{
  "GroupId": "@TGS#2J4SZEAEL", // 要添加成员的群组（必填）
  "MemberList": [ // 一次最多可以添加 300 个成员。
      {
          "Member_Account": "tommy" // 要添加的成员 ID（必填）
      },
      {
          "Member_Account": "jared"
  }]
}

有关更多信息，请参见 添加群组成员。

• Webhook 成功组队：如果在创建组时设置了最大组成员数，当所有必需的成员都在组中时，游戏才能开始。当收到组满后的 webhook 时，游戏可以开始。以下是示例请求 URL：

https://www.example.com?SdkAppid=$SDKAppID&CallbackCommand=$CallbackCommand&contenttype=json&ClientIP=$ClientIP&OptPlatform=$OptPlatform

以下是请求示例：

{
  "CallbackCommand": "Group.CallbackAfterGroupFull", // Webhook 命令
  "GroupId": "@TGS#2J4SZEAEL" // 群组 ID
}

有关更多信息，请参见 组满后的处理。

• 通知新成员加入组：当新玩家进入游戏（群聊）时，系统会发送用户加入群后的 webhook 通知其他组成员。以下是示例请求 URL：

https://www.example.com?SdkAppid=$SDKAppID&CallbackCommand=$CallbackCommand&contenttype=json&ClientIP=$ClientIP&OptPlatform=$OptPlatform

以下是请求示例：

{
  "CallbackCommand": "Group.CallbackAfterNewMemberJoin", // Webhook 命令
  "GroupId" : "@TGS#2J4SZEAEL",
  "Type": "Public", // 群组类型
  "JoinType": "Apply", // 加入方式：`Apply`（申请）；`Invited`（邀请）
  "Operator_Account": "leckie", // 操作员
  "NewMemberList": [ // 新成员列表
      {
          "Member_Account": "jared"
      },
      {
          "Member_Account": "tommy"
      }
  ]
}

注意：

要启用此 webhook，您必须配置 webhook URL 并开启相应协议。有关配置方法的详细信息，请参见 Webhook 配置。 有关更多信息，请参见 用户加入群后的处理。

• 在游戏中离开团队：当玩家自愿离开游戏或因网络问题而退出时，服务器可以通过 用户离开群后的 webhook 通知其他玩家有人离开群聊，并且还可以向因网络问题而离开的玩家发送消息。以下是关于 用户离开群后的处理。

https://www.example.com?SdkAppid=$SDKAppID&CallbackCommand=$CallbackCommand&contenttype=json&ClientIP=$ClientIP&OptPlatform=$OptPlatform

以下是请求示例：

{
  "CallbackCommand": "Group.CallbackAfterMemberExit", // Webhook 命令
  "GroupId": "@TGS#2J4SZEAEL", // 群组 ID
  "Type": "Public", // 群组类型
  "ExitType": "Kicked", // 成员离开类型：`Kicked` - 被踢出；`Quit` - 自愿离开
  "Operator_Account": "leckie", // 操作员
  "ExitMemberList": [ // 离开的成员列表
      {
          "Member_Account": "jared"
      },
      {
          "Member_Account": "tommy"
      }
  ]
}

• 游戏结束后解散群聊：游戏结束后，服务器端可以直接解散群聊。以下是关于 解散群组。

https://console.tim.qq.com/v4/group_open_http_svc/destroy_group?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json

以下是请求示例：

{
  "GroupId": "@TGS#2J4SZEAEL"
}

音视频聊天在临时团队中较为复杂，下面将详细阐述。

在后台获取团队信息

• 获取群组详情：您可以调用服务器 API 获取群组资料 来获取群组的详细信息，例如群组中的成员数量和成员的基本信息。您可以在请求中使用 Filter 字段来筛选要拉取的信息。以下是示例请求 URL：

https://console.tim.qq.com/v4/group_open_http_svc/get_group_info?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json

以下是请求示例：

{
  "GroupIdList": [ // 指定查询的群组 ID 列表。此参数为必填项。
      "@TGS#1NVTZEAE4",
      "@TGS#1CXTZEAET"
  ]
}

有关更多信息，请参见 获取群组资料。

• 获取群组成员详情：您可以调用 API 获取群组成员资料 来获取群组成员的详细信息（包括自定义字段）。以下是示例请求 URL：

https://console.tim.qq.com/v4/group_open_http_svc/get_group_member_info?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json

以下是请求示例：

{
  "GroupId":"@TGS#1NVTZEAE4"  // 群组 ID（必填）
}

在响应中，MemberNum 字段表示群组中的成员总数，AppMemberDefinedData 表示群组成员的自定义字段信息。

注意：

此 API 不支持音视频群组（AVChatRoom）。有关更多信息，请参见 获取群组成员资料。

团队成员获取团队信息

团队成员可以调用 API 获取组成员资料 来获取其他成员的详细信息，例如角色和状态。

GroupGetMemberInfoListParam param = new GroupGetMemberInfoListParam
{
  group_get_members_info_list_param_group_id = "group_id",
  group_get_members_info_list_param_identifier_array = new List<string>
  {
    "user_id"
  }
};
TIMResult res = TencentIMSDK.GroupGetMemberInfoList(param, (int code, string desc, GroupGetMemberInfoListResult result, string user_data)=>{
 // 处理异步逻辑
});

注意：

• 有关更多信息，请参见 Unity - 获取组成员资料.
• 有关其他组信息，例如在组满员后开始游戏以及成员加入或离开团队的信息，请参见 基于团队的场景. 此类信息将通过回调通知组。
• 有关组选择和其他组相关信息，请参见 组系统。有关组管理的更多信息，请参见 控制台指南 - 组管理.

过滤敏感信息

过滤敏感内容是游戏中的一项重要功能。实现方案如下：

1. 在发送组消息之前绑定 webhook。
2. 根据 webhook 数据识别消息类型，并将消息数据传递给腾讯云安全或其他第三方检测服务。
3. 如果消息是普通文本消息，等待腾讯云安全的检测结果，并返回数据包指示是否将消息传递给聊天后台。

发送消息前 webhook 的示例数据：

{
    "CallbackCommand": "Group.CallbackBeforeSendMsg", // Webhook 命令
    "GroupId": "@TGS#2J4SZEAEL", // 组 ID
    "Type": "Public", // 组类型
    "From_Account": "jared", // 发送者
    "Operator_Account":"admin", // 请求发起者
    "Random": 123456, // 随机数
    "OnlineOnlyFlag": 1, // 如果是在线消息则值为 `1`，如果不是则为 `0`（默认）。对于音视频组，值为 `0`。
    "MsgBody": [ // 消息体。有关更多信息，请参见 `TIMMessage` 消息对象。
        {
            "MsgType": "TIMTextElem", // 文本
            "MsgContent":{
                "Text": "红包"
            }
        }
    ],
    "CloudCustomData": "你的云自定义数据"
}

注意：

你可以根据 MsgType 字段在 MsgBody 中识别消息类型。有关字段的更多信息，请参见 发送组消息之前.

你可以选择以特定方式处理不合规的消息，这可以通过返回到聊天后台的数据包实现。

{
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0 // 不同的 `ErrorCode` 值有不同的含义。
}

注意：

你可以根据需要使用它们。

自定义消息类型（如道具赠送和交易消息）

游戏聊天除了简单的文本、表情和语音消息外，还需要自定义消息。自定义消息允许开发者自定义消息的内容格式，以实现更多聊天室功能，例如游戏道具赠送和交易。

聊天提供九种基本消息类型：文本、表情、地理位置、图片、语音、文件、用户生成短视频（UGSV）、系统通知和自定义消息。除自定义消息外，所有消息的格式都是固定的，用户只需输入相应的信息。有关消息类型的详细描述，请参见 一对一消息类型. 有关消息格式的更多信息，请参见 消息格式.

你可以通过服务器 API 向用户发送自定义消息 向一个用户发送一对一消息， 向多个用户发送一对一消息, 和 在组中发送普通消息。以下是发送普通消息的基本请求示例：

{
    "GroupId": "@TGS#2C5SZEAEF",
    "Random": 8912345, // 随机数。如果两条消息的随机数在五分钟内相同，则视为相同消息。
    "MsgBody": [ // 消息体，由元素数组组成。有关详细说明，请参见字段描述。
        {
            "MsgType": "TIMTextElem", // 文本
            "MsgContent":{
                "Text": "红包"
            }
        },
        {
            "MsgType": "TIMFaceElem", // 表情
            "MsgContent":{
            "Index": 6,
            "Data": "abc\u0000\u0001"
            }
        }
    ],
    "CloudCustomData": "你的云自定义数据",
    "SupportMessageExtension": 0,
}

你可以修改 CloudCustomData 来定义自定义消息数据（存储在云端），并在 MsgBody（消息体）中输入自定义消息进行发送。

团队中的音视频聊天

游戏中的音视频聊天是一项重要功能。聊天应用通过使用腾讯实时通信（TRTC）和 TUICallKit 提供实时音视频通话功能。

注意：

我们为每个 SDKAppID 提供 7 天的音视频通话能力免费试用。每个 SDKAppID 在聊天 控制台.

有关 TUICallKit 的更多信息，请参见 集成方案（UI 包含）- 音视频通话.

游戏聊天室类型

游戏聊天室类型描述如下：

聊天提供以下类型的聊天室：

以下提供一些基于聊天组特征的示例解决方案，可根据需要应用于你的游戏。

注意：

有关朋友和私人一对一聊天的权限控制的更多信息，请参见 一对一消息权限控制.

有关组系统的更多 信息 ，请参见 组系统.

立即订购

点击 这里快速进入购买页面进行订购。