Instant messaging is a common requirement of games, and instant chat has become an essential feature in multiplayer games. The game platform itself involves a variety of group types, custom message types (such as in-game props gifting and trading), global access, and other complex requirements. This document sorts out the implementation methods of common requirements in the process of building in-game chat, along with possible problems and considerations, helping developers quickly understand the business and implement their requirements.
Preparations
Calculating the UserSig with a key
In the Chat account system, the password required by a user login is calculated by the server with a key provided by Chat. For more information, see Generating UserSig. In the development phase, to avoid holding back development on the client, you can also calculate the UserSig in the console as shown below:
Configuring an admin account
Managing in-game instant messaging may require admins to send email announcements to games, manage temporary team-up messages, and so on, which can be done through Chat server APIs. To call these APIs, you need to create a Chat admin account. By default, Chat provides an account with the UserID of administrator. You can also create multiple admin accounts as needed. Note that you can create up to five admin accounts.
Configuring the callback address and enabling the callback
To implement in-game team-up and other requirements, you use the Webhook event, where the Chat backend calls the business backend in certain scenarios. You only need to provide an HTTP API and configure it in the Webhook Configuration module in the console as shown below:
Integrating the client SDK
After completing the preparations, you need to integrate the Chat client SDK into your project. You can select different integration options as needed. For detailed directions, see TUIKit Introduction.
The following describes common Chat features to be integrated into games and provides best practices with implementation code.
Game Chat Room Feature Development Guide
User profile
Common user profile
Common user profiles stored in gaming business can be divided into basic information profiles and other information profiles.
Basic Information
Other Information
Username, gender, date of birth, level, role, mobile number, etc.
Other information required by games
Profile storage
The gaming business has a large number of users and it is difficult to store huge amounts of user data. Tencent Cloud Chat offers a complete set of profile solutions through its user profile hosting capabilities. The following compares storing user profiles to Tencent Cloud Chat and to the business background.
Item
Chat
Business Background
Storage capacity
Supports automatic scaling
Supports limited capacity and difficult to scale
User profiles
Supports standard and custom fields, with restrictions on the lengths and names of the fields
Customizable, more flexible
Profile read/write
Supports easy-to-use service APIs and guidelines
Requires development on your own
APIs
Requires the API call frequency to be 200 times/second or less
Allows you to develop API call and other capabilities as needed
Security
Supports remote disaster recovery and cross-region deployment
Requires maintenance on your own
In addition to profile storage and read/write capabilities, Chat has the following advantages thanks to its user profile hosting service:
1. Chat provides remote disaster recovery, cross-region deployment, and auto scaling capabilities. In this way, you are completely free from complex processing flows, such as server downtime, multi-copy primary-secondary replication, and capacity scaling.
2. Chat provides the business processing flows commonly used in the industry, with which you do not have to worry about user profile business logic.
3. Chat provides professional operation processes and teams, ensuring 99.99% service quality annually and helping you offer services known for their stability.
4. Chat provides easy-to-use service APIs and easy-to-access guidelines, with premium services throughout the whole process.
Chat user profile storage methods
The Chat storage scheme includes user profile storage and read/write capabilities. The following describes how Chat stores user profile, friend profile, and extension data. All data is stored in Key-Value format. Key is of the String type and supports only uppercase and lowercase letters, digits, and underscores. Value supports the following types:
Type
Description
uint64_t
Integer (Not supported by custom fields.)
string
String. The string length cannot exceed 500 bytes.
bytes
Buffer. The buffer length cannot exceed 500 bytes.
string array
String array. Each string cannot exceed 500 bytes. Available only to the Tag_SNS_IM_Group field of the friend list.
User profile: A user profile includes standard and custom fields. For the custom fields, see the extension data part below. For the standard fields currently supported by Chat, see Standard Profile Fields.
Friend profile: A friend profile includes standard and custom friend fields. Chat's contact list supports up to 3,000 friends. The standard friend fields are described as follows:
Custom profile: To apply for custom profile fields, the app admin can log in to the Chat console and find your app and go to Feature Configuration. After the application is submitted, custom profile fields will take effect in five minutes.
For more information on user profile management, see Profile Management.
For more information on relationship chain custom profile management, see Custom friend fields.
Chat user profile storage limits
Service feature limits
Data storage: Each string or buffer cannot exceed 500 bytes.
Custom fields: The keywords of custom fields must consist of English letters with a length no longer than 8 bytes. The values of custom fields cannot exceed 500 bytes.
Friend relationship chain: Each user can have up to 3,000 friends.
API-related limits
Account management: Up to 100 usernames can be imported at a time, and the status of up to 500 users can be queried per request.
Other call frequency: Up to 200 times per second.
For more information on the use limits, see Use Limits.
Email systems
Email systems are almost mandatory in games these days. Emails can contain text messages, as well as email attachments such as game props and rewards. An email can be sent to a single user, or it can be sent as a group email to give out event rewards. The following describes how the features of an email system are implemented from diverse aspects such as players receiving emails, email list, email unread count, sending emails to all members, and email validity period.
Email receiving and sending
Players receiving emails: When system emails are sent successfully and players are online, the players can receive the system emails properly. The players can obtain the historical or latest emails by getting the message list of email conversations. They can also add or delete the listener for the receiving of new messages of all types (including text, custom, and rich media messages). The sample code for Unity is as follows:
A one-to-one message can be sent to up to 500 users at a time, and the highest call frequency is 200 times per second.
Sending messages to specific users, without the need to create a recipient group. If the number of recipients is large, you need to send the messages in batches.
Pushes messages to all users in an app. You can specify user tags and attributes for message sending.
Pushing messages to all users in an app or to a large number of users with specific characteristic attributes, such as campaign emails
Note:
Pushing to all users is available only to the Ultimate edition. To use it, you need to purchase the Ultimate edition, go to the console, choose Feature Configuration > Login and Message > Push to all users, and enable the feature.
The following is a sample of a basic request for sending an ordinary message in a group:
{
"GroupId":"@TGS#2C5SZEAEF",
"Random":8912345,// A random number. If the random numbers of two messages are the same within five minutes, they are considered to be the same message.
"MsgBody":[// Message body, which consists of an element array. For details, see the field description.
{
"MsgType":"TIMTextElem",// Text
"MsgContent":{
"Text":"red packet"
}
},
{
"MsgType":"TIMCustomElem",// Custom
"MsgContent":{
"Data":"message",
"Desc":"notification",
"Ext":"url",
"Sound":"dingdong.aiff"
}
}
],
}
MsgBody (message body) is a message array. You can add text and custom messages to be sent to it.
Email list
The storage of the historical email list is equivalent to the storage of messages. It consists of the storage of historical one-to-one messages and the storage of historical group messages. Because a group chat requires at least two users, you can create a group containing the account specified by the admin and the user receiving the email for storage.
Note:
For the Free edition and Pro edition, the storage period is seven days. For the Ultimate edition, the storage period is 30 days. The Pro edition and Ultimate edition allow you to extend the storage period. You can log in to the console to modify related configuration.
Extending the storage period of historical messages is a paid value-added service. For more information on billing, see Value-added Service Pricing.
When the network is normal, the latest cloud data will be pulled; when it is abnormal, the SDK will return the locally stored historical messages. Paged pulling is supported. The following is Unity sample code for pulling the historical email list:
// Pull historical one-to-one messages
// Set `msg_getmsglist_param_last_msg` to `null` for the first pull
// `msg_getmsglist_param_last_msg` can be the last message in the returned message list for the second pull.
A record of a user-system email is equivalent to a conversation in a chat. Tencent Cloud Chat provides a conversation unread count feature to remind users that they have not yet read messages. When a user clicks into the conversation and returns to the conversation list, the unread message count is cleared. The following is Unity sample code:
Sending emails to all members is to send email messages to all players in a game. Tencent Cloud Chat provides the pushing to all members feature at the server side. The following is sample code:
"MsgLifeTime":120,// Offline storage for 120s (two minutes)
"MsgBody":[
{
"MsgType":"TIMTextElem",
"MsgContent":{
"Text":"hi, beauty"
}
}
]
}
The feature of sending messages to all members allows you to set the offline storage period, so that even if some users are not online, they can still receive the messages within the specified offline storage period. Configure MsgLifeTime (unit: second) to specify the offline storage period: The maximum period is 604,800 seconds (seven days). The default value is 0, which indicates that messages are not stored offline.
The storage period of historical emails is as follows: For the Free edition and Pro edition, the storage period is seven days. For the Ultimate edition, the storage period is 30 days. The Pro edition and Ultimate edition allow you to extend the storage period. For more information on the storage of historical emails, see Historical message storage period settings.
In addition, when sending a message on the server side, you can set MsgLifeTime to specify the offline storage period (up to seven days) of the message. If MsgLifeTime is 0, it indicates that the message is sent to online users only and is not stored offline. For more information, see here.
Temporary team-up
Temporary team-up is essential in online multiplayer games. The following describes temporary team-up scenarios and how the background and team members obtain team information.
Team-based scenarios
Team-based scenarios include creating a team, leaving a temporary team, becoming the team leader, inviting others to join a team, and disbanding a team. The following are some code examples to explain the implementation of different scenarios.
Creating a team before the game begins: When the first player enters the game, the server automatically creates a group and the maximum number of group members can be specified. If the request specifies the group owner or group members, the specified group owner or group members will be automatically added to the group when the group is created. The following is a sample request URL:
"Owner_Account":"leckie",// UserId of the group owner (optional)
"Type":"Public",// Group type: Private, Public, ChatRoom, AVChatRoom, or Community
"Name":"TestGroup",// Group name (required)
"MaxMemberCount":5// Maximum number of group members (optional)
}
Note:
An app supports up to 100,000 groups. For extra groups, you need to pay certain fees, as described in Pricing. For more information on group creation on the server side, see Creating a Group.
Adding group members: If new players enter the game after the group chat is created, you need to add the new players to the existing group. The following is a sample request URL:
Webhook for successful team-up: If the maximum number of group members is set when creating a group, the game can start only when all the required number of members are in the group. When the webhook after a group is full is received, the game can be started. The following is a sample request URL:
Notification on a new member joining the group: When a new player enters the game (group chat), the system sends the webhook after a user joins a group to notify other group members. The following is a sample request URL:
"JoinType":"Apply",// Group joining method: `Apply` (application); `Invited` (invitation)
"Operator_Account":"leckie",// Operator
"NewMemberList":[// List of new members
{
"Member_Account":"jared"
},
{
"Member_Account": "tommy
}
]
}
Note:
To enable this webhook, you must configure the webhook URL and toggle on the corresponding protocol. For details on the configuration method, see Webhook Configuration. For more information, see After a User Joins a Group.
Leaving a team during a game: When a player leaves the game voluntarily or due to network problems, the server can notify other players in the group that someone leaves the group chat through the webhook after a user leaves a group and can also send a message to the player who leaves the game due to network problems. The following is a request URL example for After a User Leaves a Group:
"ExitType":"Kicked",// Member leaving type: `Kicked` - being kicked out; `Quit` - voluntarily leaving
"Operator_Account":"leckie",// Operator
"ExitMemberList":[// List of members who left the group
{
"Member_Account":"jared"
},
{
"Member_Account":"tommy"
}
]
}
Disbanding a group chat after a game ends: After a game ends, the server side can disband the group chat directly. The following is a request URL example for Disbanding a Group:
Audio/Video chat in temporary teams is complex and will be elaborated below.
Getting team information in the background
Getting group details: You can call the server API Getting Group Profiles to get group details such as the number of members in the group and the basic information of the group members. You can use the Filter field in the request to filter the information to pull. The following is a sample request URL:
Getting group member details: You can call the API Getting Group Member Profiles to get the detailed information of group members (including custom fields). The following is a sample request URL:
In the response, the MemberNum field indicates the total number of members in the group, and AppMemberDefinedData indicates the custom field information of group members.
Members of a team can call the API Getting Group Member Profiles to get the detailed information, such as role and status, of other members in the team.
For other group information such as starting a game after a group is full and members joining or leaving a team, see Team-based scenarios. Such information will be notified to the group via callbacks.
For more information about group selection and other group related information, see Group System. For more information about group management, see Console Guide - Group Management.
Filtering sensitive information
Filtering sensitive content is an important feature for games. The implementation scheme is as follows:
1. Bind the webhook before sending a group message.
2. Identify the message type based on the webhook data and deliver the message data to Tencent Cloud Security or another third-party detection service.
3. If the message is an ordinary text message, wait for the detection result of Tencent Cloud Security and return the data packet indicating whether to deliver the message to the Chat backend.
Sample data of the webhook before sending a message:
"OnlineOnlyFlag":1,// The value is `1` if it is an online message and `0` (default) if it’s not. For audio-video groups, the value is `0`.
"MsgBody":[// Message body. For more information, see the `TIMMessage` message object.
{
"MsgType":"TIMTextElem",// Text
"MsgContent":{
"Text":"red packet"
}
}
],
"CloudCustomData":"your cloud custom data"
}
Note:
You can identify the message type based on the MsgType field in MsgBody. For more information on the fields, see Before a Group Message Is Sent.
You can choose to handle a non-compliant message in a specific way, which can be implemented through the data packet in the webhook returned to the Chat backend.
{
"ActionStatus":"OK",
"ErrorInfo":"",
"ErrorCode":0// Different `ErrorCode` values have different meanings.
}
ErrorCode
Description
0
Speaking is allowed, and messages can be delivered normally.
1
Speaking is rejected, and the client returns 10016.
2
Silent discarding is enabled, and the client returns messages normally.
Note:
You can use them as needed.
Customizing message types (such as props gifting and trading messages)
Game chats require custom messages in addition to simple messages such as text, emoji, and voice messages. Custom messages allow developers to customize the content format of messages to implement more chat room features such as game props gifting and trading.
Tencent Cloud Chat provides nine basic message types: text, emoji, geographical location, image, voice, file, user generated short video (UGSV), system notification, and custom messages. The formats of all messages except custom messages are fixed, and users only need to enter corresponding information. For the detailed descriptions of the message types, see One-to-One Message Types. For more information on the message formats, see Message Formats.
"Random":8912345,// A random number. If the random numbers of two messages are the same within five minutes, they are considered to be the same message.
"MsgBody":[// Message body, which consists of an element array. For details, see the field description.
{
"MsgType":"TIMTextElem",// Text
"MsgContent":{
"Text":"red packet"
}
},
{
"MsgType":"TIMFaceElem",// Emoji
"MsgContent":{
"Index":6,
"Data":"abc\\u0000\\u0001"
}
}
],
"CloudCustomData":"your cloud custom data",
"SupportMessageExtension":0,
}
You can modify CloudCustomData to define the custom message data (stored on the cloud) and enter the custom message in MsgBody (message body) for sending.
Audio/Video chat in teams
Audio/Video chat in games is an important feature. Tencent Cloud Chat apps are equipped with real-time audio/video call features by using Tencent Real-Time Communication (TRTC) and TUICallKit.
Note:
We provide a 7-day free trial of the audio/video call capability for each SDKAppID. You can obtain only one free trial for each SDKAppID in the Chat console.
A channel usually engages a large number of chat users and does not have a list of fixed members. Users can join and leave a channel at any time. Offline message push is not required.
Live game lobby
A live game lobby usually engages a number of chat users. Users can join and leave the live room at any time. Historical message query is supported.
Team
A team usually engages a small number of chat users, who do not need to be friends with each other. A team is terminated when a game ends. Offline message push is not required.
Friend
One-to-one chat. Chat records are stored. Chat partners can only be friends in the contact list.
Private message
One-to-one chat. Chat partners can be strangers.
Audio-video group
There is no limit on the number of chat users. Users can join and leave an audio-video group at any time.
Chat provides the following types of chat rooms:
Type
Characteristics
Work group (Work)
A work group allows users to join the group by being invited by a friend who is a member of the group. The invitation does not need to be accepted by the invitee or approved by the group owner.
Public group (Public)
A public group allows the group owner to designate group admins. To join the group, a user needs to search for the group ID and send a request, and the request needs to be approved by the group owner or an admin before the user can join the group.
Meeting group (Meeting)
A meeting group allows users to join and leave freely and view historical messages sent before they join the group. Meeting groups are ideal for scenarios that integrate Tencent Real-Time Communication (TRTC), such as audio/video conferencing and online education. This group type is the same as chat room (ChatRoom) in earlier versions.
Audio-video group (AVChatRoom)
An audio-video group allows users to join and exit freely, supports an unlimited number of members, and does not store message history. Audio-video groups can be used with Cloud Streaming Services (CSS) to support on-screen comment chat scenarios.
Community group (Community)
A community group allows users to join and exit freely, supports up to 100,000 members, and stores message history. To join the group, a user needs to search for the group ID and send an application, and the application does not need to be approved by an admin before the user can join the group.
The following provides some sample solutions based on Chat group characteristics, which can be applied to your games as needed.
Type
Solution
Characteristics
Channel and live game lobby
Community group
A community group supports a large number of users and allows users to join and leave freely, without approval.
Friend
One-to-one chat+Permission control (allowing only friends to send messages to each other)
Only friends are allowed to send messages to each other.
Private message
One-to-one chat+Permission control (allowing any two users in the app to send one-to-one messages to each other)
Any two strangers can send messages to each other.
Team-up
Public group (Public) and meeting group (Meeting)
Only team members in the game can enter the group chat. Audio-video chat is supported.
Audio-video group
Audio-video group (AVChatRoom)
There is no limit on the number of group members, and users can join or leave an audio-video group at any time.
Yes
No
Was this page helpful?