Bad Words / Profanity Filter

Better Messages includes a server-side bad-words filter that rejects messages containing any term on a configurable banned list. The block happens before the message is delivered — recipients never see it, and the sender gets a clear error message you can customize. Useful for family-friendly communities, paid memberships, support channels, and any site where moderation reduces friction.

What it adds#

Admin-managed banned-word list (one term per line)
Case-insensitive matching across the entire message text
Configurable error message shown to the sender on blocked attempts
Optional bypass for administrator accounts (or any role you choose)
Works pre-send — blocked messages never reach the recipient or the database

How it works#

When a user submits a message, the filter walks each entry in the banned-word list and tests it as a word-boundary regex against the message text. If any term matches, the send is rejected and the configured error message is returned. The blocked message is not stored anywhere — there's no trail, no recipient notification, no database record.

Match scenario	Outcome
Message contains an exact banned word as a standalone token	Blocked, error shown
Banned word appears inside a larger word (e.g. "ass" inside "class")	Allowed — matching is word-boundary, not substring
Word in a different case	Blocked (case-insensitive)
Banned word inside an attached file's name	Allowed (only message text is scanned)
Sender has `manage_options` and Skip Administrators is on	Allowed
Sender edits an existing message to add a banned word	Allowed — the filter runs on send, not on edit

If you need substring matching for a specific term, type it with a leading or trailing fragment (e.g. viagra already matches Viagra, viagra! etc., but cialis will not match cialispharma). Multi-word phrases (e.g. click here) also work — the word-boundary regex treats the whole phrase as the token.

When to use#

Site type	Recommended setup
Family / kid-friendly community	Aggressive list, no admin bypass, friendly error message
General community / forum	Standard profanity list + competitor brand names
Marketplace	Block contact-info attempts: "WhatsApp", "Telegram", external emails, phone formats
LMS	Block academic dishonesty terms ("answer key", paid-essay services)
Support / commercial	Block spam keywords + common phishing terms

How to enable#

Navigate to WP Admin → Better Messages → Settings → Restrictions → Bad Words Filter.

Bad Words List — Enter banned words or phrases, one per line (case doesn't matter)
Skip Administrators — Let accounts with the manage_options capability bypass the filter
Filter Message — Custom message shown to the sender when their message is rejected

Frequently asked questions#

Can I bypass the filter for moderators, not just admins?#

The built-in Skip Administrators toggle covers only accounts with the manage_options capability. For a broader bypass (a custom Moderator role, say), hook the same two actions the filter itself uses at a later priority and clear its error — the $errors array is passed by reference:

add_action( 'better_messages_before_message_send', function ( &$args, &$errors ) {
    if ( current_user_can( 'moderate_comments' ) ) {
        unset( $errors['restrictBadWord'] );
    }
}, 20, 2 );

add_action( 'better_messages_before_new_thread', function ( &$args, &$errors ) {
    if ( current_user_can( 'moderate_comments' ) ) {
        unset( $errors['restrictBadWord'] );
    }
}, 20, 2 );

better_messages_can_send_message will not do it — that filter decides whether the user may post in the thread at all, and runs separately from the bad-words check.

Does the filter run on edited messages?#

No. The filter is attached to better_messages_before_new_thread and better_messages_before_message_send, and editing a message goes through update_message(), which does not fire either. A sender who edits an already-delivered message can introduce a banned word that way.

If that matters on your site, either turn off Settings → Messaging → Edit Messages (or shorten its Edit Time Limit) or add your own check on better_messages_message_content_before_save.

No — only the message text is scanned. Attached file names and contents are not. For images that may contain text, an image moderation service (or AI content moderation on the WebSocket version) is more appropriate.

What happens to a user who keeps trying to send banned words?#

Nothing automatic — each attempt is just rejected with the same error. For tiered escalation (e.g. temp-ban after N attempts), pair this with pre-moderation so a moderator sees the pattern.

How big can the banned-word list be?#

Up to a few hundred entries performs fine. Beyond that, performance starts to drop — every message runs each term through a regex test. Consolidate variants with a single root form when possible.