# Blacklist The `blacklist` module lets a chat keep a list of forbidden text and a list of exceptions, then ask whether a given text is blocked. | Command | Parameters | What it does | |---|---|---| | `/blacklist` | `[text...]` | Bare, lists both lists; with text, judges it | | `/blacklist_add` | `[text...]` | Adds text to the blacklist, or the message you replied to | | `/blacklist_del` | `` | Removes text from the blacklist | | `/whitelist_add` | `[text...]` | Adds an exception, or the message you replied to | | `/whitelist_del` | `` | Removes an exception | | `/blacklist_rules` | — | Lists both lists in one message | | `/blacklist_check` | `` | Judges a text against both lists | | `/whitelist_rnd` | — | Returns one whitelist entry at random | All are public and single-shot. `/blacklist` is the short form of the two read commands: on its own it does what `/blacklist_rules` does, and given text it does what `/blacklist_check` does. Nothing is lost by using it — the long names remain for when the intent should be explicit. `/whitelist_rnd` returns a single whitelist entry chosen at random, and says so plainly when the whitelist is empty rather than answering with nothing. ## The bot does not police the chat This is the first thing to know, because the module's name promises something it deliberately does not do. Nothing happens automatically. The bot never reads ordinary messages, never deletes anything, and never warns or restricts anyone. The lists sit inert until `/blacklist_check` asks about a specific text. Automatic moderation would need three things this bot does not have: a message-level hook in the dispatcher, privacy mode disabled in BotFather so Telegram delivers ordinary group messages at all, and admin rights with permission to delete in every group. All three are out of scope by choice. ## Lists belong to a topic, not to the bot Each thread keeps its own two lists. In a forum supergroup, entries added in one topic are invisible in the next. A non-forum group has one set of lists; a private chat with the bot has its own, shared with nobody. This is the most common surprise: running `/blacklist_check` in the wrong topic gives a different answer than the same command one topic over, and it is not a bug. Every reply says "in this topic" for that reason. Within a thread, anyone can add and anyone can remove — including entries someone else added. The lists belong to the conversation, so the permission to edit them does too. A per-owner rule would strand entries whose author has left the group. ## How the whitelist works The whitelist is not a second independent list. It is an exception layer over the blacklist, and it rescues a match only when it **covers** that match in the text being checked. With `ass` blacklisted and `assassin` whitelisted: | Checked text | Verdict | Why | |---|---|---| | `assassin` | Allowed | The whitelist entry spans the whole match | | `dumbass` | Blacklisted | Nothing whitelisted covers this `ass` | | `I met an assassin, dumbass` | **Blacklisted** | The first match is rescued; the second is not | The third row is the one worth remembering. A whitelist entry does not make a whole message safe — it only rescues the occurrences it actually contains. ## Matching Matching is by substring, after the text is normalized: - **Case does not matter.** `Cat`, `CAT` and `cat` are one rule. - **Spacing does not matter.** `cat dog` and `cat dog` are one rule, and a newline is just a space. - **Diacritics do matter.** `ma`, `má` and `mà` are three separate entries. To catch all three, add all three. - **The same word matches across devices.** Vietnamese typed on an iPhone and on an Android phone can differ in how the accents are encoded; normalization resolves that, so the two forms match each other. - **Full-width and other presentation variants fold** onto their plain forms. `/blacklist_check` accepts text of any length. Entries themselves are capped at 200 bytes — roughly 200 plain letters, or about 65 Vietnamese characters. ## Listing Every `/blacklist_add`, `/blacklist_del`, `/whitelist_add` and `/whitelist_del` answers with the current contents of the list it touched, so you see the result without running anything else. That includes the two outcomes that change nothing — text already present, or text that was not there to remove — since those are exactly the moments you want to see what the list actually holds. A whitelist command shows the whitelist; a blacklist command shows the blacklist. `/blacklist_rules` prints both lists in one message, each with its entry count, showing entries as they were typed rather than in the normalized form. Each entry is tappable to copy, ready to paste into a `_del` command. Telegram caps a message at 4096 characters. A list longer than that is trimmed with a count of what was left out; both headings always appear, so a long blacklist never hides the whitelist entirely.