Twitch-specific IRC Commands
The Twitch IRC server sends your bot the following commands only if your bot requests the commands capability. For information about requesting the commands capability, see Requesting Twitch-specific capabilities. Because the messages for these commands include minimum information, you should also request the tags capability to get a richer set of information.
| Message | Description |
|---|---|
| CLEARCHAT | Sent when the bot or moderator removes all messages from the chat room or removes all messages for the specified user. |
| CLEARMSG | Sent when the bot removes a single message from the chat room. |
| GLOBALUSERSTATE | Sent after the bot authenticates with the server. |
| HOSTTARGET | Sent when a channel starts or stops hosting viewers from another channel. |
| NOTICE | Sent to indicate the outcome of an action like banning a user. |
| RECONNECT | Sent when the Twitch IRC server needs to terminate the connection. |
| ROOMSTATE | Sent when the bot joins a channel or when the channel’s chat settings change. |
| USERNOTICE | Sent when events like someone subscribing to the channel occurs. |
| USERSTATE | Sent when the bot joins a channel or sends a PRIVMSG message. |
| WHISPER | Sent when a user sends a WHISPER message. |
CLEARCHAT
Sent when a moderator (or bot with moderator privileges) removes all messages from the chat room or removes all messages for the specified user.
The Twitch IRC server sends this message when:
- A moderator enters the /clear command in the chat room or a bot sends the /clear chat command message .
- A moderator enters the /ban or /timeout command in the chat room or a bot sends the /ban or /timeout chat command message.
Prototype
:tmi.twitch.tv CLEARCHAT #<channel> :<user>
| Parameter | Description |
|---|---|
| channel | The name of the channel (chat room) where the messages were removed from. |
| user | The login name of the user whose messages were removed from the chat room because they were banned or put in a timeout. |
Examples
The following message indicates that all chat messages were removed from the dallas chat room.
:tmi.twitch.tv CLEARCHAT #dallas
The following message indicates that all chat messages that ronni posted in the dallas chat room were removed.
:tmi.twitch.tv CLEARCHAT #dallas :ronni
Adding tags to the CLEARCHAT message
To include additional information with the CLEARCHAT message, request the tags capability (see Requesting Twitch-specific capabilities). For details about the tags that the CLEARCHAT message can include, see Twitch IRC tags.
The following example shows a CLEARCHAT message with tags.
@room-id=12345678;target-user-id=87654321;tmi-sent-ts=1642715756806 :tmi.twitch.tv CLEARCHAT #dallas :ronni
CLEARMSG
Sent when a bot with moderator privileges deletes a single message from the chat room.
The Twitch IRC server sends this message when:
- The bot sends a /delete chat command message.
Prototype
:tmi.twitch.tv CLEARMSG #<channel> :<message>
| Parameter | Description |
|---|---|
| channel | The name of the channel (chat room) where the message was removed from. |
| message | The chat message that was removed. |
Example
The following message indicates that the specified chat message was removed from the dallas channel.
:tmi.twitch.tv CLEARMSG #dallas :HeyGuys
Adding tags to the CLEARMSG message
To include additional information with the CLEARMSG message, request the tags capability (see Requesting Twitch-specific capabilities). For details about the tags that the CLEARMSG message can include, see Twitch IRC tags.
The following example shows a CLEARMSG message with tags.
@login=foo;room-id=;target-msg-id=94e6c7ff-bf98-4faa-af5d-7ad633a158a9;tmi-sent-ts=1642720582342 :tmi.twitch.tv CLEARMSG #bar :what a great day
GLOBALUSERSTATE
Sent after the bot successfully authenticates (by sending the PASS/NICK commands) with the server.
Prototype
:tmi.twitch.tv GLOBALUSERSTATE
Example
:tmi.twitch.tv GLOBALUSERSTATE
Adding tags to the GLOBALUSERSTATE message
As you can see from the example, the GLOBALUSERSTATE message on its own is not very useful. To include useful information with the GLOBALUSERSTATE message, request the tags capability (see Requesting Twitch-specific capabilities). For details about the tags that the GLOBALUSERSTATE message can include, see Twitch IRC tags.
The following example shows a GLOBALUSERSTATE message with tags after dallas logged 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
HOSTTARGET
Sent when a channel starts or stops hosting viewers from another channel.
The Twitch IRC server sends this message when:
- A moderator enters the /host or /unhost command in the chat room or a bot with moderator privileges sends a /host or /unhost chat command message.
Prototype
:tmi.twitch.tv HOSTTARGET #<hosting-channel> :[-|<channel>] <number-of-viewers>
| Parameter | Description |
|---|---|
| - | The channel is no longer hosting viewers. |
| channel | The channel being hosted. |
| hosting-channel | The channel that’s hosting the viewers. |
| number-of-viewers | The number of viewers from <channel> that are watching the broadcast. |
Examples
The following message indicates that channel abc is hosting channel xyz who has 10 viewers watching its broadcast.
:tmi.twitch.tv HOSTTARGET #abc :xyz 10
The following message indicates that channel abc is no longer hosting another channel.
:tmi.twitch.tv HOSTTARGET #abc :- 10
Adding tags to the HOSTTARGET message
There are no tags available for the HOSTTARGET message.
NOTICE
Sent to indicate the outcome of an action like banning a user.
The Twitch IRC server sends this message when:
- A moderator (or bot with moderator privileges) sends a message with pretty much any of the chat commands. For example, /emoteonly, /subscribers, /ban or /host.
Prototype
:tmi.twitch.tv NOTICE #<channel> :<message>
| Parameter | Description |
|---|---|
| channel | The channel (chat room) where the action occurred. |
| message | A message that describes the outcome of the action. |
Examples
The following example shows that Twitch removed a message that foo posted to the bar chat room.
:tmi.twitch.tv NOTICE #bar :The message from foo is now deleted.
The following example shows that foo was banned from the bar chatroom.
:tmi.twitch.tv NOTICE #bar :foo is now banned from this channel.
Adding tags to the NOTICE message
To include additional information with the NOTICE message, request the tags capability (see Requesting Twitch-specific capabilities). For details about the tags that the NOTICE message can include, see Twitch IRC tags.
The following example shows a NOTICE message with tags after Twitch removed a message that foo posted to the bar chat room. You can use the ID in the msg-id tag to determine the action’s outcome.
@msg-id=delete_message_success :tmi.twitch.tv NOTICE #bar :The message from foo is now deleted.
RECONNECT
Sent when the Twitch IRC server needs to terminate the connection for maintenance reasons. This gives your bot a chance to perform minimal clean up and save state before the server terminates the connection. The amount of time between receiving the message and the server closing the connection is indeterminate.
The normal course of action is to reconnect to the Twitch IRC server and rejoin the channels you were previously joined to prior to the server terminating the connection.
Prototype
:tmi.twitch.tv RECONNECT
Adding tags to the RECONNECT message
There are no tags available for the RECONNECT message.
ROOMSTATE
Sent when the bot joins a channel or when the channel’s chat settings change.
The Twitch IRC server sends this message when:
- The bot joins a channel
- A moderator (or bot with moderator privileges) sends a message with one of the following chat command messages:
- /emoteonly(off)
- /followers(off)
- /slow(off)
- /subscribers(off)
- /uniquechat(off)
Prototype
:tmi.twitch.tv ROOMSTATE #<channel>
| Parameter | Description |
|---|---|
| channel | The name of the channel (chat room) that the room state information applies to. |
Example
:tmi.twitch.tv ROOMSTATE #bar
Adding tags to the ROOMSTATE message
To include additional information with the ROOMSTATE message, request the tags capability (see Requesting Twitch-specific capabilities). For details about the tags that the ROOMSTATE message can include, see Twitch IRC tags.
The following example shows a ROOMSTATE message with tags after joining a channel.
@emote-only=0;followers-only=-1;r9k=0;rituals=0;room-id=12345678;slow=0;subs-only=0 :tmi.twitch.tv ROOMSTATE #bar
The following example shows a ROOMSTATE message with tags after turning on the unique-chat chat setting.
@r9k=1;room-id=713936733 :tmi.twitch.tv ROOMSTATE #bar
USERNOTICE
Sent when events like someone subscribing to the channel occurs.
The Twitch IRC server sends this message when:
- A user subscribes to the channel, re-subscribes to the channel, or gifts a subscription to another user.
- Another broadcaster raids the channel. Raid is a Twitch feature that lets broadcasters send their viewers to another channel to help support and grow other members in the community. Learn more
- A viewer milestone is celebrated such as a new viewer chatting for the first time.
Prototype
:tmi.twitch.tv USERNOTICE #<channel> :[<message>]
| Parameter | Description |
|---|---|
| channel | The name of the channel that the event occurred in. |
| message | Optional. The chat message that describes the event. |
Examples
The following example shows the USERNOTICE sent after ronni resubscribed to the dallas channel.
:tmi.twitch.tv USERNOTICE #dallas :Great stream -- keep it up!
The following example shows the USERNOTICE sent after tww2 gifts a subscription to Mr_Woodchuck in forstycup’s channel.
:tmi.twitch.tv USERNOTICE #forstycup
Adding tags to the USERNOTICE message
As you can see from the examples, the USERNOTICE message on its own is not very useful. To include useful information with the USERNOTICE message, request the tags capability (see Requesting Twitch-specific capabilities). For details about the tags that the USERNOTICE message can include, see Twitch IRC tags.
The following example shows a USERNOTICE message with tags 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 a USERNOTICE message with tags after tww2 gifts 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=12345678;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
USERSTATE
Sent when the bot joins a channel or sends a PRIVMSG message.
Prototype
:tmi.twitch.tv USERSTATE #<channel>
| Parameter | Description |
|---|---|
| channel | The name of the channel that the bot joined or sent a PRIVMSG in. |
Example
:tmi.twitch.tv USERSTATE #dallas
Adding tags to the USERSTATE message
As you can see from the example, the USERSTATE message on its own is not very useful. To include useful information with the USERSTATE message, request the tags capability (see Requesting Twitch-specific capabilities). For details about the tags that the USERSTATE message can include, see Twitch IRC tags.
The following example shows a USERSTATE message with tags after 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
WHISPER
Sent when a WHISPER message is directed specifically to your bot. Your bot will never receive whispers sent to other users.
Prototype
:<to-user>!<to-user>@<to-user>.tmi.twitch.tv WHISPER <from-user> :<message>
| Parameter | Description |
|---|---|
| from-user | The user that’s sending the whisper message. |
| to-user | The user that’s receiving the whisper message. |
Example
The following example shows that the user foo sent a hello whisper message to the bot petsgomoo.
:petsgomoo!petsgomoo@petsgomoo.tmi.twitch.tv WHISPER foo :hello
Adding tags to the WHISPER message
To include other useful information with the WHISPER message, request the tags capability (see Requesting Twitch-specific capabilities). For details about the tags that the WHISPER message can include, see Twitch IRC tags.
The following example shows the same WHISPER message shown above but with tags.
@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