Twitch offers an IRC interface to its chat. This allows for people to do things like develop bots for their channel, or to connect to a channel’s chat with an IRC client instead of using the web interface. While our IRC server is built to follow RFC1459, it is important to note that there are several cases where it will behave slightly differently than another IRC server would. These cases are noted when necessary in the following document.
Such differences in behavior are necessary both to accommodate the massive scale at which our chat servers must operate, as well as the complex Twitch-specific features that we provide our users.
Lines prefixed with < are sent from client to server, and lines prefixed with > are sent from the server to the connecting client.
You can connect to Twitch IRC using the following bits of information:
irc.chat.twitch.tvon port 443
A successful connection session will look something like this:
1 2 3 4 5 6 7 8 9
< PASS oauth:twitch_oauth_token < NICK twitch_username > :tmi.twitch.tv 001 twitch_username :Welcome, GLHF! > :tmi.twitch.tv 002 twitch_username :Your host is tmi.twitch.tv > :tmi.twitch.tv 003 twitch_username :This server is rather new > :tmi.twitch.tv 004 twitch_username :- > :tmi.twitch.tv 375 twitch_username :- > :tmi.twitch.tv 372 twitch_username :You are in a maze of twisty passages, all alike. > :tmi.twitch.tv 376 twitch_username :>
About once every five minutes, you will receive a
PING :tmi.twitch.tv from the server, in order to ensure that your connection to the server is not prematurely terminated, you should reply with
If your connection fails for any reason, you will be disconnected from the server. Some common reasons for being disconnected immediately include:
If you send an invalid command, you will receive a 421 numeric back:
< WHO #channel > :tmi.twitch.tv 421 twitch_username WHO :Unknown command
A brief list of commands supported by our IRC server include: ### JOIN: Opening up a chat room
- After a successful
JOIN, you will not receive a membership state events (
MODE) unless you’ve requested our IRCv3
- The channel name should be entered in lowercase.
- Attempting to join a suspended or deleted channel will result in a
- Attempting to join a non-existent channel will result in the JOIN being quietly dropped.
1 2 3 4
< JOIN #channel > :twitch_username!twitch_username@twitch_username.tmi.twitch.tv JOIN #channel > :twitch_username.tmi.twitch.tv 353 twitch_username = #channel :twitch_username > :twitch_username.tmi.twitch.tv 366 twitch_username #channel :End of /NAMES list
< PART #channel > :twitch_username!twitch_username@twitch_username.tmi.twitch.tv PART #channel
PRIVMSG #channel :Message to send
Basic message reception is as follows:
> :twitch_username!twitch_username@twitch_username.tmi.twitch.tv PRIVMSG #channel :message here
Using IRCv3 capability registration, it is possible to register for Twitch-specific capabilities. The capabilities are defined below:
< CAP REQ :twitch.tv/membership > :tmi.twitch.tv CAP * ACK :twitch.tv/membership
Adds membership state event (
MODE) functionality. By default we do not send this data to clients without this capability.
The list of current chatters in a channel:
1 2 3
> :twitch_username.tmi.twitch.tv 353 twitch_username = #channel :twitch_username user2 user3 > :twitch_username.tmi.twitch.tv 353 twitch_username = #channel :user5 user6 nicknameN > :twitch_username.tmi.twitch.tv 366 twitch_username #channel :End of /NAMES list
Someone joined a channel:
> :twitch_username!twitch_username@twitch_username.tmi.twitch.tv JOIN #channel
Someone left a channel:
> :twitch_username!twitch_username@twitch_username.tmi.twitch.tv PART #channel
Someone gained or lost operator:
> :jtv MODE #channel +o operator_user > :jtv MODE #channel -o operator_user
- If there are greater than 1000 chatters in a room, NAMES will only return the list of OPs currently in the room
- Due to caching, events are not sent immediately to a channel. They are instead batched up and sent every 10 seconds.
WHO is unsupported
- All elevated users are given OP. To determine a user’s actual elevation level, request the tags capability and parse the
< CAP REQ :twitch.tv/commands > :tmi.twitch.tv CAP * ACK :twitch.tv/commands
Enables custom raw commands detailed below.
General notices from the server - could be about state change (slowmode enabled), feedback (you have banned
> @msg-id=slow_off :tmi.twitch.tv NOTICE #channel :This room is no longer in slow mode.
|subs_on||This room is now in subscribers-only mode.|
|already_subs_on||This room is already in subscribers-only mode.|
|subs_off||This room is no longer in subscribers-only mode.|
|already_subs_off||This room is not in subscribers-only mode.|
|slow_on||This room is now in slow mode. You may send messages every
|slow_off||This room is no longer in slow mode.|
|r9k_on||This room is now in r9k mode.|
|already_r9k_on||This room is already in r9k mode.|
|r9k_off||This room is no longer in r9k mode.|
|already_r9k_off||This room is not in r9k mode.|
|bad_host_hosting||This channel is already hosting
|host_off||Exited host mode.|
|emote_only_on||This room is now in emote-only mode.|
|already_emote_only_on||This room is already in emote-only mode.|
|emote_only_off||This room is no longer in emote-only mode.|
|already_emote_only_off||This room is not in emote-only mode.|
|msg_channel_suspended||This channel has been suspended.|
Host starts message:
> :tmi.twitch.tv HOSTTARGET #hosting_channel :target_channel [number]
Host stops message:
> :tmi.twitch.tv HOSTTARGET #hosting_channel :- [number]
Number is assumed to be the number of viewers watching the host.
Username is timed out or banned on a channel. See CLEARCHAT tags below to differentiate.
> :tmi.twitch.tv CLEARCHAT #channel :twitch_username
Chat is cleared on channel:
> :tmi.twitch.tv CLEARCHAT #channel
Use with tags CAP. See USERSTATE tags below.
> :tmi.twitch.tv USERSTATE #channel
Twitch IRC processes ocasionally need to be restarted. When this happens, clients that have requested the IRCv3
twitch.tv/commands capability are issued a
RECONNECT. After a short period of time, the connection will be closed.
In this circumstance, please reconnect and rejoin channels that were on that connection as you would normally.
Use with tags CAP. See ROOMSTATE tags below.
> :tmi.twitch.tv ROOMSTATE #channel
USERNOTICE is a special notice from a user currently only used for re-subscription messages. See USERNOTICE tags below.
> :tmi.twitch.tv USERNOTICE #channel :message
< CAP REQ :twitch.tv/tags > :tmi.twitch.tv CAP * ACK :twitch.tv/tags
Adds IRC v3 message tags to
GLOBALUSERSTATE (if enabled with commands CAP)
> @badges=global_mod/1,turbo/1;color=#0D4200;display-name=TWITCH_UserNaME;emotes=25:0-4,12-16/1902:6-10;mod=0;room-id=1337;subscriber=0;turbo=1;user-id=1337;user-type=global_mod :twitch_username!twitch_username@twitch_username.tmi.twitch.tv PRIVMSG #channel :Kappa Keepo Kappa
> @badges=staff/1,bits/1000;bits=100;color=;display-name=TWITCH_UserNaME;emotes=;id=b34ccfc7-4977-403a-8a94-33c6bac34fb8;mod=0;room-id=1337;subscriber=0;turbo=1;user-id=1337;user-type=staff :twitch_username!twitch_username@twitch_username.tmi.twitch.tv PRIVMSG #channel :cheer100
badgesis a comma-separated list of chat badges, valid badges are
coloris a hexadecimal RGB color code
display-nameis the user’s display name, escaped as described in the IRCv3 spec.
emotescontains information to replace text in the message with the emote images and can be empty. The format is as follows:
emote_idis 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)
\001ACTIONdoes not count and indexing starts from the first character that is part of the user’s “actual message”. In the example 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.
idis a unique identifier for a message.
turboare either 0 or 1 depending on whether the user has mod, sub or turbo badge or not.
room-idis the ID of the channel.
user-idis the user’s ID.
user-typeis either empty,
bits, if present, means the user used this amount of cheer/bits. All instances of
/(^|\s)cheer\d+(\s|$)/should be replaced with the appropriate emote:
redfor >= 10000 bits,
bluefor >= 5000,
greenfor >= 1000,
purplefor >= 100, or otherwise
SIZEis a digit between 1 and 4.
USERSTATE is sent when joining a channel and every time you send a PRIVMSG to a channel. Example:
> @color=#0D4200;display-name=TWITCH_UserNaME;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 #channel
emote-setscontains your emote set, which you can use to request a subset of
GLOBALUSERSTATE is sent on successful login, if the capabilities have been acknowledged before then. Example:
> @color=#0D4200;display-name=TWITCH_UserNaME;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
ROOMSTATE is sent when joining a channel and every time one of the chat room settings, like slow mode, change. The message on join contains all room settings. Example:
> @broadcaster-lang=;r9k=0;slow=0;subs-only=0 :tmi.twitch.tv ROOMSTATE #channel
Changes only contain the relevant tag. Setting slow mode to 10 seconds for example:
> @slow=10 :tmi.twitch.tv ROOMSTATE #channel
broadcaster-langis the chat language when broadcaster language mode is enabled, and empty otherwise. A few examples would be
fifor Finnish and
es-MXfor Mexican variant of Spanish.
r9kis R9K mode. Messages with more than 9 characters must be unique.
subs-onlyis subscribers only mode. Only subscribers and moderators can chat.
slowdetermines how many seconds chatters without moderator privileges must wait between sending messages.
emote-onlyis emote-only mode. All non-moderator messages can only be emotes.
> @badges=staff/1,broadcaster/1,turbo/1;color=#008000;display-name=TWITCH_UserName;emotes=;mod=0;msg-id=resub;msg-param-months=6;room-id=1337;subscriber=1;system-msg=TWITCH_UserName\shas\ssubscribed\sfor\s6\smonths!;login=twitch_username;turbo=1;user-id=1337;user-type=staff :tmi.twitch.tv USERNOTICE #channel :Great stream -- keep it up!
Trailing part of the message will be entirely omitted, if the user did not enter a message:
> @badges=staff/1,broadcaster/1,turbo/1;color=#008000;display-name=TWITCH_UserName;emotes=;mod=0;msg-id=resub;msg-param-months=6;room-id=1337;subscriber=1;system-msg=TWITCH_UserName\shas\ssubscribed\sfor\s6\smonths!;login=twitch_username;turbo=1;user-id=1337;user-type=staff :tmi.twitch.tv USERNOTICE #channel
msg-idis the type of the notice. See above examples for valid types.
msg-param-monthsis the number of consecutive months the user has subscribed for in a resub notice.
system-msgis the message printed in chat along with this notice.
loginis the username of the user, who sent the notice.
@ban-duration=1;ban-reason=Follow\sthe\srules :tmi.twitch.tv CLEARCHAT #channel :target_username
@ban-reason=Follow\sthe\srules :tmi.twitch.tv CLEARCHAT #channel :target_username
ban-durationis the duration of the timeout in seconds. The tag is omitted on permanent bans.
ban-reasonis the reason the moderator gave for the timeout or ban.