Aispam Commands

Complete guide to the Aispam module — the per-chat AI spam filter

🤖 Aispam Commands

The Aispam module is an opt-in, per-chat AI spam filter. When it is on, every new message in the chat is judged by TypeSafe’s Jev decision model against the chat’s own title, description and rules, and messages the model is confident are spam are deleted.

It is the only module that deletes on a judgement rather than a rule, and it is off in every chat until an admin turns it on.

Commands

on also accepts yes, true or enable, and off also accepts no, false or disable (case-insensitive). A bare /aispam reports status and lists the data sent to the model.

What Happens To A Flagged Message

Only one action exists: the message is deleted. No warning, no mute, no restriction, no reply, and no notice to the sender. Every deletion is mirrored to MESSAGE_DUMP with the probability, category, model version and the message text, which is the audit trail and the only feedback loop for tuning.

Thresholds

Jev is English-first, so only a message it reads as English takes the lower bar. The message’s own language decides, not the chat’s configured language: an English chat still receives posts written in other languages, and those are held to the higher bar. If the language answer is missing or unreadable, the higher bar applies.

What Is Skipped

These messages are never sent to the model:

• Anything from an admin or an approved user.
• Members still solving a captcha challenge.
• This bot’s own commands: a bare /command, or /command@thisbot. A slash message aimed at another bot is judged like any other text.
• Messages with no text or caption, and messages from bots, channels, anonymous admins or linked channels.
• Edits to a message already posted: only a message as first posted is judged, so a message edited into spam afterwards is not checked again.

What The Model Receives

For each checked message:

• The chat’s title, description, rules and language.
• The sender’s profile: days since the bot first saw them, messages in the last hour, warn count.
• The message text or caption, the domains it links to, and whether it is a forward or a reply.
• The sender’s few most recent messages in this chat, and how many messages they posted in the last hour.

The sender window is kept in Redis, keyed per chat and user. The message count covers only the last hour; the sender’s last five texts are kept until they have posted nothing in the chat for an hour, then expire on their own. Nothing else about a message is stored. A message joins the window even when the check that follows it fails, and losing Redis costs the window rather than the check: the message is still judged, with no history.

No names, usernames, user IDs, phone numbers, or messages from other chats are sent. /aispam prints this list in the chat.

Failure Behaviour

The filter fails open: a timeout, rate limit, server error or unparseable answer produces no verdict and no action. 429 and 5xx get at most one retry, after the provider’s Retry-After (0.5 s if it sends none). If it asks for more than 2 s, or the check’s 8 s budget runs out first, there is no retry and the check fails open. After five consecutive failures in a chat, checks for that chat pause for five minutes and the chat gets one notice; the stored setting is untouched, so protection resumes on its own.

Checks run on a bounded worker queue. When the queue is full — a raid, or a provider brownout — checks are shed rather than queued unbounded. A shed check means “not checked”, and antiflood still owns floods.

When the operator sets AISPAM_DAILY_LIMIT, checks past that many in a UTC day are skipped the same way until the next UTC day. A skipped check is not a failure: it does not pause the chat.

Required Permissions

Bot Permissions Required: the bot must be an admin with the Delete Messages permission. Enabling does not check this. Without it, messages are still sent to the model (and still use the operator’s API quota) and deletions are still mirrored to MESSAGE_DUMP, but nothing is removed from the chat.

Enabling is refused, with a message explaining why, when the bot operator has not configured an API key or has switched the filter off globally, so an admin is not told their chat is protected when the operator has not set the filter up. It does not check the bot’s own rights; see above.

Operator Setup

The key is registered with logredact, so it never appears in logs.