Chat and IRC

Twitch offers an IRC interface to our chat functionality. This allows you to, for instance:

  • Develop bots for your channel.
  • Connect to a channel’s chat with an IRC client instead of using the Web interface.

While our IRC server generally follows RFC1459, there are several cases where it behaves slightly differently than other IRC servers; as described below, there are many Twitch-specific IRC capabilities. The differences are necessary to accommodate:

  • The massive scale at which our chat servers operate, and
  • Complex Twitch-specific features that we provide (to viewers, broadcasters, and developers).

Syntax Notes

All references to <channel> and <user> are to channel and user names (not IDs, as in the API endpoints).

Always enter the channel name (<channel>) in lowercase.

The examples below use these syntax conventions:

Lines prefixed with: Are sent from: To:
< client server
> server connecting client

Connecting to Twitch IRC

Your password (PASS) should be an OAuth token authorized through our API with the chat_login scope.

  • The token must have the prefix oauth:. For example, if your token is abcd, you send oauth:abcd.
  • To quickly get a token for your account, use this Twitch Chat OAuth Password Generator.

Your nickname (NICK) must be your Twitch user name in lowercase.

Use server irc.chat.twitch.tv. For SSL, use port 443; otherwise, use port 6667.

A successful connection session looks like this:

1
2
3
4
5
6
7
8
9
< PASS oauth:<Twitch OAuth token>
< NICK <user>
> :tmi.twitch.tv 001 <user> :Welcome, GLHF!
> :tmi.twitch.tv 002 <user> :Your host is tmi.twitch.tv
> :tmi.twitch.tv 003 <user> :This server is rather new
> :tmi.twitch.tv 004 <user> :-
> :tmi.twitch.tv 375 <user> :-
> :tmi.twitch.tv 372 <user> :You are in a maze of twisty passages.
> :tmi.twitch.tv 376 <user> :>

About once every five minutes, the server will send you a PING :tmi.twitch.tv. To ensure that your connection to the server is not prematurely terminated, reply with PONG :tmi.twitch.tv.

If your connection fails for any reason, you will be disconnected from the server. Common reasons for failed connections are:

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

IRC Command and Message Limits

If you send more than 20 commands or messages to the server within 30 seconds, you will be locked out for 30 minutes.

If you send commands/messages only to channels in which you have Moderator or Operator status, the limit is 100 messages per 30 seconds.

These limits cannot be changed, so be careful when working with IRC.

Invalid IRC Commands

If you send an invalid command, you will get a 421 message back:

1
2
< WHO #<channel>
> :tmi.twitch.tv 421 <user> WHO :Unknown command

IRC Generic Capabilities

Capability Description
JOIN Join a channel.
PART Depart from a channel.
PRIVMSG Send a message to a channel.

JOIN (Generic)

Join a channel.

1
2
3
4
< JOIN #<channel>
> :<user>!<user>@<user>.tmi.twitch.tv JOIN #<channel>
> :<user>.tmi.twitch.tv 353 <user> = #<channel> :<user>
> :<user>.tmi.twitch.tv 366 <user> #<channel> :End of /NAMES list

To receive membership state events (JOIN, MODE, NAMES, and PART) after a successful JOIN, you must request the Twitch-specific Membership capability.

If you try to join a suspended or deleted channel, you get a msg_channel_suspended NOTICE. If you try to join a nonexistent channel, the JOIN is quietly dropped.

PART (Generic)

Depart from a channel.

1
2
< PART #<channel>
> :<user>!<user>@<user>.tmi.twitch.tv PART #<channel>

PRIVMSG (Generic)

Send a message to a channel.

1
2
< PRIVMSG #<channel> :This is a sample message
> :<user>!<user>@<user>.tmi.twitch.tv PRIVMSG #<channel> :This is a sample message

Twitch-Specific IRC Capabilities

Using IRC v3 capability registration, you can register for Twitch-specific capabilities, to access Twitch-specific commands, data, etc.

Due to caching, events are not sent to a channel immediately; instead, they are batched up and sent every 10 seconds.

The Twitch API does not support WHO, part of the IRC specification.

All elevated users are given operator privileges. To determine a user’s actual elevation level, request the tags capability and parse the user-type tag.

There are three Twitch-specific capabilities:

  • Membership — Adds membership state event data. By default, we do not send this data to clients without this capability.
1
2
< CAP REQ :twitch.tv/membership
> :tmi.twitch.tv CAP * ACK :twitch.tv/membership
  • Tags — Adds IRC V3 message tags to several commands, if enabled with the commands capability.
1
2
< CAP REQ :twitch.tv/tags
> :tmi.twitch.tv CAP * ACK :twitch.tv/tags
  • Commands — Enables several Twitch-specific commands.
1
2
< CAP REQ :twitch.tv/commands
> :tmi.twitch.tv CAP * ACK :twitch.tv/commands

Twitch IRC Capability: Membership

Capability Description
JOIN Join a channel.
MODE Gain/lose moderator (operator) status in a channel.
NAMES List current chatters in a channel.
PART Depart from a channel.

JOIN (Twitch Membership)

Join a channel.

1
> :<user>!<user>@<user>.tmi.twitch.tv JOIN #<channel>

Example: ronni joined the dallas channel.

1
> :ronni!ronni@ronni.tmi.twitch.tv JOIN #dallas

MODE (Twitch Membership)

Gain/lose moderator (operator) status in a channel.

1
2
> :jtv MODE #<channel> +o <user>
> :jtv MODE #<channel> -o <user>

Example: ronni got moderator status in the dallas channel.

1
> :jtv MODE #dallas +o ronni

NAMES (Twitch Membership)

List current chatters in a channel. If there are more than 1000 chatters in a room, NAMES return only the list of operator privileges currently in the room.

1
2
3
> :<user>.tmi.twitch.tv 353 <user> = #<channel> :<user> <user2> <user3>
> :<user>.tmi.twitch.tv 353 <user> = #<channel> :<user4> <user5> ... <userN>
> :<user>.tmi.twitch.tv 366 <user> #<channel> :End of /NAMES list

Example: The chatters in the dallas channel are ronni, fred, wilma, barney, and betty.

1
2
3
> :ronni.tmi.twitch.tv 353 ronni = #dallas :ronni fred wilma
> :ronni.tmi.twitch.tv 353 ronni = #dallas :barney betty
> :ronni.tmi.twitch.tv 366 ronni #dallas :End of /NAMES list

PART (Twitch Membership)

Depart from a channel.

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

Example: ronni left the dallas channel.

1
> :ronni!ronni@ronni.tmi.twitch.tv PART #dallas

Twitch IRC Capability: Tags

Capability Description
CLEARCHAT Temporary or permanent ban on a channel.
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.

1
2
> :tmi.twitch.tv CLEARCHAT #<channel> :<user>
@ban-duration=<ban-duration>;ban-reason=<ban-reason> :tmi.twitch.tv CLEARCHAT #<channel> :<user>
Parameter Description
ban-duration (Optional) Duration of the timeout, in seconds. If omitted, the ban is permanent.
ban-reason The moderator’s reason for the timeout or ban.

Example: ronni is permanently banned from the dallas channel.

1
2
> :tmi.twitch.tv CLEARCHAT #dallas :ronni
@ban-reason=Follow\sthe\srules :tmi.twitch.tv CLEARCHAT #dallas :ronni

GLOBALUSERSTATE (Twitch Tags)

On successful login.

1
> @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
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 1 if the user has a Turbo badge; otherwise, 0.
user-id The user’s ID.
user-type 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 he logged in.

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

