Contents

Twitch IRC: Tags

Overview

As stated in the IRCv3 Message Tag specification, “Message tags are a mechanism for adding additional metadata on a per-message basis. This is achieved via an extension to the protocol message format, enabled via capability negotiation. Tags are simple keys that MAY have optional string data as values.Tagged messages can be sent by both servers and clients. The usage of individual tags [is] specified in their own documents.”

In other words, tags are optional metadata which Twitch can attach to an IRC message. When a client requests the tags capability, the EBS adds one or more tags to each message to that client.

This guide documents the tags and values supported by Twitch IRC. If a tag is not documented here, it is not supported.

Here is the general format for an individual tag:
> @tag-name=<tag-name> :tmi.twitch.tv <command> #<channel> :<user>

Here is the general format for a set of tags:
@tag-name-1=<tag-value-1>;tag-name-2=<tag-value-2>;... <rest of the command syntax depends on the particular IRC command used>

Notes: 

Command Description
CLEARCHAT Purges all chat messages in a channel, or purges chat messages from a specific user (typically after a timeout or ban).
CLEARMSG Removes a single message from a channel. This is triggered via /delete <target-msg-id> on IRC.
GLOBALUSERSTATE On successful login, provides data about the current logged-in user through IRC tags. It is sent after successfully authenticating (sending a PASS/NICK command).
PRIVMSG Sends a message to a channel.
ROOMSTATE Sends room-state data when a user joins a channel or a room setting is changed. For a join, the message contains all chat-room settings. For changes, only the relevant tag is sent.
USERNOTICE Sends a notice to the user when any of several events occurs.
USERSTATE Sends user-state data when a user joins a channel or sends a PRIVMSG to a channel.

CLEARCHAT (Twitch Tags)

Purges all chat messages in a channel, or purges chat messages from a specific user (typically after a timeout or ban).

Prototype:

> @ban-duration=<ban-duration> :tmi.twitch.tv CLEARCHAT #<channel> :<user>
Parameter Description
ban-duration (Optional) Duration of the timeout, in seconds. If omitted, the ban is permanent.

Example: ronni is permanently banned from the dallas channel.

> :tmi.twitch.tv CLEARCHAT #dallas :ronni

CLEARMSG (Twitch Tags)

Removes a single message from a channel. This is triggered by the/delete <target-msg-id> command on IRC.

Prototype:

> @login=<login>;target-msg-id=<target-msg-id> :tmi.twitch.tv CLEARMSG #<channel> :<message>
ParameterDescription
loginName of the user who sent the message.
messageThe message.
target-msg-idUUID of the message.

Example: ronni’s HeyGuys message is deleted from the dallas channel.

> @login=ronni;target-msg-id=abc-123-def :tmi.twitch.tv CLEARMSG #dallas :HeyGuys

GLOBALUSERSTATE (Twitch Tags)

On successful login, provides data about the current logged-in user through IRC tags. It is sent after successfully authenticating (sending a PASS/NICK command).

Prototype:
> @badge-info=<badge-info>;badges=<badges>;color=<color>;display-name=<display-name>;emote-sets=<emote-sets>;turbo=<turbo>;user-id=<user-id>;user-type=<user-type> :tmi.twitch.tv GLOBALUSERSTATE

Note: Before doing this, you must request and receive the tags capability:
< CAP REQ :twitch.tv/tags
> :tmi.twitch.tv CAP * ACK :twitch.tv/tags

For more information, see Twitch IRC Capabilities.

Parameter Description
badge-info Metadata related to the chat badges in the badges tag.

Currently this is used only for subscriber, to indicate the exact number of months the user has been a subscriber. This number is finer grained than the version number in badges. For example, a user who has been a subscriber for 45 months would have a badge-info value of 45 but might have a badges version number for only 3 years.
badges Comma-separated list of chat badges and the version of each badge (each in the format <badge>/<version>, such as admin/1). There are many valid badge values; e.g., admin, bits, broadcaster, global_mod, moderator, subscriber, staff, turbo. Many badges have only 1 version, but some badges have different versions (images), depending on how long you hold the badge status; e.g., subscriber.
color Hexadecimal RGB color code; the empty string if it is never set.
display-name The user’s display name, escaped as described in the IRCv3 spec. This is empty if it is never set.
emote-sets A comma-separated list of emotes, belonging to one or more emote sets. This always contains at least 0. Get Chat Emoticons by Set gets a subset of emoticons.
turbo (Deprecated, use badges instead) 1 if the user has a Turbo badge; otherwise, 0.
user-id The user’s ID.
user-type (Deprecated, use badges instead) The user’s type. Valid values: empty, mod, global_mod, admin, staff. The broadcaster can have any of these.

Example: This is the global user state of dallas, an admin user, after logging in.

> @badge-info=subscriber/8;badges=subscriber/6;color=#0D4200;display-name=dallas;emote-sets=0,33,50,237,793,2126,3517,4578,5569,9400,10337,12239;turbo=0;user-id=1337;user-type=admin :tmi.twitch.tv GLOBALUSERSTATE

PRIVMSG (Twitch Tags)

Sends a message to a channel. 

Prototype:

> @badge-info=<badge-info>;badges=<badges>;color=<color>;display-name=<display-name>;emotes=<emotes>;id=<id-of-msg>;mod=<mod>;room-id=<room-id>;subscriber=<subscriber>;tmi-sent-ts=<timestamp>;turbo=<turbo>;user-id=<user-id>;user-type=<user-type> :<user>!<user>@<user>.tmi.twitch.tv PRIVMSG #<channel> :<message>

All PRIVMSGs contain the fields listed in the preceding prototype. In addition, the bits field is sent for Bits messages. To learn more about Bits, see the Extensions Monetization Guide

ParameterDescription
badge-info

Metadata related to the chat badges in the badges tag.

Currently this is used only for subscriber, to indicate the exact number of months the user has been a subscriber. This number is finer grained than the version number in badges. For example, a user who has been a subscriber for 45 months would have a badge-info value of 45 but might have a badges version number for only 3 years.

badgesComma-separated list of chat badges and the version of each badge (each in the format <badge>/<version>, such as admin/1). There are many valid badge values; e.g., admin, bits, broadcaster, global_mod, moderator, subscriber, staff, turbo. Many badges have only 1 version, but some badges have different versions (images), depending on how long you hold the badge status; e.g., subscriber.
bits(Sent only for Bits messages) The amount of cheer/Bits employed by the user. All instances of these regular expressions:
/(^\|\s)<emote-name>\d+(\s\|$)/
(where <emote-name> is an emote name returned by the Get Cheermotes endpoint), should be replaced with the appropriate emote:
static-cdn.jtvnw.net/bits/<theme>/<type>/<color>/<size>
  • themelight or dark
  • typeanimated or static
  • colorred for 10000+ Bits, blue for 5000-9999, green for 1000-4999, purple for 100-999, gray for 1-99
  • size – A digit between 1 and 4
colorHexadecimal RGB color code; the empty string if it is never set.
display-nameThe user’s display name, escaped as described in the IRCv3 spec. This is empty if it is never set.
emotesInformation to replace text in the message with emote images. This can be empty. Syntax:
<emote ID>:<first index>-<last index>,<another first index>-<another last index>/<another emote ID>:<first index>-<last index>...
  • emote ID – The number to use in this URL:
    http://static-cdn.jtvnw.net/emoticons/v1/:<emote ID>/:<size>
    (size is 1.0, 2.0 or 3.0.)
  • first index, last index – Character indexes. \001ACTION does not count. Indexing starts from the first character that is part of the user’s actual message. See the example (normal message) below.
idA unique ID for the message.
messageThe message.
mod1 if the user has a moderator badge; otherwise, 0.
room-idThe channel ID.
subscriber(Deprecated, use badges instead) 1 if the user has a subscriber badge; otherwise, 0.
tmi-sent-tsTimestamp when the server received the message.
turbo(Deprecated, use badges instead) 1 if the user has a Turbo badge; otherwise, 0.
user-idThe user’s ID.
user-type(Deprecated, use badges instead) The user’s type. Valid values: mod, global_mod, admin, staff. If the broadcaster is not any of these user types, this field is left empty.

Example of a non-Bits message: The first Kappa (emote ID 25) is from character 0 (K) to character 4 (a), and the other Kappa is from 12 to 16.

> @badge-info=;badges=global_mod/1,turbo/1;color=#0D4200;display-name=ronni;emotes=25:0-4,12-16/1902:6-10;id=b34ccfc7-4977-403a-8a94-33c6bac34fb8;mod=0;room-id=1337;subscriber=0;tmi-sent-ts=1507246572675;turbo=1;user-id=1337;user-type=global_mod :ronni!ronni@ronni.tmi.twitch.tv PRIVMSG #ronni :Kappa Keepo Kappa

