twitched
A Javascript library for easily creating Twitch.tv chat applications and bots.
About
The library was written as I needed a performant Twitch library that could join multiple channels and process incoming messages for each. While there are a few other great Twitch chat libraries out there, I found none to fit my needs. Although I developed this library as part of a larger project, I thought others might find it useful :)
Note: The library utilizes many of the new ES6 features such as classes, arrow functions, and string templates.
Installation
Installation is simple using npm:
npm install twitchedUsage
TwitchChat
The heart of the library is the TwitchChat object which connects to and processes incoming IRC messages from the Twitch server.
To join a specific Twitch channel, use the TwitchChat object's .join() method, which will return a TwitchChannel object that allows you to interact with that specific Twitch channel directly.
Creating a TwitchChat object is easy and requires a Twitch user's username and OAuth password.
The OAuth password is NOT the user's Twitch password and should be obtained using Twitch Chat OAuth Password Generator
"use strict";
var TwitchChat = require('twitched');
// create the TwitchChat client
var chat = new TwitchChat("Username", "OAuthPassword");
// join a channel
chat.join("summit");
// writes chat messages to the console
chat.onMessage((channel, user, message) => {
console.log(`[${channel.name}]${user}: ${message}`);
});
// connect to Twitch
chat.connect();The TwitchChat object also exposes event handlers that you can register and respond to. These are considered global events occur for all channels that you have joined. If you want to respond to specific channel events, see the TwitchChannel object below.
Here
"use strict";
var TwitchChat = require('twitched');
// create the TwitchChat client
var chat = new TwitchChat("Username", "OAuthPassword");
var summit = chat.join("summit");
// chat events
chat.onConnect(() => {}); // the client has connected to Twitch
chat.onDisconnect(() => {}); // the client has disconnected from Twitch
chat.onMessage((channel, user, message) => {}); // the client has received a chat message
chat.onChannelJoin((channel) => {}); // the client has joined a channel
chat.onChannelLeave((channel) => {}); // the client has left a channel
chat.onLoginError(() => {}); // the client was unable to authenticateTwitchChannel
The TwitchChannel object allows you to define event handlers for events that occur specifically on that channel only. This is extremely powerful as it allows you to define different handlers on different channels.
Note the TwitchChannel should NOT be created directly; rather, use the TwitchChat object's .join() method instead.
The following example shows the basic usage and how each channel can have different handlers for the same event.
"use string";
var TwitchChat = require('twitched');
// create the TwitchChat client
var chat = new TwitchChat("Username", "OAuthPassword");
// create and join two TwitchChannel objects
var summit = chat.join("summit1g");
var sodapoppin = chat.join("sodapoppin");
// defines a message handler that is specific to summit1g's channel
summit.onMessage((user, message) => {
console.log(`Received message from ${user} on summit's channel.`);
});
// defines a message handler that is specific to sodapoppin's channel
sodapoppin.onMessage((user, message) => {
console.log(`Sodapoppin received a message from ${user}.`);
});
// connect to Twitch
chat.connect();The TwitchChannel object also defines events that you can register handlers for and respond to, as well as exposing common Twitch chat functions. For a better explanation of the Twitch chat functions, head over to Twitch Chat and Moderation Commands
Here is a quick run down of the TwitchChannel object's API.
"use string";
var TwitchChat = require('twitched');
// create the TwitchChat client
var chat = new TwitchChat("Username", "OAuthPassword");
var summit = chat.join("summit1g");
// TwitchChannel event handlers
summit.onJoin(() => {}); // the client has joined the channel
summit.onLeave(() => {}); // the client has left the channel
summit.onUserJoin((user) => {}); // a user has joined the channel
summit.onUserLeave((user) => {}); // a user has left the channel
summit.onMessage((user, message) => {}); // a message has been received
// TwitchChannel chat function
summit.clearChat(); // clears all messages in chat
summit.banUser("mervman"); // bans a user from chat
summit.unbanUser("mervman"); // unbans a user from chat
summit.timeoutUser("mervman", 60); // times out a user for a number of seconds
summit.slowOn(); // enables slow mode
summit.slowOff(); // disables slow mode
summit.subscribersOn(); // enables subscriber only mode in chat
summit.subscribersOff(); // disables subscriber only mode in chat
summit.r9kOn(); // enables R9K
summit.r9kOff(); // disable R9KThe TwitchChannel also allows you to define custom commands to can be responded to which is perfect for creating bots. Each command must begin with the "!" character.
"use string";
var TwitchChat = require('twitched');
// create the TwitchChat client
var chat = new TwitchChat("Username", "OAuthPassword");
var summit = chat.join("summit1g");
// greets a user
summit.command("!hello", (user, message) => {
summit.send(`Hello @${user}! We hope you enjoy the stream`);
});
// tells a joke
summit.command("!joke", (user, message) => {
summit.send("What do you call a 3 humped camel.......? PREGNANT! Ha!");
});
// connect to Twitch
chat.connect();Examples
There are many examples that you can run and play with in the examples/ folder in this repository. You may use and modify all code found in the example files to fit your needs.
Contributing
I am always looking to improve this library and welcome all suggestions and criticisms. If you would like to contribute, you can issue a pull request and I will be sure to take a look.
Thanks!
