Bot Modules

Overview

The Bot Modules system provides configurable chat bot modules for automated moderation and messaging. Each module can be independently enabled/disabled per account, with module-specific configuration and exemption rules. The system currently supports four modules: link protection, spam protection, word filter, and timed messages. Exempt roles (moderators, VIPs, subscribers) can be configured per module to bypass enforcement.

Architecture

Backend

• GraphQL (apps/api/src/graphql/bot_modules.rs) -- Queries for listing all module configs and fetching individual modules by name. Mutations for upserting and deleting module configs.
• Database (apps/api/src/db/bot_modules.rs) -- PostgreSQL operations for the bot_module_configs table. Supports list, get, upsert, and delete operations.
• Validation -- Module names are validated against a whitelist: link_protection, spam_protection, word_filter, timed_messages.

Frontend

• Bot modules settings page with a card per module.
• Toggle switch for enable/disable.
• Module-specific configuration form.
• Exempt roles selector (checkboxes for mods, VIPs, subs).

API

GraphQL Queries

Query	Permission	Description
botModules	bot-modules:read	List all bot module configs for the account
botModule(name)	bot-modules:read	Get a single bot module config by name. Validates name against whitelist.

GraphQL Mutations

Mutation	Permission	Description
updateBotModule(name, enabled, config?, exemptRoles?)	bot-modules:edit	Upsert a bot module config. Name is validated against the whitelist. Config and exempt_roles default to {} if not provided.
deleteBotModule(name)	bot-modules:edit	Delete a bot module config. Name is validated against the whitelist.

REST Endpoints

All paths live under /v1.

Method	Path	Permission	Description
GET	/v1/bot-modules	bot-modules:read	List all module configs for the account
PUT	/v1/bot-modules/{module_name}	bot-modules:edit	Upsert a module config (enabled, config, exempt_roles). Module name is validated against the whitelist.
DELETE	/v1/bot-modules/{module_name}	bot-modules:edit	Delete a module config

Valid Module Names

Module	Description
link_protection	Detects and moderates messages containing links
spam_protection	Detects and moderates spam patterns (repeated messages, excessive caps, etc.)
word_filter	Filters messages containing blocked words/phrases
timed_messages	Sends automatic messages at configured intervals

Permissions

Permission	Description
bot-modules:read	View bot module configurations
bot-modules:edit	Create, update, and delete bot module configurations

Database

Table	Database	Description
bot_module_configs	PostgreSQL	id, account_id, module_name, enabled (bool), config (JSONB), exempt_roles (JSONB), created_at, updated_at

Config JSONB Structure (per module)

The config field contains module-specific settings. Examples:

link_protection:

{
  "action": "delete",
  "warning_message": "Links are not allowed",
  "whitelist_domains": ["youtube.com", "twitch.tv"],
  "timeout_duration": 60
}

spam_protection:

{
  "max_repeated_messages": 3,
  "max_caps_percentage": 80,
  "min_message_length_for_caps": 10,
  "action": "timeout",
  "timeout_duration": 30
}

word_filter:

{
  "blocked_words": ["badword1", "badword2"],
  "blocked_patterns": ["regex_pattern"],
  "action": "delete",
  "warning_message": "Your message was removed"
}

timed_messages:

{
  "messages": [
    { "text": "Follow us on Twitter!", "interval_minutes": 15 },
    { "text": "Join our Discord!", "interval_minutes": 30 }
  ],
  "min_chat_lines_between": 5
}

Exempt Roles JSONB Structure

{
  "moderators": true,
  "vips": true,
  "subscribers": false
}

Data Flow

1. Account owner/admin enables a bot module and configures it via the dashboard.
2. Configuration is saved via updateBotModule mutation (upsert pattern).
3. When a chat message is received, the bot checks each enabled module:
   • Is the user exempt (mod/VIP/sub based on exempt_roles)?
   • Does the message violate the module's rules (based on config)?
4. If a violation is detected, the configured action (delete, timeout, warn) is executed.
5. Timed messages module sends messages at configured intervals when chat activity meets the minimum threshold.

Feature gating

The whole Bot Modules surface is gated on the umbrella feature:bot_modules flag: every query and mutation (botModules, botModule, updateBotModule, deleteBotModule on GraphQL; GET/PUT/DELETE /v1/bot-modules on REST) enforces it on both protocols — GraphQL via FeatureGuard::new("feature:bot_modules") chained before the permission guard, REST via require_feature(..., "feature:bot_modules", ...) after the permission check. With feature:bot_modules disabled the API rejects the call directly (Feature 'feature:bot_modules' is not available, HTTP 403), so listing configs is gated too — the webapp route gate is UX only, not the boundary.