Example of a Bits message: 

> @badge-info=;badges=staff/1,bits/1000;bits=100;color=;display-name=ronni;emotes=;id=b34ccfc7-4977-403a-8a94-33c6bac34fb8;mod=0;room-id=1337;subscriber=0;tmi-sent-ts=1507246572675;turbo=1;user-id=1337;user-type=staff :ronni!ronni@ronni.tmi.twitch.tv PRIVMSG #ronni :cheer100

ROOMSTATE (Twitch Tags)

Sends room-state data when a user joins a channel or a room setting is changed. For a join, the message contains all chat-room settings. For changes, only the relevant tag is sent.

Prototype:

> @emote-only=<emote-only>;followers-only=<followers-only>;r9k=<r9k>;slow=<slow>;subs-only=<subs-only> :tmi.twitch.tv ROOMSTATE #<channel>
Parameter Description
emote-only Emote-only mode. If enabled, only emotes are allowed in chat. Valid values: 0 (disabled) or 1 (enabled).
followers-only Followers-only mode. If enabled, controls which followers can chat. Valid values: -1 (disabled), 0 (all followers can chat), or a non-negative integer (only users following for at least the specified number of minutes can chat).
r9k R9K mode. If enabled, messages with more than 9 characters must be unique. Valid values: 0 (disabled) or 1 (enabled).
slow The number of seconds a chatter without moderator privileges must wait between sending messages.
subs-only Subscribers-only mode. If enabled, only subscribers and moderators can chat. Valid values: 0 (disabled) or 1 (enabled).

Example: This is for a join in the dallas channel.

> @emote-only=0;followers-only=0;r9k=0;slow=0;subs-only=0 :tmi.twitch.tv ROOMSTATE #dallas

Example: On the dallas channel, slow mode is set to 10 seconds:

> @slow=10 :tmi.twitch.tv ROOMSTATE #dallas

USERNOTICE (Twitch Tags)

Sends a notice to the user when any of the following events occurs:

Prototype:

> @badge-info=<badge-info>;badges=<badges>;color=<color>;display-name=<display-name>;emotes=<emotes>;id=<id-of-msg>;login=<user>;mod=<mod>;msg-id=<msg-id>;room-id=<room-id>;subscriber=<subscriber>;system-msg=<system-msg>;tmi-sent-ts=<timestamp>;turbo=<turbo>;user-id=<user-id>;user-type=<user-type> :tmi.twitch.tv USERNOTICE #<channel> :<message>

All USERNOTICEs contain the fields listed in the preceding prototype.

ParameterDescription
badge-info

Metadata related to the chat badges in the badges tag.

Currently this is used only for subscriber, to indicate the exact number of months the user has been a subscriber. This number is finer grained than the version number in badges. For example, a user who has been a subscriber for 45 months would have a badge-info value of 45 but might have a badges version number for only 3 years.

badgesComma-separated list of chat badges and the version of each badge (each in the format <badge>/<version>, such as admin/1). There are many valid badge values; e.g., admin, bits, broadcaster, global_mod, moderator, subscriber, staff, turbo. Many badges have only 1 version, but some badges have different versions (images), depending on how long you hold the badge status; e.g., subscriber.
colorHexadecimal RGB color code; the empty string if it is never set.
display-nameThe user’s display name, escaped as described in the IRCv3 spec. This is empty if it is never set.
emotesInformation to replace text in the message with emote images. This can be empty. Syntax:
<emote ID>:<first index>-<last index>,<another first index>-<another last index>/<another emote ID>:<first index>-<last index>...
  • emote ID – The number to use in this URL:
    http://static-cdn.jtvnw.net/emoticons/v1/:<emote ID>/:<size>
    (size is 1.0, 2.0 or 3.0.)
  • first index, last index – Character indexes. \001ACTION does not count. Indexing starts from the first character that is part of the user’s actual message. See the example (normal message) below.
idA unique ID for the message.
loginThe name of the user who sent the notice.
messageThe message. This is omitted if the user did not enter a message.
mod1 if the user has a moderator badge; otherwise, 0.
msg-idThe type of notice (not the ID). Valid values: sub, resub, subgift, anonsubgift, submysterygift, giftpaidupgraderewardgift, anongiftpaidupgrade, raid, unraid, ritual, bitsbadgetier.
room-idThe channel ID.
subscriber(Deprecated, use badges instead) 1 if the user has a subscriber badge; otherwise, 0.
system-msgThe message printed in chat along with this notice.
tmi-sent-tsTimestamp when the server received the message.
turbo(Deprecated, use badges instead) 1 if the user has a Turbo badge; otherwise, 0.
user-idThe user’s ID.
user-type(Deprecated, use badges instead) The user’s type. Valid values: mod, global_mod, admin, staff. If the broadcaster is not any of these user types, this field is left empty.

