TextChatService
A service handling in-experience text chat, including managing channels, decorating messages, filtering text, creating commands, and developing custom chats interfaces.
To learn more, see TextChatService Overview.
For further customization, TextChatService has the following singleton children:
Summary
Properties
Determines if chat translation is enabled.
Determines whether to fully enable TextChatService or revert to the legacy chat system.
Determines whether TextChatService should create default TextChatCommands.
Determines whether TextChatService should create default TextChannels.
Methods
Displays a chat bubble above the provided part or player character.
Determines whether a user has permission to chat in experiences.
Determines whether or not two users would receive messages between each other.
Determines whether a user has permission to chat directly with other users in experiences based on factors such as their parental control settings.
Events
Fires when TextChatService:DisplayBubble() is called.
Fires when TextChannel:DisplaySystemMessage() is invoked on the client, or when the client receives a valid TextChannel:SendAsync() response from the server.
Fires when TextChannel:SendAsync() is called by the sending client.
Callbacks
Properties
ChatTranslationEnabled
Determines if chat translation is enabled. If true, a system message will notify player's when their first join that chat messages may be translated into the player's preferred language.
ChatVersion
Determines whether to fully enable TextChatService or revert to the legacy chat system. Setting this property to Enum.ChatVersion.LegacyChatService effectively disables TextChatService.
CreateDefaultCommands
Determines whether TextChatService should create default TextChatCommands.
If true, the following TextChatCommands are created and put in a Folder named TextChatCommands inside TextChatService:
| Name | Primary Alias | Secondary Alias | Description | Usage Example |
|---|---|---|---|---|
| RBXClearCommand | clear | cls | Clears the chat log for the local user. | /cls |
| RBXConsoleCommand | console | Opens the Developer Console. | /console | |
| RBXEmoteCommand | emote | e | Plays an avatar emote. | /e dance |
| RBXHelpCommand | help | ? | Shows a list of chat commands. | /help |
| RBXMuteCommand | mute | m | Mutes a user by their Name or DisplayName in all TextChannels. | /m Username |
| RBXTeamCommand | team | t | Enters team chat mode where messages are only visible to teammates. | /t |
| RBXUnmuteCommand | unmute | um | Unmutes a user by their Name or DisplayName in all TextChannels. | /um Username |
| RBXVersionCommand | version | v | Shows the chat version. | /version |
| RBXWhisperCommand | whisper | w | Enters whisper mode with another Player. | /w DisplayName or /w @Username |
Note that you can edit, create, and remove TextChatCommands even if CreateDefaultCommands is true. Also note that mute and unmute commands apply to all TextChannels.
CreateDefaultTextChannels
Determines whether TextChatService should create default TextChannels. If true, a Folder named TextChannels is created inside TextChatService at runtime to contain the TextChannels outlined in the table below. Each of the default channels has the described special behavior applied to messages using its internally bound TextChannel.OnIncomingMessage callback function, changing how messages appear when sent through the channel. The callback is assigned automatically either at runtime (if the TextChannel exists) or when the TextChannel is created.
| Channel | Description |
|---|---|
| RBXGeneral | TextChannel for player messages. In the chat window, messages are modified such that PrefixText receives a rich text font color tag to give chatting players their distinctive name color. If Player.Team exists, that Team.TeamColor is used instead of the default name color. |
| RBXSystem | TextChannel for system messages. In the chat window, messages are modified such that TextChatMessage.Text is given a light grey color tag by default, or a red color tag if TextChatMessage.Metadata contains the word "Error". |
| RBXTeam[BrickColor] | TextChannel for team-specific player messages, created when a TeamColor is in use by any Team within the Teams service. Name of the created channel is RBXTeam followed by the TeamColor name. For example, RBXTeamCrimson is a TextChannel created when there is an active team whose TeamColor property is the "Crimson" BrickColor. In the chat window, messages are modified such that PrefixText is colored according to the TeamColor and is prepended with [Team]. Team channels create TextSources for all non‑Neutral players with the matching TeamColor, allowing them to use team‑only chat. Channels are removed if there are no remaining teams with an associated TeamColor. |
| RBXWhisper:[UserId1]_[UserId2] | TextChannel for whisper messages between two players, created when a player uses the /whisper command on another player. For example RBXWhisper:2276836_505306092 is a TextChannel for players with UserIds2276836 and 505306092. Inside whisper channels are two TextSources associated with the respective UserIds. In the chat window, messages are colored the same as those in RBXGeneral and TextChatMessage.PrefixText is modified to show whether a message was sent from or received by the local user. Whisper channels are removed when either player leaves the experience. |
Note that the default TextChannel.OnIncomingMessage callbacks can be overwritten. Also note that you can edit, create, and remove TextChannels even if CreateDefaultTextChannels is true.
Messages from different TextChannels can be separated into different tabs in the chat window using ChannelTabsConfiguration.
Methods
DisplayBubble
Displays a chat bubble above the provided part or player character, and fires the BubbleDisplayed event with the parameters specified in this method. Can display bubbles for non-player characters (NPCs) if you specify a part within the character, such as its head.
Note that this method is only available for use in LocalScript, or in a Script with RunContext of Enum.RunContext.Client.
Parameters
The part or character that the bubble to be displayed above.
The text to be displayed in the chat bubble.
Returns
CanUserChatAsync
Determines whether a user has permission to chat in experiences. Factors such as parental control settings may prevent the user from sending messages. Errors if the userId is not in the current server. Note that this method is only available for use in a Script with RunContext of Enum.RunContext.Server or Enum.RunContext.Legacy.
Parameters
Returns
CanUsersChatAsync
Determines whether or not two users would receive messages between each other. Factors such as incompatible parental control settings or blocked status may prevent the delivery of messages between users TextChannels internally use this result to determine whether to deliver messages between users. Note that this method is only available for use in a Script with RunContext of Enum.RunContext.Server or Enum.RunContext.Legacy.
Parameters
Returns
CanUsersDirectChatAsync
Determines whether a user has permission to chat directly with other users in experiences based on their parental control settings. To be used when:
- The line of communication is user-initiated (not developer- or gameplay-initiated)
- Access to the communication is closed and limited
An example of a direct chat is a whisper channel between two users.
You may use this method to gate certain features in your experience depending on the result.
When creating a TextChannel for a direct chat, use TextChannel:SetDirectChatRequester() to set the requesterUserId so that the channel can determine whether to deliver messages between users. When TextChannel.DirectChatRequester is non-nil, TextChannels internally use this result to determine whether to deliver messages between users.
Note that this method is only available for use in a Script with RunContext of Enum.RunContext.Server or Enum.RunContext.Legacy.
Parameters
The user who would have initiated the direct chat request. If the requesterUserId is not in the current server, this method will error.
A list of users who the requesterUserId would like to chat with directly. Users not in the current server are ignored.
Returns
A list of users who could participate in the direct chat request. If none of the users can direct chat with the requesterUserId, the result is an empty array.
Code Samples
local TextChatService = game:GetService("TextChatService")
local directChatParticipants = TextChatService:CanUsersDirectChatAsync(userId1, { userId2 })
-- Check for eligible participants
if #directChatParticipants > 0 then
local directChannel = Instance.new("TextChannel")
directChannel.Parent = TextChatService
for _, participant in directChatParticipants do
directChannel:AddUserAsync(participant)
end
return directChannel
end
warn("Could not create TextChannel. Not enough eligible users.")
return nilEvents
MessageReceived
Like TextChannel.MessageReceived, fires when TextChannel:DisplaySystemMessage() is invoked on the client, or when the client receives a valid TextChannel:SendAsync() response from the server. This event is only fired on the client.
If the server's TextChannel.ShouldDeliverCallback property is bound and returns false, the client will not fire TextChatService.MessageReceived.
Use the TextChatMessage parameter to get the TextSource and the text of the message (with TextChatMessage.Text).
The TextChatMessage parameter is the final result of any functions bound to TextChatService.OnIncomingMessage or TextChannel.OnIncomingMessage.
Parameters
The received TextChatMessage.
SendingMessage
Fires when TextChannel:SendAsync() is called by the sending client. Use this to allow placeholder messages to be shown to the user while waiting for server response to TextChannel:SendAsync().
Parameters
The TextChatMessage from the TextChannel:SendAsync() call.