Contents

Twitch IRC Tags

Reviews for Extensions, organizations, games, and chatbot verification are temporarily paused while we revise our processes. We are working to resume reviews as quickly as possible and will share updates with you shortly. Thank you for your patience and understanding.

Most IRC messages provide enough information that you can figure out what happened. For example, in the following PRIVMSG message, you know that user abc posted HeyGuys in the xyz channel.

:abc!abc@abc.tmi.twitch.tv PRIVMSG #xyz :HeyGuys

But what if you wanted to know more about the user? For example, are they a subscriber or what kind of badges do they have? Well, you’re in luck. Twitch provides rich information about the user if you request the tags capability (see Requesting Twitch-specific capabilities).

@badge-info=;badges=broadcaster/1;client-nonce=997dcf443c31e258c1d32a8da47b6936;color=#0000FF;display-name=abc;emotes=;first-msg=0;flags=0-6:S.7;id=eb24e920-8065-492a-8aea-266a00fc5126;mod=0;room-id=713936733;subscriber=0;tmi-sent-ts=1642786203573;turbo=0;user-id=713936733;user-type= :abc!abc@abc.tmi.twitch.tv PRIVMSG #xyz :HeyGuys

If you request the commands capability, you should always include the tags capability because the Twitch-specifc IRC commands aren’t typically useful on their own.

The Twitch IRC server follows the IRCv3 Message Tag specification for including tags in messages. Tags are optional metadata that Twitch attaches to an IRC message. Tags are key/value pairs (key=value). The key’s value is optional (key=). Tags may appear in any order. You should only parse tags you recognize and ignore the others.

Tags are in the form: @tag-name-1=<tag-value-1>;tag-name-2=<tag-value-2>;....

The following are the commands that may include tags. If a tag is not documented here, it is not supported for third-party developer use.

Message Description
CLEARCHAT Sent when the bot or moderator removes all messages from the chat room or removes all messages for the specified user. Learn more
CLEARMSG Sent when the bot removes a single message from the chat room. Learn more
GLOBALUSERSTATE Sent when the bot authenticates with the server. Learn more
NOTICE Sent to indicate the outcome of an action like banning a user.
PRIVMSG Sent when a user posts a message to the chat room.
ROOMSTATE Sent when the bot joins a channel or when the channel’s chat room settings change. Learn more
USERNOTICE Sent when events like someone subscribing to the channel occurs. Learn more
USERSTATE Sent when the bot joins a channel or sends a PRIVMSG message. Learn more
WHISPER Sent when someone sends your bot a whisper message. Learn more

CLEARCHAT tags

The Twitch IRC server sends this message after a bot or moderator removes all messages from the chat room or removes all messages for the specified user. Learn more

Prototype

@ban-duration=<duration>;room-id=<room-id>;target-user-id=<user-id>;tmi-sent-ts=<timestamp>

The following are the tags that the message may include.

Tag Description
ban-duration Optional. The message includes this tag if the user was put in a timeout. The tag contains the duration of the timeout, in seconds.
room-id The ID of the channel where the messages were removed from.
target-user-id Optional. The ID of the user that was banned or put in a timeout. The user was banned if the message doesn’t include the ban-duration tag.
tmi-sent-ts The UNIX timestamp.

Examples

The following example shows the message that the Twitch IRC server sent after dallas permanently banned ronni from the chat room and removed all of ronni’s messages.

@room-id=12345678;target-user-id=87654321;tmi-sent-ts=1642715756806 :tmi.twitch.tv CLEARCHAT #dallas :ronni

The following example shows the message that the Twitch IRC server sent after dallas removed all messages from the chat room.

@room-id=12345678;tmi-sent-ts=1642715695392 :tmi.twitch.tv CLEARCHAT #dallas

The following example shows the message that the Twitch IRC server sent after dallas put ronni in a timeout and removed all of ronni’s messages from the chat room.

@ban-duration=350;room-id=12345678;target-user-id=87654321;tmi-sent-ts=1642719320727 :tmi.twitch.tv CLEARCHAT #dallas :ronni

CLEARMSG tags

The Twitch IRC server sends this message after the bot removes a single message from the chat room. Learn more

Prototype

@login=<login>;room-id=<room-id>;target-msg-id=<target-msg-id>;tmi-sent-ts=<timestamp>

The following are the tags that the message may include.

Tag Description
login The name of the user who sent the message.
room-id Optional. The ID of the channel (chat room) where the message was removed from.
target-msg-id A UUID that identifies the message that was removed.
tmi-sent-ts The UNIX timestamp.

Example

The following example shows the message that the Twitch IRC server sent after the moderator deleted ronni’s HeyGuys message from the dallas chat room.

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

GLOBALUSERSTATE tags

The Twitch IRC server sends this message after the bot authenticates with the server. Learn more

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>

The following are the tags that the message may include.

Tag Description
badge-info Contains metadata related to the chat badges in the badges tag.

Currently, this tag contains metadata only for subscriber badges, to indicate the number of months the user has been a subscriber.
badges Comma-separated list of chat badges in the form, <badge>/<version>. For example, admin/1. There are many possible badge values, but here are few:
  • admin
  • bits
  • broadcaster
  • moderator
  • subscriber
  • staff
  • turbo
Most badges have only 1 version, but some badges like subscriber badges offer different versions of the badge depending on how long the user has subscribed.

To get the badge, use the Get Global Chat Badges and Get Channel Chat Badges APIs. Match the badge to the set-id field’s value in the response. Then, match the version to the id field in the list of versions.
color The color of the user’s name in the chat room. This is a hexadecimal RGB color code in the form, #<RGB>. This tag may be empty if it is never set.
display-name The user’s display name, escaped as described in the IRCv3 spec. This tag may be empty if it is never set.
emote-sets A comma-delimited list of IDs that identify the emote sets that the user has access to. Is always set to at least zero (0). To access the emotes in the set, use the Get Emote Sets API.
turbo A Boolean value that indicates whether the user has site-wide commercial free mode enabled. Is true (1) if enabled; otherwise, false (0).
user-id The user’s ID.
user-type The type of user. Possible values are:
  • "" — A normal user
  • admin — A Twitch administrator
  • global_mod — A global moderator
  • staff — A Twitch employee

Example

The following example shows the message that the Twitch IRC server sent after a user authenticated with the Twitch IRC server. The message shows the 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=12345678;user-type=admin :tmi.twitch.tv GLOBALUSERSTATE

NOTICE tags

The Twitch IRC server sends this message to indicate the outcome of the action.

Prototype

@msg-id=<msg-id>;target-user-id=<user-id>

The following are the tags that the message may include.

Tag Description
msg-id An ID that you can use to programmatically determine the action’s outcome. For a list of possible IDs, see NOTICE Message IDs.
target-user-id The ID of the user that the action targeted.

Example

The following example shows the message that the Twitch IRC server sent after the moderator deleted a message from the chat room. The msg-id tag is set to delete_message_success, which indicates that the user’s message was successfully deleted.

@msg-id=delete_message_success :tmi.twitch.tv NOTICE #bar :The message from foo is now deleted.

The following example shows the message that the Twitch IRC server sent after the user was unable to send a Whisper message. The msg-id tag is set to whisper_restricted, which indicates that the user can’t send whisper messages. You can use the ID in target-user-id along with the Get Users API to get the name of the user the whisper was intended for.

@msg-id=whisper_restricted;target-user-id=12345678 :tmi.twitch.tv NOTICE #bar :Your settings prevent you from sending this whisper.

PRIVMSG tags

The Twitch IRC server sends this message after a user posts a message to the chat room.

Tags provided by the server

Prototype

@badge-info=<badge-info>;badges=<badges>;bits=<bits>client-nonce=<nonce>;color=<color>;display-name=<display-name>;emotes=<emotes>;first-msg=<first-msg>;flags=<flags>;id=<msg-id>;mod=<mod>;room-id=<room-id>;subscriber=<subscriber>;tmi-sent-ts=<timestamp>;turbo=<turbo>;user-id=<user-id>;user-type=<user-type>;reply-parent-msg-id=<reply-parent-msg-id>;reply-parent-user-id=<reply-parent-user-id>;reply-parent-user-login=<reply-parent-user-login>;reply-parent-display-name=<reply-parent-display-name>;reply-parent-msg-body=<reply-parent-msg-body>;reply-thread-parent-msg-id=<reply-thread-parent-msg-id>;reply-thread-parent-user-login=<reply-thread-parent-user-login>;vip=<vip>

