ChatSage

ChatSage is an AI-powered chatbot designed for Twitch chat environments in any language. It provides contextually relevant responses based on chat history, user queries, and real-time stream information (current game, title, tags).

Important: Access to the cloud version of ChatSage is currently invite-only via an allow-list. The self-serve web dashboard is disabled for unapproved channels. If you'd like to try the bot, please contact me here: Contact form.

Table of Contents

• Features (Core Capabilities)
• Adding ChatSage to Your Channel
• Usage Examples
• Development Prerequisites
• Getting Started
• Running the Bot
• Configuration
• Twitch Token Management
• Docker

Features (Core Capabilities)

• Receives chat messages via Twitch EventSub webhooks and sends replies via the Twitch Helix API.
• Fetches real-time stream context (game, title, tags, thumbnail images) using the Twitch Helix API.
• Utilizes Google's Gemini 3 Flash LLM for natural language understanding and response generation (lightweight commands like !lurk and !translate use Gemini 3.1 Flash Lite for speed and cost efficiency).
• Maintains conversation context (history and summaries) per channel.
• Supports custom chat commands with permission levels.
• Configurable bot language settings for multilingual channel support.
• Configurable through environment variables.
• Includes structured logging suitable for production environments.
• Web-based channel management interface for streamers to add/remove the bot.

Adding ChatSage to Your Channel

Note: Only pre-approved channels on the allow-list can enable ChatSage. If you are not yet approved but want to try it, please reach out via the Contact form.

If your channel is approved, you can add or remove ChatSage using the web interface:

1. Visit the ChatSage Management Portal:

   • Go to ChatSage Management Portal (approved channels only)
   • Click on "Login with Twitch"

2. Authorize the Application:

   • You'll be redirected to Twitch to authorize ChatSage
   • Grant the required permissions
   • This process is secure and uses Twitch's OAuth flow

3. Manage the Bot:

   • Once logged in, you'll see your dashboard
   • Use the "Add Bot to My Channel" button to have ChatSage join your channel
   • Use "Remove Bot from My Channel" if you want to remove it

4. Bot Joining Time:

   • After adding the bot, it should join your channel within a few minutes
   • If the bot doesn't join after 10 minutes, please try removing and adding again
   • Important: if the bot is not responding, grant it mod status with the command "/mod ChatSageBot"

5. User Interaction:

   • Viewers can interact with ChatSage by mentioning it: @ChatSageBot hello (the username will be updated to reflect the new name, ChatSage, when Twitch allows me)
   • Or by using various commands like !ask, !translate, etc.

Usage Examples

Chat Commands

For a complete list of available commands and their usage, please visit Bot Commands Documentation.

Context-Aware Responses

ChatSage understands the flow of conversation. For example, the !lurk command provides a polite, contextual send-off.

Scenario: The chat is discussing making dinner.

User: !lurk going to make some pasta

ChatSageBot: @user, enjoy making the pasta! Hope it turns out delicious. We'll be here when you get back!

This demonstrates how the bot can craft personalized responses based on both the command and the user's provided reason.

Development Prerequisites

• Node.js (Version 22.0.0 or later recommended)
• npm (or yarn)

Getting Started

