In-Experience Text Chat

The in-experience text chat system powered by TextChatService allows users to easily communicate and socialize with each other in live experiences. In addition to supporting the default text chat, you can customize the front-end user interface (UI) and chat functionalities, including customizing message appearance, adding chat bubbles, and creating custom commands to improve your user engagement and immersion.

Enabling Text Chat

To enable in-experience text chat in your experience:

  1. In the Model tab, click the Service icon in the Advanced section to display a list of services.

  2. From the Insert Service window, select TextChatService and click the Insert button.

  3. In the Explorer window, select TextChatService.

  4. In the Properties window, find the ChatVersion dropdown and select TextChatService.

Chat Window Configuration

After enabling the service, you can toggle appearance of the chat window and input bar in one of two ways:

  • Directly in Studio by toggling the Enabled property of the service's ChatWindowConfiguration and ChatInputBarConfiguration children.


  • Through scripting, from a LocalScript within StarterPlayerScripts.

    LocalScript

    1local TextChatService = game:GetService("TextChatService")
    2
    3local chatWindowConfiguration = TextChatService:FindFirstChildOfClass("ChatWindowConfiguration")
    4local chatInputBarConfiguration = TextChatService:FindFirstChildOfClass("ChatInputBarConfiguration")
    5
    6if chatWindowConfiguration then
    7 chatWindowConfiguration.Enabled = true
    8end
    9if chatInputBarConfiguration then
    10 chatInputBarConfiguration.Enabled = true
    11end
    12

Chat Window Customization

You can customize the default chat window to match your experience’s UI layout, design, and style by using the following properties in Studio:

Property Description Default
Appearance
BackgroundColor3 Background color of the chat window in Color3. [25, 27, 29]
BackgroundTransparency Transparency of the chat window. 0.3
FontFace Font of chat text displayed on the chat window. Font.GothamMedium
TextColor3 Color of chat text displayed on the chat window in Color3. [255, 255, 255]
TextSize Size of chat text displayed on the chat window. 14
TextStrokeColor3 Chat text stroke color displayed on the chat window in Color3. [0, 0, 0]
TextStrokeTransparency Transparency of chat text stroke displayed on the chat window. 0.5
Behavior
HeightScale Height scale of the chat window relative to the screen size. 1
WidthScale Width scale of the chat window relative to the screen size. 1

Customizing Message Appearance

You can customize the appearance of chat message bodies and prefixes using rich text tags and TextChatService.OnIncomingMessage callbacks without overriding the existing UI. The customization options let you modify the appearance of chat messages to match your experience's theme, and you can also sort or highlight messages from different user groups by adding chat tags and coloring usernames.

Adding Chat Tags

If your experience has users with special attributes like VIP status, you can attach chat tags wrapped in brackets to the front of user messages to highlight their chat messages. The following LocalScript in StarterPlayerScripts examines all Player instances representing users in your experience and appends VIP chat tags for those with the IsVIP attribute.

LocalScript

1local TextChatService = game:GetService("TextChatService")
2local Players = game:GetService("Players")
3
4TextChatService.OnIncomingMessage = function(message: TextChatMessage)
5 local properties = Instance.new("TextChatMessageProperties")
6
7 if message.TextSource then
8 local player = Players:GetPlayerByUserId(message.TextSource.UserId)
9 if player:GetAttribute("IsVIP") then
10 properties.PrefixText = "<font color='#F5CD30'>[VIP]</font> " .. message.PrefixText
11 end
12 end
13
14 return properties
15end
16
VIP users' chat tags

Coloring Usernames

When a user sends a chat message, their username displays as the prefix portion of the message. By default, each user's name is colored according to their TeamColor but you can change the colors of chat usernames using TextChatService.OnIncomingMessage and font color tags. The following LocalScript in StarterPlayerScripts assigns a predetermined color to each user, picking randomly from a table of RGB colors.

LocalScript