The following are the tags that the message may include.

Tag Description
badge-info Contains metadata related to the chat badges in the badges tag.

Currently, this tag contains metadata only for subscriber badges, to indicate the number of months the user has been a subscriber.
badges Comma-separated list of chat badges in the form, <badge>/<version>. For example, admin/1. There are many possible badge values, but here are few:
  • admin
  • bits
  • broadcaster
  • moderator
  • subscriber
  • staff
  • turbo
Most badges have only 1 version, but some badges like subscriber badges offer different versions of the badge depending on how long the user has subscribed.

To get the badge, use the Get Global Chat Badges and Get Channel Chat Badges APIs. Match the badge to the set-id field’s value in the response. Then, match the version to the id field in the list of versions.
bits The amount of Bits the user cheered. Only a Bits cheer message includes this tag. To learn more about Bits, see the Extensions Monetization Guide. To get the cheermote, use the Get Cheermotes API. Match the cheer amount to the id field’s value in the response. Then, get the cheermote’s URL based on the cheermote theme, type, and size you want to use.
color The color of the user’s name in the chat room. This is a hexadecimal RGB color code in the form, #<RGB>. This tag may be empty if it is never set.
display-name The user’s display name, escaped as described in the IRCv3 spec. This tag may be empty if it is never set.
emotes A comma-delimited list of emotes and their positions in the message. Each emote is in the form, <emote ID>:<start position>-<end position>. The position indices are zero-based.

To get the actual emote, see the Get Channel Emotes and Get Global Emotes APIs. For information about how to use the information that the APIs return, see Twitch emotes.

NOTE It’s possible for the emotes flag’s value to be set to an action instead of identifying an emote. For example, \001ACTION barfs on the floor.\001.
id An ID that uniquely identifies the message.
mod A Boolean value that determines whether the user is a moderator. Is true (1) if the user is a moderator; otherwise, false (0).
pinned-chat-paid-amount The value of the Hype Chat sent by the user.
pinned-chat-paid-currency The ISO 4217 alphabetic currency code the user has sent the Hype Chat in.
pinned-chat-paid-exponent Indicates how many decimal points this currency represents partial amounts in. Decimal points start from the right side of the value defined in pinned-chat-paid-amount.
pinned-chat-paid-level The level of the Hype Chat, in English. Possible values are:
  • ONE
  • TWO
  • THREE
  • FOUR
  • FIVE
  • SIX
  • SEVEN
  • EIGHT
  • NINE
  • TEN
pinned-chat-paid-is-system-message A Boolean value that determines if the message sent with the Hype Chat was filled in by the system.
If true (1), the user entered no message and the body message was automatically filled in by the system.
If false (0), the user provided their own message to send with the Hype Chat.
reply-parent-msg-id An ID that uniquely identifies the direct parent message that this message is replying to. The message does not include this tag if this message is not a reply.
reply-parent-user-id An ID that identifies the sender of the direct parent message. The message does not include this tag if this message is not a reply.
reply-parent-user-login The login name of the sender of the direct parent message. The message does not include this tag if this message is not a reply.
reply-parent-display-name The display name of the sender of the direct parent message. The message does not include this tag if this message is not a reply.
reply-parent-msg-body The text of the direct parent message. The message does not include this tag if this message is not a reply.
reply-thread-parent-msg-id An ID that uniquely identifies the top-level parent message of the reply thread that this message is replying to. The message does not include this tag if this message is not a reply.
reply-thread-parent-user-login The login name of the sender of the top-level parent message. The message does not include this tag if this message is not a reply.
room-id An ID that identifies the chat room (channel).
subscriber A Boolean value that determines whether the user is a subscriber. Is true (1) if the user is a subscriber; otherwise, false (0).
tmi-sent-ts The UNIX timestamp.
turbo A Boolean value that indicates whether the user has site-wide commercial free mode enabled. Is true (1) if enabled; otherwise, false (0).
user-id The user’s ID.
user-type The type of user. Possible values are:
  • "" — A normal user
  • admin — A Twitch administrator
  • global_mod — A global moderator
  • staff — A Twitch employee
