Instant Messaging Overview
Instant Messaging allows you to quickly implement functions like instant messaging and data synchronization in your app. It is designed with the following goals:
Easily add messaging functions to existing apps
Many of our customers already have their products running smoothly and the only thing they need is to add instant messaging as a bonus feature in their apps. With this in mind, Instant Messaging is designed to work independently without interfering with your existing account systems.
We offer a full collection of UI frameworks and SDKs for you to design and develop messaging functions for a variety of platforms and scenarios.
Provide extensibility for custom features
Instant Messaging supports common types of messages including text messages, images, audios, videos, locations, and binary data. You can define your own types of messages and build UI for them if you need. You can also implement functions like recalling messages, editing messages, mentioning people, transient messages, delivery receipts, push notifications, and text moderation. If you want to build chat rooms that could hold infinite numbers of users, or system conversations that could be used for chatbots, Instant Messaging also got you covered.
Enhance security with permission management
When you use Instant Messaging, clients and servers use full-duplex communication channels through WebSocket with TLS encrypted transmissions. This ensures that conversations happening within your app cannot be fetched by any unauthorized parties. To further control user activities, you can use our third-party signing mechanism to verify all the sensitive operations before they can be processed. We also provide out-of-the-box role management and blacklist system that work perfectly for scenarios like group chats and chat rooms.
Lower costs for maintenance
With our 24/7 technical support backed by experienced engineers, you can be confident that you are able to integrate our services into your projects with a minimal amount of hassle. Besides this, you are also freed from handling all the errors that might happen to software and infrastructure, as well as upgrading servers when the usage of your app grows quickly.
Instant Messaging is already widely used in scenarios like in-app socializing, remote collaboration, customer service, live streaming, and game state synchronization.
Features
Here are the main features offered by Instant Messaging:
Basic chatting
- Besides one-on-one chats and group chats, we also offer open chat rooms that could hold infinite numbers of people, which can be used for scenarios like live streaming and open courses that demand massive discussions in a group. There are also system conversations that could interact with users spontaneously, as well as temporary conversations which work best if you need to build customer service systems. All these functions share the same programming interface.
- Users can send all kinds of messages, including text messages, images, audios, videos, locations, and binary data. You can develop your own types of messages if you need.
- History messages are automatically saved on the cloud, which can be retrieved in multiple ways.
Advanced messaging features
- Mentioning people with "@"
- Recalling and editing messages
- Getting receipts when messages are delivered and read
- Muting conversations
- Sending status updates like "Someone is typing…"
- Converting messages to push notifications when receivers are offline
- Setting priorities for messages in chat rooms so that important messages can get quicker delivery
Multi-device sign-on and message synchronization
It is becoming a common requirement that users can have their accounts logged in on multiple devices at the same time. Here we allow you to make your own decision whether users can do so and receive messages on all their devices, or they can only log in on a single device at a time. What if a user accidentally loses their connection to the Internet? No worries. Our synchronization mechanism guarantees that unreceived messages can always be synchronized to users' devices once the connection is re-established.
Group management
For group chats and chat rooms, users can be nominated as administrators so they can gain additional permissions and help creators manage conversations. Features like inviting users, removing users, blacklisting users, and muting users can also be easily implemented. The messages sent through all the conversations can be filtered upon a list of keywords you define or through a plugin you build. This helps your apps comply with the laws and regulations in the areas they are operated.
Access control
For any user that wants to send and receive messages, the only thing they need is a
clientIdidentifying them. By decoupling with the account system of the app, it is made easy for you to add Instant Messaging into your app and it also helps us better focus on our role as a "messenger". We provide a third-party signing mechanism that allows you to verify all the operations performed within the app with your own server. This ensures that all the requests sent to the server are legitimate. Our SDKs and the cloud use full-duplex communication channels through WebSocket with TLS encrypted transmissions, which further ensures the security of users' conversations.Customizable components
We offer a number of common features that you can directly use, while you also have the freedom to build your own logic for your special needs:
- You can verify operations like creating/joining/leaving conversations and retrieving history messages by connecting to your existing account system via our third-party signing mechanism.
- You can attach hooks to different stages of a message delivery process to implement your custom logic like filtering out certain keywords or customizing push notifications.
- You can use webhooks to implement message synchronization between the cloud and your app's backend.
- Besides client-side SDKs, we also offer REST APIs for you to implement functions under trusted environments.
Our flexibility and extensibility give you the power to add more fun to your app besides the basic chatting functions.
Cross-Platform Support
We offer client-side SDKs for a variety of mainstream platforms. Feel free to take a look at their source code on our GitHub. You are welcome to talk to us if you have any questions or needs.
You may also try out our demos to quickly familiarize yourself with our services. You can find them on Download > Demos.
Terminologies
The concepts mentioned below will be used frequently in our documentation. It would be helpful if you could familiarize yourself with them.
clientId, User, and Log in
In Instant Messaging, each terminal is called a "client". Each client has a unique ID (clientId) that marks itself within an app. Such an ID can be generated by your app, but it has to be a string of alphanumeric characters, underscores, and hyphens that is not longer than 64 characters and does not begin with a numeric character. In most cases, each client matches an actual user of your app, but it does not mean that only users can act as clients. A probe can also be a client that keeps broadcasting the data collected by it to other people.
To start using Instant Messaging, each client needs to build a WebSocket connection to the cloud and register itself with a unique clientId. Such a process is called "logging in". Keep in mind that this is not the same as the log-in process of the app itself.
By default, a clientId can log in on multiple devices, and multiple clientIds can log in on the same device as well. If you want each user to be logged in on only one device at a time, you can specify a "tag" when logging in so that when duplicated tags are detected on the cloud, the devices that are already logged in will be logged out. You can decide whether to use tags or not based on your actual needs.
After logging in, our SDK will ensure that the connection is always alive and will automatically reconnect if the network status ever changes. The connection will be ended once the app goes into the background and push notifications will be used for message delivery.
Conversation
When a user starts chatting with someone after logging in, a Conversation would be formed. In Instant Messaging, a conversation contains all the members belonging to it and holds all the messages sent by them, so whenever a client sends a message, it is always sent into a conversation. Before a client could send messages to others, it has to create or join a conversation first and invite other people to it (optional). Only those who are inside a conversation can have access to the messages in it.
When a conversation is created, a record would be added to the _Conversation table which can be found on Developer Center > Your game > Game Services > Cloud Services > Data Storage > Data. Each conversation holds properties like group name, members, as well as custom attributes. The table below shows the relationship between the properties of a conversation and the fields of the _Conversation table:
| Property | Table Field | Type | Constraint | Description |
|---|---|---|---|---|
name | name | String | Optional | The name of the group chat. |
attributes | attr | Object | Optional | Custom attributes. |
conversationId | objectId | String | A unique ID generated by the cloud (read-only). | |
creator | c | String | The clientId of the creator (read-only). | |
members | m | Array | All the members of a basic conversation (not applicable for chat rooms or system conversations). | |
mute | mu | Array | Members who muted the conversation. These members will not receive push notifications. | |
lastMessageAt | lm | Date | The time the last message is sent. | |
transient | tr | Boolean | Optional | Whether it is a chat room. |
system | sys | Boolean | Optional | Whether it is a system conversation. |
unique | unique | Boolean | Optional | If this is true, the same conversation will be reused when a new conversation is created with the same composition of members and unique to be true. |
We do have different types of conversations designed for different scenarios. All of them will be stored in _Conversation regardless of their types.
Common Scenarios
Let's first go through some common scenarios where Instant Messaging could be used.
One-on-one chats
This is the conversation between two clients and you can decide whether other users can find it or not (usually it is private). It will be converted to a group chat if new clients are added to it and, again, you can decide if all the members will stay in the same conversation or form a new one.
Group chats
A group chat contains two or more clients and oftentimes members can be added or removed at any time. A name is usually assigned to a group chat, such as "Family", "Friends", or "Co-workers". It is possible for a group chat to have only two or even one member, but it does not make any difference on whether it is considered a group chat or not. You can decide if group chats are public (such as searchable by name) or not.
Chat rooms
A chat room is similar to a group chat since both of them involve a lot of people. What makes a chat room different is that the number of people in it is often way higher than that of a group chat. In such a situation, the number of people in a chat room becomes more meaningful than the specific list of people in it. There is also a difference in how members of a conversation are managed. By opening a chat room, a client joins it, and by closing it, the client leaves it. Therefore, message synchronization and push notifications are disabled for chat rooms.
Official accounts and bots
You can build official accounts in your app and have them broadcast messages to the users who subscribe to them or chat with specific users. You can also implement bots that can automatically reply to messages sent from users.
Customer service
Customers can start temporary conversations with representatives to discuss solutions to their problems. These conversations can be closed once the problems are solved.
Instant Messaging offers the following four types of conversations to cover all these scenarios.
Basic Conversation
This is the most commonly used type of conversation that could serve one-on-one chats and group chats. It offers the following functions:
- Send and receive messages among members of it
- Add and remove members (500 maximum) with all the existing members notified
- Find out who are online
- Mention members, recall messages, edit messages, send transient messages, get receipts when messages are delivered and read, send will messages, and receive push notifications
- Receive push notifications when offline and synchronize unreceived messages when online
- Store message history on the cloud and perform various types of queries on it
Tips: You may assign properties to a conversation to mark if it is a one-on-one chat or a group chat. You may also mark if a conversation is private or public. Such properties can be stored in Conversation.attributes.
Chat Room
This type of conversation is dedicated to chat rooms (it has tr to be true in _Conversation). Similar to a basic conversation, users can create, join, or leave it at any time and all the messages will be stored on the cloud. It is different from a basic conversation on the following basis:
- No limit on the number of people; does not have a fixed list of members; members are removed once they are offline (field
mis ignored) - The number of members can be retrieved instead of the specific list of members
- No offline messages, push notifications, or delivery receipts
- No notifications for members joining or leaving
- Cannot invite or remove people
- A user can only be in one chat room at each time and will automatically leave the previous one when joining a new one
- A user has to rejoin a chat room if it becomes offline for more than 30 minutes
Tips: Although a chat room does not limit the number of people in it, the user experience can be impaired when there are too many people sending a lot of messages. We suggest that you limit the number of people in each chat room to less than 5,000 and split big chat rooms into smaller ones if possible.
System Conversation
This type of conversation can be used to build bots, official accounts, service accounts, and in-app notifications (it has sys to be true in _Conversation). It has the following traits:
- A user subscribes to it by joining and unsubscribes by leaving (field
mis ignored) - Conversations can only be created on the server side and clients can only subscribe or unsubscribe to the existing conversations
- Messages can be sent to either all subscribers or specific users
- The messages sent from users will be stored in the
_SysMessagetable and cannot be seen by other users - You can set up hooks to receive messages from users and reply to them with REST API
Temporary Conversation
This type of conversation does not get stored in the _Conversation table. It is meant for special scenarios with:
- Short TTL
- Fewer members (10 clients maximum)
- No message history needed
We recommend temporary conversation to be used for customer service. It has the following traits:
- Cannot mute or unmute
- Cannot update attributes
- Allow message operations and querying members just like basic conversations
Tips: Temporary conversations last shorter and do not get stored in the _Conversation table. This reduces the size of data stored in your app and lowers the cost needed as well.
Summary
| Type of Conversation | Scenarios | Member Management | Message Operations | Message History |
|---|---|---|---|---|
| Basic Conversation | One-on-one chats and group chats | Members are persisted (500 members maximum) | Only members can send or receive messages | Supported |
| Chat Room | Chat rooms, barrage, and real-time comments | Members are not persisted; Users cannot be invited; No limit on the number of people | Everyone can send messages; Online users can receive messages | Supported |
| System Conversation | Official accounts, bots, system notifications, and custom messages | Does not have the concept of members; A list of subscribers can be maintained; No limit on the number of subscribers | Messages can be sent to subscribers through API; Webhooks can be set up to handle messages | Supported |
| Temporary Conversation | Customer service | Fixed members | Only members can send or receive messages | Not supported |
Message
A message is a basic unit for transmitting data within a conversation. Each message can hold up to 5 KB of data in the format of text. There is no requirement on how the text should be formatted and you are free to define your own types of messages based on it.
When sending a message, a parameter can be specified to make it either a normal message or a transient message. A normal message comes with features like delivery receipts, persistent storage, and push notifications, while a transient message cannot be saved, received later, or pushed to offline users. Therefore, status updates like "Someone is typing…" are best sent as transient messages and messages composed by users shall be sent as normal messages.
Our service ensures that a normal message can be delivered at least once. At the same time, our SDKs are able to filter out duplicate messages. We offer both SDKs and REST API for you to send messages: SDKs are often for clients and REST API is for sending messages from the server side. When using REST API, you can specify the sender of a message and the ID of the target conversation, as well as the receivers of the message if it is sent to a system conversation.
Default Types for Rich Media Messages
We offer a number of predefined JSON-based types (TypedMessage) for rich media messaging, including:
- Text (
TextMessage) - Image (
ImageMessage) - Audio (
AudioMessage) - Video (
VideoMessage) - Location (
LocationMessage)
The image below shows the inheritance relationships among them:
As mentioned above, rich media messages are based on the JSON format. Therefore, they need to be serialized to a JSON string containing the following properties when sent via the REST API. Client-side SDKs will do the conversion automatically when sending messages.
| Property | Constraint | Description | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
_lctype | Type of the rich media message
| |||||||||||||||
_lctext | Text description of the rich media message | |||||||||||||||
_lcattrs | A JSON string containing custom attributes | |||||||||||||||
_lcfile | If the message contains a file (image, audio, video, or generic file), _lcfile would contain the information about that file. | |||||||||||||||
url | The URL of the file after it is uploaded. Note that the URL in historical messages will not be updated when you bind or re-bind a custom domain name. | |||||||||||||||
objId | Optional | The objectId of the file in the _File class. | ||||||||||||||
metaData | Optional | File metadata. |
The above properties are common to all types of rich media messages.
You can easily extend your own message types based on our framework.
Advanced Features
As mentioned earlier, we offer the following functions besides basic chatting:
- Mentioning people with "@"
- Recalling and editing messages
- Text moderation
- Getting receipts when messages are delivered and read
- Muting conversations
- Sending status updates like "Someone is typing…"
- Converting messages to push notifications when receivers are offline
- Setting priorities for messages in chat rooms so that important messages can get prioritized delivery
You can read Advanced Messaging Features and Text Moderation to learn more about them.
Restrictions
- In every minute, a client can send at most 60 messages, query history messages at most 120 times, and perform operations like joining conversations, leaving conversations, logging in, and logging out at most 30 times. Incoming requests will be rejected if the limits are exceeded (the callbacks implemented with SDK will not be triggered). If you are performing these operations with REST API, the limits will not apply.
- For each app, at most 160,000 messages can be delivered to all the clients each second. The messages exceeding the limit will be discarded. Please contact us if your app needs a higher quota.
- The size of each message (including metadata such as
pushData) shall be less than or equal to 5 KB. - Each conversation can hold at most 500 people. If you add more than 500 IDs into the
mfield with the Data Storage API, only the first 500 IDs will be used. - The same ID is not supposed to be logged in on too many devices. If we detect that an ID is logged in on more than 5 IP addresses at the same time, this ID will be billed with each IP as an independent user on that day.
- If a user has more than 50 conversations containing unread messages, the cloud will randomly pick 50 of them and deliver their unread messages (or the amounts of them) to the user when the user logs in. The undelivered messages will not be lost but need to be manually retrieved.
- If a user has a conversation containing more than 100 offline messages, the former messages will not be automatically delivered when the user logs in and the user will not see the amount of them. The undelivered messages can be manually retrieved.
- Updating the file URL (Developer Center > Your game > Game Services > Cloud Services > Data Storage > File > Settings) will not automatically refresh the URLs in the existing messages (including rich media messages).
- There are request frequency and quantity limitations on invoking Instant Messaging-related REST APIs. See Instant Messaging REST API Guide for details.
Lifespan of Conversations
If no message is sent to a conversation (basic conversation, chat room, or system conversation) in the past 6 months through either SDK or REST API, or none of its fields in the _Conversation table are updated, the conversation will be considered inactive and will be deleted automatically. Keep in mind that querying messages does not update the _Conversation table, so a conversation that only gets queried will also be seen as inactive.
If you attempt to send a message to a deleted conversation through either SDK or REST API, the error 4401 INVALID_MESSAGING_TARGET will be returned which means that the conversation does not exist anymore. The messages associated with deleted conversations will also be gone.
Active conversations will never get deleted.
Lifespan of Messages
A message will be stored on the cloud for 6 months. This means that you can only query the message history of a conversation in the past 6 months. If you would like to pay to extend the period, please reach out to us. You may also synchronize the message history to your own server with REST API.
Hooks
See Hooks.
Price
Charged by active users, up to 500 users for free each day, for overage: 1 USD / 10,000 users per day.
- REST API charges by number of requests. Same as Data Storage: first 30,000 times for free each day, for overage: 0.04 USD / 1000 times.
- A file fee is charged for multimedia messages using the file service. Please refer to the price page of the official website.
- All requests to the '_Conversation' table incur a data storage charge. The price is the same as Data Storage.
Guides
Basic features:
- 1. Basic Conversations and Messages
- 2. Advanced Messaging Features, Push Notifications, Synchronization, and Multi-Device Sign-on
- 3. Security, Permission Management, Chat Rooms, and Temporary Conversations
- 4. Hooks and System Conversations
REST API: