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