Tutorial · Menus, HUD and sound

How to add chat tags in Roblox Studio

A chat tag is the coloured label in front of a name in the chat window: [VIP], [Admin], [Owner] or a group rank. Players buy VIP passes partly for the tag, so it is worth getting right. This guide splits the job the safe way: the server decides who gets which tag and stores it on the Player, and a LocalScript adds that tag and a name colour to every chat message with TextChatService.OnIncomingMessage.

Updated 14 November 20267 min readIntermediateLuauWritten by

In short

In a LocalScript in StarterPlayerScripts, set TextChatService.OnIncomingMessage to a function. For each message, find the sender with Players:GetPlayerByUserId(message.TextSource.UserId), make a TextChatMessageProperties, and set its PrefixText to your tag plus the old prefix, using rich text: <font color="#FFD700">[VIP]</font> followed by message.PrefixText. Return the properties. Decide the tag on the server and store it in a Player attribute so the client only reads it.

  • Set OnIncomingMessage once in your whole game. A second script that sets it replaces the first.
  • This needs TextChatService. It does not work with the legacy chat, and Roblox's new platform-integrated chat mode does not run this callback.
  • Check VIP passes and group ranks on the server, then share the result with an attribute every client can read.

Get the script

Chat tags script with name colours

A LocalScript in StarterPlayerScripts that adds each player's tag and name colour, set by the server as attributes, to their chat messages.

LocalScript in StarterPlayerScripts named ChatTags
-- LocalScript in StarterPlayerScripts named ChatTags.
-- Adds each sender's tag and name colour (set by ChatTagService) to their chat messages.
local Players = game:GetService("Players")
local TextChatService = game:GetService("TextChatService")

local function colorTag(text: string, color: Color3): string
	-- Rich text: <font color="#RRGGBB">text</font>
	return string.format('<font color="#%s">%s</font>', color:ToHex(), text)
end

-- Set this callback only once in the whole game: a second script setting it replaces this one
TextChatService.OnIncomingMessage = function(message: TextChatMessage): TextChatMessageProperties?
	local source = message.TextSource
	if not source then
		return nil -- a system message, not from a player
	end
	local player = Players:GetPlayerByUserId(source.UserId)
	if not player then
		return nil
	end

	local tag = player:GetAttribute("ChatTag")
	local tagColor = player:GetAttribute("ChatTagColor")
	local nameColor = player:GetAttribute("NameColor")
	if type(tag) ~= "string" then
		return nil -- no tag: leave the message as Roblox draws it
	end

	local name = message.PrefixText
	if typeof(nameColor) == "Color3" then
		name = colorTag(name, nameColor)
	end
	local label = "[" .. tag .. "]"
	if typeof(tagColor) == "Color3" then
		label = colorTag(label, tagColor)
	end

	local properties = Instance.new("TextChatMessageProperties")
	properties.PrefixText = label .. " " .. name
	return properties
end

RoCode builds it in the place you have open in Roblox Studio, on Windows or macOS with a desktop browser; on a phone the button sends the prompt and the link to your computer. Free to start, with free credits every day. More Roblox Studio scripts

Where to put it

Explorer: the server Script decides tags, this LocalScript shows them
ServerScriptService
  ChatTagService Script new
StarterPlayer
  StarterPlayerScripts
    ChatTags LocalScript new

Before you test

This LocalScript reads the ChatTag, ChatTagColor and NameColor attributes. The ChatTagService Script in Step 1 sets them.

Type-checked with luau-lsp strict against Roblox's API definitions on 14 November 2026. Not playtested in Studio yet: press Play and watch the Output window before you publish.

Prompt for RoCode

Add chat tags to my game with TextChatService: a Script in ServerScriptService that gives the place owner an Owner tag, a list of admin UserIds an Admin tag, my group's rank 200 and above a Staff tag and VIP game pass owners a gold VIP tag, stored as ChatTag, ChatTagColor and NameColor attributes on the Player and updated when someone buys the pass, and a LocalScript in StarterPlayerScripts that sets TextChatService.OnIncomingMessage to add the tag and name colour to PrefixText with rich text.