1local TextChatService = game:GetService("TextChatService")
2
3local nameColors = {
4 Color3.fromRGB(255, 0, 0),
5 Color3.fromRGB(0, 255, 0),
6 Color3.fromRGB(0, 0, 255),
7 Color3.fromRGB(255, 255, 0),
8}
9
10TextChatService.OnIncomingMessage = function(textChatMessage: TextChatMessage)
11 local properties = Instance.new("TextChatMessageProperties")
12
13 local textSource = textChatMessage.TextSource
14 if textSource then
15 local index: number = (textSource.UserId % #nameColors) + 1
16 local randomColor: Color3 = nameColors[index]
17 properties.PrefixText = string.format("<font color='#%s'>%s</font>", randomColor:ToHex(), textChatMessage.PrefixText)
18 end
19
20 return properties
21end
22

Adding Chat Bubbles

In addition to displaying messages on the chat window, you can support the display of customizable chat bubbles above user avatars for immersive engagement.

To enable and customize bubble chat in your experience:

  1. In the Explorer window, select BubbleChatConfiguration under TextChatService.

  2. In the Properties window, check the Enabled checkbox under the Behavior category.

  3. Customize the Appearance and Behavior properties of bubbles in the same Properties window.

Chat Bubbles Customization

The following table shows common properties that you can adjust to customize the basic bubble appearance and behavior. For a full list of customization properties, see BubbleChatConfiguration.

Property Description Default
Appearance
BackgroundColor3 Background color of bubbles in Color3. [250, 250, 250]
Font Font of the bubble text. Font.GothamSemibold
TextColor3 Color of bubble text in Color3. [57, 59, 61]
TextSize Size of bubble text. 16
Behavior
Enabled A checkbox indicating whether bubble chat is enabled in the experience. True (Checked)
AdorneeName String name of the body part or Attachment that bubbles attach to; if multiple instances of the same name exist, the system attaches to the first instance found. "HumanoidRootPart"
BubbleDuration Time before a bubble fades out, in seconds. 30
BubblesSpacing Vertical space between stacked bubbles, in pixels. 6
LocalPlayerStudsOffset If adorned to the local player, the offset of bubbles in studs from their adornee, relative to the camera orientation (Vector3). (0, 0, 0)
MaxDistance Maximum distance from the camera that bubbles are shown. 100
MinimizeDistance Distance from the camera when bubbles turn into a single bubble with an ellipsis () to indicate chatter. 40
VerticalStudsOffset Extra space between bubbles and their adornee, in studs. 0

Creating Custom Commands

You can add additional functionalities to chat, such as admin commands, using TextChatCommand. Users sending a defined command in the chat input bar trigger a callback defined by TextChatCommand.Triggered to perform your customized actions.

The following example shows how to create a chat command that allows users to increase or decrease their character's size when they input /super or /mini.

  1. Insert a TextChatCommand instance inside TextChatService.

  2. Rename it to SizeCommand.

  3. Set its PrimaryAlias property to /super and its SecondaryAlias to /mini.

  4. Insert the following Script inside ServerScriptService to define a callback for the chat command that scales the character's size.

    Script

    1local TextChatService = game:GetService("TextChatService")
    2local Players = game:GetService("Players")
    3
    4local sizeCommand: TextChatCommand = TextChatService:WaitForChild("SizeCommand")
    5
    6sizeCommand.Triggered:Connect(function(textSource, message)
    7 local scaleMult = 1
    8 local messageWords = string.split(message, " ")
    9 if messageWords[1] == "/super" then
    10 scaleMult = 2
    11 elseif messageWords[1] == "/mini" then
    12 scaleMult = 0.5
    13 end
    14
    15 local player = Players:GetPlayerByUserId(textSource.UserId)
    16 if player then
    17 local character = player.Character
    18 if character then
    19 local humanoid = character:FindFirstChildOfClass("Humanoid")
    20 if humanoid then
    21 for _, child in ipairs(humanoid:GetChildren()) do
    22 if child:IsA("NumberValue") then
    23 child.Value *= scaleMult
    24 end
    25 end
    26 end
    27 end
    28 end
    29end)
    30