18 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

TextChatService

Inherits from: Instance → Object

A service handling in-experience text chat, including managing TextChannels, decorating messages, filtering text, creating TextChatCommands, and developing custom chats interfaces. To learn more, see text chat overview.

For further customization, TextChatService has the following singleton children:

Inherits from: Instance

Memory category: Instances

Tags: NotCreatable, Service

Properties

Name	Type / Returns	Description
TextChatService.ChatTranslationEnabled	boolean	Determines whether a user has chat translation enabled.
TextChatService.ChatVersion	ChatVersion	Determines whether to fully enable `TextChatService` or revert to the legacy chat system.
TextChatService.CreateDefaultCommands	boolean	Determines whether `TextChatService` should create default `TextChatCommands`.
TextChatService.CreateDefaultTextChannels	boolean	Determines whether `TextChatService` should create default `TextChannels`.
TextChatService.PlatformIntegratedChat	RolloutState	Determines whether platform-integrated chat is enabled for the experience. Requires `RobloxScript` security.

Inherited from Instance

Name	Type / Returns	Description
Instance.Archivable	boolean	Determines if an `Instance` and its descendants can be cloned using `Instance:Clone()`, and can be saved/published.
Instance.archivable	boolean
Instance.Capabilities	SecurityCapabilities	The set of capabilities allowed to be used for scripts inside this container.
Instance.IsInSandbox	boolean	Indicates whether the instance is inside a sandboxed container.
Instance.Name	string	A non-unique identifier of the `Instance`.
Instance.Parent	Instance	Determines the hierarchical parent of the `Instance`.
Instance.PredictionMode	PredictionMode	Reflects the client-side prediction mode applied to the instance under server-authoritative physics.
Instance.RobloxLocked	boolean	A deprecated property that used to protect `CoreGui` objects.
Instance.Sandboxed	boolean	When enabled, the instance can only access abilities in its `Capabilities` list.
Instance.UniqueId	UniqueId	A unique identifier for the instance.

Inherited from Object

Name	Type / Returns	Description
Object.ClassName	string	A read-only string representing the class this `Object` belongs to.
Object.className	string

TextChatService.ChatTranslationEnabled

Determines whether a user has chat translation enabled. If true, messages the user receives will be translated into their preferred language. Use TextChatMessage.Translation to get the message translation. This property is client-side only and reflects the user's own preference; read it from a LocalScript to adapt custom chat UIs when the user toggles translation.

