Grim Games Live Grim Games Live

GRiMbot documentation

SETUP BOT

This is the hosted copy of the GRiMbot technical manual. Use the table of contents to open any page in the manual.

GRiMbot product page Manual home

SETUP BOT

Purpose and scope

System → SETUP BOT records the Twitch application, channel, GRiMbOS credentials, Twitch account authorizations, and Bot Timezone. Complete this procedure before configuring Twitch-dependent features.

Prerequisites

  • GRiMbot is running and GRiMbOS is open.
  • You can sign in to the Twitch broadcaster account.
  • Twitch two-factor authentication is enabled on the account used for the Twitch Developer Console.
  • You can create an application in the Twitch Developer Console.
  • You know the channel login in lowercase.
  • You have chosen a unique GRiMbOS username and password.
  • You know the correct IANA Bot Timezone.
  • A separate Twitch bot account is available if Chat Messages should use a different name.

Procedure

1. Record the Twitch application

  1. Open System → SETUP BOT.
  2. Select Twitch App.
  3. Copy the OAuth redirect address displayed by GRiMbOS.
  4. Open the Twitch Developer Console while signed in to the account that will manage the application.
  5. Open the page to create or manage an application.
  6. Create an application with a unique application name.
  7. Add the redirect URL displayed in GRiMbOS to OAuth Redirect URLs exactly as shown.
  8. Select Application Integration for the category.
  9. Select Confidential for the client type.
  10. Create the application.
  11. Copy its Client ID into GRiMbOS.
  12. In the Twitch application, click New Secret.
  13. Copy the new Client Secret into GRiMbOS.
  14. Enter Channel name as the Twitch login in lowercase, without #.
  15. Keep the GRiMbOS username already set in .env, or enter a new unique value.
  16. Leave GRiMbOS password blank to keep the value set in .env, or enter a new unique value.
  17. Click Save configuration.
  18. If you changed the GRiMbOS username or password, sign out and sign in with the new credentials.

Each click on Save configuration requests a new TWITCH_EVENTSUB_SECRET. The new value replaces the previous value. Packaged local installations use WebSocket EventSub, so this secret replacement does not require manual webhook subscription work.

[!SECURITY] Twitch may show a newly created Client Secret only once. Clicking New Secret invalidates the old Client Secret. Store the new value in an approved password manager. Never paste it into chat, screenshots, issue reports, or wiki pages.

2. Authorize Twitch accounts

  1. Select Sign-In.
  2. Click Sign in as broadcaster….
  3. In the new Twitch tab, confirm that the displayed Twitch account is the broadcaster account.
  4. Approve the requested access.
  5. Return to GRiMbOS and confirm that the broadcaster account is connected.
  6. If using a separate bot account, sign out of the wrong Twitch session first or use a private browser window.
  7. Click Sign in as bot….
  8. Confirm that the displayed account is the bot account.
  9. Approve the requested access.
  10. Select Progress and click Refresh.
  11. Confirm that Twitch events arrive over shows websocket on a packaged local installation.
  12. Trigger a real Twitch EventSub event that is safe for the channel, such as a new follow from an account that is not already following.
  13. Confirm that GRiMbot receives and processes the event.

The broadcaster account is required. The bot account is optional. Without a separate bot authorization, GRiMbot sends Chat Messages as the broadcaster.

Packaged local installations restart WebSocket EventSub and create its subscriptions automatically after authorization. Do not use Re-subscribe EventSub for this local WebSocket setup.

3. Use the callback fallback only when needed

If Twitch approves access but the callback page cannot load:

  1. Copy the full URL from the failed callback tab.
  2. Return to Sign-In.
  3. Set Account to the account you just authorized.
  4. Paste the full URL into Pasted address.
  5. Click Finish sign-in.

[!IMPORTANT] Treat the full callback URL as sensitive. It contains a short-lived authorization code. Paste it only into your own GRiMbOS window.

4. Set Bot Timezone

  1. Select Bot Timezone.
  2. Choose the IANA timezone for the broadcaster's location, such as America/Chicago.
  3. Click Save.

GRiMbOS uses Bot Timezone for features that need local date or time, including the stream schedule and Discord Custom Announcement stream start.

5. Confirm completion

  1. Select Progress.
  2. Click Refresh.
  3. Confirm that the status line says Setup is complete.
  4. Confirm the displayed Chat Message identity.
  5. Confirm that Twitch events arrive over shows the expected transport.
  6. Verify Bot Timezone separately on the Bot Timezone tab.
  7. Verify that the GRiMbOS password is not a shipped default by checking the local .env.

