GroupShield
Moderating large WhatsApp groups is a nightmare. GroupShield automates it with custom rules, bilingual support, and a self-healing architecture.
GroupShield
Moderating large WhatsApp groups is a nightmare. GroupShield automates it with custom rules, bilingual support, and a self-healing architecture.
One bot to rule them all. Simple for admins, transparent for users.
No complex dashboards. Configure rules, languages, and enforcement steps through a natural DM conversation.
Define precise hours when messages are allowed. Perfect for forum-style groups.
Block forbidden phrases or enforce "Allowed Only" lists. Supports exact matches and regex containment.
Prevent flood attacks with configurable limits for consecutive identical messages and daily volume.
Warn, Delete, Remove, Block. You define the escalation path that fits your community culture.
Full support for Hebrew and English out of the box, ensuring every user understands the rules.
A two-layer filter: a local wordlist catches known violations, then a Groq/Llama LLM catches leet-speak, special-character substitutions, and creative bypass attempts. Prompt injection attempts are blocked before they reach the model. Zero false positives ā fails silently on infra errors.
Locks the group before Shabbat and all major Jewish holidays, reopens after. Times are fetched weekly from HebCal API. The group re-locks if someone manually overrides it during Shabbat. If the API fails, a guided recovery flow lets the admin enter times manually.
The bot writes the active group rules directly into the WhatsApp group description ā automatically on setup, and on demand with a single command. Always in sync with the configured policy.
Link a dedicated WhatsApp group as the management hub. Multiple admins can run commands, receive violation reports, and undo enforcement actions ā all without accessing the bot directly.
Real data from the running production instance.
A visual simulation of how GroupShield transforms your community management.
Incoming message is captured directly from the managed group.
Cross-references content against regex logic and configured spam limits.
Executes strict enforcement: deletes violation, warns, blocks or removes.
Delivers transparent logs to the admin group and a private DM to the user.
A real-time trace of a message engineered to slip through every filter.
The forbidden-word list is checked with normalization, homoglyphs, morphological variants, and fuzzy matching. "×'×ש" is not in the list and no known variant matches it.
The message is converted to a bigram vector and compared against all words in the list. Best score: 0.09 ā well below the 0.65 suspicious threshold. No match.
The scorer checks 9 heuristic patterns. Pattern 7 fires: "××" vocative prefix followed by an unknown word ā a classic Arabic-origin insult structure. Message is routed to the AI layer.
The model receives the message with a zero-tolerance system prompt. It returns YES in under 4 seconds ā Arabic-origin insult confirmed. Result is cached to prevent duplicate API calls.
The violation triggers the enforcement pipeline: message deleted from the group, private DM warning sent to the user, then removal. Each step is logged with a unique action ID for potential undo.
The full enforcement report is sent to the management group. The LLM catch is flagged ā the developer reviews the pattern and decides whether to add "×'×ש" to the permanent word list so future instances are caught instantly, without needing the AI.
Built for high availability, massive scale, and zero-maintenance.
Reliable WhatsApp Web automation utilizing persistent sessions and a self-healing crash recovery protocol.
Local persistent database structured to handle configurations and warnings for thousands of groups efficiently.
Rate-limited message processing pipeline that prevents connection bans and ensures deterministic rule evaluation.
Containerized setup for effortless deployment across any cloud provider with zero dependency conflicts.
Advanced crash-recovery system that automatically restores the WhatsApp connection if the browser unexpectedly drops.
Configure complex rules, schedules, and immunity groups intuitively inside WhatsApp. No dashboard required.
The AI moderation layer runs Llama-3.1-8b-instant via Groq with a 4-second timeout and a monthly usage cap. A suspicion scorer pre-filters messages before any API call. Prompt injection attempts ā in Hebrew or English ā are blocked instantly without involving the LLM at all. Fails silently on infra errors: zero false positives.
Every Thursday a cron job fetches candle-lighting times (Jerusalem) and Havdalah times (Netanya) from the HebCal API. The bot locks groups 5 minutes before entry and unlocks 5 minutes after exit, re-locking on any manual override. If the fetch fails, a guided recovery flow lets the admin enter times manually.
graph TD
A["š± WhatsApp Group"] -->|"New Message"| B["š¤ Puppeteer Bot\n(Node.js)"]
B -->|"Enqueue"| C["ā” Event Queue\n(Rate-Limiter)"]
C --> D["š§ Rule Engine\n(Regex / Time / Spam)"]
D -->|"Clear Violation"| E["āļø Enforcement Pipeline"]
D -->|"Suspicious / Context Word"| LLM["š¤ AI Layer\n(Groq / Llama 3.1)"]
LLM -->|"Violation"| E
LLM -->|"Clean"| F["ā
Ignore"]
D -->|"Immune user"| F
E --> G["šļø Delete Message"]
E --> H["š© DM Warning"]
E --> I["š« Remove User"]
E --> J["š£ Report to Mgmt Group"]
SCHED["šÆļø Shabbat Scheduler\n(Cron / HebCal API)"] -->|"Friday evening"| LOCK["š Lock Group\n(Admins Only)"]
SCHED -->|"Saturday night"| UNLOCK["š Unlock Group"]
B -->|"Read/Write"| K[("šļø SQLite DB\n(Multitenant)")]
K --- L["Groups Config"]
K --- M["Warnings Log"]
K --- N["Immune List"]
style A fill:#075e54,color:#fff
style B fill:#128c7e,color:#fff
style C fill:#1a1a2e,stroke:#00e5ff,color:#fff
style D fill:#1a1a2e,stroke:#00e5ff,color:#fff
style E fill:#1a1a2e,stroke:#f59e0b,color:#fff
style LLM fill:#1a1a2e,stroke:#a855f7,color:#fff
style SCHED fill:#1a1a2e,stroke:#f59e0b,color:#fff
style LOCK fill:#1a1a2e,stroke:#ef4444,color:#fff
style UNLOCK fill:#1a1a2e,stroke:#00ffa3,color:#fff
style K fill:#1a1a2e,stroke:#00ffa3,color:#fff
The live production environment and orchestration pipeline.
Deployed on a dedicated Linux VPS ensuring 24/7 uptime and stable network resources for Puppeteer.
Daemonized via PM2 for background execution, automatic crash-restarts, and active log monitoring.
Version-controlled deployments that seamlessly pull GitHub updates and smoothly reload the bot instances.
Sensitive config variables (admin numbers, tokens) managed via .env files and excluded from version control via .gitignore.
Daily snapshots of the SQLite database to a remote location, ensuring zero data loss even on full server failure.
Active heartbeat monitoring that detects when the bot process goes offline and sends an immediate WhatsApp alert to the admin.
Yes. GroupShield does not save your messages. Message contents are strictly evaluated in memory and discarded immediately unless a violation occurs (for reporting purposes only).
Absolutely. A single GroupShield instance can seamlessly manage thousands of groups, each with its own independent rule configuration.
GroupShield is built with a self-healing architecture. It automatically detects connection drops and safely restarts the browser session without missing any backend data.
No. GroupShield currently only processes text messages. You can optionally configure it to automatically block all non-text media if you wish.
GroupShield works flawlessly with WhatsApp's maximum group size (1024 members) and handles high-volume message traffic effortlessly.
Not at all. The entire setup process is done through an intuitive chat interface directly in WhatsApp.
It uses a two-layer approach. First, a local wordlist detects known offensive words instantly with no API call. Then, a suspicion scorer decides whether a message is worth escalating. Suspicious messages are passed to a Groq-hosted Llama 3.1 model that catches bypass attempts like letter substitutions (e.g. × replaced by @) and leet-speak. Prompt injection attempts are blocked before they reach the model.
Yes. Admins can add custom forbidden phrases or mark specific words as allowed (overriding the default list) using simple commands directly in WhatsApp ā no code changes needed.
Yes. GroupShield itself runs 24/7 on a VPS ā Shabbat mode locks the WhatsApp group, not the bot. The bot stays active and re-locks the group automatically if an admin manually reopens it during Shabbat.
Each violation increments the user's warning counter. If warnings are enabled, the bot sends a private DM to the user explaining the violation. Once the warning threshold is reached, the full enforcement pipeline kicks in: delete the message, remove the user, and send a detailed report to the management group.
Yes. Every removal report contains a unique action ID. Admins can reply to the report with "undo" to reverse the action ā the bot cancels the removal, resets the user's warnings, and logs the reversal.