1. Clone the repository:

   git clone [https://github.com/detekoi/chatsage.git](https://github.com/detekoi/chatsage.git)
   cd chatsage

2. Install dependencies:

   npm install

   (Or yarn install if you prefer Yarn)

3. Configure environment variables:

   • Copy the example environment file:

     cp .env.example .env

   • Edit the .env file and fill in your credentials and settings. Refer to the comments within .env.example for details on each variable (Twitch bot username/token, Twitch application client ID/secret, Gemini API key, channels to join, etc.). Do not commit your .env file.

Running the Bot

• Development: Uses Node's built-in watch mode for automatic restarts on file changes. Enables human-readable ("pretty") logs by default if PINO_PRETTY_LOGGING=true in .env.

  npm run dev

• Production: Runs the bot using standard node. Outputs structured JSON logs suitable for log aggregation systems.

  npm start

Configuration

ChatSage is configured primarily through environment variables. The required and optional variables are documented in the .env.example file. Key variables include:

• TWITCH_BOT_USERNAME: Username for the bot's Twitch account.
• TWITCH_CHANNELS: Comma-separated list of channels to join. Used as fallback if Firestore channel management is unavailable.
• TWITCH_CHANNELS_SECRET_NAME: Resource name for the channels list in Google Secret Manager. Used as fallback if Firestore channel management is unavailable.
• GEMINI_API_KEY: Your API key for the Google Gemini service.
• TWITCH_CLIENT_ID, TWITCH_CLIENT_SECRET: Credentials for your registered Twitch application (used for Helix API calls).
• TWITCH_BOT_REFRESH_TOKEN_SECRET_NAME: Resource name for the refresh token in Google Secret Manager.
• STREAM_INFO_FETCH_INTERVAL_SECONDS: How often to refresh stream context data.
• LOG_LEVEL: Controls the verbosity of logs.

Ensure all required variables are set in your environment or .env file before running the bot.

Twitch Token Management

ChatSage uses a secure token refresh mechanism to maintain authentication with Twitch:

Bot Authentication

1. Prerequisites for Token Generation:

   • Twitch Application: Ensure you have registered an application on the Twitch Developer Console. Note your Client ID and generate a Client Secret.
   • OAuth Redirect URI: In your Twitch Application settings, add http://localhost:3000 as an OAuth Redirect URL. The Twitch CLI specifically uses this as the first redirect URL by default.
   • Twitch CLI: Install the Twitch CLI on your local machine.

2. Configure Twitch CLI:

   • Open your terminal or command prompt.
   • Run twitch configure.
   • When prompted, enter the Client ID and Client Secret from your Twitch Application.

3. Generate User Access Token and Refresh Token using Twitch CLI:

   • Run the following command in your terminal. Replace <your_scopes> with a space-separated list of scopes required for your bot. For ChatSage, you need at least user:read:chat and user:write:chat.

     twitch token -u -s 'user:read:chat user:write:chat'

     (You can add other scopes if your bot's custom commands need them, e.g., channel:manage:polls channel:read:subscriptions)

   • The CLI will output a URL. Copy this URL and paste it into your web browser.

   • Log in to Twitch using the Twitch account you want the bot to use.

   • Authorize your application for the requested scopes.

   • After authorization, Twitch will redirect your browser to http://localhost:3000. The CLI, which temporarily runs a local server, will capture the authorization code and exchange it for tokens.

   • The CLI will then print the User Access Token, Refresh Token, Expires At (for the access token), and the Scopes granted.

4. Store the Refresh Token Securely:

   • From the Twitch CLI output, copy the Refresh Token. This is the crucial token your bot needs for long-term authentication.
   • Store this Refresh Token securely in Google Secret Manager.

5. Google Secret Manager Setup:

   • Create a Google Cloud Project if you don't have one.
   • Enable the Secret Manager API in your project.
   • Create a new secret in Secret Manager to store the Twitch Refresh Token you just obtained.
   • Note the Resource Name of this secret. It will look like projects/YOUR_PROJECT_ID/secrets/YOUR_SECRET_NAME/versions/latest.
   • Set this full resource name as the value for the TWITCH_BOT_REFRESH_TOKEN_SECRET_NAME environment variable in your bot's configuration (e.g., in your .env file or Cloud Run environment variables).
   • Ensure the service account running your ChatSage application (whether locally via ADC or in Cloud Run) has the "Secret Manager Secret Accessor" IAM role for this secret.

6. Authentication Flow in ChatSage:

   • On startup, ChatSage (specifically auth.js) will use the TWITCH_BOT_REFRESH_TOKEN_SECRET_NAME to fetch the stored refresh token from Google Secret Manager.
   • It will then use this refresh token, along with your application's TWITCH_CLIENT_ID and TWITCH_CLIENT_SECRET, to obtain a fresh, short-lived OAuth Access Token from Twitch.
   • This access token is used to authenticate with the Twitch Helix API for sending chat messages and subscribing to EventSub webhooks.
   • If the access token expires or becomes invalid, the bot will use the refresh token to automatically obtain a new one.
   • If the refresh token itself becomes invalid (e.g., revoked by Twitch, user password change), the application will log a critical error, and you will need to repeat the token generation process (Steps 3-4) to get a new refresh token.

Channel Management Web UI

The web interface uses a separate OAuth flow to allow streamers to manage the bot in their channel:

1. Firebase Functions Setup:

   • The web UI is built with Firebase Functions and Hosting.
   • It uses Twitch OAuth to authenticate streamers.
   • When a streamer adds or removes the bot, it updates a Firestore collection.
   • The bot periodically checks this collection to determine which channels to join or leave.

2. Environment Variables for Web UI:

   • TWITCH_CLIENT_ID: Twitch application client ID.
   • TWITCH_CLIENT_SECRET: Twitch application client secret.
   • CALLBACK_URL: The OAuth callback URL (your deployed function URL).
   • FRONTEND_URL: The URL of your web interface.
   • JWT_SECRET_KEY: Secret for signing authentication tokens.
   • SESSION_COOKIE_SECRET: Secret for session cookies.

This approach provides better security by using standard OAuth flows and official tools, and not storing sensitive tokens directly in configuration files where possible. It also gives streamers control over adding or removing the bot from their channel.

EventSub for Serverless Deployment (Optional)

This project supports Twitch's EventSub to enable a "scale-to-zero" serverless deployment on platforms like Google Cloud Run. This significantly reduces hosting costs by only running the bot when a channel it's in is live.

Overview

• How it works: The bot subscribes to stream.online events. When a streamer goes live, Twitch sends a webhook that starts the bot instance. The bot stays active while the stream is live and scales down to zero instances when all monitored channels are offline.
• Cost Savings: This model can reduce hosting costs significantly.

Required Environment Variables

To enable this feature, set the following in your deployment environment (e.g., Cloud Run):

• LAZY_CONNECT=true: Enables the scale-to-zero logic.
• TWITCH_EVENTSUB_SECRET: A long, random, secret string you create to secure your webhook endpoint.
• PUBLIC_URL: The public-facing URL of your deployed service (e.g., https://your-service.a.run.app).

Setup Process

1. Deploy with EventSub Variables: Deploy your application with the environment variables listed above. For Cloud Run, you would use gcloud run deploy with --set-env-vars.

2. Subscribe to Events: After deploying, run the management script to subscribe all your channels to the stream.online event.

   node scripts/manage-eventsub.js subscribe-all

3. Verify Subscriptions: You can check that the subscriptions were created successfully:

   node scripts/manage-eventsub.js list

This setup ensures the bot only consumes resources when it needs to be active in a live channel.

Docker

A Dockerfile is provided for building a container image of the application.

1. Build the image:

   docker build -t chatsage:latest .

2. Run the container: You need to pass the environment variables to the container. One way is using an environment file:

   docker run --rm --env-file ./.env -it chatsage:latest

   (Ensure your .env file is populated correctly)

Deploying to Cloud Run (locally)

For a local deploy that mirrors the GitHub Actions workflow, use the portable script:

scripts/deploy-cloud-run.sh --project streamsage-bot --region us-central1 --service chatsage

Notes:

• The script uses the same env and secret mappings as .github/workflows/deploy-cloud-run.yml.
• You must be authenticated with gcloud and have access to the project’s secrets.
• On first deploy, PUBLIC_URL can be empty. After deploy, the script prints the URL; set PUBLIC_URL to that value and redeploy for EventSub callbacks.

Examples:

# First deploy
scripts/deploy-cloud-run.sh

# After you get the URL, redeploy with PUBLIC_URL set
PUBLIC_URL="https://chatsage-XXXX-uc.a.run.app" \
  scripts/deploy-cloud-run.sh --project streamsage-bot --region us-central1 --service chatsage