8 min read

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

Customize bubble chat

With TextChatService, you can use bubble chat to display customizable speech chat bubbles above user avatars and NPCs. Bubble chat can make your game more visually immersive and help users easily identify messages and their speakers in a contextually relevant manner. This feature is especially useful for games where users need to focus on the content in the meantime communicating with others in a less obtrusive way.

Enable bubble chat

To enable bubble chat in your game:

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

   

2. In the Properties window, check the BubbleChatConfiguration.Enabled checkbox.

   

Bubble customization

After enabling bubble chat, you can customize the appearance and behavior of your chat bubbles to match your game's theme. Use the Properties window of BubbleChatConfiguration for basic changes like text color and spacing, or implement advanced customization for bubble background images and other visual adjustments.

Alternatively, add a LocalScript in StarterPlayerScripts with all your customization settings. This allows the engine to apply your customizations during runtime, overriding the settings in Studio. It's useful for adding special effects to chat bubbles when users trigger certain events or conditions.

Basic customization

The following table shows common bubble chat customization properties. For a full list of customization properties, see BubbleChatConfiguration.

Appearance

Behavior

Advanced customization

For advanced customization of your bubble, add UI objects representing certain aspects of the bubble appearance as children under BubbleChatConfiguration, including:

• ImageLabel for background image settings.
• UIGradient for background gradient settings.
• UICorner for the corner shape of bubbles.
• UIPadding for the padding space between the text and bubble edges, relative to the parent's normal size.

After adding these objects, you can modify properties of these objects applicable to chat bubbles for advanced bubble customization. The following example LocalScript adds a background image and sharp corners to bubbles:

local TextChatService = game:GetService("TextChatService")

local bubbleChatConfiguration = TextChatService.BubbleChatConfiguration
bubbleChatConfiguration.TailVisible = false
bubbleChatConfiguration.TextColor3 = Color3.fromRGB(220, 50, 50)
bubbleChatConfiguration.FontFace = Font.fromEnum(Enum.Font.LuckiestGuy)

local bubbleUICorner = bubbleChatConfiguration:FindFirstChildOfClass("UICorner")
if not bubbleUICorner then
	bubbleUICorner = Instance.new("UICorner")
	bubbleUICorner.Parent = bubbleChatConfiguration
end
bubbleUICorner.CornerRadius = UDim.new(0, 0)

local bubbleUIPadding = bubbleChatConfiguration:FindFirstChildOfClass("UIPadding")
if not bubbleUIPadding then
	bubbleUIPadding = Instance.new("UIPadding")
	bubbleUIPadding.Parent = bubbleChatConfiguration
end
bubbleUIPadding.PaddingTop = UDim.new(0, 20)
bubbleUIPadding.PaddingRight = UDim.new(0, 10)
bubbleUIPadding.PaddingBottom = UDim.new(0, 15)
bubbleUIPadding.PaddingLeft = UDim.new(0, 10)

local bubbleImageLabel = bubbleChatConfiguration:FindFirstChildOfClass("ImageLabel")
if not bubbleImageLabel then
	bubbleImageLabel = Instance.new("ImageLabel")
	bubbleImageLabel.Parent = bubbleChatConfiguration
end
bubbleImageLabel.Image = "rbxassetid://109157529833093"
bubbleImageLabel.ScaleType = Enum.ScaleType.Slice
bubbleImageLabel.SliceCenter = Rect.new(40, 40, 320, 120)
bubbleImageLabel.SliceScale = 0.5

The following tables outline the available GuiObject and appearance modifier children along with their valid customization properties:

ImageLabel

UIGradient

UICorner

UIPadding

Per-bubble customization

You can individually style and modify chat bubble behaviors based on specific conditions in order to override your general settings. For example, you can use chat bubbles to differentiate NPCs and users, highlight critical health status, and apply special effects to messages with pre-defined keywords.

To set per-bubble customization, add a client-side LocalScript using BubbleChatMessageProperties, which overrides matching properties of BubbleChatConfiguration, and the TextChatService.OnBubbleAdded callback to specify how to customize each bubble. The callback supplies you with the TextChatMessage property as well as the adornee, so you can apply the customization based on attributes associated with users, the chat text content, user character properties, and any special conditions you want to define.

The following basic customization properties are available for per-bubble customization:

The following example adds special appearance to VIP users' chat bubbles by checking if a chat message sender has the IsVIP attribute:

local TextChatService = game:GetService("TextChatService")
local Players = game:GetService("Players")

-- Event handler for when a new chat bubble is added to the game
TextChatService.OnBubbleAdded = function(message: TextChatMessage, adornee: Instance)
	-- Check if the chat message has a TextSource (sender) associated with it
	if message.TextSource then
		-- Create a new BubbleChatMessageProperties instance to customize the chat bubble
		local bubbleProperties = Instance.new("BubbleChatMessageProperties")

		-- Get the user who sent the chat message based on their UserId
		local player = Players:GetPlayerByUserId(message.TextSource.UserId)

		if player:GetAttribute("IsVIP") then
			-- If the player is a VIP, customize the chat bubble properties
			bubbleProperties.TextColor3 = Color3.fromHex("#F5CD30")
			bubbleProperties.BackgroundColor3 = Color3.fromRGB(25, 27, 29)
			bubbleProperties.FontFace = Font.fromEnum(Enum.Font.PermanentMarker)
		end
		return bubbleProperties
	end
end

All advanced customization options are available for per-bubble customization. Similar to advanced customization for general bubbles, add instances that you want to customize as children of BubbleChatMessageProperties. The following example adds a special gradient effect along with other properties to chat bubbles of users with low health status by checking the Humanoid.Health property of chat message senders' characters:

local TextChatService = game:GetService("TextChatService")
local Players = game:GetService("Players")

-- Event handler for when a new chat bubble is added to the game
TextChatService.OnBubbleAdded = function(message: TextChatMessage, adornee: Instance)
	-- Check if the chat message has a TextSource (sender) associated with it
	if message.TextSource then
		-- Get the user who sent the chat message by using their UserId
		local player = Players:GetPlayerByUserId(message.TextSource.UserId)

		-- Find the humanoid in the user's character
		local humanoid = player.Character:FindFirstChildWhichIsA("Humanoid")

		if humanoid and humanoid.Health < 25 then
			-- Create a new BubbleChatMessageProperties instance to customize the chat bubble
			local bubbleProperties :BubbleChatMessageProperties = Instance.new("BubbleChatMessageProperties")

			-- Customize the chat bubble properties for low health condition
			bubbleProperties.BackgroundColor3 = Color3.fromRGB(245, 245, 245)
			bubbleProperties.TextColor3 = Color3.fromRGB(234, 51, 96)
			bubbleProperties.TextSize = 20
			bubbleProperties.FontFace = Font.fromEnum(Enum.Font.DenkOne)

			-- Add a UIGradient as a child to customize the gradient
			local uiGradient : UIGradient = Instance.new("UIGradient")
			uiGradient.Color = ColorSequence.new(Color3.fromRGB(110, 4, 0), Color3.fromRGB(0, 0, 0))
			uiGradient.Rotation = 90
			uiGradient.Parent = bubbleProperties

			return bubbleProperties
		end
	end
end

Manually display bubbles

You might want to display a chat bubble when players haven't sent a message, such as with NPCs. Use the TextChatService:DisplayBubble method to manually display a chat bubble.

Customization of these bubbles is the same as the customization of the bubbles that are automatically displayed when Players send messages through TextChannels using the TextChatService.OnBubbleAdded callback.

Note

To generate speech or other text using an LLM, see the TextGenerator class.

NPC bubbles

Display chat bubbles for non-player characters (NPCs) by calling TextChatService:DisplayBubble(character, message), with the NPC character and the message as parameters. These bubbles are customizable using the TextChatService.OnBubbleAdded callback just like any other chat bubble.

TextChatService:DisplayBubble() only works on client-side scripts, so be sure to use a Script with RunContext set to RunContext.Client, or a LocalScript in an appropriate container, such as StarterPlayerScripts. If you attach a ProximityPrompt to an NPC, a script for displaying a chat bubble might look like this:

local TextChatService = game:GetService("TextChatService")
local Workspace = game:GetService("Workspace")

local prompt = Workspace.SomeNPC.ProximityPrompt
local head = prompt.Parent:WaitForChild("Head")

prompt.Triggered:Connect(function()
	TextChatService:DisplayBubble(head, "Hello world!")
end)