Contents

Twitch IRC Capability: Tags

Overview

All supported tags and values are documented. Any tags/values not documented here are not supported.

Undocumented tags can be added/removed at any time. Also, tags may appear in any order. Please write your code to parse tags individually and ignore unrecognized tags. 

Some tags are marked as deprecated. We recommend developers not use these tags.

Command Description
CLEARCHAT Temporary or permanent ban on a channel.
CLEARMSG Single message removal on a channel. This is triggered via /delete <target-msg-id> on IRC.
GLOBALUSERSTATE On successful login.
PRIVMSG Send a message to a channel.
ROOMSTATE When a user joins a channel or a room setting is changed.
USERNOTICE On subscription (first month) or resubscription (subsequent months) to a channel.
USERSTATE When a user joins a channel or sends a PRIVMSG to a channel.

CLEARCHAT (Twitch Tags)

Temporary or permanent ban on a channel.

> @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)

Single message removal on a channel. This is triggered via /delete <target-msg-id> on IRC.

> @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.

> @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

This is sent if the tags capability was requested beforehand.

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. This is empty 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)

Send a message to a channel.

These fields are sent for all PRIVMSGs:

> @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>

In addition, the bits field is sent for Bits messages.

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. This is empty 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: This is 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=dallas;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 #dallas :Kappa Keepo Kappa

Example: This is a Bits message.

> @badge-info=;badges=staff/1,bits/1000;bits=100;color=;display-name=dallas;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 #dallas :cheer100

ROOMSTATE (Twitch Tags)

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.

> @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 chatters 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)

On any of the following events:

These fields are sent for all USERNOTICEs:

> @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>
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. This is empty 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)

When a user joins a channel or sends a PRIVMSG to a channel.

> @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. This is empty 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 emotes. This always contains at least 0. 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