Filters

Filters let you block or flag content based on specific words, domains, emails, or regex patterns. To use filters in moderation, you first create a blocklist, then attach it to a moderation policy.

Create a Blocklist

Create a custom blocklist with a name, type, and list of entries.

// Create a word blocklist
await client.createBlockList({
  name: "profanity_custom",
  words: ["badword1", "badword2", "offensive"],
  type: "word",
});

// Create a domain blocklist
await client.createBlockList({
  name: "blocked_domains",
  words: ["spam-site.com", "phishing.net"],
  type: "domain",
});

// Create a regex filter
await client.createBlockList({
  name: "phone_numbers",
  words: ["\\b\\d{3}[-.]?\\d{3}[-.]?\\d{4}\\b"],
  type: "regex",
});

// Create a domain allowlist (only these domains are permitted)
await client.createBlockList({
  name: "trusted_domains",
  words: ["myapp.com", "getstream.io"],
  type: "domain_allowlist",
});

// Create an email allowlist
await client.createBlockList({
  name: "approved_emails",
  words: ["support@myapp.com", "info@myapp.com"],
  type: "email_allowlist",
});

Request Parameters

Update a Blocklist

Replace the word list or settings of an existing blocklist.

await client.updateBlockList({
  name: "profanity_custom",
  words: ["badword1", "badword2", "offensive", "newword"],
  is_leet_check_enabled: true,
  is_plural_check_enabled: true,
});

List Blocklists

const response = await client.listBlockLists();

Get a Blocklist

const response = await client.getBlockList({ name: "profanity_custom" });

Delete a Blocklist

await client.deleteBlockList({ name: "profanity_custom" });

Attach a Blocklist to a Policy

Once created, attach your blocklist to a moderation policy to activate it. Each rule specifies the blocklist name and the action to take when matched.

await client.moderation.upsertConfig({
  key: "chat:messaging",
  block_list_config: {
    rules: [
      { name: "profanity_custom", action: "remove" },
      { name: "blocked_domains", action: "flag" },
      { name: "phone_numbers", action: "flag" },
    ],
  },
});

Filter Types

Word Matching

Word blocklists match exact words (case-insensitive). Adjacent punctuation is ignored, but partial word matches are not.

For a blocklist containing dogs, house:

• "Dogs, are great" — matches (case-insensitive, ignores comma)
• "I live in a lighthouse" — does not match (no partial match on house)

With leet speak detection enabled: d0g matches dog, w0m@n matches woman. With plural detection enabled: houses matches house, dog matches dogs.

Domain Matching

Domain filters match the suffix of URLs. gmail.com matches https://gmail.com, http://support.gmail.com, etc. A more specific filter like messenger.facebook.com only matches that subdomain.

When a domain_allowlist is attached to the policy, those hosts also win for AI link detection. Allow-listed URLs are not treated as unknown or forbidden links. Other AI labels on the same message (for example scam or harassment) still apply. Attachment URLs on the allowlist are skipped the same way.

Regex Matching

Regex filters support standard regular expression syntax. Tips:

• Use (?i) for case-insensitive matching
• Use \b for whole-word boundaries
• Escape special characters with \
• Max 100 patterns per filter, max 60 characters per pattern

Text normalization

Before filters run, text is decoded to the form a browser would render: HTML entities (decimal, hex, and named — with or without a trailing semicolon) are resolved, then zero-width and other invisible characters are stripped. A word list containing spam therefore matches visit spam now, and a regex (?i)https?:// matches an entity-encoded URL.

The stored message is not rewritten. See Text Normalization for the full list of entity forms, invisible code points, and what is not decoded (percent-encoding, fullwidth letters, homoglyphs).

Limits