Community Bot

A modular Discord community bot built on the official Bot API (discord.py). It welcomes new members, gates out raid bots, lets members opt into roles and announcements, and runs engagement, moderation, and notification features you turn on per server.

Everything it does is consent-based and within Discord's Terms of Service: it greets people who join, messages only members who opted in, and never scrapes the member list or cold-DMs people.

Features

Area	What it does
Welcome / Goodbye	Personalized join greeting (channel embed + optional DM), farewell on leave, optional avatar "welcome card" image
Auto-role	Automatically gives new members a role on join
Verification gate	A "click to verify" button that grants a role — blocks most raid/spam bots
Self-roles	/roles menu so members pick interest roles themselves
Opt-in subscribe	Members /subscribe; admins /announce to only that list
Role-targeted announce	Broadcast to one interest role's members
Leveling / XP	Earn XP by chatting, /rank, /leaderboard, level-up role rewards
Starboard	Messages that hit a ⭐ threshold get reposted to a highlights channel
Polls & Suggestions	/poll with reaction voting, /suggest to a suggestions board
Birthdays	Opt-in /birthday set, daily greeting (stores month/day only)
Tickets	Members open a private support channel via a button
Auto-moderation	Filters invite links, spam bursts, and banned words (mods exempt)
FAQ	/faq lookups + optional keyword auto-responder
Creator notifications	Posts new YouTube/RSS uploads to a channel (Twitch optional)
Scheduler	/remind reminders and recurring scheduled announcements
AI assistant	/ask course Q&A, AI-personalized welcome DMs, and /promo_draft announcement copy — powered by OpenRouter (optional)

Requirements

• Python 3.8+
• pip install -r requirements.txt (installs discord.py, Pillow for welcome cards, feedparser for notifications)

Setup

1. Create the bot

1. Discord Developer Portal → New Application → name it.
2. Bot tab → Add Bot. Click Reset Token → Copy, and paste it into config.json (token). Treat it like a password.

2. Enable privileged intents

On the Bot tab, under Privileged Gateway Intents:

• Server Members Intent — required (welcomes, goodbyes, auto-role, leveling, etc.).
• Message Content Intent — only needed for Auto-moderation and the FAQ auto-responder. If you want those, enable it here and set "message_content_intent": true in config.json. Leave both off otherwise — everything else still works.

3. Invite the bot

OAuth2 → URL Generator: check scopes bot and applications.commands. Under Bot Permissions grant what your features need — a safe set is Manage Roles, Manage Channels, Kick/Moderate Members, Read Messages/View Channels, Send Messages, Embed Links, Add Reactions, Manage Messages, Read Message History. Open the generated URL, pick your server, authorize.

For roles to work (auto-role, verification, level rewards), drag the bot's role above the roles it should assign in Server Settings → Roles.

4. Install & configure

pip install -r requirements.txt

Edit config.json:

Field	Meaning
token	Your bot token. Required.
message_content_intent	true only if you enabled Message Content (for automod + FAQ auto-responder).
openrouter_api_key	Optional. Your OpenRouter key — enables the AI features (/ask, AI welcomes, /promo_draft).
openrouter_model	Model for the AI features (default openai/gpt-4o-mini).
welcome_channel_messages	Templates for the channel welcome (one chosen at random).
welcome_dm_messages	Templates for the welcome DM.
goodbye_messages	Templates for the farewell message.

Template placeholders: {user} (display name), {mention}, {username}, {server}, {count}.

5. Run

python bot.py

On first start it loads every cog and syncs slash commands (they can take a few minutes to appear in Discord).

Turning features on (per server)

Most features are dormant until an admin (needs Manage Server) points them at a channel or role:

