Authenticating with the Twitch IRC Server

Reviews for Extensions, organizations, games, and chatbot verification are temporarily paused while we revise our processes. We are working to resume reviews as quickly as possible and will share updates with you shortly. Thank you for your patience and understanding.

Before your bot can join a channel, it needs to authenticate with the Twitch IRC server. To authenticate with the server, your bot sends the PASS and NICK messages. The order that you send the messages matters — you must send PASS before sending NICK; otherwise, the server replies with:

:tmi.twitch.tv NOTICE * :Improperly formatted auth

Registering your bot

To get an access token, you must first register your bot. For information about registering your bot, see Registering an app.

Getting an access token

After registering your bot and getting a client ID, you can generate a user access token. For information about user access tokens, see Authentication. There are a number of ways to get an access token, including:

Getting it programmatically. If you use this approach, Twitch recommends using the Authorization Code flow.
Using the Twitch CLI. To get a token, use the CLI’s token command.

If you just need a token for testing chat functionality, you can try this option:

Open a browser and enter the following URL in the address bar:

https://id.twitch.tv/oauth2/authorize?response_type=token&client_id=<your client id>&redirect_uri=http://localhost:3000&scope=chat%3Aread+chat%3Aedit

Replace <your client id> with the client ID you received when registering your bot.

Replace the URL in the redirect_uri query parameter with the redirect URI you specified when registering your bot.

Enter your Twitch credentials if asked, and then authorize the scopes.

Get the access token from the address bar (see the access_token parameter in the fragment portion of the URI).

http://localhost:3000/#access_token=5i40r6owzqxbwn8vplow75lkede10&scope=chat%3Aread+chat%3Aedit&token_type=bearer

The scopes that you specify when requesting the token depends on your bot’s functionality. If the bot just reads chat messages, it only needs the chat:read, but if it also sends messages, it’ll need the chat:edit scope, too. For a list of scopes that you can specify, see Chat scopes. If you plan to send messages that include Twitch chat commands, see Twitch chat commands for a list of scopes.

Whose user token to use?

The user name that Twitch uses in the chat room for your bot comes from the user access token. If you want Twitch to use your bot’s name in the Twitch chat room, you need to:

Create a Twitch account for the bot.
Get an access token for the bot’s Twitch account with the appropriate scopes.

If your bot needs to send moderator chat commands, you’ll also need to get it added as a moderator in the channel.

Sending the PASS and NICK messages

Set the PASS message’s text string to the access token. The string’s format is oauth:<token> where token is the access token.

PASS oauth:yfvzjqb705z12hrhy1zkwa9xt7v662

Set the NICK message’s text string to your bot’s nickname. The nickname should be the lowercase login name of the Twitch account used to get your access token.

NICK <user>

Here’s what the snippet of code might look like if you used this websocket package for Node.js.

client.on('connect', function(connection) {
    console.log('WebSocket Client Connected');
    
    connection.sendUTF('CAP REQ :twitch.tv/membership twitch.tv/tags twitch.tv/commands');
    connection.sendUTF('PASS oauth:yfvzjqb705z12hrhy1zkwa9xt7v662');
    connection.sendUTF('NICK myusername');
});

The PASS/NICK reply

If the Twitch IRC server successfully authenticates your bot, it replies with the following numeric messages:

: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> :>
@badge-info=;badges=;color=;display-name=<user>;emote-sets=0,300374282;user-id=12345678;user-type= :tmi.twitch.tv GLOBALUSERSTATE

Note that the above reply was formatted for readability, but the message is actually a single string that contains multiple messages. Each message is delimited by CRLF (\r\n). For example:

:tmi.twitch.tv 001 <user> :Welcome, GLHF!\r\n:tmi.twitch.tv 002 <user> :Your host is tmi.twitch.tv\r\n:tmi.twitch.tv 003 <user> :This server is rather new\r\n:tmi.twitch.tv 004 <user> :-\r\n:tmi.twitch.tv 375 <user> :-\r\n:tmi.twitch.tv 372 <user> :You are in a maze of twisty passages, all alike.\r\n:tmi.twitch.tv 376 <user> :>\r\n@badge-info=;badges=;color=;display-name=<user>;emote-sets=0,300374282;user-id=12345678;user-type= :tmi.twitch.tv GLOBALUSERSTATE\r\n

If the server fails to authenticate your bot, it replies with the following message and closes the connection.

:tmi.twitch.tv NOTICE * :Login authentication failed

Also, as stated above, if you don’t send the PASS and NICK messages in the correct order, the authentication fails and the server replies with:

:tmi.twitch.tv NOTICE * :Improperly formatted auth

Next steps

Join the chat room where your bot will send and receive messages. See Joining a chat room.