Twitch deprecations

Twitch has deprecated /-chat commands through the IRC connection and they will be removed February 18, 2023. See the announcement. This removes a lot of chat client functionality which affects tmi.js. To resolve this and keep the nice interface of tmi.js, it will be rewritten completely to support making API calls directly. Version 1.x of tmi.js will continue to function as it normally does until and a new v2 will be available in the near future. The action method will continue to work as they're not removing the /me command.
The host method and hosting/hosted events will no longer function as of October 3, 2022. See the FAQ.

Last updated Oct 24, 2022

Getting started

Install

Install using npm:

npm i tmi.js

Examples

Anonymous connection

An anonymous connection allows you to connect to Twitch without having to authenticate. This is ideal for chat overlays.


const tmi = require('tmi.js');

const client = new tmi.Client({
	channels: [ 'my_name' ]
});

client.connect();

client.on('message', (channel, tags, message, self) => {
	// "Alca: Hello, World!"
	console.log(`${tags['display-name']}: ${message}`);
});

Using authorization allows the bot to send messages on behalf of the authenticated account. Typically this would be a dedicated bot account, but it could be an interface for a user to send messages directly.


const tmi = require('tmi.js');

const client = new tmi.Client({
	options: { debug: true },
	identity: {
		username: 'my_bot_name',
		password: 'oauth:my_bot_token'
	},
	channels: [ 'my_name' ]
});

client.connect();

client.on('message', (channel, tags, message, self) => {
	// Ignore echoed messages.
	if(self) return;

	if(message.toLowerCase() === '!hello') {
		// "@alca, heya!"
		client.say(channel, `@${tags.username}, heya!`);
	}
});

Simple command handler

This command handler example will split a message like this example chat message: !Echo Chat message here into the command "echo" with the arguments [ "Chat", "message", "here" ].


client.on('message', (channel, tags, message, self) => {
	if(self || !message.startsWith('!')) return;

	const args = message.slice(1).split(' ');
	const command = args.shift().toLowerCase();

	if(command === 'echo') {
		client.say(channel, `@${tags.username}, you said: "${args.join(' ')}"`);
	}
});

Guide

Client options

Parameter	Type	Default	Description
`options`	`object`	`{}`	General options object
`debug`	`boolean`	`false`	Sets the log level of the logger to "info" which will log connection and chat events.
`messagesLogLevel`	`string`	`"info"`	Sets the log level of chat messages. Useful for custom logging of chat messages while keeping more general events.
`joinInterval`	`number`	`2000`	Controls the delay in milliseconds between JOIN requests when using the channels array option. Minimum of 300 milliseconds. If the identity has special permission from Twitch for a higher join rate then you should implement your own calls to the `client.join` method.
`skipMembership`	`boolean`	`false`	Disables receiving JOIN/PART events for other users. Good for decreasing network traffic when joining lots of channels or you don't care about this data. After a threshold per channel Twitch stops sending this data so it may not be necessary for all cases.
`skipUpdatingEmotesets`	`boolean`	`false`	Disables the fetch request for getting the emote about your emotesets data. This will affect automatic emote parsing for self messages.
`updateEmotesetsTimer`	`number`	`60000`	Sets the timer delay in milliseconds for automatically refetching the emotesets data. Set to `0` to disable the timer. Good for decreasing network traffic.
`clientId`	`string`	`null`	Sets the client ID for the emotesets API call.
`channels`	`string[]`	`[]`	Channels to automatically join upon connecting. The rate of joins is controlled by the `options.joinInterval` option.
`identity`	`object`	`{}`	Options for the identity of the authenticated user. Omit for an anonymous connection.
`username`	`string`	`undefined`	The username associated with the OAuth token.
`password`	`string \| () => (string \| Promise<string>)`	`undefined`	An OAuth token with at least the `chat:read` and/or `chat:edit` scopes. Can either be a string or a function that returns either a string or Promise that resolves to a string.
`connection`	`object`	`{}`	Options for the connection itself.
`reconnect`	`boolean`	`true`	Automatically reconnect the client if it gets disconnected for any reason. Sometimes Twitch will request the client to reconnect and tmi.js will disconnect and reconnect even if this option is set to `false`.
`secure`	`boolean`	`true`	If omitted then when `connection.server` and `connection.port` are not specified then this option will be `true`. This will then set the port to `443` and use the WSS protocol (secure WebSocket) when connecting to the server.
`server`	`string`
`port`	`number`
`agent`	`http.Agent (any)`		Passes an HTTP proxy agent instance to `ws`. Node only.
`fetchAgent`	`http.Agent (any)`		Passes an HTTP proxy agent instance to `node-fetch`. Node only.
`maxReconnectAttempts`	`number`	`Infinity`	Maximum number of reconnect attempts before it stops attempting. Set to the value to `Infinity` to not reconnecting. The `"maxreconnect"` event will be emitted as well an error logged.
`reconnectInterval`	`number`	`1000`	The base time in milliseconds that the reconnect timer will delay to attempt a reconnect.
`maxReconnectInterval`	`number`	`30000`	The maximum time in milliseconds that the reconnect timer will delay to attempt another reconnect.
`reconnectDecay`	`number`	`1.5`	A multiplier for the next reconnect timer interval. Values greater than `1` are recommended.

Send messages

You must use an authenticated client (via the identity option) to send messages to chat. This means you need an OAuth token connected to a Twitch account. Ideally this would be an alternate account dedicated to the bot, like the "Nightbot" account.


// Regular
client.say(channel, message);
// Action
client.action(channel, message);