Chatbots & IRC Guide
Twitch offers an IRC interface to our chat functionality. This allows you to, for instance:
- Develop one or more bots for your channel.
- Connect to a channel’s chat with an IRC client instead of using the Web interface. Some developers prefer IRC because it fits their existing workflow, for example when they already have several non-Twitch IRC channels. Other developers prefer IRC because it is lighter weight and can thus be used on machines that are less powerful than 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 in this document, there are many Twitch-specific IRC capabilities. The differences are necessary to accommodate:
- The massive scale at which our chat servers operate.
- Complex Twitch-specific features that we provide to viewers, broadcasters, and developers.
All references to
<user> are references to channel and user logins and not IDs. Always enter the channel login (
<channel>) in lowercase. The examples in the following table use these syntax conventions:
|Lines prefixed with:||Are sent from:||To:|
Connecting to Twitch IRC
|WebSocket Clients||IRC Clients|
To authenticate, your password (
pass) should be an OAuth token authorized through our API and should use both the
chat:read scope (to read messages) and the
chat:edit scope (to send messages).
- The token must have the prefix
oauth:. For example, if your token is
- To quickly get a token for your account, use this Twitch Chat OAuth Password Generator.
Your nickname (
nick) must be your Twitch username (login name) in lowercase.
A successful connection session looks like the following example:
< 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
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 login or password
Re-Connecting to Twitch IRC
To re-connect to Twitch, follow the same process. Best practice suggests trying again with exponential backoff (immediate, 1s, 2s, 4s, 8s).
As the popularity of a chatbot grows, there is a possibility that it may approach or exceed the typical rate limits provided for a Twitch account. Chatbots that enhance the Twitch user experience and have reached these limits may apply for the verified bot status. This status provides elevated rate limits should a request be approved. Verified status is granted rarely.
- Have higher chat limits than regular Twitch accounts.
- Have higher authentication and join limits than regular Twitch accounts.
- Do not have higher limits for sending whispers than regular Twitch accounts (i.e. Twitch private messages).
- Are not exempt from AutoMod mode. AutoMod analyzes chat messages and flags potentially risky messages for a channel moderator, who can then allow or deny them to appear in chat.
Requesting Verified Bot Status
If a chatbot has reached the rate limits for messages, authentications, or joins; a developer may request the verified bot status. To make this request, fill out the IRC Command and Message Rate form. Once a request has been reviewed, developers can expect a response via email.
There are limits to the number of IRC commands or messages a developer can send to the server, the number of authentication and joins that can be attempted, and the number of Whispers (i.e. private messages) that can be sent.
Command and message rate limits
If command and message rate limits are exceeded, an application cannot send chat messages or commands for 30 minutes.
|20 per 30 seconds||Users sending commands or messages to channels in which they are not the broadcaster and do not have Moderator status|
|100 per 30 seconds||Users sending commands or messages to channels in which they are the broadcaster or have Moderator status|
|7500 per 30 seconds site-wide||Verified bots. The channel limits above also apply. In other words, one of the two limits above will also be applied depending on whether the verified bot is the broadcaster or has Moderator status.|
Authentication and join rate limits
|20 authenticate attempts per 10 seconds per user||Regular Twitch account|
|20 join attempts per 10 seconds per user||Regular Twitch account|
|200 authenticate attempts per 10 seconds per user||Verified bot|
|2000 join attempts per 10 seconds per user||Verified bot|
Whispers rate limits
If the Whisper rate limits are exceeded, an application cannot send Whispers for 24 hours.
|3 per second, up to 100 per minute, for 40 accounts per day||All Twitch accounts|
Invalid IRC Commands
If you send an invalid command, you will get a
421 message back:
< WHO #<channel> > :tmi.twitch.tv 421 <user> WHO :Unknown command
Generic IRC Commands
The Twitch API does not support
WHO, part of the IRC specification. Please note that the channel login must be in lowercase, per the Syntax Notes.
||Join a channel.|
||Leave a channel.|
||Send a message to a channel.|
Join a channel.
< 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 commands related to the users in the channel (
PART) after a successful
JOIN, you must request the Twitch-specific Membership capability.
If you try to join a suspended or deleted channel, you will get a
NOTICE. If you try to join a nonexistent channel, the
JOIN is quietly dropped.
If you try to join channels in excess of your rate limit, the
JOIN is first quietly dropped. If your rate is greatly exceeded, the connection will be terminated.
Leave a channel.
< PART #<channel> > :<user>!<user>@<user>.tmi.twitch.tv PART #<channel>
Send a message to a channel.
< PRIVMSG #<channel> :This is a sample message > :<user>!<user>@<user>.tmi.twitch.tv PRIVMSG #<channel> :This is a sample message
Scopes for IRC Commands
Twitch slash commands are sent via
PRIVMSG. The following table lists these commands and required scopes.
Twitch 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 and sent every 10 seconds.
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 several Twitch-specific capabilities:
Membership: Adds membership state event data. By default, we do not send this data to clients without this capability.
< 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.
< CAP REQ :twitch.tv/tags > :tmi.twitch.tv CAP * ACK :twitch.tv/tags
Commands: Enables several Twitch-specific commands.
< CAP REQ :twitch.tv/commands > :tmi.twitch.tv CAP * ACK :twitch.tv/commands
< CAP REQ :twitch.tv/tags twitch.tv/commands