Contents

Twitch Chat & Chatbots

Twitch provides an Internet Relay Chat (IRC) interface that lets chatbots connect to Twitch chat rooms using a WebSocket or TCP connection. Once connected, bots can send and receive chat messages. For example, bots can provide simple reminders like get up and move or hydrate, or they can perform Twitch actions like banning a user, or they can react to user input.

For a simple example to get you started quickly, see Getting Started.

Twitch’s IRC service is based on RFC1459 and IRCv3 Message Tag specification. If you’re not already familiar with them, reading them may help you understand the Twitch IRC server.

While Twitch’s IRC server generally follows RFC1459, it doesn’t support all IRC messages. For a list of supported messages, see Supported IRC messages.

Normal message flow

After connecting to the server, the first messages that all bots must send are the PASS and NICK messages. These messages are used to authenticate the user account that the bot is running under.

Once the server successfully authenticates your bot, the next step is to send a JOIN message to join the chat room that the bot runs in.

The messages your bot sends and receives depends on what your bot does and the Twitch-specific IRC capabilities it requests. If your bot simply sends out get up and move reminders at specific intervals, your bot can mostly ignore all other messages from the server. To send the reminder, your bot sends a PRIVMSG message (see Sending a message to the chat room).

If your bot responds to messages that users post in the chat room, your bot will need to read and parse the PRIVMSG messages that the server sends; the server sends a PRIVMSG message for each message users post in the chat room. For example, if your bot performs an action in response to a user command, it must parse the user’s posted message to see if it contains the command. The Getting Started example does just this by looking for the !dice command, rolling the die, and sending a PRIVMSG message with the rolled number.

Without requesting Twitch-specific IRC capabilities, your bot is limited to sending and receiving PRIVMSG messages. Requesting the membership capability allows your bot to receive JOIN and PART messages when users join and leave the chat room. Or, if your bot requests command capabilities, your bot can send PRIVMSG messages that contain Twitch chat commands like /ban and /uniquechat. When you use Twitch commands, the server may send your bot NOTICE messages or Twitch-specific messages like CLEARCHAT to let you know whether the command succeeded. You’ll also receive these messages if the chat room’s moderator enters the same commands in the chat. For information about Twitch capabilities, see Twitch-specific IRC capabilities.

To leave a chat room, your bot sends a PART message.

The Twitch IRC server also sends your bot PING messages to ensure that your bot is still alive and able to respond to the server’s messages. See Keepalive messages.

Supported IRC messages

While Twitch’s IRC server generally follows RFC1459, it doesn’t support all IRC messages. The following is the list of IRC messages that Twitch supports; if it’s not listed here, Twitch doesn’t support it.

Message Message flow Description
JOIN Send Your bot sends this message to join a channel. See Joining a channel.
NICK Send Your bot sends this message to specify the bot’s nickname when authenticating with the Twitch IRC server. See Authenticating with the Twitch IRC server.
NOTICE Receive Your bot receives this message from the Twitch IRC server when your bot fails to authenticate with the server. You can get NOTICE messages for other reasons if you request the commands capability.
PART Send
Receive
Your bot sends this message to leave a channel.

Your bot receives this message from the Twitch IRC server when a channel bans it.
PASS Send Your bot sends this message to specify the bot’s password when authenticating with the Twitch IRC server. See Authenticating with the Twitch IRC server.
PING Receive Your bot receives this message from the Twitch IRC server when the server wants to ensure that your bot is still alive and able to respond to the server’s messages. See Keepalive messages.
PONG Send Your bot sends this message in reply to the Twitch IRC server’s PING message. See Keepalive messages.
PRIVMSG Send
Receive
Your bot sends this message to post a chat message in the channel’s chat room.

Your bot receives this message from the Twitch IRC server when a user posts a chat message in the chat room. See Sending and receiving chat messages.

If your bot sends a message that Twitch’s IRC server doesn’t support, the server replies with the standard 421 numeric message. For example, if you send:

WHO #<channel>

The server replies with:

:tmi.twitch.tv 421 <user> WHO :Unknown command

Twitch-specific IRC messages

Twitch sends the following Twitch-specific messages to your bot if you request the commands and membership capability. See Twitch-specific IRC capabilities.

Message Message flow Description
CLEARCHAT Receive Your bot receives this message from the Twitch IRC server when all messages are removed from the chat room, or all messages for a specific user are removed from the chat room. Read more.
CLEARMSG Receive Your bot receives this message from the Twitch IRC server when a specific message is removed from the chat room. Read more.
GLOBALUSERSTATE Receive Your bot receives this message from the Twitch IRC server when a bot connects to the server. Read more.
HOSTTARGET Receive Your bot receives this message from the Twitch IRC server when a channel starts or stops host mode. Read more.
NOTICE Receive Your bot receives this message from the Twitch IRC server to indicate whether a command succeeded or failed. For example, a moderator tried to ban a user that was already banned. Read more.
RECONNECT Receive Your bot receives this message from the Twitch IRC server when the server needs to perform maintenance and is about to disconnect your bot. Read more.
ROOMSTATE Receive Your bot receives this message from the Twitch IRC server when a bot joins a channel or a moderator changes the chat room’s chat settings. Read more.
USERNOTICE Receive Your bot receives this message from the Twitch IRC server when events like user subscriptions occur. Read more.
USERSTATE Receive Your bot receives this message from the Twitch IRC server when a user joins a channel or the bot sends a PRIVMSG message. Read more.
WHISPER Receive Your bot receives this message from the Twitch IRC server when a user sends a WHISPER message. Read more.

Connecting to the Twitch IRC Server

