Documentation

Discord Embed Bot

Reference for the embed pipeline, management commands, and deployment. Implemented in sizzbedbot_V1.py; optional bedbotControl.py for PM2 control.

Spec v2.1 Python · discord.py Self-hosted
Stable Roadmap: modular split

1. High-Level Overview

This bot detects social media links in guild channels and threads, then offers cleaner alternate embed formats via reactions. It also includes moderation-safe management commands for diagnostics, invite handling, and audit visibility.

1.1 Core Responsibilities

  • Parse message text for platform URLs and map them to supported embed transformers.
  • Suppress default Discord embeds when replacement behavior is selected by users.
  • Provide guarded owner/admin management commands for info, invite status, and invite generation.
  • Enforce anti-abuse protections: rate limits, invite caps, and response redaction in channel-visible flows.
Design goal: Keep embed UX fast for normal users while treating admin and owner paths as explicit, auditable, and failure-safe operations.

1.2 Public repo safety

sizzbedbot_V1.py contains no embedded secrets. It is safe to publish alongside private_config.example.py, .env.example, and this documentation file (index.html). Never commit .env, private_config.py, or real tokens.

2. Configuration & Environment

2.1 Primary: .env file

python-dotenv loads variables at startup. Use a committed .env.example as the template; copy to .env locally (gitignored). 

DISCORD_TOKEN=your_bot_token_here
BOT_OWNER_ID=your_discord_user_id_here
# Optional — only if you run bedbotControl.py (comma-separated user IDs, no spaces)
BEDBOT_CONTROL_TRUSTED_IDS=111111111111111111,222222222222222222
  • DISCORD_TOKEN — Discord API authentication for whichever script you run.
  • BOT_OWNER_ID — your Discord user ID (not the bot’s), for owner-only paths in sizzbedbot_V1.py.
  • BEDBOT_CONTROL_TRUSTED_IDS — who may use /start, /restart, /shutdown on the control bot.

2.2 Optional: private_config.py

Gitignored copy of private_config.example.py. Use only if you want Python-side fallbacks when something is not set in the environment.

  • Token: environment DISCORD_TOKEN is read first; private_config.DISCORD_TOKEN is used only if env is empty.
  • Owner ID: environment BOT_OWNER_ID wins when set to a non-zero value; otherwise private_config.BOT_OWNER_ID.
  • Control IDs: environment BEDBOT_CONTROL_TRUSTED_IDS wins when non-empty; otherwise the list in private_config.

2.3 Companion script: bedbotControl.py

Separate small bot for PM2 lifecycle commands. Shares the same token resolution as the main bot and reads BEDBOT_CONTROL_TRUSTED_IDS from .env (or optional private_config). If no trusted IDs are configured, control commands are effectively disabled.

2.4 Runtime Permissions

Intents
  • message_content for URL detection.
  • guilds, messages, reactions for command and reaction flow.
Permissions
  • Read/Send Messages, Read History, Add Reactions.
  • Embed Links, Attach Files, Send in Threads.
  • Manage Messages for embed suppression paths.

Recommended invite permission integer: 277025516608.

3. Architecture & Modules

The current implementation is monolithic but functionally layered for predictable ownership and future splitting.

  • Config + State: env load, owner identity, in-memory caches, persistent JSON state.
  • Helpers: duration formatting, rate-limit checks, invite tracking, safe mention wrappers.
  • Command Surface: slash commands and mention aliases with owner/admin privilege boundaries.
  • Embed Engine: platform detection and replacement transformation in message pipeline.
  • Instagram URLs: detection supports instagram.com and common mirror hosts; query strings (e.g. tracking parameters) are not carried into generated mirror links — only the canonical p/<id> or reel/<id> path is used.

4. Reliability & Persistence Model

4.1 Persisted Data

  • server_settings tracks per-guild invite enablement.
  • invite_records stores metadata for generated invites and auditing.
  • guild_invite_timestamps supports per-guild anti-abuse enforcement.

4.2 Fault Handling

  • State serialization/deserialization errors are caught and logged without bot termination.
  • External request paths use fallback behavior where possible.
  • Ambiguous state defaults to safe reject behavior instead of permissive behavior.

5. UX & Command Behavior

5.1 Help and Discoverability

The help flow is split into embed usage, management capabilities, and command matrix, so users can find practical actions quickly instead of reading a large wall of text.

5.2 Info and Redaction

  • Non-owner /info is current-server only and sent ephemerally.
  • Owner /info can inspect wider server scope, still ephemeral.
  • Channel-visible mention responses are constrained to current guild and redacted where needed.

5.3 Invite Generation Paths

  • Server view actions create limited-lifetime invites, DM first, and keep channel output safe.
  • /join allows owner server selection and tracked invite creation.
  • @bot join stays guild-scoped and follows the same tracked flow.

6. Security & Abuse Protections

6.1 Rate Limiting

  • Per-user command buckets separate read-style and write-style actions.
  • Fast burst cooldown and hard cooldown reduce repeated spam pressure.
  • Owner bypass is explicit and intentionally scoped.

6.2 Invite Abuse Controls

  • Global and per-guild limits on invite creation for non-owners, with cool-down periods when thresholds are exceeded.
  • Per-guild timestamp tracking layered on top of global checks.
  • Owner-only reset paths for operational recovery.

6.3 Redaction Guarantees

  • AllowedMentions.none() is used for potentially sensitive outputs.
  • Channel invite listings hide full user and URL details.
  • Full visibility paths remain owner-only and ephemeral.

7. Developer Workflow

7.1 Local Dev Loop (Practical)

  1. Create venv and install dependencies from requirements.txt.
  2. Copy .env.example → .env; set DISCORD_TOKEN and BOT_OWNER_ID (and BEDBOT_CONTROL_TRUSTED_IDS if testing the control bot).
  3. Run python sizzbedbot_V1.py in a dedicated test guild.
  4. Validate slash sync, mention commands, and embed transforms against sample links (including Instagram links with query strings).
  5. Run abuse scenarios: command bursts, invite caps, and cooldown resets.

7.2 Suggested Repo Workflow

Branch Strategy
  • feature/embeds-* for platform handlers.
  • feature/mod-tools-* for management UX.
  • hotfix/* for production-safe critical patches.
Definition of Done
  • Manual test evidence in dev guild.
  • No token leakage in logs, commits, or index.html / docs snapshots.
  • Rate limit + redaction behavior verified.

7.3 Deploy Checklist (Render)

  • Configure DISCORD_TOKEN and BOT_OWNER_ID in the host dashboard (same names as .env).
  • Set start command to python sizzbedbot_V1.py.
  • Optionally mount persistent volume for longer invite-state retention.
  • Do not upload private_config.py unless your host supports secret files; prefer injected env vars.

8. Extensibility & Future Work

  • Keep README.md and CHANGES.md aligned with config and behavior for operators.
  • Split into cogs: embeds.py, management.py, security.py.
  • Add tests for rate limiting, invite caps, and redaction output.
  • Move state persistence to SQLite/Postgres if long-term auditing is needed.
  • Introduce structured logging and command correlation IDs for easier support debugging.