Field	Value
type	boolean
tags	["NotReplicated"]
security	{"read":"None","write":"RobloxScriptSecurity"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":false}
capabilities	["Chat"]

TextChatService.ChatVersion

Deprecated. This property has been deprecated in newly created Studio experiences. TextChatService is the only allowed chat system and is automatically enabled.

Determines whether to fully enable TextChatService or revert to the legacy chat system. Setting this property to ChatVersion.LegacyChatService effectively disables TextChatService.

Field	Value
type	ChatVersion
security	{"read":"None","write":"RobloxScriptSecurity"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":true,"can_save":true}
capabilities	["Chat"]

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 `Class.Player.Name\|Name` or `Class.Player.DisplayName\|DisplayName` in all `Class.TextChannel\|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 `Class.Player.Name\|Name` or `Class.Player.DisplayName\|DisplayName` in all `Class.TextChannel\|TextChannels`.	`/um Username`
RBXVersionCommand	version	v	Shows the chat version.	`/version`
RBXWhisperCommand	whisper	w	Enters whisper mode with another `Class.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.

Field	Value
type	boolean
security	{"read":"None","write":"PluginSecurity"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":true,"can_save":true}
capabilities	["Chat"]

TextChatService.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	`Class.TextChannel` for player messages. In the chat window, messages are modified such that `Class.TextChatMessage.PrefixText\|PrefixText` receives a rich text font color tag to give chatting players their distinctive name color. If `Class.Player.Team` exists, that `Class.Team.TeamColor` is used instead of the default name color.
RBXSystem	`Class.TextChannel` for system messages. In the chat window, messages are modified such that `Class.TextChatMessage.Text` is given a light grey color tag by default, or a red color tag if `Class.TextChatMessage.Metadata` contains the word `"Error"`.
RBXTeam[BrickColor]	`Class.TextChannel` for team-specific player messages, created when a `Class.Team.TeamColor\|TeamColor` is in use by any `Class.Team` within the `Class.Teams` service. Name of the created channel is RBXTeam followed by the `Class.Team.TeamColor\|TeamColor` name. For example, RBXTeamCrimson is a `Class.TextChannel` created when there is an active team whose `Class.Team.TeamColor\|TeamColor` property is the "Crimson" `Datatype.BrickColor`. In the chat window, messages are modified such that `Class.TextChatMessage.PrefixText\|PrefixText` is colored according to the `Class.Player.TeamColor\|TeamColor` and is prepended with [Team]. Team channels create `Class.TextSource\|TextSources` for all non‑`Class.Player.Neutral\|Neutral` players with the matching `Class.Team.TeamColor\|TeamColor`, allowing them to use team‑only chat. Channels are removed if there are no remaining teams with an associated `Class.Team.TeamColor\|TeamColor`.
RBXWhisper:[UserId1]_[UserId2]	`Class.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 `Class.TextChannel` for players with `Class.Player.UserId\|UserIds` 2276836 and 505306092. Inside whisper channels are two `Class.TextSource\|TextSources` associated with the respective `Class.Player.UserId\|UserIds`. In the chat window, messages are colored the same as those in RBXGeneral and `Class.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.

Field	Value
type	boolean
security	{"read":"None","write":"PluginSecurity"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":true,"can_save":true}
capabilities	["Chat"]

TextChatService.PlatformIntegratedChat

Requires RobloxScript security; not accessible from experience scripts. Controls whether platform-integrated chat is enabled for the experience. When set to RolloutState.Enabled, TextChatService.OnIncomingMessage and TextChannel.OnIncomingMessage callbacks from developer scripts are not invoked, and only CoreScripts can set those callbacks. When set to RolloutState.Disabled, behavior is explicitly disabled. Defaults to RolloutState.Default.

Field	Value
type	RolloutState
security	{"read":"RobloxScriptSecurity","write":"RobloxScriptSecurity"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":true,"can_save":true}
capabilities	["Chat"]

Methods

Name	Type / Returns	Description
TextChatService:CanUserChatAsync	boolean	Determines whether a user has permission to chat in experiences.
TextChatService:CanUsersChatAsync	boolean	Determines whether or not two users can receive messages from each other.
TextChatService:CanUsersDirectChatAsync	Array	Determines whether a user has permission to chat directly with other users in experiences based on factors such as their parental control settings.
TextChatService:DisplayBubble	()	Displays a chat bubble above the provided part or player character.
TextChatService:GetChatGroupsAsync	Array	Returns chat group IDs that indicate which players can synchronously text chat together.

Inherited from Instance

Name	Type / Returns	Description
Instance:AddTag	()	Applies a tag to the instance.
Instance:children	Instances	Returns an array of the object's children.
Instance:ClearAllChildren	()	This method destroys all of an instance's children.
Instance:Clone	Instance	Create a copy of an instance and all its descendants, ignoring instances that are not `Archivable`.
Instance:clone	Instance
Instance:Destroy	()	Sets the `Instance.Parent` property to `nil`, locks the `Instance.Parent` property, disconnects all connections, and calls `Destroy()` on all children.
Instance:destroy	()
Instance:FindFirstAncestor	Instance?	Returns the first ancestor of the `Instance` whose `Instance.Name` is equal to the given name.
Instance:FindFirstAncestorOfClass	Instance?	Returns the first ancestor of the `Instance` whose `Object.ClassName` is equal to the given className.
Instance:FindFirstAncestorWhichIsA	Instance?	Returns the first ancestor of the `Instance` for whom `Object:IsA()` returns true for the given className.
Instance:FindFirstChild	Instance?	Returns the first child of the `Instance` found with the given name.
Instance:findFirstChild	Instance
Instance:FindFirstChildOfClass	Instance?	Returns the first child of the `Instance` whose `ClassName` is equal to the given class name.
Instance:FindFirstChildWhichIsA	Instance?	Returns the first child of the `Instance` for whom `Object:IsA()` returns true for the given className.
Instance:FindFirstDescendant	Instance?	Returns the first descendant found with the given `Instance.Name`.
Instance:GetActor	Actor?	Returns the `Actor` associated with the Instance, if any.
Instance:GetAttribute	Variant	Returns the value which has been assigned to the given attribute name.
Instance:GetAttributeChangedSignal	RBXScriptSignal	Returns an event that fires when the given attribute changes.
Instance:GetAttributes	Dictionary	Returns a dictionary of the instance's attributes.
Instance:GetChildren	Instances	Returns an array containing all of the instance's children.
Instance:getChildren	Instances
Instance:GetDebugId	string	Returns a coded string of the debug ID used internally by Roblox.
Instance:GetDescendants	Instances	Returns an array containing all of the descendants of the instance.
Instance:GetFullName	string	Returns a string describing the instance's ancestry.
Instance:GetStyled	Variant	Returns the styled or explicitly modified value of the specified property, or else the default property value if it hasn't been styled/modified.
Instance:GetStyledPropertyChangedSignal	RBXScriptSignal	Returns an event that fires when the given style property changes on the instance.
Instance:GetTags	Array	Gets an array of all tags applied to the instance.
Instance:HasTag	boolean	Check whether the instance has a given tag.
Instance:IsAncestorOf	boolean	Returns true if an `Instance` is an ancestor of the given descendant.
Instance:IsDescendantOf	boolean	Returns `true` if an `Instance` is a descendant of the given ancestor.
Instance:isDescendantOf	boolean
Instance:IsPropertyModified	boolean	Returns `true` if the value stored in the specified property is not equal to the code-instantiated default.
Instance:QueryDescendants	Instances	Returns an array containing all descendants of the instance that match the `selector` string.
Instance:Remove	()	Sets the object's `Parent` to `nil`, and does the same for all its descendants.
Instance:remove	()
Instance:RemoveTag	()	Removes a tag from the instance.
Instance:ResetPropertyToDefault	()	Resets a property to its default value.
Instance:SetAttribute	()	Sets the attribute with the given name to the given value.
Instance:WaitForChild	Instance	Returns the child of the `Instance` with the given name. If the child does not exist, it will yield the current thread until it does.

Inherited from Object

Name	Type / Returns	Description
Object:GetPropertyChangedSignal	RBXScriptSignal	Get an event that fires when a given property of the object changes.
Object:IsA	boolean	Returns true if an object's class matches or inherits from a given class.
Object:isA	boolean

TextChatService: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 can be used with all current player UserIds in a Script with RunContext of RunContext.Server or RunContext.Legacy. This method can also be used in a LocalScript but only with the UserId of the local player.

Parameters

Name	Type	Default	Description
userId	User		The `Player.UserId` of the user whose chat permission is being checked.

Returns

Type	Description
boolean	A boolean indicating whether the user has permission to chat.

Field	Value
tags	["Yields"]
security	None
thread safety	Unsafe
capabilities	["Chat"]

TextChatService:CanUsersChatAsync

Determines whether or not two users can receive messages from each other. Both users must be in the current server, otherwise an error will occur.

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 RunContext.Server or RunContext.Legacy.

Parameters

Name	Type	Default	Description
userIdFrom	User		The `Player.UserId` of the potential message sender.
userIdTo	User		The `Player.UserId` of the potential message receiver.

Returns

Type	Description
boolean	A boolean indicating whether the two users can exchange messages.

Field	Value
tags	["Yields"]
security	None
thread safety	Unsafe
capabilities	["Chat"]

TextChatService:CanUsersDirectChatAsync

Determines whether a user has permission to chat directly with other users in experiences based on their parental control settings, such as a whisper channel between two users. To be used when:

The line of communication is user-initiated (not developer- or gameplay-initiated).
Access to the communication is closed and limited.

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 RunContext.Server or RunContext.Legacy.

Parameters

Name	Type	Default	Description
requesterUserId	User		The user who would have initiated the direct chat request. If the user is not in the current server, this method will error.
userIds	Array		A list of users who the `requesterUserId` would like to chat with directly. Users not in the current server are ignored.

Returns

Type	Description
Array	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.

Field	Value
tags	["Yields"]
security	None
thread safety	Unsafe
capabilities	["Chat"]

Code samples: View on Creator Hub (TextChatService-User-Chat).

TextChatService: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 RunContext.Client.

Parameters

Name	Type	Default	Description
partOrCharacter	Instance		The part or character that the bubble to be displayed above.
message	string		The text to be displayed in the chat bubble.

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe
capabilities	["Chat"]

TextChatService:GetChatGroupsAsync

Returns a sorted array of arrays of chat group IDs for the given players. Each chat group ID is a string that represents a communication-compatible group within the current universe.

If two or more players share the same chat group ID, those players are able to synchronously text chat with each other based on their age-check status and chat settings.

This method is server-side only and intended for real-time use cases such as matchmaking and teleporting. It is more efficient than calling TextChatService:CanUsersChatAsync() pairwise when evaluating many players at once, since pairwise checks scale as N^2 and cannot be merged across player lists. Chat group IDs are unique to the current universe, may change over time, and should not be stored once the user has left the experience. While you can hold onto the data returned for the purposes of gameplay while the user is in the experience, this data should not be stored after they've left.

To use this method, you must enable Chat & Voice Groups APIs in Experience Settings ⟩ Communication in Roblox Studio and agree to the Roblox Terms of Use.

In Roblox Studio this API is only available when the experience is running in Team Test.

Parameters

Name	Type	Default	Description
players	Instances		A list of `Players` currently in the experience to evaluate for text chat compatibility.

Returns

Type	Description
Array	A sorted array of arrays of chat group ID strings. Players who share a matching chat group ID are eligible to synchronously text chat with each other.

Field	Value
tags	["Yields"]
security	None
thread safety	Unsafe
capabilities	["Chat"]

Code samples: View on Creator Hub (TextChatService-Chat-Groups-Teleport, TextChatService-GetChatGroupsAsync).

Events

Name	Type / Returns	Description
TextChatService.BubbleDisplayed		Fires when `TextChatService:DisplayBubble()` is called.
TextChatService.MessageReceived		Fires when `TextChannel:DisplaySystemMessage()` is invoked on the client, or when the client receives a valid `TextChannel:SendAsync()` response from the server.
TextChatService.SendingMessage		Fires when `TextChannel:SendAsync()` is called by the sending client.

Inherited from Instance

Name	Type / Returns	Description
Instance.AncestryChanged		Fires when the `Instance.Parent` property of this object or one of its ancestors is changed.
Instance.AttributeChanged		Fires whenever an attribute is changed on the `Instance`.
Instance.ChildAdded		Fires after an object is parented to this `Instance`.
Instance.childAdded
Instance.ChildRemoved		Fires after a child is removed from this `Instance`.
Instance.DescendantAdded		Fires after a descendant is added to the `Instance`.
Instance.DescendantRemoving		Fires immediately before a descendant of the `Instance` is removed.
Instance.Destroying		Fires immediately before (or is deferred until after) the instance is destroyed via `Instance:Destroy()`.
Instance.StyledPropertiesChanged		Fires whenever any style property is changed on the instance, including when a property is set to `nil`.

Inherited from Object

Name	Type / Returns	Description
Object.Changed		Fires immediately after a property of the object changes, with some limitations.

TextChatService.BubbleDisplayed

Fires when TextChatService:DisplayBubble() is called.

Parameters

Name	Type	Default	Description
partOrCharacter	Instance		The part or character that the bubble chat is displayed above.
textChatMessage	TextChatMessage		The `TextChatMessage` associated with the bubble.

Field	Value
security	None
capabilities	["Chat"]

TextChatService.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

Name	Type	Default	Description
textChatMessage	TextChatMessage		The received `TextChatMessage`.

Field	Value
security	None
capabilities	["Chat"]

TextChatService.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

Name	Type	Default	Description
textChatMessage	TextChatMessage		The `TextChatMessage` from the `TextChannel:SendAsync()` call.

Field	Value
security	None
capabilities	["Chat"]

Callbacks

Name	Type / Returns	Description
TextChatService.OnBubbleAdded	Tuple	Called when a bubble chat is about to be displayed.
TextChatService.OnChatWindowAdded	Tuple	Called when a new message is about to be displayed in the chat window. This can only be implemented on the client.
TextChatService.OnIncomingMessage	Tuple	Called when `TextChatService` is receiving an incoming message.

TextChatService.OnBubbleAdded

Called when a bubble chat is about to be displayed. This can only be implemented on the client.

Use this to customize individual bubble chat messages. If this callback returns a BubbleChatMessageProperties, those properties will be applied to the associated bubble, overriding BubbleChatConfiguration properties. If a UICorner, UIGradient, or ImageLabel is parented under BubbleChatMessageProperties, they will also override their respective counterparts defined in BubbleChatConfiguration.

If the chat message is sent by a player, message.TextSource will correspond to that player, and adornee will be nil.

If the chat message is sent via TextChatService:DisplayBubble, adornee will be the partOrCharacter provided, and message.TextSource will be nil.

When bound to the client sending a message, this callback is run twice: first when the message is initially sent and received locally, then again when the client receives the result of the filtered message from the server.

Parameters

Name	Type	Default	Description
message	TextChatMessage		The incoming `TextChatMessage`.
adornee	Instance		The part or character the bubble chat message is attached to.

Returns

Type	Description
Tuple	If a `BubbleChatMessageProperties` is returned, its properties override the `BubbleChatConfiguration` properties.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Chat"]

TextChatService.OnChatWindowAdded

Called when a new message is about to be displayed in the chat window. This can only be implemented on the client.

Use this to customize individual messages that appear in the chat window. If this callback returns a ChatWindowMessageProperties, those properties will be applied to the associated message, overriding ChatWindowConfiguration properties. If a UIGradient is parented under ChatWindowMessageProperties, it will also override the TextColor3 property defined in ChatWindowConfiguration.

Parameters

Name	Type	Default	Description
message	TextChatMessage		The incoming `TextChatMessage`.

Returns

Type	Description
Tuple	If a `ChatWindowMessageProperties` is returned, its properties override the `ChatWindowConfiguration` properties.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Chat"]

TextChatService.OnIncomingMessage

Called when TextChatService is receiving an incoming message. Can only be implemented on the client.

Use this to decorate TextChatMessages. If this callback returns a TextChatMessageProperties, those properties are merged with the TextChatMessage parameter to create a new TextChatMessage.

When bound to the client sending a message, this callback is run twice; first when the message is initially sent and received locally, and again when the client receives the result of the filtered message from the server.

Note that this TextChatService.OnIncomingMessage callback runs before any TextChannel.OnIncomingMessage callbacks.

This should be defined only once in the source code. Multiple bindings will override one another in a non‑deterministic manner. This callback is not invoked when TextChatService.PlatformIntegratedChat is set to RolloutState.Enabled.

Parameters

Name	Type	Default	Description
message	TextChatMessage		The incoming `TextChatMessage`.

Returns

Type	Description
Tuple	If a `TextChatMessageProperties` is returned, those properties are merged with the `TextChatMessage` parameter to create a new `TextChatMessage` with those properties, otherwise, if `nil` is returned, then `TextChatMessage` is not changed.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Chat"]