In addition, each built-in module has its own finer feature flag, keyed bot_module:{module_name} — bot_module:link_protection, bot_module:spam_protection, bot_module:word_filter, bot_module:timed_messages. Writing or deleting a module config checks that per-module flag on both protocols after the umbrella feature:bot_modules check, so a specific module disabled for the account's plan cannot be configured even when the Bot Modules area itself is enabled. Which plans enable which module flag is a plan_features mapping, editable by admins without a deploy.

Key Files

Path	Description
apps/api/src/graphql/bot_modules.rs	GraphQL queries and mutations
apps/api/src/routes/bot_modules.rs	REST endpoints
apps/api/src/db/bot_modules.rs	Database operations

Extension Bot Modules

In addition to the four built-in modules above, accounts can install extension bot modules from the Lumio Extension Store. Extension bot modules are community-developed moderation and automation modules that run inside the same V8 isolate sandbox used by all extensions, with the same security guarantees.

How It Works

Extension bot modules use the bot_module category in lumio.config.json. When installed, the extension registers one or more triggers (commands, keywords, patterns, events, timers, or moderation hooks) that the Bot Module Worker evaluates against incoming chat messages and events.

Chat message arrives
  → Bot Module Worker loads triggers for account
  → Matches against extension triggers (command prefix, keyword, regex, event type)
  → Dispatches to V8 isolate handler for the matched extension
  → Handler returns response/action (send message, timeout, ban, delete)
  → Worker executes action via platform API

Installation and Configuration

Users install extension bot modules from the Extension Store like any other extension. Once installed, the module appears in Dashboard > Bot Modules alongside built-in modules. Each extension bot module supports:

• Enable/disable toggle per account
• Configuration via config_schema fields defined by the extension developer (rendered as a form in the dashboard)
• Trigger overrides — account owners can customize command prefixes, keyword lists, and regex patterns without modifying the extension code
• Exempt roles — the same moderator/VIP/subscriber exemption system used by built-in modules

Configuration Validation

Config values set by users (through the dashboard settings panel or API) are validated against the extension's declared schema. Invalid values (wrong type, missing required fields, unknown settings) are rejected with clear error messages. This ensures extensions always receive correctly typed configuration.

Kill Switch

Account owners can immediately disable a misbehaving extension bot module via the kill switch. The kill switch:

1. Disables the extension's triggers instantly (no restart required)
2. Removes the extension from the Bot Module Worker's active trigger set
3. Preserves configuration so the module can be re-enabled later

The kill switch is accessible from Dashboard > Bot Modules (per-module toggle) or via POST /v1/bot-modules/kill with the extension install ID. It requires bot-modules:edit.

Trigger Types

Triggers are declared, not registered in code: the extension's lumio.config.json carries a triggers object whose keys are the trigger types below. Each entry names the handler the Bot Module Worker dispatches to.

triggers key	Description	Limits
commands	Matches a chat command (e.g. !rank). Each entry carries name, description, cooldown_global, cooldown_user, min_role, and optional discord_options.	max 20
keywords	Matches any of a list of keywords in message text	max 50, min 3 chars each
patterns	Matches a regex pattern against message text	max 10, max 200 chars each
events	Fires on a platform event (e.g. twitch:follower)	—
timers	Fires on a recurring interval — name, interval (seconds), handler	min interval 60 s

min_role accepts everyone, follower, subscriber, vip, moderator, or broadcaster. A module that exports a moderate handler additionally runs on every message for moderation decisions (has_moderate on the worker's install trigger config).

Permissions

Extension bot modules use the same permission system as other extensions. The chat:ban permission requires enhanced review during the extension approval process due to its impact on user experience.

Feature gating

Extension bot modules are gated by the extension-platform feature flags rather than by a plan constant. Installing and running them requires the account to have the extension platform enabled; see Extensions.

Key Files

Path	Description
apps/bot-module-worker/	Bot Module Worker HTTP service (binary)
crates/lo-bot-module-worker/src/router.rs	Trigger matching and dispatch logic
crates/lo-bot-module-worker/src/executor.rs	Handler execution and result handling
crates/lo-bot-module-worker/src/types.rs	InstallTriggerConfig, CommandTrigger, KeywordTrigger, PatternTrigger
crates/lo-extensions-v8/src/executor.rs	V8 isolate execution for extension handlers
apps/api/src/routes/bot_module_extensions.rs	Trigger sync, kill switch, and extension log/metric endpoints