simple-helix-api

About

simple-helix-api is a package needed to simplify working with the Twitch API.

The library was created following the Twitch API documentation as much as possible. All requests are divided into categories for ease of use. Below is a list of current categories supported by package.

analytics, automod, channel, chat, clips, commercial, events, games, markers, moderation, other, polls, predictions, rewards, schedule, search, soundtrack, streams, subscriptions, tags, teams, users, videos

In addition, some requests that are associated with a list of something (a list of users, categories, clips, etc.) have one request in order to get a complete list.

Usage

Before we starting, be sure you have client_id registered in Dev Dashboard on Twitch.

Access Token

First, you need for Access Token provided by Twitch. With this package you can generate link to the endpoint that returns Access Token to you. If you already have, then skip this step.

const HelixAPI = require("simple-helix-api"); // you can use import

// Create client
const Helix = new HelixAPI({
    client_id: "xxxxxxx" // client_id from Twitch Dev Dashboard
});

// List of scopes you need for your application. Left it empty to request all scopes. See scopes list: https://dev.twitch.tv/docs/authentication#scopes
const scopes = ["chat:read", "channel:manage:predictions", "moderation:read"];

// Redirect uri must match to specified in Twitch Dev Dashboard
const redirect_uri = "http://localhost...";

// Generate auth link
const link = Helix.getAuthLink(scopes, redirect_uri);
console.log(link);

Now you can use this package on full power.

Example

Let's look at a basic example of working with package. In this example, we will get and output user information to the console.

Almost all requests requires an user ID. Get yours, store it and use everywhere.

Attetion! All requests and categories names matches with Twitch API documentation, but recommended to use autocomplete of your favorite code editor to see all categories and requests.

const HelixAPI = require("simple-helix-api");

const Helix = new HelixAPI({
    access_token: "xxxxxxx", // Your personal Access Token provided by Twitch. If you don't have one, see step above.
    client_id: "xxxxxxx" // Client ID from Twitch Dev Dashboard
});

(async () => {
    const user = await Helix.users.get("InfiniteHorror"); // Also you can specify user ID instead of user login
    console.log(user);
})();

More examples

There is a several examples of requests you can use with this package. Be aware that some requests requires additional parameters, so check the official documentation on the Twitch Dev Portal.

Update stream title and category

const game = await Helix.games.get("League of Legends");
const updated = await Helix.channel.modify(user_id, game.id, "en", "Title has been changed with simple-helix-api");

Start commercial

await Helix.commercial.start(user_id, 30);

Update chat settings

Some requests requires moderator ID. Moderator ID can be equal to the user ID.

await Helix.chat.updateSettings(user_id, moderator_id, {
    follower_mode: true,
    follower_mode_duration: 10
});

Ban user

const user = await Helix.users.get("anyToxicPerson");
await Helix.moderation.ban(user_id, user_id, {
    user_id: user.id,
    reason: "Friendship is Magic"
});

Get all followers of channel

const followers = await Helix.users.allFollows(user_id);
console.log(followers);

Get all clips of channel

The time of response depends on count of clips of your channel.

const clips = await Helix.clips.all(user_id);
console.log(clips);

EventSub Websocket

Release version: 3.1.0

Description: You can receive realtime notifications using Websocket.

You can check all events on this page.

Example

const HelixAPI = require("simple-helix-api"); // you can use import

// Init Helix instance
const Helix = new HelixAPI({
    access_token: "xxxxxxx",
    client_id: "xxxxxxx"
});

// Listen connect and disconnect events
Helix.EventSub.events.on(Helix.EventSub.WebsocketEvents.CONNECTED, () => {
    console.log("Connected to WebSocket");
});

Helix.EventSub.events.on(Helix.EventSub.WebsocketEvents.DISCONNECTED, () => {
    console.log("Disconnected from WebSocket");
});

// List of conditions. Each event can have different from each other conditions, so please check Twitch docs.
const conditions = [{
    broadcaster_user_id: String("user_id here") // User ID and other numbers must be converted to string for condition
}];

// Create EventSub client
const EventSubClient = await Helix.EventSub.connect();

// Register listeners for events
EventSubClient.subscribe("channel.follow", conditions[0], follow => {
    console.log(`Thank you for following, ${follow.user_name}`);
});

Chat Client

Release version: 3.3.0
Description: Create your own chatbot.

All you need to connecting to chat is OAuth password.

Available chat events:

sub, resub, subgift, submysterygift, giftpaidupgrade, rewardgift, anongiftpaidupgrade, raid, unraid, ritual, bitsbadgetier, clear, delete, ban

You can check all available chat events and tags for chat events here.

Example

const HelixAPI = require("simple-helix-api"); // you can use import

// Init Helix instance
const Helix = new HelixAPI({
    access_token: "xxxxxxx",
    client_id: "xxxxxxx"
});

const username = "USERNAME", // Bot or your channel username
const password = "oauth:PASSWORD", // OAuth password
const channels = ["channel1"] // Optional. Leave it blank or null to autoconnect to your channel
const secure = true; // Optional. Use secure connection (443)

Helix.tmi.events.on(Helix.tmi.WebsocketEvents.CONNECTED, () => {
    console.log("Chat client connected");
});

Helix.tmi.events.on(Helix.tmi.WebsocketEvents.DISCONNECTED, () => {
    console.log("Chat client disconnected");
});

const chat = await Helix.tmi.connect(username, password, channels, secure);

// Listen regular messages, highlighted messages or reward messages
chat.on("message", message => {
    const username = message["display-name"];
    console.log(`${username}: ${message.text}`);
});

/*
    Listen chat events.
    Chat events tags can be found here:
    https://dev.twitch.tv/docs/irc/tags#usernotice-tags
*/

// Listen sub event
chat.on("sub", sub => {
    const subscriber = sub["display-name"];
    const plan = sub["msg-param-sub-plan-name"];
    console.log(`${subscriber} has subscribed to the channel with ${plan}`);
});

// Listen sub event
chat.on("resub", resub => {
    const subscriber = resub["display-name"];
    const streak = resub["msg-param-streak-months"];
    console.log(`${subscriber} is resubscribed to the channel for the ${streak} month in a row`);
});

// Listen raid event
chat.on("raid", raid => {
    const raider = raid["msg-param-displayName"];
    const viewers = raid["msg-param-viewerCount"];
    console.log(`${raider} raiding with ${viewers} viewers`);
});

// Listen clear chat event
chat.on("clear", () => {
    console.log("Chat has been cleared");
});

// Sending commands
// chat.command("ban", shine_discord21); // Pass single argumnet to chat command
// chat.command("ban", ["shine_discord21", "Some bot account"]); // Pass multiple arguments to chat command
chat.command("clearchat");

const date = new Date().toLocaleTimeString();
chat.say(`[Chat Client]: connected at ${date}`, channels);

Contribution

Sometimes I may miss some changes in the Twitch API, so I will be glad of any help. Feel free to fork and share PR's.

You can report of any issues here.