On this page
  1. Get the script
  2. How it works
  3. 1. Server
  4. 2. Show tags
  5. 3. Styles
  6. 4. Test
  7. Common errors
  8. With RoCode
  9. Questions
  10. Sources

How chat tags work

Every chat message is a TextChatMessage. Its PrefixText is the part before the message, which is the sender's display name by default, and it supports rich text: tags like <font color="#FF0000"> that colour part of the text.

When a message arrives on a player's device, Roblox calls TextChatService.OnIncomingMessage if you have set it. Your function can return a TextChatMessageProperties object, and Roblox merges its properties into the message before it is drawn. So a tag is just a new PrefixText: the tag in colour, then the original name.

Who does what
PartRuns onJob
ChatTagServiceServerChecks owner, admin list, group rank and VIP pass. Sets ChatTag, ChatTagColor and NameColor attributes on the Player.
Player attributesBothCopied from the server to every client, so each device knows everyone's tag.
ChatTags LocalScriptEvery clientSets OnIncomingMessage and adds the tag to each message it shows.

Step 1: Decide tags on the server

  1. Hover over ServerScriptService, click + and insert a Script named ChatTagService.
  2. Paste the code below. Fill in your admin UserIds, and set GROUP_ID and VIP_PASS_ID if you have a group or a VIP pass. Leave them at 0 to turn those tags off.
Script in ServerScriptService named ChatTagService
-- Script in ServerScriptService named ChatTagService.
-- Decides each player's chat tag and stores it in attributes every client can read.
local GroupService = game:GetService("GroupService")
local MarketplaceService = game:GetService("MarketplaceService")
local Players = game:GetService("Players")

local ADMIN_USER_IDS: { [number]: boolean } = {
	-- [123456789] = true,
}
local GROUP_ID = 0 -- your group's ID, or 0 for no rank tags
local STAFF_RANK = 200 -- group members at or above this rank get the Staff tag
local VIP_PASS_ID = 0 -- your VIP pass ID, or 0 for no VIP tag

type Tag = { text: string, color: Color3, nameColor: Color3? }

-- Highest first: a player gets the first tag they qualify for
local TAGS: { [string]: Tag } = {
	owner = { text = "Owner", color = Color3.fromRGB(255, 85, 85), nameColor = Color3.fromRGB(255, 170, 170) },
	admin = { text = "Admin", color = Color3.fromRGB(255, 140, 60) },
	staff = { text = "Staff", color = Color3.fromRGB(90, 170, 255) },
	vip = { text = "VIP", color = Color3.fromRGB(255, 205, 60), nameColor = Color3.fromRGB(255, 230, 150) },
}

local function hasStaffRank(player: Player): boolean
	if GROUP_ID == 0 then
		return false
	end
	-- Asks Roblox's servers, so it can fail. A failure means no tag, not an error.
	local ok, info = pcall(function()
		return GroupService:GetRolesInGroupAsync(player.UserId, GROUP_ID)
	end)
	if ok and type(info) == "table" and type(info.Roles) == "table" then
		for _, role in info.Roles do
			if type(role) == "table" and type(role.Rank) == "number" and role.Rank >= STAFF_RANK then
				return true
			end
		end
	end
	return false
end

local function ownsVip(player: Player): boolean
	if VIP_PASS_ID == 0 then
		return false
	end
	local ok, owns = pcall(function()
		return MarketplaceService:UserOwnsGamePassAsync(player.UserId, VIP_PASS_ID)
	end)
	return ok and owns == true
end

local function pickTag(player: Player): Tag?
	if game.CreatorType == Enum.CreatorType.User and game.CreatorId == player.UserId then
		return TAGS.owner
	elseif ADMIN_USER_IDS[player.UserId] then
		return TAGS.admin
	elseif hasStaffRank(player) then
		return TAGS.staff
	elseif ownsVip(player) then
		return TAGS.vip
	end
	return nil
end

