Get rid of the unwanted spam joins out of the box
- Join-time challenge is disabled as for now, due to being buggy, but will be back as option in the future.
- Triggered on the events, which introduces new chat members (invite, join, etc). Also works with join requests.
- Restrict newcomer to be read-only.
- Set up a challenge for the newcomer (join request), which is a simple task as shown on the image above, but yet, unsolvable for the vast majority of automated spam robots.
- If the newcomer succeeds in choosing the right answer - restrictions gets fully lifted, challenge ends.
- Otherwise - newcomer gets banned for 10 minutes (There is a "false-positive" chance, rememeber? Most robots aint coming back, anyway).
- If the newcomer struggles to answer in a set period of time (defaults to 3 minutes) - challenge automatically fails the same way, as in p.5.
- After the challenge bot cleans up all related messages, only leaving join notification for the newcomers, that made it. There are no traces of unsuccesful joins left, and that is awesome.
- Every chat member first message is being checked for spam using two approaches:
- Known spammers DB lookup - checks if the message author is in the known spammers DB.
- GPT-powered content analysis - asks GPT to analyze the message for harmful content.
- If the message is considered as spam - newcomer gets kick-banned.
- If the message is not considered as spam - user becomes a normal trusted chat member.
- Create a bot via BotFather and enable group messages access.
- Clone the repository:
git clone https://github.com/iamwavecut/ngbot.git
cd ngbot- Copy the example environment file and configure it:
cp .env.example .env
# Edit .env with your favorite editor and set required variables- Start the bot:
docker compose up -d- Add your bot to chat and give it Ban, Delete, and Invite permissions.
- Optional: Change bot language with
/lang <code>(e.g.,/lang ru).
- Follow steps 1-3 from Quick Start.
- Build and run:
go mod download
go run .All configuration is done through environment variables. You can:
- Set them in your environment
- Use a
.envfile (recommended) - Pass them directly to docker compose or the binary
See .env.example for a quick reference of all available options.
| Required | Variable name | Description | Default | Options |
|---|---|---|---|---|
| ✔️ | NG_TOKEN |
Telegram BOT API token | ||
| ✔️ | NG_LLM_API_KEY |
OpenAI API key for content analysis | ||
NG_LANG |
Default language to use in new chats | en |
be, bg, cs, da, de, el, en, es, et, fi, fr, hu, id, it, ja, ko, lt, lv, nb, nl, pl, pt, ro, ru, sk, sl, sv, tr, uk, zh |
|
NG_HANDLERS |
Enabled bot handlers | admin,gatekeeper,reactor |
Comma-separated list of handlers | |
NG_LOG_LEVEL |
Logging verbosity | 2 |
0=Panic, 1=Fatal, 2=Error, 3=Warn, 4=Info, 5=Debug, 6=Trace |
|
NG_DOT_PATH |
Bot data storage path | ~/.ngbot |
Any valid filesystem path | |
NG_LLM_API_MODEL |
OpenAI model to use | gpt-4o-mini |
Any valid OpenAI model | |
NG_LLM_API_URL |
OpenAI API base URL | https://api.openai.com/v1 |
Any valid OpenAI API compliant base URL | |
NG_LLM_API_TYPE |
API type | openai |
openai, gemini |
|
NG_FLAGGED_EMOJIS |
Emojis used for content flagging | 👎,💩 |
Comma-separated list of emojis | |
NG_SPAM_LOG_CHANNEL_USERNAME |
Channel for spam logging | Any valid channel username | ||
NG_SPAM_VERBOSE |
Verbose in-chat notifications | false |
true, false |
|
NG_SPAM_VOTING_TIMEOUT |
Voting time limit | 5m |
Any valid duration string | |
NG_SPAM_MIN_VOTERS |
Minimum required voters | 2 |
Any positive integer | |
NG_SPAM_MAX_VOTERS |
Maximum voters cap | 10 |
Any positive integer | |
NG_SPAM_MIN_VOTERS_PERCENTAGE |
Minimum voter percentage | 5 |
Any positive float | |
NG_SPAM_SUSPECT_NOTIFICATION_TIMEOUT |
Suspect notification timeout | 2m |
Any valid duration string |
Don't hesitate to contact me
- Individual chat's settings (behaviours, timeouts, custom welcome messages, etc).
- Chat-specific spam filters.
- Settings UI in private and/or web.
Feel free to add your requests in issues.