youtube-chat

To use youtube-chat, import the LiveChat class, instantiate it with either a channelId or a liveId, set up event listeners for chat messages and lifecycle events, and then call .start().

Note: If you provide a channelId, the library will automatically attempt to acquire the current liveId for that channel.

const { LiveChat } = require("youtube-chat");

// Recommended: use channelId to automatically find the current liveId
const liveChat = new LiveChat({ channelId: "CHANNEL_ID_HERE" });

// Listen for chat messages
liveChat.on("chat", (chatItem) => {
  console.log(chatItem.author.name, chatItem.message);
});

// Start the fetch loop
const ok = await liveChat.start();
if (!ok) {
  console.log("Failed to start, check emitted error");
}

// To stop the loop later:
// liveChat.stop();

Install the youtube-chat package using npm or yarn to fetch YouTube live chat without using the official API.

npm i youtube-chat
# or
yarn add youtube-chat

Use start() to begin the polling process and stop() to terminate it.

• start(): An asynchronous method that attempts to fetch the live page options. If successful, it sets up a periodic interval to fetch chat items and emits the start event. Returns true if started, false if already running or if an error occurred.
• stop(reason?: string): Clears the internal polling interval and emits the end event with the provided reason.

const liveChat = new LiveChat({ liveId: '...' });

// Start polling
const success = await liveChat.start();

if (success) {
  // ... listen to events ...
}

// Stop polling
liveChat.stop('Closing application');

The LiveChat class is the primary entry point for interacting with YouTube live chat. You can import it from the youtube-chat package to manage live chat sessions.

import { LiveChat } from "youtube-chat";

// Usage depends on the implementation details of LiveChat
// typically involving providing a video ID or chat ID.

The LiveChat constructor requires a YoutubeId object. The object must contain at least one of the following keys:

• liveId: The specific ID of the live broadcast.
• channelId: The ID of the YouTube channel.
• handle: The YouTube handle of the creator.

If none of these are provided, the constructor throws a TypeError.

// Example valid YoutubeId shapes:
new LiveChat({ liveId: 'abc123xyz' });
new LiveChat({ channelId: 'UC...' });
new LiveChat({ handle: '@username' });

The ChatItem interface represents the structured format of a single chat entry after processing. It contains information about the author, the message content (which can be text or emojis), superchat details, and user status flags (membership, verification, ownership, and moderation).

export interface ChatItem {
  id: string
  author: {
    name: string
    thumbnail?: ImageItem
    channelId: string
    badge?: {
      thumbnail: ImageItem
      label: string
    }
  }
  message: MessageItem[]
  superchat?: {
    amount: string
    color: string
    sticker?: ImageItem
  }
  isMembership: boolean
  isVerified: boolean
  isOwner: boolean
  isModerator: boolean
  timestamp: Date
}

The ImageItem interface is a standard structure for images used throughout the chat data, such as author thumbnails, badges, or superchat stickers.

export interface ImageItem {
  url: string
  alt: string
}

The YoutubeId type is a union used to specify which YouTube entity to target for chat retrieval. It can be identified by a channelId, a liveId (for a specific live stream), or a handle.

export type YoutubeId = { channelId: string } | { liveId: string } | { handle: string }

The EmojiItem interface extends ImageItem and is used when a chat message contains a custom emoji. It includes the emojiText and a flag isCustomEmoji to distinguish it from standard images.

export interface EmojiItem extends ImageItem {
  emojiText: string
  isCustomEmoji: boolean
}