IRC.md

Twitch IRC

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.

Connecting

You can connect to Twitch IRC using the following bits of information:

• The server name to connect to is: irc.chat.twitch.tv.
• The port to connect to is 6667
• SSL is supported on irc.chat.twitch.tv on port 443
• Your nickname must be your Twitch username in lowercase.
• Your password should be an OAuth token authorized through our API with the chat_login scope.
  • The token must have the prefix of oauth:. For example, if you have the token abcd, you send oauth:abcd.
  • You can quickly get a token for your account with this helpful page (thanks to Andrew Bashore!).

Upon a Successful Connection

A successful connection session will look something like this:

< 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 PONG :tmi.twitch.tv.

On an Unsuccessful Connection

If your connection fails for any reason, you will be disconnected from the server. Some common reasons for being disconnected immediately include:

• Connecting on the wrong port
• Connecting to the wrong server
• Using an incorrect username and/or password

Command & Message Limit

• If you send more than 20 commands or messages to the server within a 30 second period, you will be locked out for 2 hours automatically. These are not lifted so please be careful when working with IRC!
• This limit is elevated to 100 messages per 30 seconds for users that only send messages/commands to channels in which they have Moderator/Operator status.

Commands you can send

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

JOIN #channel

Note:

• After a successful JOIN, you will not receive a membership state events (NAMES, JOIN, PART, or MODE) unless you've requested our IRCv3 Membership capability.
• The channel name should be entered in lowercase.
• Attempting to join a suspended or deleted channel will result in a msg_channel_suspended NOTICE.
• Attempting to join a non-existent channel will result in the JOIN being quietly dropped.

< 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: Leaving a chat room

PART #channel

< PART #channel
> :twitch_username!twitch_username@twitch_username.tmi.twitch.tv PART #channel

PRIVMSG: Sending a message

PRIVMSG #channel :Message to send

Basic message reception is as follows:

> :twitch_username!twitch_username@twitch_username.tmi.twitch.tv PRIVMSG #channel :message here

Twitch Capabilities

Using IRCv3 capability registration, it is possible to register for Twitch-specific capabilities. The capabilities are defined below:

Membership

< CAP REQ :twitch.tv/membership
> :tmi.twitch.tv CAP * ACK :twitch.tv/membership

Adds membership state event (NAMES, JOIN, PART, or MODE) functionality. By default we do not send this data to clients without this capability.

NAMES

The list of current chatters in a channel:

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

JOIN

Someone joined a channel:

> :twitch_username!twitch_username@twitch_username.tmi.twitch.tv JOIN #channel

PART

Someone left a channel:

> :twitch_username!twitch_username@twitch_username.tmi.twitch.tv PART #channel

MODE

Someone gained or lost operator:

> :jtv MODE #channel +o operator_user
> :jtv MODE #channel -o operator_user

Notes:

• 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 user-type tag

Commands

< CAP REQ :twitch.tv/commands
> :tmi.twitch.tv CAP * ACK :twitch.tv/commands

Enables custom raw commands detailed below.

NOTICE

General notices from the server - could be about state change (slowmode enabled), feedback (you have banned from the channel), etc. Each NOTICE message includes a msg-id tag which can be used for i18ln.

> @msg-id=slow_off :tmi.twitch.tv NOTICE #channel :This room is no longer in slow mode.

