Real-time Chat
Real-time chat makes it easy to power a live community.
Users can chat with each other 1-on-1, as part of a group, and in chat rooms. Messages can contain images, links, and other content. These messages are delivered immediately to clients if the recipients are online and stored in message history so offline users can catch up when they connect.
Every message which flows through the real-time chat engine belongs to a channel which is used internally to identify which users should receive the messages. Users explicitly join and leave channels when they connect. This makes it easy to selectively listen for messages which they care about or decide to “mute” certain channels when they’re busy. Users can also join multiple channels at once to chat simultaneously in multiple groups or chat rooms.
Chat channels
There are 3 types of channels:
- A chat room is great for public chat. Any user can join and participate without the need for permission. These rooms can scale to millions of users all in simultaneous communication. This is perfect for live participation apps or games with live events or tournaments.
- A group chat is private to only users part of a group. Each user must be a member of the group and no other users can participate. You can use group chat with team-based gameplay or collaboration.
- Direct chat is private between two users. Each user will receive a notification when they’ve been invited to chat. Both users must join for messages to be exchanged which prevents spam from bad users.
Persistence
By default all channels are persistent, so messages sent through them are saved to the database and available in message history later. This history can be used by offline users to catch up with messages they’ve missed the next time they connect.
If messages should only be sent to online users and never kept in message history, clients can join channels with persistence disabled.
Hidden channel members
By default, all users joining a channel are visible to other users. Existing channel participants will receive an event when the user connects and disconnects, and new channel joiners will receive a list of users already in the channel.
Users can opt to hide their channel presence when connecting, so they will not generate join/leave notifications and will not appear in listings of channel members. They will still be able to send and receive real-time messages as normal.
Join chat
To send messages to other users a user must join the chat channel they want to communicate on. This will also enable messages to be received in real-time.
Each user can join many rooms, groups, and direct chats with their session. The same user can also be connected to the same chats from other devices because each device is identified as a separate session.
Rooms
A room is created dynamically for users to chat. A room has a name and will be set up on the server when any user joins. The list of room names available to join can be stored within client code or via remote configuration with a storage record.
The roomId variable contains an ID used to send messages.
Groups
A group chat can only be joined by a user who is a member of the group. Messages are pushed in real-time to group members and they can read historic messages. If a user is kicked or leaves a group they can no longer receive messages or read history.
A group ID is needed when a user joins group chat and can be listed by the user.
The "<group id>" variable must be an ID used to send messages.
Direct
Users can direct message another user by ID. Friends, groups, leaderboards, matchmaker, room chat, and searches in storage are all ways to find users for chat.
Neither user will receive messages in real-time until both users have joined the chat. This is important because it prevents spam messages from bad users.
To invite another user to a direct chat:
Users will receive an in-app notification when a request to chat has been received. To accept the invitation users respond with the same joinChat request targeting the requesting user:
The "<user id>" variable must be an ID used to send messages.
A user can block other users to stop unwanted direct messages.
List online users
Each user who joins a chat becomes a “presence” in the chat channel (unless they’ve joined as a “hidden” channel user). These presences keep information about which users are online.
A presence is made up of a unique session combined with a user ID. This makes it easy to distinguish between the same user connected from multiple devices in the chat channel.
The user who joins a chat channel receives an initial presence list of all other connected users in the chat channel. A callback can be used to receive presence changes from the server about users who join and leave. This makes it easy to maintain a list of online users and update it when changes occur.
The server is optimized to only push presence updates when other users join or leave the chat.
Receive messages
A user joins a chat channel to start receiving messages in real-time. Each new message is received by an event handler and can be added to your UI. Messages are delivered in the order they are handled by the server.
Groups
In group chat a user will receive other messages from the server. These messages contain events on users who join or leave the group, when someone is promoted as an admin, etc. You may want users to see these messages in the chat stream or ignore them in the UI.
You can identify event messages from chat messages by the message Type.
| Code | Purpose | Source | Description |
|---|---|---|---|
| 0 | Chat Message | User | All messages sent by users. |
| 1 | Chat Update | User | A user updating a message they previously sent. |
| 2 | Chat Remove | User | A user removing a message they previously sent. |
| 3 | Joined Group | Server | An event message for when a user joined the group. |
| 4 | Added to Group | Server | An event message for when a user was added to the group. |
| 5 | Left Group | Server | An event message for when a user left a group. |
| 6 | Kicked from Group | Server | An event message for when an admin kicked a user from the group. |
| 7 | Promoted in Group | Server | An event message for when a user is promoted as a group admin. |
| 8 | Banned in Group | Server | An event message for when a user got banned from a group. |
| 9 | Demoted in Group | Server | An event message for when a user got demoted in a group. |
Send messages
When a user has joined a chat channel, its ID can be used to send messages with JSON encoded strings.
Every message sent returns an acknowledgment when it’s received by the server. The acknowledgment returned contains a message ID, timestamp, and details back about the user who sent it.
Filtering message content
It is common to implement filtering of user messages in chat channels to prevent abusive or offensive conduct. This can be achieved in LayerG by using hooks in your server runtime code to either sanitize or reject any message containing inappropriate content.
This code triggers on the server when a message is sent:
In the above example you are creating and maintaining your own filtering criteria (the “Bad Word” index), but you can also elect to integrate with any third-party filtering API if desired.
Leave chat
A user can leave a chat channel to no longer be sent messages in real-time. This can be useful to “mute” a chat while in some other part of the UI.
Message history
Every chat conversation stores a history of messages (unless persistence is set false). The history also contains event messages sent by the server to group chat channels. Each user can retrieve old messages for channels when they next connect online. A user does not have to join a chat channel to see chat history. This is useful to “peek” at old messages without the user appearing online in the chat.
Messages can be listed in order of most recent to oldest and also in reverse (oldest to newest). Messages are returned in batches of up to 100 each with a cursor for when there are more messages.
A cursor can be used to page after a batch of messages for the next set of results.
We recommend you only list the most recent 100 messages in your UI. A good user experience could be to fetch the next 100 older messages when the user scrolls to the bottom of your UI panel.
Cacheable cursors
It can be useful to retrieve only the messages added since the list was last retrieved by a client. This can be done with the cacheable cursor returned with each channel message. Sending the cursor through a new list operation will retrieve only messages newer than those seen.
The cacheable cursor marks the position of the most recent channel messages retrieved. We recommend you store the cacheable cursor in device storage and use it when the client makes its next request for recent notifications.