Chat
The Chat service houses the Luau code responsible for running the legacy chat system. Similar to StarterPlayerScripts, default objects like Scripts and ModuleScripts are inserted into the service.
Summary
Properties
Determines whether player's chat messages will appear above their in-game avatar.
Toggles whether the default chat framework should be automatically loaded when the game runs.
Methods
Fires the Chat.Chatted event with the parameters specified in this method.
Invoke a chat callback function registered by RegisterChatCallback. Used by the Luau Chat System.
Register a function to be called upon the invocation of some chat system event (InvokeChatCallback).
Customizes various settings of the in-game bubble chat.
Will return false if the player with the specified Player.UserId is not allowed to chat because of their account settings.
Will return false if the two users cannot communicate because their account settings do not allow it.
Filters a string sent from a player to another player using filtering that is appropriate to the players' account settings.
Filters a string sent from a player meant for broadcast to no particular target. More restrictive than Chat:FilterStringAsync().
Events
Fires when Chat:Chat() is called.
Properties
BubbleChatEnabled
If true, entering a message in the chat will result in a chat bubble popping up above the player's Player.Character. This behavior can either be enabled by directly ticking this checkbox in Studio, or by using a LocalScript:
This must be done on the client, toggling this value in a server-side Script will have no effect.
LoadDefaultChat
Toggles whether the default chat framework should be automatically loaded when the game runs.
Methods
Chat
The Chat function fires the Chat.Chatted event with the parameters specified in this method.
By default, there is a LocalScript inside of each player's PlayerScripts object named BubbleChat, which causes a dialog-like billboard to appear above the partOrCharacter when the chatted event is fired.
Note: Since dialogs are controlled by a LocalScript, you will not be able to see any dialogs created from this method unless you are running in Play Solo mode.
Parameters
An instance that is the part or character which the BubbleChat dialog should appear above.
The message string being chatted.
An Enum.ChatColor specifying the color of the chatted message.
Returns
Code Samples
The below example would create a part in Workspace and cause it to exclaim "Blame John!"
local ChatService = game:GetService("Chat")
local part = Instance.new("Part")
part.Anchored = true
part.Parent = workspace
ChatService:Chat(part, "Blame John!", "Red")InvokeChatCallback
InvokeChatCallback will call a function registered by RegisterChatCallback, given the ChatCallbackType enum and the arguments to send the function. It will return the result of the registered function, or raise an error if no function has been registered.
This function is called by the Luau Chat System so that chat callbacks may be registered to change the behavior of certain features. Unless you are replacing the default Luau Chat System with your own, you should not need to call this function. You can read about the different callback functions at Chat:RegisterChatCallback().
Parameters
The type of callback to invoke.
The arguments that will be sent to the registered callback function.
Returns
The values returned by the function registered to the given ChatCallbackType.
RegisterChatCallback
RegisterChatCallback binds a function to some chat system event in order to affect the behavior of the Luau chat system. The first argument determines the event (using the Enum.ChatCallbackType enum) to which the second argument, the function, shall be bound. The default Luau chat system uses InvokeChatCallback to invoke registered functions. Attempting to register a server- or client- only callback on a peer that isn't a server or client respectively will raise an error. The following sections describe in what ways registered functions will be used.
OnCreatingChatWindow
Client-only. Invoked before the client constructs the chat window. Must return a table of settings to be merged into the information returned by the ChatSettings module.
OnClientFormattingMessage
Client-only. Invoked before the client displays a message (whether it is a player chat message, system message, or /me command). This function is invoked with the message object and may (or may not) return a table to be merged into message.ExtraData.
OnClientSendingMessage
Not invoked at this time.
OnServerReceivingMessage
Server-only. Invoked when the server receives a message from a speaker (note that speakers may not necessarily be a Player chatting). This callback is called with the Message object. The function can make changes to the Message object to change the manner in which the message is processed. The Message object must be returned for this callback to do anything. Setting this callback can allow the server to, for example:
- Set message.ShouldDeliver to false in order to cancel delivery of the message to players (useful for implementing a chat exclusion list)
- Get/set the speaker's name color (message.ExtraData.NameColor, a Color3) on a message-by-message basis
Parameters
The callback to which the function shall be registered (this determines in what way the function is called).
The function to call when the callback is invoked using Chat:InvokeChatCallback.
Returns
SetBubbleChatSettings
This function customizes various settings of the in-game bubble chat.
Before using this, make sure that bubble chat is enabled by setting Chat.BubbleChatEnabled to true.
The settings argument is a table where the keys are the names of the settings you want to edit and the values are what you want to change these settings to. Note that you don't have to include all of them in the settings argument, omitting some will result in them keeping their default value.
This function is client-side only, attempting to call it on the server will trigger an error.
Parameters
A settings table.
Returns
Code Samples
When run from a LocalScript, this snippet will make all the chat bubbles appear with bigger text under a different font and a light blue background. Note that all the other settings will keep their default value.
local ChatService = game:GetService("Chat")
ChatService:SetBubbleChatSettings({
BackgroundColor3 = Color3.fromRGB(180, 210, 228),
TextSize = 20,
Font = Enum.Font.Cartoon,
})If you want to reset the bubble chat to its default look, you can call this function with an empty table, because any setting you omit from the argument will result in it returning to its default value:
local ChatService = game:GetService("Chat")
ChatService:SetBubbleChatSettings({})CanUserChatAsync
Will return false if the player with the specified Player.UserId is not allowed to chat because of their account settings.
Parameters
Returns
CanUsersChatAsync
Will return false if the two users cannot communicate because their account settings do not allow it.
Parameters
Returns
FilterStringAsync
Partial Deprecation Warning: Calling this function from the client using a LocalScript is deprecated, and will be disabled in the future. Text filtering should be done from a Script on the server using the similarly-named TextService:FilterStringAsync(), which uses a different set of parameters and return type.
Games that do not properly filter player-generated text might be subject to moderation action. Please be sure a game properly filters text before publishing it.
FilterStringAsync filters a string using filtering that is appropriate for the sending and receiving player. If the filtered string is to be used for a persistent message, such as the name of a shop, writing on a plaque, etc, then the function should be called with the author as both the sender and receiver.
This function should be used every time a player can enter custom text in any context, most commonly using a TextBox. Some examples of text to be filtered:
- Custom chat messages
- Custom character names
- Names for a shop in a tycoon-style game
Parameters
The raw string to be filtered, exactly as entered by the player.
The author of the text.
The intended recipient of the provided text; use the author if the text is persistent (see description).
Returns
FilterStringForBroadcast
Filters a string sent from playerFrom for broadcast to no particular target. The filtered message has more restrictions than Chat:FilterStringAsync().
Some examples of where this method could be used:
- Message walls
- Cross-server shouts
- User-created signs
Calling FilterString from LocalScripts is deprecated and will be disabled in the future. Text filtering should be done from server-side Scripts using FilterStringAsync.
Note: A game not using this filter function for custom chat or other user generated text may be subjected to moderation action.
Parameters
Message string being filtered.
Instance of the player sending the message.
Returns
Filtered message string.
Code Samples
The following example shows a simple way to use the FilterStringForBroadcast function. The example uses the message variable as the stringToFilter argument and the local player as the playerFrom argument.
The example then prints the result of the filtering function, FilteredString.
local Players = game:GetService("Players")
local Chat = game:GetService("Chat")
local playerFrom = Players.LocalPlayer
local message = "Hello world!"
-- Filter the string and store the result in the 'FilteredString' variable
local filteredString = Chat:FilterStringForBroadcast(message, playerFrom)
print(filteredString)