Reference API Roblox

Engine API

Website

Related

Reference API Roblox

TextChatService

A service handling in-experience text chat.

This class is not creatable. Instances of this class cannot be created with Instance.new.
This class is a service. It is a singleton that may be acquired with GetService.
Memory categoryInstances
Tags: [NotCreatable, Service]

Member index 22

HistoryMember
599ChatTranslationEnabled: bool
553ChatVersion: ChatVersion
553CreateDefaultCommands: bool
553CreateDefaultTextChannels: bool
580CanUserChatAsync(userId: int64): bool
580CanUsersChatAsync(userIdFrom: int64, userIdTo: int64): bool
650CanUsersDirectChatAsync(requesterUserId: int64, userIds: Array): Array
646CanUsersWhisperAsync(fromUserId: int64, toUserId: int64): bool
580DisplayBubble(partOrCharacter: Instance, message: string): null
587BubbleDisplayed(partOrCharacter: Instance, textChatMessage: TextChatMessage)
514MessageReceived(textChatMessage: TextChatMessage)
519SendingMessage(textChatMessage: TextChatMessage)
587OnBubbleAdded(message: TextChatMessage, adornee: Instance): Tuple
645OnChatWindowAdded(message: TextChatMessage): Tuple
514OnIncomingMessage(message: TextChatMessage): Tuple
inherited from Instance
553Archivable: bool
635Capabilities: SecurityCapabilities
553Name: string
553Parent: Instance
635Sandboxed: bool
616UniqueId: UniqueId
576AddTag(tag: string): null
573ClearAllChildren(): null
462Clone(): Instance
573Destroy(): null
486FindFirstAncestor(name: string): Instance
486FindFirstAncestorOfClass(className: string): Instance
486FindFirstAncestorWhichIsA(className: string): Instance
486FindFirstChild(name: string, recursive: bool = false): Instance
486FindFirstChildOfClass(className: string): Instance
486FindFirstChildWhichIsA(className: string, recursive: bool = false): Instance
486FindFirstDescendant(name: string): Instance
563GetActor(): Actor
486GetAttribute(attribute: string): Variant
462GetAttributeChangedSignal(attribute: string): RBXScriptSignal
631GetAttributes(): Dictionary
648GetChildren(): Instances
462GetDebugId(scopeLength: int = 4): string
486GetDescendants(): Array
486GetFullName(): string
641GetStyled(name: string): Variant
576GetTags(): Array
576HasTag(tag: string): bool
486IsAncestorOf(descendant: Instance): bool
486IsDescendantOf(ancestor: Instance): bool
580IsPropertyModified(name: string): bool
573Remove(): null
576RemoveTag(tag: string): null
580ResetPropertyToDefault(name: string): null
573SetAttribute(attribute: string, value: Variant): null
462WaitForChild(childName: string, timeOut: double): Instance
648children(): Instances
553clone(): Instance
573destroy(): null
553findFirstChild(name: string, recursive: bool = false): Instance
648getChildren(): Instances
553isDescendantOf(ancestor: Instance): bool
573remove(): null
462AncestryChanged(child: Instance, parent: Instance)
462AttributeChanged(attribute: string)
462ChildAdded(child: Instance)
462ChildRemoved(child: Instance)
462DescendantAdded(descendant: Instance)
462DescendantRemoving(descendant: Instance)
500Destroying()
553childAdded(child: Instance)
inherited from Object
647ClassName: string
647className: string
647GetPropertyChangedSignal(property: string): RBXScriptSignal
647IsA(className: string): bool
650isA(className: string): bool
647Changed(property: string)

Description

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.

History 39

Members 22

BubbleDisplayed

Parameters (2)
partOrCharacterInstance
textChatMessageTextChatMessage

Fires when TextChatService:DisplayBubble() is called.

Thread safetyUnsafe

History 2

CanUserChatAsync

Parameters (1)
userIdint64
Returns (1)
bool
This function yields. It will block the calling thread until completion.
Thread safetyUnsafe

History 1

Tags: [Yields]

CanUsersChatAsync

Parameters (2)
userIdFromint64
userIdToint64
Returns (1)
bool
This function yields. It will block the calling thread until completion.
Thread safetyUnsafe

History 1

Tags: [Yields]

CanUsersDirectChatAsync

Parameters (2)
requesterUserIdint64
userIdsArray
Returns (1)
Array

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
This function yields. It will block the calling thread until completion.
Thread safetyUnsafe

History 1

Tags: [Yields]

CanUsersWhisperAsync

Parameters (2)
fromUserIdint64
toUserIdint64
Returns (1)
bool
This function yields. It will block the calling thread until completion.
SecurityRobloxScriptSecurity
Thread safetyUnsafe

History 1

Tags: [Yields]

ChatTranslationEnabled

TypeDefault
booltrue
This property is not replicated. Its interface does not cross the network boundary.
Write securityRobloxScriptSecurity
Thread safetyReadSafe
CategoryData
Loaded/Savedfalse

History 4

Tags: [NotReplicated]

ChatVersion

TypeDefault
ChatVersionLegacyChatService

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

Write securityNotAccessibleSecurity
Thread safetyReadSafe
CategoryData
Loaded/Savedtrue

History 2

CreateDefaultCommands

TypeDefault
booltrue

Determines whether TextChatService should create default TextChatCommands.

If true, the following TextChatCommands are created and put in a Folder named TextChatCommands inside TextChatService:

NamePrimary AliasSecondary AliasDescriptionUsage Example
RBXClearCommandclearclsClears the chat log for the local user./cls
RBXConsoleCommandconsoleOpens the Developer Console./console
RBXEmoteCommandemoteePlays an avatar emote./e dance
RBXHelpCommandhelp?Shows a list of chat commands./help
RBXMuteCommandmutemMutes a user by their Name or DisplayName in all TextChannels./m Username
RBXTeamCommandteamtEnters team chat mode where messages are only visible to teammates./t
RBXUnmuteCommandunmuteumUnmutes a user by their Name or DisplayName in all TextChannels./um Username
RBXVersionCommandversionvShows the chat version./version
RBXWhisperCommandwhisperwEnters 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.

Write securityPluginSecurity
Thread safetyReadSafe
CategoryData
Loaded/Savedtrue

History 4

CreateDefaultTextChannels

TypeDefault
booltrue

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.

ChannelDescription
RBXGeneralTextChannel 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.
RBXSystemTextChannel 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 UserIds 2276836 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.

Write securityPluginSecurity
Thread safetyReadSafe
CategoryData
Loaded/Savedtrue

History 4

DisplayBubble

Parameters (2)
partOrCharacterInstance
messagestring
Returns (1)
null

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.

Thread safetyUnsafe

History 1

MessageReceived

Parameters (1)
textChatMessageTextChatMessage

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.

Thread safetyUnsafe

History 1

OnBubbleAdded

Parameters (2)
messageTextChatMessage
adorneeInstance
Returns (1)
Tuple

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.

Thread safetyUnsafe

History 1

OnChatWindowAdded

Parameters (1)
messageTextChatMessage
Returns (1)
Tuple

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.

Thread safetyUnsafe

History 1

OnIncomingMessage

Parameters (1)
messageTextChatMessage
Returns (1)
Tuple

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.

Thread safetyUnsafe

History 1

SendingMessage

Parameters (1)
textChatMessageTextChatMessage

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().

Thread safetyUnsafe

History 3

Settings