Twitch — Live Notifications

GrumpyTwitch watches Twitch streamers and automatically posts an announcement when they go live.

---

Activation

In configs/config.yml:

addons:
  twitch: true   # Default: true (active as soon as the bot starts)

twitchClientId: ""      # Twitch app Client ID (dev.twitch.tv) — required for live detection
twitchClientSecret: ""  # Twitch app Client Secret — required for live detection

Credentials required — unlike YouTube! Twitch has no anonymous way to query a streamer's live status. Without twitchClientId/twitchClientSecret, /twitch add, /twitch remove, and /twitch list remain fully usable (pure database management), but the actual live poller does nothing — no live checks are ever performed. On bot startup, the setup status banner clearly shows this state:

twitch: 🟡 enabled (no credentials — inactive)

Once both fields are set and the bot has been restarted, the status switches to 🟢 enabled.

Registering a Twitch App

1. Log in at dev.twitch.tv/console/apps (a free Twitch account is enough) and create a new app.
2. After creating it, copy the Client ID and generate a new Client Secret.
3. Enter both values in configs/config.yml as twitchClientId / twitchClientSecret.
4. Restart the bot.

The OAuth redirect URL set when creating the app doesn't matter — GrumpyCore only uses the App Access Token via the client_credentials flow (no user login, no redirect needed).

---

Configuration File

There is no configs/modules/twitch.yml. The module has no configurable values in a module YAML — the credentials live at the top level of configs/config.yml (twitchClientId/twitchClientSecret, see above), and watched streamers are managed entirely via slash commands in the database.

---

Commands

All subcommands require Manage Guild permission and are guild-only (no DMs).

/twitch add

Watches a new Twitch streamer.

Option	Required	Description
login	✅	Twitch username
channel	❌	Text/announcement channel for live announcements (default: current channel)
ping-role	❌	Role pinged when they go live

/twitch add login:somestreamer
/twitch add login:somestreamer channel:#stream-alerts ping-role:@Stream-Fans

If Twitch credentials aren't configured, the watch is still created — the confirmation additionally includes a note that monitoring will only become active once twitchClientId/twitchClientSecret are set up.

Limit: maximum 10 watched streamers per server.

---

/twitch remove <id>

Removes a watch by the ID shown in /twitch list.

/twitch remove id:3

---

/twitch list

Lists all watched streamers on the server with ID, login name, notify channel, ping role if set, and current live status (🔴 if currently live).

/twitch list

---

Flow & Details

• Poll interval: every 5 minutes the live status of all watched streamers (batched across all servers) is queried via the Twitch Helix API (GET /helix/streams). A single call costs only 1 point regardless of how many logins it carries (rate limit: 800 points/minute) — up to 100 logins are batched per request.
• Edge detection (offline → live): an announcement is only posted on the transition from offline to live, not on every tick while the stream keeps running. The live state (isLive) is stored per watch in the database and compared on every tick.
• App Access Token: the bot automatically fetches a Twitch app access token (client_credentials flow) and caches it until shortly before it expires (with a safety margin), so it doesn't need to request a new one on every tick.
• Announcement: purple embed (Twitch color) with stream title, game, viewer count, thumbnail, and stream link; optionally pings the configured role.
• Without credentials: the poller skips every tick entirely (debug-level log only, no spam) as long as twitchClientId/twitchClientSecret are missing.

---

Permissions

Action	Permission
/twitch add / remove / list	Manage Guild
Bot posting the announcement	Send Messages in the notify channel
Twitch app registration	Bot admin's Twitch account (free, outside Discord)