vip A Boolean value that determines whether the user that sent the chat is a VIP. The message includes this tag if the user is a VIP; otherwise, the message doesn’t include this tag (check for the presence of the tag instead of whether the tag is set to true or false).

Examples

The following example shows the message that the Twitch IRC server sent after ronni posted a message in the chat room.

@badge-info=;badges=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

The following example shows the message that the Twitch IRC server sent after ronni cheered 100 Bits.

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

If ronni had cheered, Cheer1 Cheer1, the bits tag would be set to 2.

The following example shows that a VIP sent the message (see the vip tag).

@badge-info=;badges=vip/1,partner/1;client-nonce=cd15335a5e2059c3b087e22612de485e;color=;display-name=fun2bfun;emotes=;first-msg=0;flags=;id=1fd20412-965f-4c96-beb3-52266448f564;mod=0;returning-chatter=0;room-id=102336968;subscriber=0;tmi-sent-ts=1661372052425;turbo=0;user-id=12345678;user-type=;vip=1

If ronni sent a Hype Chat, pinned-chat-paid-* tags would be set to reflect that.

The following example shows the message that the Twitch IRC server sent after a user sent a Hype Chat of $2 USD

@badge-info=;badges=glhf-pledge/1;color=;emotes=;first-msg=0;flags=;id=f6fb34f8-562f-4b4d-b628-32113d0ef4b0;mod=0;pinned-chat-paid-amount=200;pinned-chat-paid-canonical-amount=200;pinned-chat-paid-currency=USD;pinned-chat-paid-exponent=2;pinned-chat-paid-is-system-message=0;pinned-chat-paid-level=ONE;returning-chatter=0;room-id=12345678;subscriber=0;tmi-sent-ts=1687471984306;turbo=0;user-id=12345678;user-type=

Any currency that is used will carry information in tags that will indicate the ISO 4217 currency code, and the currency’s exponent. In the case of the United States dollar, $2 USD will be represented as 200 in pinned-chat-paid-amount with the pinned-chat-paid-exponent of 2. This indicates the decimal place is 2 decimals from the right.

In the case of South Korean won, ₩1500 KRW will be represented with the pinned-chat-paid-exponent of 0, indicating the decimal does not need to be moved. The following example shows the message that the Twitch IRC server sent after a user sent a Hype Chat of ₩1500 KRW

@badge-info=;badges=partner/1;color=;emotes=;first-msg=0;flags=;id=bf4a779b-e26f-4688-8dcc-c41f221d8bbe;mod=0;pinned-chat-paid-amount=1500;pinned-chat-paid-canonical-amount=1500;pinned-chat-paid-currency=KRW;pinned-chat-paid-exponent=0;pinned-chat-paid-is-system-message=0;pinned-chat-paid-level=ONE;returning-chatter=0;room-id=12345678;subscriber=0;tmi-sent-ts=1687474201232;turbo=0;user-id=12345678;user-type=

Tags a client may include

A client may send a PRIVMSG message to the Twitch IRC server with the following tags.

Tag Description
reply-parent-msg-id An ID that uniquely identifies the parent message that this message is replying to.

Examples

The following example shows a PRIVMSG message that the client sent in reply to another message.

@reply-parent-msg-id=b34ccfc7-4977-403a-8a94-33c6bac34fb8 PRIVMSG #ronni :Good idea!

ROOMSTATE tags

The Twitch IRC server sends this message after a bot joins a channel or when the channel’s chat room settings change. Learn more

For JOIN messages, the message contains all chat room setting tags, but for actions that change a single chat room setting, the message includes only that chat room setting tag. For example, if the moderator turned on unique chat, the message includes only the r9k tag.

