Bot Control

Bot Control is the runtime switchboard for every chat / social bot Lumio runs on behalf of accounts. It surfaces each account × platform combination and lets operators pause or resume the bot without touching account-level configuration. Use it for incident response, platform rate-limit flare-ups, or when debugging a single account's bot behaviour.

Where to find it

Admin sidebar → Bot Control (/bot-control).

Quick start

1. Open Admin → Bot Control.
2. Filter by platform and/or search by account name or ID.
3. Find the account card and, inside it, the row for the misbehaving platform.
4. Click Pause to stop it immediately, or Resume to bring it back.
5. Watch the status badge update: Active, Paused, or No Connection.

Detailed walkthrough

Layout

The page fetches every account × platform status in one call and renders one card per account. The card header is the account name plus the first 8 characters of the account ID. Inside the card, each platform the account touches gets a row.

Status badges

Each row shows one of three states, derived from has_channel_connection and bot_enabled:

• Active — the account has a channel connection and the bot is enabled.
• Paused — the connection exists but the bot is explicitly disabled. No messages are sent or received.
• No Connection — the account has no channel connection for this platform. Pause / Resume is hidden.

Filters

• Search — client-side match against account name or account ID over the already-loaded data. Not debounced, because nothing is refetched.
• Platform — dropdown with "All Platforms" plus the distinct platforms actually present in the loaded data, so the option list reflects real connections rather than a fixed platform list.

Row contents

Platform icon, platform name, bot username (or --), status badge, and the Pause / Resume button. Rows without a connection show the badge and no button.

Pause / Resume

The button posts to /api/bot-statuses/toggle with { account_id, platform, enabled }. The backend flips the bot-enabled flag and publishes the change on a Redis pub/sub bot-action channel so the relevant bot worker picks it up. The UI updates the row optimistically instead of refetching the whole list.

The Pause / Resume button is not permission-gated in the UI — enforcement is server-side on bot-control:edit. An admin holding only bot-control:read sees the button but the call returns 403.

Common scenarios

• Twitch platform incident — filter by twitch; there is no select-all, so pause accounts one by one or use the Providers page to flip the global kill-switch.
• Customer-reported bot spam — find the account, pause it on the affected platform, investigate bot commands / modules.
• Resume after maintenance — filter by platform, resume each paused row.
• Audit which accounts have a Discord bot connected — filter by discord; rows with Active or Paused have a connection, No Connection does not.

Permissions

Action	Permission
View bot statuses	bot-control:read
Pause / resume a bot	bot-control:edit

Dashboard entry requires admin:access. System admins hold these implicitly.

API

UI action	GraphQL	REST
List bot statuses	adminBotStatuses(accountId)	GET /v1/admin/bot-control/statuses
Pause / resume	adminToggleBotForAccount	PUT /v1/admin/bot-control/\{account_id\}/\{platform\}

The frontend calls its own Next.js proxy routes at /api/bot-statuses and /api/bot-statuses/toggle. Filtering and searching happen entirely in the browser — neither the query string nor the platform dropdown reaches the API.

Tips & gotchas

• Pause is per account × platform — not global. For a platform-wide halt, toggle the kill-switch on Providers instead.
• Pausing does not revoke OAuth tokens. The bot connection stays authenticated and resumes instantly when toggled back.
• A bot with No Connection cannot be paused because there is nothing to pause. It has to be connected first from the account's side.
• The toggle is idempotent — the request carries the desired enabled value, so calling pause on an already-paused bot is a no-op.

Related

• Providers — platform-level kill-switches and global bot identity
• Bot Commands — command registry executed by these bots
• Discord Guilds — Discord-specific guild-to-account mapping