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.

Plan Restriction

Custom bot modules require the Pro plan (custom_bot_allowed in PlanLimits).

Key Files

Path	Description
apps/api/src/graphql/bot_modules.rs	GraphQL queries and mutations
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.

Trigger Types

Trigger	Description	Example
command	Matches a chat command prefix (e.g. !rank)	command("rank", handler)
keyword	Matches one or more keywords in message text	keyword(["giveaway", "enter"], handler)
pattern	Matches a regex pattern against message text	pattern(/^!(\w+)\s+(\d+)$/, handler)
event	Fires on a platform event (e.g. twitch:follower)	event("twitch:follower", handler)
timer	Fires on a recurring interval	timer("reminder", 300, handler) (every 300s)
moderate	Runs on every message for moderation decisions	moderate(handler)

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.

Plan Restriction

Extension bot modules require the Pro plan (custom_bot_allowed in PlanLimits), the same restriction as built-in custom bot modules.

Key Files

Path	Description
apps/api/src/workers/bot_module_worker.rs	Bot Module Worker service
crates/lo-extensions-v8/src/bot_module.rs	V8 isolate execution for bot module handlers
crates/lo-extensions/src/triggers.rs	Trigger matching and dispatch logic