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 In-Experience Text Chat.
Summary
Properties
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 directly with other users in experiences based on 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
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
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
Parameters
Returns
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.