1
> @badges=<badges>;bits=<bits>;color=<color>;display-name=<display-name>;emotes=<emotes>;id=<id>;mod=<mod>;room-id=<room-id>;subscriber=<subscriber>;turbo=<turbo>;user-id=<user-id>;user-type=<user-type> :<user>!<user>@<user>.tmi.twitch.tv PRIVMSG #<channel> :<message>
Parameter Description
badges Comma-separated list of chat badges and the version of each badge (each in the format <badge>/<version>, such as admin/1). Valid badge values: admin, bits, broadcaster, global_mod, moderator, subscriber, staff, turbo.
bits (Optional) 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
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.
emotes Information 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.
id A unique ID for the message.
message The message.
mod 1 if the user has a moderator badge; otherwise, 0.
room-id The channel ID.
subscriber 1 if the user has a subscriber badge; otherwise, 0.
turbo 1 if the user has a Turbo badge; otherwise, 0.
user-id The user’s ID.
user-type The user’s type. Valid values: empty, mod, global_mod, admin, staff. The broadcaster can have any of these.

Example: This is a normal (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.

1
> @badges=global_mod/1,turbo/1;color=#0D4200;display-name=dallas;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 :ronni!ronni@ronni.tmi.twitch.tv PRIVMSG #dallas :Kappa Keepo Kappa

Example: This is a bits message.

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

1
> @broadcaster-lang=<broadcaster-lang>;r9k=<r9k>;slow=<slow>;subs-only=<subs-only> :tmi.twitch.tv ROOMSTATE #<channel>
Parameter Description
broadcaster-lang The chat language when broadcaster language mode is enabled; otherwise, empty. Examples: en (English), fi (Finnish), es-MX (Mexican variant of Spanish).
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.

1
> @broadcaster-lang=en;r9k=0;slow=0;subs-only=0 :tmi.twitch.tv ROOMSTATE #dallas

Example: On the dallas channel, slow mode is set to 10 seconds:

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

USERNOTICE (Twitch Tags)

On subscription or resubscription to a channel.

1
> @badges=<badges>;color=<color>;display-name=<display-name>;emotes=<emotes>;mod=<mod>;msg-id=<msg-id>;msg-param-months=<msg-param-months>;msg-param-sub-plan=<msg-param-sub-plan>;msg-param-sub-plan-name=<msg-param-sub-plan-name>;room-id=<room-id>;subscriber=<subscriber>;system-msg=<system-msg>;login=<user>;turbo=<turbo>;user-id=<user-id>;user-type=<user-type>:tmi.twitch.tv USERNOTICE #<channel> :<message>

If the user did not enter a message, the trailing part (:<message>) is omitted

Parameter Description
badges Comma-separated list of chat badges and the version of each badge (each in the format <badge>/<version>, such as admin/1). Valid badge values: admin, bits, broadcaster, global_mod, moderator, subscriber, staff, turbo.
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.
emotes Information 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.
message The message.
mod 1 if the user has a moderator badge; otherwise, 0.
msg-id The type of notice (not the ID). Valid values: sub, resub, charity.
msg-param-months The number of consecutive months the user has subscribed for, in a resub notice.
msg-param-sub-plan 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 The display name of the subscription plan. This may be a default name or one created by the channel owner.
room-id The channel ID.
subscriber 1 if the user has a subscriber badge; otherwise, 0.
system-msg The message printed in chat along with this notice.
turbo 1 if the user has a Turbo badge; otherwise, 0.
user The name of the user who sent the notice.
user-id The user’s ID.
user-type The user’s type. Valid values: empty, mod, global_mod, admin, staff. The broadcaster can have any of these.

Example: Notice sent when ronni resubscribed to the dallas channel.

1
> @badges=staff/1,broadcaster/1,turbo/1;color=#008000;display-name=ronni;emotes=;mod=0;msg-id=resub;msg-param-months=6;msg-param-sub-plan=Prime;msg-param-sub-plan-name=Prime;room-id=1337;subscriber=1;system-msg=ronni\shas\ssubscribed\sfor\s6\smonths!;login=ronni;turbo=1;user-id=1337;user-type=staff :tmi.twitch.tv USERNOTICE #dallas :Great stream -- keep it up!

USERSTATE (Twitch Tags)

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

1
> @color=<color>;display-name=<display-name>;emote-sets=<emotes>;mod=<mod>;subscriber=<subscriber>;turbo=<turbo>;user-type=<user-type>:tmi.twitch.tv USERSTATE #<channel>
Parameter Description
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.
emotes 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 1 if the user has a subscriber badge; otherwise, 0.
turbo 1 if the user has a Turbo badge; otherwise, 0.
user-type 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.

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

Twitch IRC Capability: Commands

Capability Description
CLEARCHAT Temporary or permanent ban on a channel.
HOSTTARGET Host starts or stops a message.
NOTICE General notices from the server.
RECONNECT Rejoin channels after a restart.
ROOMSTATE When a user joins a channel or a room setting is changed.
USERNOTICE On resubscription to a channel.
USERSTATE When a user joins a channel or sends a PRIVMSG to a channel.

CLEARCHAT (Twitch Commands)

Temporary or permanent ban on a channel.

1
> :tmi.twitch.tv CLEARCHAT #<channel> :<user>

Use with the tags capability; see CLEARCHAT (Twitch Tags), which has additional parameters.

Example: All chat is cleared (deleted) on the dallas channel.

1
> :tmi.twitch.tv CLEARCHAT #dallas

HOSTTARGET (Twitch Commands)

Host starts or stops a message.

Host starts message:

1
> :tmi.twitch.tv HOSTTARGET #hosting_channel <channel> [<number-of-viewers>]

Host stops message:

1
> :tmi.twitch.tv HOSTTARGET #hosting_channel :- [<number-of-viewers>]
Parameter Description
number-of-viewers (Optional) Number of viewers watching the host.

NOTICE (Twitch Commands)

General notices from the server.

1
> @msg-id=<msg id>:tmi.twitch.tv NOTICE #<channel> :<message>
Parameter Description
message The message.
msg id A message ID string. Can be used for i18ln. Valid values: see Msg-id Tags for the NOTICE Commands Capability.

Example:

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

RECONNECT (Twitch Commands)

Rejoin channels after a restart.

Twitch IRC processes occasionally need to be restarted. When this happens, clients that have requested the IRC v3 twitch.tv/commands capability are issued a RECONNECT. After a short time, the connection is closed. In this case, reconnect and rejoin channels that were on the connection, as you would normally.

ROOMSTATE (Twitch Commands)

When a user joins a channel or a room setting is changed.

Use with the tags capability; see ROOMSTATE (Twitch Tags), which has additional parameters.

1
> :tmi.twitch.tv ROOMSTATE #<channel>

USERNOTICE (Twitch Commands)

On resubscription to a channel.

Use with the tags capability; see USERNOTICE (Twitch Tags), which has additional parameters.

1
> :tmi.twitch.tv USERNOTICE #<channel> :message

USERSTATE (Twitch Commands)

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

Use with the tags capability; see USERSTATE (Twitch Tags), which has additional parameters.

1
> :tmi.twitch.tv USERSTATE #<channel>

msg-id Tags for the NOTICE Commands Capability

msg-id Message
already_banned <user> is already banned in this room.
already_emote_only_off This room is not in emote-only mode.
already_emote_only_on This room is already in emote-only mode.
already_r9k_off This room is not in r9k mode.
already_r9k_on This room is already in r9k mode.
already_subs_off This room is not in subscribers-only mode.
already_subs_on This room is already in subscribers-only mode.
bad_host_hosting This channel is hosting <channel>.
bad_unban_no_ban <user> is not banned from this room.
ban_success <user> is banned from this room.
emote_only_off This room is no longer in emote-only mode.
emote_only_on This room is now in emote-only mode.
host_off Exited host mode.
host_on Now hosting <channel>.
hosts_remaining There are <number> host commands remaining this half hour.
msg_channel_suspended This channel is suspended.
r9k_off This room is no longer in r9k mode.
r9k_on This room is now in r9k mode.
slow_off This room is no longer in slow mode.
slow_on This room is now in slow mode. You may send messages every <slow seconds> seconds.
subs_off This room is no longer in subscribers-only mode.
subs_on This room is now in subscribers-only mode.
timeout_success <user> has been timed out for <duration> seconds.
unban_success <user> is no longer banned from this chat room.
unrecognized_cmd Unrecognized command: <command>