Several other, msg-param fields are sent only for some notices; e.g., sub/resub. See the table below for details.

msg-param Parameter Description
msg-param-cumulative-months (Sent only on sub, resub) The total number of months the user has subscribed. This is the same as msg-param-months but sent for different types of user notices.
msg-param-displayName (Sent only on raid) The display name of the source user raiding this channel.
msg-param-login (Sent on only raid) The name of the source user raiding this channel.
msg-param-months (Sent only on subgift, anonsubgift) The total number of months the user has subscribed. This is the same as msg-param-cumulative-months but sent for different types of user notices.
msg-param-promo-gift-total (Sent only on anongiftpaidupgrade, giftpaidupgrade) The number of gifts the gifter has given during the promo indicated by msg-param-promo-name.
msg-param-promo-name (Sent only on anongiftpaidupgrade, giftpaidupgrade) The subscriptions promo, if any, that is ongoing; e.g. Subtember 2018.
msg-param-recipient-display-name (Sent only on subgift, anonsubgift) The display name of the subscription gift recipient.
msg-param-recipient-id (Sent only on subgift, anonsubgift) The user ID of the subscription gift recipient.
msg-param-recipient-user-name (Sent only on subgift, anonsubgift) The user name of the subscription gift recipient.
msg-param-sender-login (Sent only on giftpaidupgrade) The login of the user who gifted the subscription.
msg-param-sender-name (Sent only on giftpaidupgrade) The display name of the user who gifted the subscription.
msg-param-should-share-streak (Sent only on sub, resub) Boolean indicating whether users want their streaks to be shared.
msg-param-streak-months (Sent only on sub, resub) The number of consecutive months the user has subscribed. This is 0 if msg-param-should-share-streak is 0.
msg-param-sub-plan (Sent only on subresub, subgift, anonsubgift) The type of subscription plan being used. Valid values: Prime, 1000, 2000, 3000. 1000, 2000, and 3000 refer to the first, second, and third levels of paid subscriptions, respectively (currently $4.99, $9.99, and $24.99).
msg-param-sub-plan-name (Sent only on subresub, subgift, anonsubgift) The display name of the subscription plan. This may be a default name or one created by the channel owner.
msg-param-viewerCount (Sent only on raid) The number of viewers watching the source channel raiding this channel.
msg-param-ritual-name (Sent only on ritual) The name of the ritual this notice is for. Valid value: new_chatter.
msg-param-threshold (Sent only on bitsbadgetier) The tier of the bits badge the user just earned; e.g. 100, 1000, 10000.

Example: Notice sent when ronni resubscribed to the dallas channel.

> @badge-info=;badges=staff/1,broadcaster/1,turbo/1;color=#008000;display-name=ronni;emotes=;id=db25007f-7a18-43eb-9379-80131e44d633;login=ronni;mod=0;msg-id=resub;msg-param-cumulative-months=6;msg-param-streak-months=2;msg-param-should-share-streak=1;msg-param-sub-plan=Prime;msg-param-sub-plan-name=Prime;room-id=1337;subscriber=1;system-msg=ronni\shas\ssubscribed\sfor\s6\smonths!;tmi-sent-ts=1507246572675;turbo=1;user-id=1337;user-type=staff :tmi.twitch.tv USERNOTICE #dallas :Great stream -- keep it up!

Example: Notice sent when tww2 gifted a subscription to Mr_Woodchuck in forstycup’s channel.

> @badge-info=;badges=staff/1,premium/1;color=#0000FF;display-name=TWW2;emotes=;id=e9176cd8-5e22-4684-ad40-ce53c2561c5e;login=tww2;mod=0;msg-id=subgift;msg-param-months=1;msg-param-recipient-display-name=Mr_Woodchuck;msg-param-recipient-id=89614178;msg-param-recipient-name=mr_woodchuck;msg-param-sub-plan-name=House\sof\sNyoro~n;msg-param-sub-plan=1000;room-id=19571752;subscriber=0;system-msg=TWW2\sgifted\sa\sTier\s1\ssub\sto\sMr_Woodchuck!;tmi-sent-ts=1521159445153;turbo=0;user-id=13405587;user-type=staff :tmi.twitch.tv USERNOTICE #forstycup

