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
OnIncomingMessageonce 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.
-- 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
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
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.
| Part | Runs on | Job |
|---|---|---|
| ChatTagService | Server | Checks owner, admin list, group rank and VIP pass. Sets ChatTag, ChatTagColor and NameColor attributes on the Player. |
| Player attributes | Both | Copied from the server to every client, so each device knows everyone's tag. |
| ChatTags LocalScript | Every client | Sets OnIncomingMessage and adds the tag to each message it shows. |
Step 1: Decide tags on the server
- Hover over ServerScriptService, click + and insert a Script named
ChatTagService. - Paste the code below. Fill in your admin UserIds, and set
GROUP_IDandVIP_PASS_IDif you have a group or a VIP pass. Leave them at 0 to turn those tags off.
-- 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
- Open StarterPlayer, hover over StarterPlayerScripts and insert a LocalScript named
ChatTags. - Paste the code below.
- 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.
-- 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:
| Look | Change |
|---|---|
| Bold tag | In colorTag, return string.format('<b><font color="#%s">%s</font></b>', ...). |
| Brackets in a different colour | Build the label from three parts: "[" .. colorTag(tag, tagColor) .. "]". |
| Coloured name, no tag | Give the tag an empty text and only a nameColor, then in the LocalScript skip the label when the tag is "". |
| A tag for one person | Add 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
- Press Play and type a message. If the place is owned by your account, your name has a red [Owner] tag.
- If the place belongs to a group, add your UserId to
ADMIN_USER_IDSand play again: you get [Admin]. - To see the VIP tag without buying, temporarily change the first line of
pickTagto returnTAGS.vip, then change it back. - 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).
- 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.
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.
- 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
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
- Roblox Creator Docs: TextChatService. OnIncomingMessage and the default channels
- Roblox Creator Docs: TextChatMessageProperties. PrefixText overrides
- Roblox Creator Docs: TextChatMessage. PrefixText supports rich text
- Roblox Creator Docs: Rich text. the font color tag
- Roblox Creator Docs: GroupService. GetRolesInGroupAsync
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.