To connect to the Twitch IRC server, use one of the following URIs.

  WebSocket clients IRC clients
SSL wss://irc-ws.chat.twitch.tv:443 irc://irc.chat.twitch.tv:6697
Non-SSL ws://irc-ws.chat.twitch.tv:80 irc://irc.chat.twitch.tv:6667

Grab your favorite library and pass the URI of the protocol you want to use in the connection method or constructor. For example, here’s what the snippet of code might look like if you used this websocket package for Node.js.

const WebSocketClient = require('websocket').client;
const client = new WebSocketClient();

client.on('connectFailed', function(error) {
    console.log('Connect Error: ' + error.toString());
});

client.on('connect', function(connection) {
    console.log('WebSocket Client Connected');
    
    // Send CAP (optional), PASS, and NICK messages
});

client.connect('ws://irc-ws.chat.twitch.tv:80');

If the connection succeeds, the next step is to request Twitch-specific capabilities if you want to use Twitch’s optional capabilities. Otherwise, the next step is to authenticate your bot with the Twitch IRC server. See Authenticating with the Twitch IRC Server.

Reconnecting to the Twitch IRC server

If your connection is dropped, you should try reconnecting using an exponential backoff approach. For example, try reconnecting immediately. If you have no luck, try again in 1 second, 2 seconds, 4 seconds, 8 seconds and so on for the number of attempts you want to make. But be aware if you’re making multiple connections that there are rate limits that apply (see Rate limites).

Keepalive messages

The Twitch IRC server sends PING messages to ensure that your bot is still alive and able to respond to the server’s messages.

PING :tmi.twitch.tv

After receiving a PING message, your bot must reply with a PONG message. The text of the PONG message must be the text from the PING message.

PONG :tmi.twitch.tv

If the bot fails to reply with a PONG, the server terminates the connection.

Parsing messages

When the Twitch IRC server sends a message, it may contain a single message or multiple messages. The following example shows what the message looks like if it contains a single message.

:foo!foo@foo.tmi.twitch.tv JOIN #bar\r\n

And here’s what the message looks like if it contains multiple messages. In this case, the message contains the JOIN, 353, 366, USERSTATE, ROOMSTATE, and PART messages. The messages are delimited by CRLF (\r\n).

:foo!foo@foo.tmi.twitch.tv JOIN #bar\r\n:foo.tmi.twitch.tv 353 foo = #bar :foo\r\n
:foo.tmi.twitch.tv 366 foo #bar :End of /NAMES list\r\n@badge-info=;badges=moderator/1;color=;display-name=foo;emote-sets=0,300374282;mod=1;subscriber=0;user-type=mod :tmi.twitch.tv USERSTATE #bar\r\n@emote-only=0;followers-only=-1;r9k=0;rituals=0;room-id=12345678;slow=0;subs-only=0 :tmi.twitch.tv ROOMSTATE #bar\r\n:foo!foo@foo.tmi.twitch.tv PART #bar\r\n

The Twitch IRC server does not guarantee the order of the messages. It may also send a message multiple times if it doesn’t think the bot received it.

For a simple example that parses messages, see Example Message Parser.

Rate limits

The Twitch IRC server enforces the following limits. It is up to your bot to keep track of its usage and not exceed the limits. Rate limit counters begin when the server processes the first message and resets at the end of the window. For example, if the limit is 20 messages per 30 seconds, the window starts when the server processes the first message and lasts for 30 seconds. At the end of the window, the counter resets and a new window begins with the next message.

Command and message rate limits

The following tables show the rate limits for the number of messages that your bot may send. If you exceed these limits, Twitch ignores the bots messages for the next 30 minutes.

The following table shows the rate limits for a normal account.

Limit Description
20 messages per 30 seconds If the user isn’t the channel’s broadcaster or moderator, the bot may send a maximum of 20 messages per 30 seconds.
100 messages per 30 seconds If the user is the channel’s broadcaster or moderator, the bot may send a maximum of 100 messages per 30 seconds.

If 10 users are running the bot on a single bot account, the rate limit applies across all 10 users (meaning that the 10 users combined can send a total of 20 messages). If each user is using a different bot account, each bot account has its own rate limit (meaning that each user can send 20 messages).

The following table shows the rate limits for a verified account.

Limit Description
20 messages per 30 seconds If the user isn’t the channel’s broadcaster or moderator, the bot may send a maximum of 20 messages per 30 seconds.
100 messages per 30 seconds If the user is the channel’s broadcaster or moderator, the bot may send a maximum of 100 messages per 30 seconds.
7,500 messages per 30 seconds The bot is limited to sending 7,500 messages per 30 seconds across all channels. This means that the bot could send 10 messages per 30 seconds to 750 different channels. However, it couldn’t, for example, send 7,500 messages per 30 seconds to a single channel because it would exceed the 20 messages per 30 second limit.

Authentication and join rate limits

The following lists show the rate limits for the number of authentication and join attempts. A bot sending a pair of PASS and NICK messages is considered an authentication attempt.

The following table shows the rate limits for a normal account.

The following table shows the rate limits for a verified account.

Verified bots

As a chatbot grows in popularity, it’s likely that it may approach or exceed the rate limits. Chatbots that enhance the Twitch user experience and have reached these limits may apply for verified bot status, but note that verified bot status is rarely granted. A bot with verified bot status enjoys:

But they:

Requesting Verified Bot status

If a chatbot has reached the rate limits for messages, authentications, or joins; the bot’s developer may request verified bot status. To request verified bot status, go to IRC Command and Message Rate and fill out the form. After Twitch reviews the request, Twitch sends its determination to the requestor via email.

Next steps