Prototype

@emote-only=<emote-only>;followers-only=<followers-only>;r9k=<r9k>;rituals=<rituals>;room-id=<room-id>;slow=<slow>;subs-only=<subs-only>

The following are the tags that the message may include.

Tag Description
emote-only A Boolean value that determines whether the chat room allows only messages with emotes. Is true (1) if only emotes are allowed; otherwise, false (0).
followers-only An integer value that determines whether only followers can post messages in the chat room. The value indicates how long, in minutes, the user must have followed the broadcaster before posting chat messages. If the value is -1, the chat room is not restricted to followers only.
r9k A Boolean value that determines whether a user’s messages must be unique. Applies only to messages with more than 9 characters. Is true (1) if users must post unique messages; otherwise, false (0).
room-id An ID that identifies the chat room (channel).
slow An integer value that determines how long, in seconds, users must wait between sending messages.
subs-only A Boolean value that determines whether only subscribers and moderators can chat in the chat room. Is true (1) if only subscribers and moderators can chat; otherwise, false (0).

Examples

The following example shows the message that the Twitch IRC server sent after a user joined the dallas chat room. The message shows the chat room’s settings.

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

The following example shows the message that the Twitch IRC server sent after the moderator turned on slow mode requiring users to wait 10 seconds between sending messages.

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

USERNOTICE tags

The Twitch IRC server sends this message after the following events occur:

Learn more

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>

The following are the tags that the message may include.

Tag Description
badge-info Contains metadata related to the chat badges in the badges tag.

Currently, this tag contains metadata only for subscriber badges, to indicate the number of months the user has been a subscriber.
badges Comma-separated list of chat badges in the form, <badge>/<version>. For example, admin/1. There are many possible badge values, but here are few:
  • admin
  • bits
  • broadcaster
  • moderator
  • subscriber
  • staff
  • turbo
Most badges have only 1 version, but some badges like subscriber badges offer different versions of the badge depending on how long the user has subscribed.

To get the badge, use the Get Global Chat Badges and Get Channel Chat Badges APIs. Match the badge to the set-id field’s value in the response. Then, match the version to the id field in the list of versions.
color The color of the user’s name in the chat room. This is a hexadecimal RGB color code in the form, #<RGB>. This tag may be empty if it is never set.
display-name The user’s display name, escaped as described in the IRCv3 spec. This tag may be empty if it is never set.
emotes A comma-delimited list of emotes and their positions in the message. Each emote is in the form, <emote ID>:<start position>-<end position>. The position indices are zero-based.

To get the actual emote, see the Get Channel Emotes and Get Global Emotes APIs. For information about how to use the information that the APIs return, see Twitch emotes.

NOTE It’s possible for the emotes flag’s value to be set to an action instead of identifying an emote. For example, \001ACTION barfs on the floor.\001.
id An ID that uniquely identifies this message.
login The login name of the user whose action generated the message.
mod A Boolean value that determines whether the user is a moderator. Is true (1) if the user is a moderator; otherwise, false (0).
msg-id The type of notice (not the ID). Possible values are:
  • sub
  • resub
  • subgift
  • submysterygift
  • giftpaidupgrade
  • rewardgift
  • anongiftpaidupgrade
  • raid
  • unraid
  • ritual
  • bitsbadgetier
room-id An ID that identifies the chat room (channel).
subscriber A Boolean value that determines whether the user is a subscriber. Is true (1) if the user is a subscriber; otherwise, false (0).
system-msg The message Twitch shows in the chat room for this notice.
tmi-sent-ts The UNIX timestamp for when the Twitch IRC server received the message.
turbo A Boolean value that indicates whether the user has site-wide commercial free mode enabled. Is true (1) if enabled; otherwise, false (0).
user-id The user’s ID.
user-type The type of user sending the whisper message. Possible values are:
  • "" — A normal user
  • admin — A Twitch administrator
  • global_mod — A global moderator
  • staff — A Twitch employee

Only subscription- and raid-related notices include the following tags:

Tag Description
msg-param-cumulative-months Included only with sub and resub notices.

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 Included only with raid notices.