[!NOTE] Setup is complete. appears when the Twitch application details, channel name, and broadcaster authorization are complete. It does not include Bot Timezone or a non-default GRiMbOS password.

Settings and choices

Setting Required Operator guidance
Client ID Yes Copy it from the registered Twitch application.
Client Secret Yes Create it in the Twitch Developer Console. Leave the field blank later to keep the saved value.
Channel name Yes Enter the Twitch channel login in lowercase.
GRiMbOS username Yes Use this name only for GRiMbOS admin access.
GRiMbOS password Yes Use a unique password. Leave the field blank later to keep the saved value.
Broadcaster authorization Yes Grants access for Twitch channel operations and EventSub topics.
Bot authorization No Changes the Chat Message identity to the separate bot account.
Bot Timezone Yes Choose a valid IANA timezone.

For a local installation with no public base URL, SETUP BOT selects WebSocket EventSub. Twitch OAuth accepts an HTTP redirect only for loopback addresses such as 127.0.0.1 or localhost. Other OAuth redirects must use HTTPS.

Save configuration replaces the EventSub secret even when the visible values did not change. Do not use it as a status refresh. Use Refresh on Progress for that purpose.

The Save button on the Bot Timezone tab saves Bot Timezone. It does not request another EventSub secret when one is already set.

Re-subscribe EventSub is for a separately managed webhook deployment. After Save configuration replaces its secret, recreate the webhook subscriptions unless authorization is being completed immediately afterward. Authorization recreates webhook subscriptions automatically.

Expected result

The Progress tab says Setup is complete., the Chat Message identity is correct, the displayed EventSub transport is correct, a real EventSub event has been received, Bot Timezone is saved, and the local .env has unique GRiMbOS credentials.

Verification checklist

  • [ ] The OAuth redirect address in Twitch matches GRiMbOS exactly.
  • [ ] Twitch two-factor authentication is enabled for the application manager.
  • [ ] The Twitch application has a unique name.
  • [ ] Category is Application Integration.
  • [ ] Client type is Confidential.
  • [ ] The Client ID and Client Secret are saved.
  • [ ] Channel name is the lowercase Twitch login.
  • [ ] The GRiMbOS password is not the default placeholder.
  • [ ] The broadcaster account is authorized.
  • [ ] The bot account is authorized if a separate Chat Message identity is required.
  • [ ] Bot Timezone matches the broadcaster's local timezone.
  • [ ] Progress says Setup is complete.
  • [ ] Bot Timezone and the GRiMbOS password were verified separately from Progress.
  • [ ] Twitch events arrive over shows websocket for the packaged local installation.
  • [ ] A real Twitch EventSub event was received and processed.
  • [ ] Re-subscribe EventSub was used only if this is a separately managed webhook deployment.
  • [ ] Connection Status reports the expected Twitch account state.

Failure handling

If Twitch reports a redirect mismatch, copy the address from Twitch App again and replace the Twitch application's OAuth Redirect URL. Match the scheme, host, port, path, and trailing slash exactly.

If the wrong Twitch account is authorized, open System → System Status, re-authorize the correct account, and verify the Chat Message identity.

If authorization succeeds but GRiMbOS cannot load the callback, use the Pasted address procedure above.

If a feature later reports missing Twitch permission, open System → System Status and re-authorize the broadcaster account. Local WebSocket EventSub restarts automatically. A webhook deployment may then use Re-subscribe EventSub if its subscriptions still need to be recreated.

If the transport shown on Progress is not websocket for a packaged local installation, review the EventSub configuration before testing an event.

If the real EventSub event is not received, re-authorize the broadcaster account and repeat the test. Do not use Event Emulator as proof of the Twitch EventSub connection.

If Bot Timezone is rejected, select a valid IANA timezone from the list instead of entering a timezone abbreviation.

If Twitch rejects the Client Secret after New Secret was clicked, copy the newest secret into GRiMbOS. The previous secret no longer works.

If GRiMbOS requests credentials after Save configuration, sign in with the new GRiMbOS username and password.

Security and data notes

  • SETUP BOT writes sensitive values to the GRiMbot environment configuration.
  • Each Save configuration replaces TWITCH_EVENTSUB_SECRET.
  • Twitch OAuth access and refresh tokens are stored on the bot machine.
  • The GRiMbOS password protects admin API requests. Restrict access to the admin address.
  • Do not expose Twitch secrets, OAuth callback URLs, tokens, or the .env file.
  • Local WebSocket EventSub does not require a public URL or inbound internet port.

Related pages