• Welcome: /welcome_channel #welcome · optional /welcome_dm true · /welcome_card true · /goodbye_channel #general · /autorole @Member
• Verification: /verify_setup role:@Verified channel:#verify (posts the Verify button)
• Self-roles: /selfrole_add @Announcements (repeat per role) → members use /roles
• Subscribe: /post_subscribe_button (posts opt-in buttons) → /announce your message
• Leveling: optional /level_channel #level-ups and /level_reward level:5 role:@Regular
• Starboard: /starboard_setup channel:#starboard threshold:3
• Suggestions: /suggest_channel #suggestions
• Birthdays: /birthday_channel #general → members /birthday set 03-14
• Tickets: /ticket_panel channel:#support category:#Tickets staff_role:@Staff
• Automod: on by default once Message Content is enabled; tune with /automod_invites, /automod_spam, /automod_word_add
• FAQ: /faq_add keywords:"refund, money back" answer:"..." · optional /faq_autorespond true
• Notifications: /feed_youtube channel_id:UC... post_channel:#videos mention_role:@YT or /feed_rss url:... post_channel:#news
• Scheduler: /schedule_add channel:#daily time:09:00 message:"Good morning!"
• AI assistant: add openrouter_api_key to config.json, then /course_setup, /welcome_ai true, and use /ask / /promo_draft

Run /help in Discord for a quick command list, and /settings to see what's configured.

AI features (OpenRouter)

Three optional AI features run on OpenRouter. Add an API key to config.json (openrouter_api_key) and optionally set openrouter_model (default openai/gpt-4o-mini). Then:

• /course_setup name:"..." description:"..." link:"..." (admin) — tell the AI about your course; this powers all three features below.
• /ask (everyone) — a 24/7 assistant that answers questions about your course, handles objections, and points to the signup link.
• /welcome_ai true (admin) — each new member's welcome DM is written by the AI and tailored to them (falls back to your templates if no key). It's one message to one person who just joined — not a bulk send.
• /promo_draft topic:"enrollment opens Monday" (admin) — generates several announcement variations for you to post in your own channels (A/B test copy). It drafts; it never sends.

Without a key these stay off and everything else still works. OpenRouter bills per use, so /ask has a short per-user cooldown.

Command reference

Everyone: /roles, /subscribe, /unsubscribe, /subscription, /rank, /leaderboard, /poll, /suggest, /birthday set, /birthday clear, /faq, /ask, /remind, /help, /ping

Admin (Manage Server): /welcome_channel, /welcome_dm, /welcome_card, /goodbye_channel, /autorole, /autorole_clear, /welcome_test, /verify_setup, /selfrole_add, /selfrole_remove, /selfrole_list, /announce, /announce_role, /post_subscribe_button, /subscribers, /level_channel, /level_reward, /level_reward_remove, /starboard_setup, /starboard_threshold, /suggest_channel, /birthday_channel, /ticket_panel, /automod_invites, /automod_spam, /automod_word_add, /automod_word_remove, /automod_words, /faq_add, /faq_remove, /faq_list, /faq_autorespond, /feed_youtube, /feed_rss, /feed_twitch, /feed_list, /feed_remove, /schedule_add, /schedule_list, /schedule_remove, /course_setup, /promo_draft, /welcome_ai, /settings

Project structure

bot.py            Entry point — loads cogs, syncs commands, runs the bot
store.py          Tiny JSON persistence layer shared by every cog
config.json       Token, intent flag, welcome/goodbye templates
requirements.txt  Dependencies
cogs/             One module per feature (welcome, verification, roles, ...)
data/             Auto-created JSON storage (settings, subscribers, levels, ...)

Add or remove features by editing the INITIAL_COGS list in bot.py. Each cog is self-contained.

Notes

• Persistence: all settings and data live as plain JSON under data/ and survive restarts. Back up that folder to keep your configuration.
• Privacy: birthdays store only month-day (MM-DD), no year, and only when a member opts in. Subscriptions are opt-in and removable anytime.
• Twitch notifications need twitch_client_id and twitch_client_secret added to config.json; without them, YouTube and RSS still work and /feed_twitch explains what's missing.
• Scheduler uses the host machine's local time.
• The bot loads cogs independently — if one fails (e.g. a missing optional package), the rest still run; check the console log.

Troubleshooting

• Slash commands missing → invite included the applications.commands scope; wait a few minutes after first start.
• No welcomes / joins not detected → enable Server Members Intent.
• Automod/FAQ auto-responder do nothing → enable Message Content Intent and set message_content_intent: true.
• Can't assign roles → move the bot's role above the target role and grant Manage Roles.
• Welcome card not appearing → install Pillow (pip install Pillow) and enable /welcome_card true.
• Login failed → wrong/reset token in config.json.