The display name of the broadcaster raiding this channel.
msg-param-login Included only with raid notices.

The login name of the broadcaster raiding this channel.
msg-param-months Included only with subgift notices.

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 Included only with anongiftpaidupgrade and giftpaidupgrade notices.

The number of gifts the gifter has given during the promo indicated by msg-param-promo-name.
msg-param-promo-name Included only with anongiftpaidupgrade and giftpaidupgrade notices.

The subscriptions promo, if any, that is ongoing (for example, Subtember 2018).
msg-param-recipient-display-name Included only with subgift notices.

The display name of the subscription gift recipient.
msg-param-recipient-id Included only with subgift notices.

The user ID of the subscription gift recipient.
msg-param-recipient-user-name Included only with subgift notices.

The user name of the subscription gift recipient.
msg-param-sender-login Included only with giftpaidupgrade notices.

The login name of the user who gifted the subscription.
msg-param-sender-name Include only with giftpaidupgrade notices.

The display name of the user who gifted the subscription.
msg-param-should-share-streak Included only with sub and resub notices.

A Boolean value that indicates whether the user wants their streaks shared.
msg-param-streak-months Included only with sub and resub notices.

The number of consecutive months the user has subscribed. This is zero (0) if msg-param-should-share-streak is 0.
msg-param-sub-plan Included only with sub, resub and subgift notices.

The type of subscription plan being used. Possible values are:
  • Prime — Amazon Prime subscription
  • 1000 — First level of paid subscription
  • 2000 — Second level of paid subscription
  • 3000 — Third level of paid subscription
msg-param-sub-plan-name Included only with sub, resub, and subgift notices.

The display name of the subscription plan. This may be a default name or one created by the channel owner.
msg-param-viewerCount Included only with raid notices.

The number of viewers raiding this channel from the broadcaster’s channel.
msg-param-ritual-name Included only with ritual notices.

The name of the ritual being celebrated. Possible values are: new_chatter.
msg-param-threshold Included only with bitsbadgetier notices.

The tier of the Bits badge the user just earned. For example, 100, 1000, or 10000.
msg-param-gift-months Included only with subgift notices.

The number of months gifted as part of a single, multi-month gift.

Examples

The following example shows the message that the Twitch IRC server sent after 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=12345678;subscriber=1;system-msg=ronni\shas\ssubscribed\sfor\s6\smonths!;tmi-sent-ts=1507246572675;turbo=1;user-id=87654321;user-type=staff :tmi.twitch.tv USERNOTICE #dallas :Great stream -- keep it up!

The following example shows the message that the Twitch IRC server sent after 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=55554444;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=87654321;user-type=staff :tmi.twitch.tv USERNOTICE #forstycup

The following example shows the message that the Twitch IRC server sent after a broadcaster raided the channel.

@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=33332222;subscriber=0;system-msg=15\sraiders\sfrom\sTestChannel\shave\sjoined\n!;tmi-sent-ts=1507246572675;turbo=1;user-id=123456;user-type= :tmi.twitch.tv USERNOTICE #othertestchannel

The following example shows the message that the Twitch IRC server 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=87654321;subscriber=0;system-msg=Seventoes\sis\snew\shere!;tmi-sent-ts=1508363903826;turbo=0;user-id=77776666;user-type= :tmi.twitch.tv USERNOTICE #seventoes :HeyGuys

USERSTATE tags

The Twitch IRC server sends this message after the bot joins a channel or sends a PRIVMSG message. Learn more

Prototype

@badge-info=<badge-info>;badges=<badges>;color=<color>;display-name=<display-name>;emote-sets=<emote-sets>;id=<id>;mod=<mod>;subscriber=<subscriber>;turbo=<turbo>;user-type=<user-type>

The following are the tags that the message may include.

Tag Description
badge-info Contains metadata related to the chat badges in the badges tag.

Currently, this tag contains metadata only for subscriber badges, to indicate the number of months the user has been a subscriber.
badges Comma-separated list of chat badges in the form, <badge>/<version>. For example, admin/1. There are many possible badge values, but here are few:
  • admin
  • bits
  • broadcaster
  • moderator
  • subscriber
  • staff
  • turbo