msg-id	reponse
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_duration seconds.
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.
host_on	Now hosting target_channel.
bad_host_hosting	This channel is already hosting target_channel.
host_off	Exited host mode.
hosts_remaining	number host commands remaining this half hour.
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.
timeout_success	target_user has been timed out for ban_duration seconds.
ban_success	target_user is now banned from this room.
unban_success	target_user is no longer banned from this room.
bad_unban_no_ban	target_user is not banned from this room.
already_banned	target_user is already banned in this room.
unrecognized_cmd	Unrecognized command: command
cmds_available	Commands available to you in this room (use /help for details): command_list
usage_me	Usage: "/me " - Send an "emote" message in the third person.
usage_help	Usage: "/help" - Lists the commands available to you in this room.
usage_mods	Usage: "/mods" - Lists the moderators of this channel.
usage_color	Usage: "/color " - Change your username color. Color must be in hex (#000000) or one of the following: Blue, BlueViolet, CadetBlue, Chocolate, Coral, DodgerBlue, Firebrick, GoldenRod, Green, HotPink, OrangeRed, Red, SeaGreen, SpringGreen, YellowGreen.
usage_ban	Usage: "/ban " - Permanently prevent a user from chatting. Use "unban" to remove a ban.
usage_unban	Usage: "/unban " - Removes a ban on a user.
usage_clear	Usage: "/clear" - Clear chat history for all users in this room.
usage_timeout	Usage: "/timeout [duration]" - Temporarily prevent a user from chatting. Duration (optional, default=600, max=1209600) must be a positive number of seconds. Use "unban" to remove a timeout.
usage_subscribers	Usage: "/subscribers" - Enables subscribers-only mode (only subscribers may chat in this channel). Use "subscribersoff" to disable.
usage_subscribersoff	Usage: "/subscribersoff" - Disables subscribers-only mode.
usage_slow	Usage: "/slow [duration]" - Enables slow mode (limit how often users may send messages). Duration (optional, default=120) must be a positive number of seconds. Use "slowoff" to disable.
usage_slowoff	Usage: "/slowoff" - Disables slow mode.
usage_r9kbeta	Usage: "/r9kbeta" - Enables r9k mode. See http://link.twitch.tv/r9k for details. Use "r9kbetaoff" to disable.
usage_r9kbetaoff	Usage: "/r9kbetaoff" - Disables r9k mode.
usage_host	Usage: "/host " - Host another channel. Use "unhost" to unset host mode.
usage_unhost	Usage: "/unhost" - Stop hosting another channel.
usage_mod	Usage: "/mod " - Grant mod status to a user. Use "mods" to list the moderators of this room.
usage_unmod	Usage: "/unmod " - Revoke mod status from a user. Use "mods" to list the moderators of this room.
usage_commercial	Usage: "/commercial [length]" - Triggers a commercial. Length (optional) must be a positive number of seconds.
usage_emoteonly	Usage: "/emoteonly" - Enables emote-only mode (only emoticons may be used in chat). Use "emoteonlyoff" to disable.
usage_emoteonlyoff	Usage: "/emoteonlyoff" - Disables emote-only mode.
usage_cheerbadge	Useage: "/cheerbadge" - Toggle the visibility of your Cheer badge in this channel.
no_help	No help available.
msg_subonly	This room is in subscribers only mode. To talk, purchase a channel subscription at http://www.twitch.tv/`channel_name`/subscribe?ref=subscriber_only_mode_chat
msg_slowmode	This room is in slow mode and you are sending messages too quickly. You will be able to talk again in cooldown seconds.
msg_duplicate	Your message was not sent because it is identical to the previous one you sent, less than 30 seconds ago.
msg_emoteonly	This room is in emote only mode. You can find your currently available emoticons using the smiley in the chat text area. See http://link.twitch.tv/emote_only_mode for more information
no_cheer_badge	You do not have a Cheer badge in this channel.
room_mods	The moderators of this room are: mod_list
color_changed	Your color has been changed.
msg_censored_channel	Your message was modified for using words banned by this channel
cheer_badge_deselected	Cheer badge unequipped.
cheer_badge_selected	Cheer badge equipped.

HOSTTARGET

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.

CLEARCHAT

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

USERSTATE

Use with tags CAP. See USERSTATE tags below.

> :tmi.twitch.tv USERSTATE #channel

RECONNECT

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.

ROOMSTATE

Use with tags CAP. See ROOMSTATE tags below.

> :tmi.twitch.tv ROOMSTATE #channel

USERNOTICE

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

Tags

< CAP REQ :twitch.tv/tags
> :tmi.twitch.tv CAP * ACK :twitch.tv/tags

Adds IRC v3 message tags to PRIVMSG, USERSTATE, NOTICE and GLOBALUSERSTATE (if enabled with commands CAP)

PRIVMSG

Normal message

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

Bits message

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

• badges is a comma-separated list of chat badges, valid badges are staff, admin, global_mod, moderator, subscriber and turbo.
• color is a hexadecimal RGB color code
  • Empty if it's never been set.
• display-name is the user's display name, escaped as described in the IRCv3 spec.
  • Empty if it's never been set.
• emotes contains information to replace text in the message with the emote images and can be empty. The format is as follows:
  • emote_id:first_index-last_index,another_first-another_last/another_emote_id:first_index-last_index
  • emote_id is 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)
  • Emote indexes are simply character indexes. \001ACTION does 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.
• id is a unique identifier for a message.
• mod, subscriber and turbo are either 0 or 1 depending on whether the user has mod, sub or turbo badge or not.
• room-id is the ID of the channel.
• user-id is the user's ID.
• user-type is either empty, mod, global_mod, admin or staff.
  • The broadcaster can have any of these, including 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: static-cdn.jtvnw.net/bits/THEME/TYPE/COLOR/SIZE, where
  • THEME is light or dark
  • TYPE is animated or static
  • COLOR is red for >= 10000 bits, blue for >= 5000, green for >= 1000, purple for >= 100, or otherwise gray
  • SIZE is a digit between 1 and 4.

USERSTATE

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-sets contains your emote set, which you can use to request a subset of /chat/emoticon_images.
  • eg: https://api.twitch.tv/kraken/chat/emoticon_images?emotesets=0,33,50,237,793,2126,3517,4578,5569,9400,10337,12239
  • Always contains at least 0.
• Other tags are shared with PRIVMSG and function the same way.

GLOBALUSERSTATE

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

• All tags are shared with PRIVMSG or USERSTATE and function the same way.

ROOMSTATE

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-lang is the chat language when broadcaster language mode is enabled, and empty otherwise. A few examples would be en for English, fi for Finnish and es-MX for Mexican variant of Spanish.
• r9k is R9K mode. Messages with more than 9 characters must be unique. 0 means disabled, 1 enabled.
• subs-only is subscribers only mode. Only subscribers and moderators can chat. 0 disabled, 1 enabled.
• slow determines how many seconds chatters without moderator privileges must wait between sending messages.

USERNOTICE

Re-subscription notice

> @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-id is the type of the notice. See above examples for valid types.
• msg-param-months is the number of consecutive months the user has subscribed for in a resub notice.
• system-msg is the message printed in chat along with this notice.
• login is the username of the user, who sent the notice.
• Other tags are shared with PRIVMSG and function the same way.

CLEARCHAT

User is timed out

@ban-duration=1;ban-reason=Follow\sthe\srules :tmi.twitch.tv CLEARCHAT #channel :target_username

User is banned

@ban-reason=Follow\sthe\srules :tmi.twitch.tv CLEARCHAT #channel :target_username

• ban-duration is the duration of the timeout in seconds. The tag is omitted on permanent bans.
• ban-reason is the reason the moderator gave for the timeout or ban.