local function applyTag(player: Player, tag: Tag?)
	-- Attributes on the Player are copied to every client
	player:SetAttribute("ChatTag", if tag then tag.text else nil)
	player:SetAttribute("ChatTagColor", if tag then tag.color else nil)
	player:SetAttribute("NameColor", if tag then tag.nameColor else nil)
end

Players.PlayerAdded:Connect(function(player: Player)
	applyTag(player, pickTag(player))
end)
for _, player in Players:GetPlayers() do
	task.spawn(function()
		applyTag(player, pickTag(player))
	end)
end

-- Someone bought VIP during this session: give the tag now, unless they already have a higher one
MarketplaceService.PromptGamePassPurchaseFinished:Connect(function(player: Player, passId: number, wasPurchased: boolean)
	if wasPurchased and passId == VIP_PASS_ID and player:GetAttribute("ChatTag") == nil then
		applyTag(player, TAGS.vip)
	end
end)

The order of the if checks in pickTag is the order of importance: an admin who also owns VIP shows [Admin]. Each tag has a colour for the label and, optionally, a colour for the name. Admin and Staff leave the name as Roblox colours it, which is the team colour when the player is on a team.

Group rank and pass checks call Roblox's web servers, which can fail or be slow, so each one is wrapped in pcall. If a check fails the player just gets no tag this session. For more about passes, including how to make one, see the game pass guide.

Step 2: Show the tags in chat

  1. Open StarterPlayer, hover over StarterPlayerScripts and insert a LocalScript named ChatTags.
  2. Paste the code below.
  3. Check that no other script in your game sets TextChatService.OnIncomingMessage. If one does, merge the two into this one.
LocalScript in StarterPlayerScripts named ChatTags
-- LocalScript in StarterPlayerScripts named ChatTags.
-- Adds each sender's tag and name colour (set by ChatTagService) to their chat messages.
local Players = game:GetService("Players")
local TextChatService = game:GetService("TextChatService")

local function colorTag(text: string, color: Color3): string
	-- Rich text: <font color="#RRGGBB">text</font>
	return string.format('<font color="#%s">%s</font>', color:ToHex(), text)
end

-- Set this callback only once in the whole game: a second script setting it replaces this one
TextChatService.OnIncomingMessage = function(message: TextChatMessage): TextChatMessageProperties?
	local source = message.TextSource
	if not source then
		return nil -- a system message, not from a player
	end
	local player = Players:GetPlayerByUserId(source.UserId)
	if not player then
		return nil
	end

	local tag = player:GetAttribute("ChatTag")
	local tagColor = player:GetAttribute("ChatTagColor")
	local nameColor = player:GetAttribute("NameColor")
	if type(tag) ~= "string" then
		return nil -- no tag: leave the message as Roblox draws it
	end

	local name = message.PrefixText
	if typeof(nameColor) == "Color3" then
		name = colorTag(name, nameColor)
	end
	local label = "[" .. tag .. "]"
	if typeof(tagColor) == "Color3" then
		label = colorTag(label, tagColor)
	end

	local properties = Instance.new("TextChatMessageProperties")
	properties.PrefixText = label .. " " .. name
	return properties
end

message.PrefixText already holds the name, so the script keeps it and puts the tag in front. Color3:ToHex() turns a colour into six hex digits such as FFCD3C, which is the format the rich text font tag needs after a #.

For the player who sends a message, Roblox calls this function twice: once when the message is sent and shown straight away, and again when the filtered version comes back from the server. The script gives the same answer both times, so the tag stays put.

Step 3: Change how tags look

Everything about the look is in the TAGS table on the server and the colorTag function on the client. Some common changes:

Common tag styles
LookChange
Bold tagIn colorTag, return string.format('<b><font color="#%s">%s</font></b>', ...).
Brackets in a different colourBuild the label from three parts: "[" .. colorTag(tag, tagColor) .. "]".
Coloured name, no tagGive the tag an empty text and only a nameColor, then in the LocalScript skip the label when the tag is "".
A tag for one personAdd an entry to TAGS and an elseif player.UserId == 123456789 line near the top of pickTag.