Most badges have only 1 version, but some badges like subscriber badges offer different versions of the badge depending on how long the user has subscribed.

To get the badge, use the Get Global Chat Badges and Get Channel Chat Badges APIs. Match the badge to the set-id field’s value in the response. Then, match the version to the id field in the list of versions.
color The color of the user’s name in the chat room. This is a hexadecimal RGB color code in the form, #<RGB>. This tag may be empty if it is never set.
display-name The user’s display name, escaped as described in the IRCv3 spec. This tag may be empty if it is never set.
emote-sets A comma-delimited list of IDs that identify the emote sets that the user has access to. Is always set to at least zero (0). To access the emotes in the set, use the Get Emote Sets API.
id If a privmsg was sent, an ID that uniquely identifies the message.
mod A Boolean value that determines whether the user is a moderator. Is true (1) if the user is a moderator; otherwise, false (0).
subscriber A Boolean value that determines whether the user is a subscriber. Is true (1) if the user is a subscriber; otherwise, false (0).
turbo A Boolean value that indicates whether the user has site-wide commercial free mode enabled. Is true (1) if enabled; otherwise, false (0).
user-type The type of user sending the whisper message. Possible values are:
  • "" — A normal user
  • admin — A Twitch administrator
  • global_mod — A global moderator
  • staff — A Twitch employee

Examples

The following example shows the message that the Twitch IRC server sent after ronni joined 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

WHISPER tags

The Twitch IRC server sends this message after someone sends your bot a whisper message. Learn more

Prototype

@badges=<badges>;color=<color>;display-name=<display-name>;emotes=<emotes>;message-id=<msg-id>;thread-id=<thread-id>;turbo=<turbo>;user-id=<user-id>;user-type=<user-type>

The following are the tags that the message may include.

Tag Description
badges Comma-separated list of chat badges in the form, <badge>/<version>. For example, admin/1. There are many possible badge values, but here are few:
  • admin
  • bits
  • broadcaster
  • moderator
  • subscriber
  • staff
  • turbo
Most badges have only 1 version, but some badges like subscriber badges offer different versions of the badge depending on how long the user has subscribed.

To get the badge, use the Get Global Chat Badges and Get Channel Chat Badges APIs. Match the badge to the set-id field’s value in the response. Then, match the version to the id field in the list of versions.
color The color of the user’s name in the chat room. This is a hexadecimal RGB color code in the form, #<RGB>. This tag may be empty if it is never set.
display-name The display name of the user sending the whisper message, escaped as described in the IRCv3 spec. This tag may be empty if it is never set.
emotes A comma-delimited list of emotes and their positions in the message. Each emote is in the form, <emote ID>:<start position>-<end position>. The position indices are zero-based.

To get the actual emote, see the Get Channel Emotes and Get Global Emotes APIs. For information about how to use the information that the APIs return, see Twitch emotes.

NOTE It’s possible for the emotes flag’s value to be set to an action instead of identifying an emote. For example, \001ACTION barfs on the floor.\001.
message-id An ID that uniquely identifies the whisper message.
thread-id An ID that uniquely identifies the whisper thread. The ID is in the form, <smaller-value-user-id>_<larger-value-user-id>.
turbo A Boolean value that indicates whether the user has site-wide commercial free mode enabled. Is true (1) if enabled; otherwise, false (0).
user-id The ID of the user sending the whisper message.
user-type The type of user sending the whisper message. Possible values are:
  • "" — A normal user
  • admin — A Twitch administrator
  • global_mod — A global moderator
  • staff — A Twitch employee

Examples

The following example shows the message that the Twitch IRC server sent after foofoo sent a hello whisper message to petgomoo (your bot).

@badges=staff/1,bits-charity/1;color=#8A2BE2;display-name=PetsgomOO;emotes=;message-id=306;thread-id=12345678_87654321;turbo=0;user-id=87654321;user-type=staff :petsgomoo!petsgomoo@petsgomoo.tmi.twitch.tv WHISPER foo :hello