Example: Notice sent when an anonymous user gifted a subscription to TenureCalculator in qa_subs_partner’s channel. This is like the “subgift” message above, except:

> @badge-info=;badges=broadcaster/1,subscriber/6;color=;display-name=qa_subs_partner;emotes=;flags=;id=b1818e3c-0005-490f-ad0a-804957ddd760;login=qa_subs_partner;mod=0;msg-id=anonsubgift;msg-param-months=3;msg-param-recipient-display-name=TenureCalculator;msg-param-recipient-id=135054130;msg-param-recipient-user-name=tenurecalculator;msg-param-sub-plan-name=t111;msg-param-sub-plan=1000;room-id=196450059;subscriber=1;system-msg=An\sanonymous\suser\sgifted\sa\sTier\s1\ssub\sto\sTenureCalculator!\s;tmi-sent-ts=1542063432068;turbo=0;user-id=196450059;user-type= :tmi.twitch.tv USERNOTICE #qa_subs_partner

Example: Notice sent when a channel is raided.

> @badge-info=;badges=turbo/1;color=#9ACD32;display-name=TestChannel;emotes=;id=3d830f12-795c-447d-af3c-ea05e40fbddb;login=testchannel;mod=0;msg-id=raid;msg-param-displayName=TestChannel;msg-param-login=testchannel;msg-param-viewerCount=15;room-id=56379257;subscriber=0;system-msg=15\sraiders\sfrom\sTestChannel\shave\sjoined\n!;tmi-sent-ts=1507246572675;tmi-sent-ts=1507246572675;turbo=1;user-id=123456;user-type= :tmi.twitch.tv USERNOTICE #othertestchannel

Example: Notice sent for a new_chatter ritual.

> @badge-info=;badges=;color=;display-name=SevenTest1;emotes=30259:0-6;id=37feed0f-b9c7-4c3a-b475-21c6c6d21c3d;login=seventest1;mod=0;msg-id=ritual;msg-param-ritual-name=new_chatter;room-id=6316121;subscriber=0;system-msg=Seventoes\sis\snew\shere!;tmi-sent-ts=1508363903826;turbo=0;user-id=131260580;user-type= :tmi.twitch.tv USERNOTICE #seventoes :HeyGuys

USERSTATE (Twitch Tags)

Sends user-state data when a user joins a channel or sends a PRIVMSG to a channel.

Prototype:

> @badge-info=<badge-info>;badges=<badges>;color=<color>;display-name=<display-name>;emote-sets=<emote-sets>;mod=<mod>;subscriber=<subscriber>;turbo=<turbo>;user-type=<user-type>:tmi.twitch.tv USERSTATE #<channel>
Parameter Description
badge-info Metadata related to the chat badges in the badges tag.

Currently this is used only for subscriber, to indicate the exact number of months the user has been a subscriber. This number is finer grained than the version number in badges. For example, a user who has been a subscriber for 45 months would have a badge-info value of 45 but might have a badges version number for only 3 years.
badges Comma-separated list of chat badges and the version of each badge (each in the format <badge>/<version>, such as admin/1). There are many valid badge values; e.g., admin, bits, broadcaster, global_mod, moderator, subscriber, staff, turbo. Many badges have only 1 version, but some badges have different versions (images), depending on how long you hold the badge status; e.g., subscriber.
color Hexadecimal RGB color code; the empty string if it is never set.
display-name The user’s display name, escaped as described in the IRCv3 spec. This is empty if it is never set.
emote-sets Your emote set, a comma-separated list of emote sets. Get Chat Emoticons by Set gets a subset of emoticon images.
mod 1 if the user has a moderator badge; otherwise, 0.
subscriber (Deprecated, use badges instead) 1 if the user has a subscriber badge; otherwise, 0.
turbo (Deprecated, use badges instead) 1 if the user has a Turbo badge; otherwise, 0.
user-type (Deprecated, use badges instead) The user’s type. Valid values: empty, mod, global_mod, admin, staff. The broadcaster can have any of these.

Example: Notice sent when ronni joins the dallas channel.

> @badge-info=;badges=staff/1;color=#0D4200;display-name=ronni;emote-sets=0,33,50,237,793,2126,3517,4578,5569,9400,10337,12239;mod=1;subscriber=1;turbo=1;user-type=staff :tmi.twitch.tv USERSTATE #dallas