Keep the tag text short, one word is best. The chat window is narrow on phones, and a long tag pushes the message onto a second line. Rich text has other tags (<i> for italics, <stroke> for an outline); keep to colour and bold so the chat stays readable.

Step 4: Test it

  1. Press Play and type a message. If the place is owned by your account, your name has a red [Owner] tag.
  2. If the place belongs to a group, add your UserId to ADMIN_USER_IDS and play again: you get [Admin].
  3. To see the VIP tag without buying, temporarily change the first line of pickTag to return TAGS.vip, then change it back.
  4. Open the Test tab, choose 2 players under Clients and Servers and click Start. Chat from both windows: each one sees the other's tag (test players have no tag unless you give one).
  5. While playing, open the Explorer, select your Player under Players and look at its Attributes in the Properties window to check what the server set.

Common errors and fixes

If no tag appears, first check the Output window, then these.

No tag shows at all

Check that TextChatService.ChatVersion is TextChatService (not LegacyChatService), that ChatTags is a LocalScript in StarterPlayerScripts, and that your Player has a ChatTag attribute while playing. Roblox's platform-integrated chat mode does not call OnIncomingMessage, so leave it off if you need tags.

Tags worked, then stopped after I added another script

Two scripts set TextChatService.OnIncomingMessage, and only one of them wins. Move the other script's code into the ChatTags function.

The tag shows the code, like <font color=...>

The colour is not a valid hex code, or a quote is missing. Color3:ToHex() gives six digits; the format string adds the # and the quotes.

The VIP tag does not appear for a buyer

Check VIP_PASS_ID is the pass ID from Creator Hub, not the game ID. Also check the pass is on sale and belongs to this experience.

GetAttribute returns nil on the client

The server has not set it yet, or set it on the character instead of the Player. ChatTagService sets attributes on the Player object, which keeps them through respawns.

Build it with RoCode

If you would rather not set this up by hand, RoCode can build it in the place you have open. RoCode is an independent AI agent for Roblox Studio, not made by Roblox: you describe the change in a web chat, and its Studio plugin creates the parts and scripts in your Explorer, so there is no code to paste.

You type

Add chat tags: [Owner] in red for me, [Staff] in blue for rank 200+ in my group, and a gold [VIP] tag with a gold name for owners of my VIP pass, decided on the server.

RoCode does
  • Can read your place first to find your VIP pass script and any existing chat code, so the callback is set only once
  • Writes the scripts with Create Script and is told to compile-check each one with Check Script
  • Sets an undo point before and after each batch of changes, so Ctrl+Z steps back one batch at a time

How RoCode connects to Studio.

Questions

How do I add a chat tag in Roblox Studio?

Set TextChatService.OnIncomingMessage in a LocalScript, and return a TextChatMessageProperties whose PrefixText is your tag plus message.PrefixText. Step 2 has the full script.

How do I make a VIP chat tag?

Check MarketplaceService:UserOwnsGamePassAsync on the server when the player joins, set a ChatTag attribute of "VIP", and let the ChatTags LocalScript show it. Step 1 also updates the tag when the pass is bought mid-game.

How do I change the colour of a player's name in chat?

Wrap message.PrefixText in a rich text font tag, such as <font color="#FFD700">, and return it as the new PrefixText. The NameColor attribute in this guide does that.

How do I give group ranks a chat tag?

On the server, call GroupService:GetRolesInGroupAsync(player.UserId, groupId) inside pcall and check the roles' Rank values, then set the tag attribute. The Staff tag in Step 1 does this.

Do chat tags work with the old chat?

No. This guide uses TextChatService. Games still on LegacyChatService need to switch the ChatVersion property first.

Why is OnIncomingMessage not working?

It only runs on the client, only one script may set it, and it is not called when platform-integrated chat is enabled. Check all three.

Sources and further reading

How the code was checked: every script on this page passes Luau's strict type checker against Roblox's API definitions (luau-lsp, 14 November 2026). A type check catches misspelt APIs and wrong types, not game logic, so playtest in Studio before you publish.

Try RoCode on your own place.

Free every day, no card required. Install the plugin, describe the feature, and review what lands in Studio.