Chatbots & IRC Guide
Introduction
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.
Syntax Notes
All references to <channel>
and <user>
are references to channel and user names not IDs. Always enter the channel name (<channel>
) in lowercase. The examples in the following table use these syntax conventions:
Lines prefixed with: | Are sent from: | To: |
---|---|---|
< | client | server |
> | server | connecting client |
Connecting to Twitch IRC
To connect:
WebSocket Clients | IRC Clients | |
---|---|---|
SSL | wss://irc-ws.chat.twitch.tv:443 | irc://irc.chat.twitch.tv:6697 |
Otherwise | ws://irc-ws.chat.twitch.tv:80 | irc://irc.chat.twitch.tv:6667 |
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 isabcd
, sendoauth:abcd
. - 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 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 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).
Known and Verified Bots
There are two special statuses for bots which enhance the Twitch user experience and are trusted: known and verified. Both statuses provide elevated privileges. Verified bots have higher throughput than known bots. Verified status is granted only rarely.
Both known and verified bots:
- Have higher chat limits than regular users.
- Are not exempt from AutoMod mode. AutoMod analyzes chat messages flags potentially risky messages for a channel moderator, who can then allow or deny them to appear in chat.
- Are exempt from whispers being dropped for being spam. The spam classifier is still run against these whispers, they may be marked as spam, and their spam status is logged for auditing purposes.
To request known or verified bot status, please fill out the form at https://dev.twitch.tv/limit-increase as follows:
- Select IRC Command and Message Rate as the service for which you want to request a limit.
- Instead of Client ID, enter your bot’s Twitch ID.
- Enter your bot request as the new limit.
After the form is reviewed, you will be emailed the results, typically within 3 business days.
Command & Message Limits
There are limits of the number of IRC commands or messages you are allowed to send to the server. If you exceed these limits, you are locked out of chat for 30 minutes.
Authentication and join rate limits are:
- 20 authenticate attempts per 10 seconds per user (200 for verified bots)
- 20 join attempts per 10 seconds per user (2000 for verified bots)
Command and message limits are:
Limit | Applies to |
---|---|
20 per 30 seconds | Users sending commands or messages to channels in which they do not have Moderator or Operator status |
100 per 30 seconds | Users sending commands or messages to channels in which they have Moderator or Operator status |
For Whispers, which are private chat message between two users:
Limit | Applies to |
---|---|
3 per second, up to 100 per minute 40 accounts per day |
Users (not bots) |
10 per second, up to 200 per minute 500 accounts per day |
Known bots |
20 per second, up to 1200 per minute 100,000 accounts per day |
Verified bots |
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.
Capability | Description |
---|---|
[JOIN](#join) |
Join a channel. |
[PART](#part) |
Leave a channel. |
[PRIVMSG](#privmsg) |
Send a message to a channel. |
JOIN
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 (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
Leave a channel.
< PART #<channel>
> :<user>!<user>@<user>.tmi.twitch.tv PART #<channel>
PRIVMSG
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.
Command | Required Scope |
---|---|
| channel:moderate |
/clear | channel:moderate |
/color | chat:edit |
/commercial | channel_commercial |
/delete | channel:moderate |
/disconnect | chat:edit |
| channel:moderate |
| channel:moderate |
/help | chat:edit |
| channel_editor |
/marker | channel_editor |
/me | chat:edit |
| channel:moderate |
/mods | chat:edit |
| channel:moderate |
| channel_editor |
| channel:moderate |
| channel:moderate |
| channel:moderate |
/vip , /unvip | channel:moderate |
/vips | chat:edit |
/w | whispers:edit |
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