# Node

> Stream Moderation - Server Side SDKs - Node

---

# Getting Started

Stream's Moderation API lets you integrate content moderation into any application. This guide walks you through installing one of the [backend SDKs](https://getstream.io/docs/platform/backend-sdks/), creating a policy, and running your first moderation check.

Moderation lives in the [Stream Dashboard](https://getstream.io/signin/?product=moderation), where you can create and tune policies, manage AI rules and blocklists, and review flagged content across your app.

## Start here

- [Moderate any content](https://getstream.io/moderation/docs/node/integrations/custom-content/): Check text, images, audio, and video from your own product.
- [Policies](https://getstream.io/moderation/docs/node/configuration/policies/): Choose which engines run and what happens when content matches.
- [Stream Chat integration](https://getstream.io/moderation/docs/node/integrations/stream-chat/): Moderate chat messages with no code changes.
- [Stream Feeds integration](https://getstream.io/moderation/docs/node/integrations/stream-feeds/): Automatically moderate activities and comments as they are created or updated.
- [Review Queue](https://getstream.io/moderation/docs/node/content-moderation/review-queue/): Review flagged content and act on it: approve, delete, or ban.
- [Live video and audio](https://getstream.io/moderation/docs/node/integrations/live-video-and-audio/): Moderate calls and livestreams in real time with keyframes and captions.

## Stream CLI and Agent Skills

Manage moderation from your terminal with the [Stream CLI](https://getstream.io/cli/docs/), including scripting policy setup and AI-agent workflows. Install the CLI and the default [Agent Skills](https://getstream.io/agent-skills/docs/):

```bash
curl -fsSL https://getstream.io/cli.sh | bash
getstream skills
```

Then ask your agent in plain English, for example:

```text
/stream Show flagged content in the review queue.
```

See the [CLI docs](https://getstream.io/cli/docs/) and [Agent Skills docs](https://getstream.io/agent-skills/docs/) for more.

## Installation

```bash
npm install @stream-io/node-sdk
# or
yarn add @stream-io/node-sdk
```

## Initialize the client

```js label="Node.js"
import { StreamClient } from "@stream-io/node-sdk";
// or: const { StreamClient } = require("@stream-io/node-sdk");

const client = new StreamClient("YOUR_API_KEY", "YOUR_API_SECRET");
```

## Create a moderation policy

Before checking content, create a policy that defines which rules to apply:

```js label="Node.js"
await client.moderation.upsertConfig({
  key: "my_config",
  ai_text_config: {
    rules: [
      { label: "SPAM", action: "flag" },
      { label: "HATRED", action: "remove" },
    ],
  },
  block_list_config: {
    rules: [{ name: "profanity_en", action: "remove" }],
  },
});
```

> For Stream Chat, use config key `chat:messaging`. For Stream Feeds, use `feeds`. See [Configuration](https://getstream.io/moderation/docs/node/configuration/policies/) for details.

## Check content

```js label="Node.js"
const response = await client.moderation.check({
  entity_type: "post",
  entity_id: "post-123",
  entity_creator_id: "user-456",
  moderation_payload: {
    texts: ["Selling a bike, pickup in the city"],
  },
  config_key: "my_config",
});

console.log(response.recommended_action); // "keep", "flag", "remove", "shadow", or "bounce"
```

## Handle the response

The response includes:

- `recommended_action` -- `"keep"`, `"flag"`, `"remove"`, `"shadow"`, `"bounce"`, `"bounce_flag"`, `"bounce_remove"`, `"mask"`, or `"mask_flag"`
- `status` -- `"completed"` or `"pending"` (if async checks are still running)
- `item` -- the review queue item, when the action is not `keep`

The check returns a recommendation for your code to enforce. Stream adds flagged and removed content to the review queue:

```mermaid
flowchart TD
  content[Your content] --> check[Check API]
  check --> rec{recommended_action}
  rec -->|keep| keep[Publish it]
  rec -->|flag| queue[Review queue]
  rec -->|shadow| hidden[Show it only to the author]
  rec -->|remove| removed[Do not publish it]
  rec -->|bounce| bounced[Reject it before it is published]
  hidden --> queue
  removed --> queue
  queue --> review[Moderator marks it reviewed, restores it, or bans the user]
```

```js label="Node.js"
if (response.recommended_action === "keep") {
  // Publish the content
} else if (response.recommended_action === "flag") {
  // Publish it, and review the queued item
  console.log("Flagged for review:", response.item);
} else if (response.recommended_action === "shadow") {
  // Show it only to the author
} else if (
  response.recommended_action === "remove" ||
  response.recommended_action === "bounce" ||
  response.recommended_action === "bounce_remove"
) {
  // Do not publish it. Removed items stay in the review queue.
  console.log("Not published:", response.item);
}
```

## What's next

- [Policies](https://getstream.io/moderation/docs/node/configuration/policies/): Choose which engines run and what happens when content matches.
- [Review queue](https://getstream.io/moderation/docs/node/content-moderation/review-queue/): Query and act on flagged content.
- [Webhooks](https://getstream.io/moderation/docs/node/content-moderation/webhooks/): Get review queue events delivered to your backend.
- [Client configuration](https://getstream.io/moderation/docs/node/guides/client-configuration/): HTTP defaults, timeouts, and connection pooling.

## FAQ

**Which engines can check content?**

LLM and NLP text engines, plus image, video and audio moderation. Start with the [LLM text engine](https://getstream.io/moderation/docs/node/engines/ai-llm-text/).

**Do messages sent from my server get moderated?**

Content sent to the Check API is always moderated. Chat messages sent from the server skip moderation by default; set `force_moderation` to `true` to include them. The flag is server-side only and ignored when sent from a client-side SDK. See [chat moderation](https://getstream.io/moderation/docs/node/integrations/stream-chat/#server-side-integration).

**Can tenants manage their own moderation?**

Yes, for chat. Tenants manage their own policies, with client-side access restricted to their team, and team blocklists need a feature flag from support. See [multitenancy](https://getstream.io/moderation/docs/node/configuration/multitenancy/).

**Can I build my own review dashboard?**

Yes, on the same APIs Stream's dashboard uses. The [dashboard guide](https://getstream.io/moderation/docs/node/guides/build-moderation-dashboard/) walks through it.

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/](https://getstream.io/moderation/docs/node/).

---

# Architecture & Benchmark

Stream's Moderation API is designed to moderate text, images, audio, and video at high volume while maintaining low latency. Here we explain the architecture behind the API and share benchmarks from production traffic that show how it performs under load.

## Architecture overview

The Moderation API integrates as a standalone platform for any app that has user-generated content. Stream Chat, Video, and Feeds are integrations on top of that same API.

A few key things about the architecture:

- **Edge network:** Your backend connects to the nearest Stream edge server. TLS termination, authentication, and rate limiting happen at the edge.
- **Text, images, audio, and video:** One API and one policy cover all content types, so you do not need a separate vendor for each.
- **Excellent performance:** English text typically completes in about 35 ms. High-volume text classification handles 1,500+ requests per second with API latency under 50 ms. Image and live video API calls remain within the same latency range.
- **Highly redundant infrastructure:** Moderation runs primarily on Google Cloud, with failover across availability zones.

### Benchmark at a glance

Stream Moderation is measured continuously on production traffic. As you can see in the chart, text classification reaches over 1,500 requests per second at the daily peak while API latency stays at about 50 ms or lower. Latency rises slightly as load increases because more text needs translation at peak times. It returns to about 35 ms overnight. There is no degradation as traffic moves through the day.

![Text classification load and latency](https://getstream.io/docs-assets/images/f3337767c2b5.png)

Image and live-video traffic show the same pattern in the API: hundreds of requests per second, with latency between about 40 ms and 50 ms. Scoring a frame takes about 300 ms, so live-stream apps send frames without waiting for the model.

![Image and live-video load and latency](https://getstream.io/docs-assets/images/bc6cf7f70ff2.png)

## APIs and content types

One policy applies across three APIs and five content types.

| API                               | What you send                                                                                    |
| --------------------------------- | ------------------------------------------------------------------------------------------------ |
| `POST /api/v2/moderation/check`   | Text, image, audio files, and video files from your own entities. Returns keep, flag, or remove. |
| `POST /api/v2/moderation/labels`  | High-volume text. Returns labels without creating a review item for every message.               |
| `POST /api/v2/moderation/analyze` | Images and live-video keyframes, with optional text.                                             |

| Content         | How it runs                                                                                                                                            |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Text**        | Use check or labels. English text on the text send path typically completes in about 35 ms.                                                            |
| **Images**      | Use analyze or check. The API responds in about 40 ms. Scoring a photo takes about 300 ms.                                                             |
| **Live video**  | Your app samples keyframes and sends them to analyze. The same image model that scores still images scores the frames. You decide how often to sample. |
| **Video files** | Use check. The API accepts the upload, and scoring runs in the background.                                                                             |
| **Audio files** | Use check. The file is transcribed and then run through the same text engines. analyze does not accept audio.                                          |

## The tech behind the Stream Moderation API

Stream uses Go as the backend language for moderation.

### Edge network

When you call the API, the request goes to the nearest edge server. This is similar to how a CDN works, with more processing at the edge. Edge servers support HTTP/3 and HTTP/2. TLS terminates at the edge. Traffic between the edge and the origin servers is encrypted and uses long-lived HTTP/2 connections. Authentication, rate limiting, and CORS handling also run at the edge.

For resilience, the edge infrastructure uses circuit breakers, request retries, consistent-hash routing, and locality-aware load balancing with failover to another availability zone when needed.

### API performance

English text typically completes in about 35 ms, with a p95 of about 70 ms. Stream achieves this by caching policies and blocklists in memory and in Redis, and by keeping its own processing to a few milliseconds around the model call.

Each API fits a different workload. The text send path calls check. Games and other high-volume text apps call labels. Images and live-video keyframes go to analyze. Uploaded video and audio files stay on check and finish in the background.

### Infra & testing

A large Go integration test suite, production smoke tests, and QA run before each deploy. The infrastructure runs primarily on Google Cloud and is highly available. Enterprise customers can add a 99.999% uptime SLA.

## Benchmark

We measure live production traffic, which includes the policies and models that customers actually run. The numbers therefore include real model time and do not come from a synthetic replay that hides it. The charts on this page cover a global snapshot of seven days of production traffic from all regions, including Europe, US East, and US West.

English text on the text send path has a p50 of about 35 ms, a p95 of about 70 ms, and a p99 of about 100 ms.

![English text latency percentiles](https://getstream.io/docs-assets/images/90797df063bd.png)

### check: text (English)

|                | p50    | p95    | p99     |
| -------------- | ------ | ------ | ------- |
| Text send path | ~35 ms | ~70 ms | ~100 ms |

### labels: high-volume text

| Load         | p50     |
| ------------ | ------- |
| 1,500+ req/s | < 50 ms |

### analyze: images and live-video keyframes

| Load                       | API p50 | Time to score a frame |
| -------------------------- | ------- | --------------------- |
| Hundreds / sec (peak ~700) | ~40 ms  | ~300 ms               |

### check: video files and audio files

Both file types are accepted by the request and scored in the background. Video files go through a full-file job. Audio files are transcribed and then moderated as text. These paths are not inline, so we do not publish a millisecond p50 for them.

**Key takeaways:**

- **check** (English text): about 35 ms p50, 70 ms p95, 100 ms p99.
- **labels**: 1,500+ requests per second at under 50 ms p50.
- **analyze**: API under 50 ms, and a frame score in about 300 ms.
- **Video files and audio files**: processed in the background on **check**.
- API latency stays at about 50 ms or lower through the daily traffic peak.

For model quality (precision and recall across content categories), see the [AI Moderation Benchmark Report](https://getstream.io/assets/stream-moderation-benchmark-17074005.pdf). This page is how the API is built and how it behaves under load.

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/architecture-and-benchmark/](https://getstream.io/moderation/docs/node/architecture-and-benchmark/).

---

# Roadmap & Changelog

## Roadmap

- Dashboard control for which text engine runs on a policy. `llm_config` and `ai_text_config` already exist together on the API
- JSON editor to set up the LLM by pasting a config
- Policy versioning: revert to an older config from the policy or evaluation screen
- Stronger scam and phishing detection (AI on top of URL allowlists, with user scoring)
- LLM judge for sensitive labels
- Vertical policy packs

## Changelog

### October 2026

**LLM context from custom data**

- AI Text (LLM) policies can read selected `moderation_payload.custom` keys as background context, e.g. the article or video a comment is posted under and the earlier replies in its thread
- Set `context_custom_keys` (up to 10 keys) and an optional `custom_keys_context_description` on `llm_config`
- Only `texts` are moderated; the context is never scored, labelled or flagged, and instructions inside it are ignored
- Details: [Context from custom data](https://getstream.io/moderation/docs/node/engines/ai-llm-text/#context-from-custom-data)

### September 2026

**Text normalization before moderation**

- Chat, Feeds, and Check now decode HTML entities and strip zero-width / invisible characters **before** filters, AI, and the review queue run
- Encoded URLs and words (`&#104;&#116;&#116;&#112;&#115;://…`, missing semicolons, `&amp;#104;` chains, `h&#8203;ttp`) match the same plain rules as the rendered text
- Stored message bodies are unchanged; the review queue shows the decoded copy
- Details: [Text Normalization](https://getstream.io/moderation/docs/node/guides/text-normalization/)

**Analyze API**

- New `analyze` method on the server-side SDKs (`POST /api/v2/moderation/analyze`) for per-field text and image screening
- Documented on the Content page next to Check, with a comparison of when to use each
- Named `texts` via the server-side SDKs. Raw `image:<label>` bytes are HTTP multipart only (not in the SDK)
- Stateful (review queue + rules) or stateless (inline verdicts only). Sync HTTP body or async completion webhooks
- New webhook events: `moderation.text_analysis.complete`, `moderation.image_analysis.complete`, `moderation.analysis.failed`
- Details: [Analyze](https://getstream.io/moderation/docs/node/content-moderation/check/#analyze)

**Keyframe video moderation**

- Uploaded videos can be sampled into frames, run through image AI, and scored worst-frame-wins
- Results present as `ai_video`, so existing video rules, billing, and queue filters keep working
- Configure sampling in the dashboard; flagged videos play in the review queue
- Call review: the timeline shows which rule fired and highlights the keyframe or caption that caused it
- Details: [AI Video File Moderation](https://getstream.io/moderation/docs/node/engines/ai-video-file-moderation/)

**Rules and flood detection**

- `user_reaction_count`: act on reaction velocity, or on the number of distinct messages a user reacted to
- `user_identical_image_count`: the same image matches by bytes, not by CDN URL
- Identical flood can count the same text across users (`track_across_users`)
- Flood windows accept `30s` and `15s`. Optional `min_text_length` skips short copy
- Optional `country_code` on Check and Analyze (ISO 3166-1 alpha-2)
- Feeds activity and comment `custom` now reaches content custom-property rules
- Domain allow lists win over AI Link / URL detection for those hosts
- Details: [Rules](https://getstream.io/moderation/docs/node/configuration/rules/) and [Flooding](https://getstream.io/moderation/docs/node/configuration/flooding/)

**Review queue and dashboard**

- Dedicated Moderation API and webhook logs, no longer mixed into Chat → Logs
- Usage → Moderation: org-wide AI text, image, and video charts plus a per-app table
- Content queue: min-confidence filter, keyword search, and filter by rule name
- Labels explorer: keyword search on stored content
- Custom queue actions for standalone (non-Chat / Feeds) entities
- Restore is the single reversal action (replaces a separate Unblock)
- Context modal shows the action taken, and nests image L2s under their L1
- Appeals: translate the reason and linked content; appeal one `stream:user` ban at a time
- Server-side shadow enforcement: shadowed Chat messages and Feeds activities stay visible only to the author
- Details: [Review Queue](https://getstream.io/moderation/docs/node/content-moderation/review-queue/), [Appeals](https://getstream.io/moderation/docs/node/content-moderation/appeals/), and [Logs & Analytics](https://getstream.io/moderation/docs/node/content-moderation/logs-and-analytics/)

### August 2026

**Policy evaluations**

- New Evaluations page under Configuration in the Moderation dashboard
- Create a fixed batch of production or pasted content, run it through a policy, and compare later runs to a baseline
- Server-side REST API under `/api/v2/moderation/policy_tests/`

### February 2026

**New Moderation Dashboard + Analytics**

- Moderation dashboard available in legacy and beta
- Call moderation analytics widgets in both dashboards

**Advanced Call Moderation Controls**

- Configurable call moderation via rule builder
- Reactive moderation support (e.g., moderate only new users)
- Ban user after X call violations

**Expanded API & SDK Moderation Support**

- `SendMessage` API now includes moderation object (server-side)
- `check_username` method added to Ruby SDK
- Delete action support in moderation queue + webhook event

### January 2026

- User Profile Moderation
- Added support for delete actions within the queue with a corresponding webhook event

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/roadmap-and-changelog/](https://getstream.io/moderation/docs/node/roadmap-and-changelog/).

---

# Policies

## Overview

Policies define how content is moderated. A policy names the engines that run, the labels those engines look for, and the action to take on a match. Each policy has a key. A team can have its own policy.

After you change a policy, use [Evaluations](https://getstream.io/moderation/docs/node/configuration/evaluations/) to re-run a fixed batch of content and see what improved or drifted.

## Upsert Config

Creates or updates a policy. If a policy with that key already exists, it is replaced. A policy can include any combination of engines: NLP text, LLM text, images, video files, audio, blocklists, flood detection, and live video rules.

```js label="Node.js"
await client.moderation.upsertConfig({
  key: "my_config",
  ai_text_config: {
    rules: [
      { label: "SPAM", action: "flag" },
      {
        label: "HATRED",
        severity_rules: [
          { severity: "low", action: "flag" },
          { severity: "high", action: "remove" },
        ],
      },
    ],
  },
  block_list_config: {
    rules: [{ name: "profanity_en", action: "remove" }],
  },
  ai_image_config: {
    rules: [
      { label: "Non-Explicit Nudity", action: "flag", min_confidence: 50 },
    ],
  },
});
```

### Request Parameters

| key               | required | type    | description                                                                           |
| ----------------- | -------- | ------- | ------------------------------------------------------------------------------------- |
| key               | true     | string  | Unique identifier for the policy. Send it as `config_key` on a check.                 |
| team              | false    | string  | Team identifier for multi-tenancy. Scopes the policy to a specific team.              |
| async             | false    | boolean | When true, checks that use this policy run asynchronously.                            |
| ai_text_config    | false    | object  | Configuration for AI text analysis. Define rules mapping harm labels to actions.      |
| ai_image_config   | false    | object  | Configuration for AI image moderation (e.g., nudity, violence detection).             |
| ai_video_config   | false    | object  | Configuration for AI video moderation.                                                |
| ai_audio_config   | false    | object  | Configuration for AI audio moderation.                                                |
| block_list_config | false    | object  | Which blocklists to use and the action for each.                                      |
| llm_config        | false    | object  | LLM text moderation. See [LLM config](#llm-config).                                   |
| flood_config      | false    | object  | Configuration for per-user flood detection (identical and similar message detectors). |

## Get Config

Retrieve one policy by its key, including every engine and rule on it.

```js label="Node.js"
await client.moderation.getConfig({ key: "my_config" });
```

### Request Parameters

| key  | required | type   | description                        |
| ---- | -------- | ------ | ---------------------------------- |
| key  | true     | string | The policy key.                    |
| team | false    | string | Team identifier for multi-tenancy. |

### Response

| key    | type   | description                                      |
| ------ | ------ | ------------------------------------------------ |
| config | object | The policy. The response field name is `config`. |

## Delete Config

Delete a policy. Checks that name this key no longer use it.

```js label="Node.js"
await client.moderation.deleteConfig({ key: "my_config" });
```

### Request Parameters

| key  | required | type   | description                        |
| ---- | -------- | ------ | ---------------------------------- |
| key  | true     | string | The policy key.                    |
| team | false    | string | Team identifier for multi-tenancy. |

## Query Configs

List policies, with sorting and pagination.

```js label="Node.js"
await client.moderation.queryModerationConfigs({
  filter: {},
  sort: [{ field: "created_at", direction: -1 }],
  limit: 10,
});
```

### Request Parameters

| key    | required | type   | description                            |
| ------ | -------- | ------ | -------------------------------------- |
| filter | false    | object | Filter conditions.                     |
| sort   | false    | array  | Sort parameters (e.g., by created_at). |
| limit  | false    | number | Maximum number of policies to return.  |
| next   | false    | string | Cursor for pagination.                 |

### Response

| key     | type   | description                                     |
| ------- | ------ | ----------------------------------------------- |
| configs | array  | Policies. The response field name is `configs`. |
| next    | string | Next cursor for pagination.                     |

## Policy fields

A policy can include any of these engines. The field names are the API names.

| Config Field           | Description                                                                                                                                | Engine Documentation                                                                   |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| ai_text_config         | NLP text classification. Each rule is a `label` and an `action`, for example `INSULT` or `HATRED`.                                         | [AI Text](https://getstream.io/moderation/docs/node/engines/ai-text/)                                |
| llm_config             | LLM classification. Each rule has a `label`, a `description`, and an `action`.                                                             | [LLM Text](https://getstream.io/moderation/docs/node/engines/ai-llm-text/)                           |
| ai_image_config        | Image classification. Every rule requires `label`, `action`, and `min_confidence` (0–100). `ocr_rules` classifies text found in the image. | [Image Moderation](https://getstream.io/moderation/docs/node/engines/image-moderation/)              |
| ai_video_config        | Video file classification. Uses the same rule shape as images. Live video uses `video_call_rule_config`.                                   | [Video Moderation](https://getstream.io/moderation/docs/node/engines/ai-video-file-moderation/)      |
| ai_audio_config        | Audio transcription plus `ai_text_config` or `llm_config` on the transcript. The top-level `rules` list is the legacy fallback.            | [Audio Moderation](https://getstream.io/moderation/docs/node/engines/ai-audio-file-moderation/)      |
| block_list_config      | Blocklist and regex filtering. The field name is `block_list_config`.                                                                      | [Blocklists and Regex Filters](https://getstream.io/moderation/docs/node/configuration/filters/)     |
| flood_config           | Per-user detection of repeated or near-duplicate messages                                                                                  | [Flooding](https://getstream.io/moderation/docs/node/configuration/flooding/)                        |
| rule_builder_config    | At most 3 rules. Each rule or group has at most 5 conditions.                                                                              | [Rules](https://getstream.io/moderation/docs/node/configuration/rules/)                              |
| intent_config          | Up to 20 conversation topics. A match sends `moderation.intent_detected`.                                                                  | [Webhooks](https://getstream.io/moderation/docs/node/content-moderation/webhooks/)                   |
| video_call_rule_config | Harm rules for live video and audio. The field name is `video_call_rule_config`.                                                           | [Live video and audio](https://getstream.io/moderation/docs/node/integrations/live-video-and-audio/) |

### LLM config

`llm_config` sets up the [AI Text (LLM)](https://getstream.io/moderation/docs/node/engines/ai-llm-text/) engine. Upserting the policy replaces the whole `llm_config`, so send every field you want to keep.

| key                             | type             | description                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| app_context                     | string           | Short description of your application and how users interact, so the LLM understands the setting.                                                                                                                                                                                                                                                                                      |
| rules                           | array            | Harm labels. Each rule has a `label` (required), a plain-language `description` of what to detect (optional; without it the LLM uses the label name alone), an `action` (`flag`, `shadow`, `remove`, `bounce`, `bounce_flag`, `bounce_remove` or `keep`) and optional [`severity_rules`](#llm-severity-rules). The engine runs when `rules` contains at least one rule with an action. |
| severity_descriptions           | object           | Optional. What each severity means to the LLM, keyed `LOW`, `MEDIUM`, `HIGH` and `CRITICAL`. When omitted, Stream fills in defaults, for example `LOW` is "Content that needs review but may be acceptable" and `HIGH` is "Content that must be removed immediately".                                                                                                                  |
| async                           | boolean          | Optional. Runs LLM moderation asynchronously. Defaults to `false`: the check waits for the LLM verdict.                                                                                                                                                                                                                                                                                |
| context_custom_keys             | array of strings | Top-level `moderation_payload.custom` keys passed to the LLM as background context. Never moderated themselves. Up to 10 keys, each 1-64 characters. See [Context from custom data](https://getstream.io/moderation/docs/node/engines/ai-llm-text/#context-from-custom-data).                                                                                                                        |
| custom_keys_context_description | string           | How the LLM should read the context keys. Up to 1000 characters (UTF-8 bytes). Requires `context_custom_keys`.                                                                                                                                                                                                                                                                         |

#### LLM severity rules

`severity_rules` is an array of `{ severity, action }`, with `severity` one of `low`, `medium`, `high` or `critical`. When the verdict's severity has a severity rule, that action is used; otherwise the rule's own `action` applies. For example, `{ "severity": "low", "action": "flag" }` sends low-severity matches to review instead of removing them.

### Intent config

`intent_config` is a list of conversation topics, up to 20. Each topic has a `label` and an optional `description`. A topic does not take an action by itself. A [rule](https://getstream.io/moderation/docs/node/configuration/rules/) with an `intent_rule` condition names the topic, the score that counts as a match, and the action. A match sends `moderation.intent_detected`. See [Webhooks](https://getstream.io/moderation/docs/node/content-moderation/webhooks/).

### Rule actions

These are the actions an engine rule can return. The API accepts the ones marked for that engine.

| Action          | What it does                                  | NLP text | LLM | Image, video, OCR | Blocklist |
| --------------- | --------------------------------------------- | -------- | --- | ----------------- | --------- |
| `keep`          | Leave the content in place.                   | yes      | yes |                   |           |
| `flag`          | Queue it for review.                          | yes      | yes | yes               | yes       |
| `mask`          | Replace the matched text.                     | yes      |     |                   | yes       |
| `mask_flag`     | Replace the matched text and queue it.        | yes      |     |                   | yes       |
| `shadow`        | Show it only to the author.                   | yes      | yes | yes               | yes       |
| `remove`        | Do not publish it, and queue it.              | yes      | yes | yes               | yes       |
| `bounce`        | Reject it before it is published.             | yes      | yes | yes               | yes       |
| `bounce_flag`   | Reject it and queue it.                       | yes      | yes | yes               | yes       |
| `bounce_remove` | Reject it, treat it as removed, and queue it. | yes      | yes | yes               | yes       |

`queryModerationRules` returns `default_llm_labels` and `ai_image_label_definitions`. Use those strings as rule labels. `SPAM` is a valid NLP label. `HARASSMENT` is not; use `HATRED`, `INSULT`, `SEXUAL_HARASSMENT`, or `MORAL_HARASSMENT`.

### Severity Levels

For AI text analysis rules, you can define severity-based rules instead of a single action. This allows different actions depending on how severe the detected violation is. The available severity levels are:

| Severity   | Description                                                                |
| ---------- | -------------------------------------------------------------------------- |
| `low`      | Minor or borderline violations. Typically used for flagging or monitoring. |
| `medium`   | Moderate violations that may warrant content removal or closer review.     |
| `high`     | Serious violations that typically result in content removal.               |
| `critical` | The most severe violations requiring immediate action.                     |

When using severity rules, each severity level can be mapped to a different action. For example, you might flag low-severity harassment but automatically remove high-severity harassment, as shown in the Upsert Config example above.

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/configuration/policies/](https://getstream.io/moderation/docs/node/configuration/policies/).

---

# Rules

Rules run an action when their conditions match. Scope a rule to specific policies with `config_keys`, or leave that list empty to apply it app-wide.

## Upsert Rule

Create or update a moderation rule. This endpoint uses `POST /api/v2/moderation/moderation_rule` and allows you to define the rule name, conditions, actions, and other configuration in a single request.

```js label="Node.js"
await client.moderation.upsertModerationRule({
  name: "ban_on_severe_harassment",
  rule_type: "user",
  config_keys: ["chat:messaging"],
  logic: "AND",
  action: {
    type: "ban_user",
    ban_options: { duration: 3600, reason: "Severe harassment" },
  },
  conditions: [
    {
      type: "text_rule",
      text_rule_params: { harm_labels: ["HATRED"], severity: "critical" },
    },
  ],
  enabled: true,
  description: "Auto-ban users for critical harassment",
});
```

### Request Parameters

| key             | required | type    | description                                                                                                                     |
| --------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
| name            | true     | string  | Unique name for the rule. Rules are keyed by name. There is no `id` field.                                                      |
| rule_type       | true     | string  | `user`, `content`, `call`, or `flood`.                                                                                          |
| config_keys     | false    | array   | Policy keys this rule applies to. Empty means every policy.                                                                     |
| action          | false    | object  | `type` is one of `ban_user`, `flag_content`, `block_content`, and the rest of the action enum. Ban details go in `ban_options`. |
| conditions      | false    | array   | Typed conditions. Each item sets `type` and the matching `*_params` object. Flat `label` / `severity` keys are not a condition. |
| groups          | false    | array   | Condition groups for complex logic.                                                                                             |
| enabled         | false    | boolean | Whether the rule is active.                                                                                                     |
| description     | false    | string  | Human-readable description of the rule.                                                                                         |
| cooldown_period | false    | string  | Cooldown period between rule triggers (e.g., "1h", "24h").                                                                      |
| team            | false    | string  | Team identifier for multi-tenancy.                                                                                              |

### Response

| key  | type   | description                             |
| ---- | ------ | --------------------------------------- |
| rule | object | The created or updated moderation rule. |

## Get Rule

Retrieve a single moderation rule by its ID. This endpoint uses `GET /api/v2/moderation/moderation_rule/{id}` and returns the full rule object including its conditions, actions, and metadata.

```js label="Node.js"
await client.moderation.getModerationRule({ id: "rule_id" });
```

### Request Parameters

| key | required | type   | description                                   |
| --- | -------- | ------ | --------------------------------------------- |
| id  | true     | string | The unique identifier of the moderation rule. |

### Response

| key  | type   | description          |
| ---- | ------ | -------------------- |
| rule | object | The moderation rule. |

## Delete Rule

Delete a moderation rule by its ID. This endpoint uses `DELETE /api/v2/moderation/moderation_rule/{id}` and permanently removes the rule from the system.

```js label="Node.js"
await client.moderation.deleteModerationRule({ id: "rule_id" });
```

### Request Parameters

| key | required | type   | description                                             |
| --- | -------- | ------ | ------------------------------------------------------- |
| id  | true     | string | The unique identifier of the moderation rule to delete. |

### Response

| key      | type   | description       |
| -------- | ------ | ----------------- |
| duration | string | Request duration. |

## Query Rules

Query moderation rules with optional filters, sorting, and pagination. This endpoint uses `POST /api/v2/moderation/moderation_rules` and supports standard query patterns for listing and searching rules.

```js label="Node.js"
await client.moderation.queryModerationRules({
  filter: { enabled: true },
  sort: [{ field: "created_at", direction: -1 }],
  limit: 10,
});
```

### Request Parameters

| key    | required | type   | description              |
| ------ | -------- | ------ | ------------------------ |
| filter | false    | object | Filter conditions.       |
| sort   | false    | array  | Sort parameters.         |
| limit  | false    | number | Maximum rules to return. |
| next   | false    | string | Cursor for pagination.   |

### Response

| key   | type   | description                 |
| ----- | ------ | --------------------------- |
| rules | array  | List of moderation rules.   |
| next  | string | Next cursor for pagination. |

## Rule Actions Reference

The following table lists all available action types that can be assigned to a moderation rule. Each action defines what happens when the rule conditions are met.

| action type           | description                                                                                                                                                                                                                                                                                                                          |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| flag_content          | Flag the content for manual review.                                                                                                                                                                                                                                                                                                  |
| block_content         | Block the content.                                                                                                                                                                                                                                                                                                                   |
| shadow_content        | Shadow the content so other users do not see it.                                                                                                                                                                                                                                                                                     |
| bounce_content        | Bounce the message back to the sender.                                                                                                                                                                                                                                                                                               |
| bounce_flag_content   | Bounce the message and flag it.                                                                                                                                                                                                                                                                                                      |
| bounce_remove_content | Bounce the message and remove it.                                                                                                                                                                                                                                                                                                    |
| ban_user              | Ban the user. `ban_options.duration` is seconds (`3600` is one hour); omit it for a ban that does not expire. `shadow_ban` hides the ban from the user. `ip_ban` also bans that IP. Live video rules use the actions on [Live video and audio](https://getstream.io/moderation/docs/node/integrations/live-video-and-audio/) instead of this list. |
| flag_user             | Flag the user.                                                                                                                                                                                                                                                                                                                       |
| webhook_only          | Send `moderation_rule.triggered` without a further enforcement action. See [Rule-Triggered Webhooks](https://getstream.io/moderation/docs/node/content-moderation/webhooks/#rule-triggered-webhooks).                                                                                                                                              |

## Global vs policy-specific rules

### Global rules

Global rules apply to all the content in your application, as long as it reaches the moderation system.

```json
{
  "name": "Global Spam Detection",
  "description": "Applies to every policy",
  "team": "moderation",
  "config_keys": [], // Empty array = global rule
  "rule_type": "user",
  "enabled": true,
  "cooldown_period": "24h",
  "conditions": [
    // ... conditions
  ],
  "logic": "AND",
  "action": {
    // ... action definition
  }
}
```

### Policy-specific rules

These rules only run for the policies you list in `config_keys`.

E.g., if you have a rule that only applies to chat, you can set the `config_keys` to `["chat:messaging", "chat:support"]`, then counters will only be counted for messages sent in the channel types mentioned.

```json
{
  "name": "Chat-Only Rule",
  "description": "Only applies to chat policies",
  "team": "moderation",
  "config_keys": ["chat:messaging", "chat:support"], // These policies only
  "rule_type": "user",
  "enabled": true,
  "cooldown_period": "12h",
  "conditions": [
    // ... conditions
  ],
  "logic": "AND",
  "action": {
    // ... action definition
  }
}
```

## Basic rule structure

Every rule has three main parts:

1. **Conditions**: What behavior to watch for
2. **Threshold**: How many violations before taking action
3. **Action**: What to do when the threshold is reached

### Example: Complete Rule Structure

```json
{
  "name": "Spam Detection",
  "description": "Detects and bans users for spam behavior",
  "team": "moderation",
  "config_keys": ["chat:messaging", "chat:support"],
  "rule_type": "user",
  "enabled": true,
  "cooldown_period": "24h",
  "conditions": [
    {
      "type": "text_rule",
      "text_rule_params": {
        "threshold": 5,
        "time_window": "1h",
        "llm_harm_labels": {
          "SCAM": "Fraudulent content, phishing attempts, or deceptive practices",
          "PLATFORM_BYPASS": "Content that attempts to circumvent platform moderation systems"
        }
      }
    },
    {
      "type": "content_count_rule",
      "content_count_rule_params": {
        "threshold": 50,
        "time_window": "1h"
      }
    }
  ],
  "logic": "OR",
  "action": {
    "type": "ban_user",
    "ban_options": {
      "duration": 3600,
      "reason": "Spam behavior detected",
      "shadow_ban": false,
      "ip_ban": false
    }
  }
}
```

This rule:

- Watches for spam and advertising content
- Triggers when a user posts 5+ spam messages within 1 hour or 50+ messages within 1 hour
- Bans the user for 1 hour when triggered

## Condition types

These are the conditions you can put on a rule. Send them on [Upsert Rule](#upsert-rule). A rule can have at most 5 conditions, and a policy at most 3 rules.

Every condition `type`. Conditions in one rule combine with `AND` or `OR`. The sections after the table document the types that take extra fields.

| type                            | What it matches                                                           |
| ------------------------------- | ------------------------------------------------------------------------- |
| `text_rule`                     | NLP or LLM labels on text.                                                |
| `image_rule`                    | Image labels.                                                             |
| `video_rule`                    | Video-file labels.                                                        |
| `text_content`                  | Text harm labels on one piece of content.                                 |
| `image_content`                 | Image harm labels on one piece of content.                                |
| `video_content`                 | Video harm labels on one piece of content.                                |
| `ocr_content`                   | Text harm labels on text read out of one image.                           |
| `content_custom_property`       | A custom field on the entity. Stream Chat and Feeds only.                 |
| `content_country_code`          | The ISO country code on the check (`US`, `DE`).                           |
| `content_custom_property_count` | How often a user's content has a matching custom field.                   |
| `content_count_rule`            | How many messages a user sent in a window.                                |
| `content_flag_count_rule`       | How many times a user's content was flagged in a window.                  |
| `user_rule`                     | A user-level harm label.                                                  |
| `user_reaction_count`           | How many reactions a user sent, or how many messages they reacted to.     |
| `user_channel_count`            | How many channels a user created in a window.                             |
| `user_channel_ban_count`        | How many distinct channels have banned the user in a window.              |
| `user_flag_count_rule`          | How many times the user was flagged in a window.                          |
| `user_created_within`           | The user's account is newer than the window.                              |
| `user_custom_property`          | A custom field on the user.                                               |
| `user_role`                     | The user's role.                                                          |
| `user_identical_content_count`  | How many times a user sent the same text.                                 |
| `user_identical_image_count`    | How many times a user sent the same image bytes.                          |
| `channel_message_count_rule`    | The channel's lifetime message count.                                     |
| `flood_identical`               | The same text repeated. Can count across users.                           |
| `flood_similar`                 | Near-duplicate text, per user.                                            |
| `keyframe_rule`                 | Harm labels on consecutive live-video frames.                             |
| `keyframe_ocr_rule`             | Harm labels on text read from consecutive frames.                         |
| `closed_caption_rule`           | Harm labels on consecutive captions.                                      |
| `call_type_rule`                | The Stream call type.                                                     |
| `call_custom_property`          | A custom field on the call.                                               |
| `call_violation_count`          | How many live-video rules the user has triggered.                         |
| `ip_content_count_rule`         | How much content one IP sent.                                             |
| `ip_flag_count_rule`            | How many flags one IP received.                                           |
| `intent_rule`                   | A conversation topic from `intent_config` scored at or above a threshold. |

### Reaction velocity

`user_reaction_count` is a **user** rule. It fires when one user sends too many reactions in a window (app-wide, not per channel). A reaction has no text to score, so message rules never see this.

`count` picks the unit:

- `reactions` (default): every reaction event
- `reacted_messages`: each message they reacted to counts once. Stacking several reaction types on one post is still 1.

```json
{
  "type": "user_reaction_count",
  "user_reaction_count_params": {
    "threshold": 10,
    "time_window": "1m",
    "count": "reacted_messages"
  }
}
```

| Field         | Required | Description                                                       |
| ------------- | -------- | ----------------------------------------------------------------- |
| `threshold`   | yes      | Inclusive. Must be greater than 0.                                |
| `time_window` | yes      | One of `15s`, `30s`, `1m`, `5m`, `30m`, `1h`, `24h`, `7d`, `30d`. |
| `count`       | no       | `reactions` (default) or `reacted_messages`.                      |

Use a user action (`ban`, `flag` the user, or a webhook). This only runs when a reaction is moderated.

### Identical images

`user_identical_image_count` is a **user** rule. It counts how many times the same user posts the same image. Identity comes from the **image bytes** Stream already downloads for moderation, not the CDN URL, so a re-upload still matches.

```json
{
  "type": "user_identical_image_count",
  "user_identical_image_count_params": {
    "threshold": 3,
    "time_window": "5m",
    "match": "exact"
  }
}
```

| Field                 | Required | Description                                                                              |
| --------------------- | -------- | ---------------------------------------------------------------------------------------- |
| `threshold`           | yes      | Inclusive. Must be at least 1.                                                           |
| `time_window`         | yes      | One of `15s`, `30s`, `1m`, `5m`, `30m`, `1h`.                                            |
| `match`               | no       | `exact` (default): same file bytes. `similar`: near-duplicate after resize or re-encode. |
| `similarity_distance` | no       | Only with `match: "similar"`. 1 to 20, default 10. Lower is stricter.                    |

Images that cannot be fetched are skipped (fail-open).

### Flood identical and similar

`rule_type: "flood"` is for repeated copy. Conditions are `flood_identical` (exact text after normalization, or media when there is no text) and `flood_similar` (near-duplicate text). Both default to **per user**. Actions are the content actions (`flag`, `remove`, `shadow_block`) and `webhook_only`. There is no cooldown: with a content action, once the threshold is hit every further match is actioned. With `webhook_only`, the rule sends `moderation_rule.triggered` once each time the count reaches a multiple of `threshold` (100, 200, 300... for a threshold of 100), and cross-user rules list the senders since the previous webhook in `matched_user_ids`. See [Rule-triggered webhooks](https://getstream.io/moderation/docs/node/content-moderation/webhooks/#flood-rule-notify-on-repeated-copy).

```json
{
  "type": "flood_identical",
  "flood_identical_params": {
    "threshold": 5,
    "time_window": "30s",
    "track_across_users": true,
    "min_text_length": 20,
    "allowlist": ["gg"]
  }
}
```

| Field                | Required | Description                                                                                                                                                      |
| -------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `threshold`          | yes      | 2 to 100, inclusive.                                                                                                                                             |
| `time_window`        | yes      | One of `15s`, `30s`, `1m`, `2m`, `3m`, `5m`, `10m`, `15m`, `30m`, `1h`.                                                                                          |
| `allowlist`          | no       | Phrases that do not count, after the same normalization.                                                                                                         |
| `track_across_users` | no       | Identical only. Default `false` is per user. `true` counts that same text from **anyone** (coordinated copy-paste). It is total occurrences, not distinct users. |
| `min_text_length`    | no       | Identical only. Skip shorter text (3 to 500). Omitted or `0` uses 3. Attachment-only messages still count.                                                       |

`flood_similar` uses the same `threshold`, `time_window`, and `allowlist`, plus `similarity_distance` (1 to 16). It has no across-users option.

This is separate from policy [flood_config](https://getstream.io/moderation/docs/node/configuration/flooding/), which stays per user and has no `track_across_users` or `min_text_length`.

### Custom properties (Stream Chat and Feeds only)

`content_custom_property` matches a key on the moderated entity. Stream Chat sends `message.custom`. Stream Feeds sends activity and comment `custom`. A rule on `audience_rating` can match a message, a post, or a comment. Other products do not send this field.

```json
{
  "type": "content_custom_property",
  "content_custom_property_params": {
    "property_key": "audience_rating",
    "operator": "eq",
    "expected_value": "kids"
  }
}
```

Operators: `exists`, `not_exists`, `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `contains`, `not_contains`.

To act on how often a user sends matching custom values, use `content_custom_property_count` with `threshold` and `time_window`.

## Time windows

Counting conditions accept `15s`, `30s`, `1m`, `5m`, `30m`, `1h`, `24h`, `7d`, and `30d`. Flood conditions use a shorter set: `15s`, `30s`, `1m`, `2m`, `3m`, `5m`, `10m`, `15m`, `30m`, and `1h`. Live video cooldowns are `5s`, `10s`, `1m`, `5m`, and `10m`.

## Cooldown Periods

The Rule Builder supports cooldown periods to prevent immediate re-triggering of rules after an action has been taken. This is particularly useful when users are banned and then unbanned by administrators.

When a rule with a cooldown period is triggered and an action is taken (like banning a user), the system records this action with an expiration time. During the cooldown period, the same rule will not trigger again for that user, even if they continue to violate the conditions.

### Configuration

Add a `cooldown_period` field to the rule:

```json
{
  "name": "Spam Detection with Cooldown",
  "description": "Spam detection rule with 24h cooldown",
  "team": "moderation",
  "config_keys": [],
  "rule_type": "user",
  "enabled": true,
  "cooldown_period": "24h",
  "conditions": [
    // ... conditions
  ],
  "action": {
    "type": "ban_user",
    "ban_options": {
      "duration": 3600,
      "reason": "Spam behavior detected",
      "shadow_ban": false,
      "ip_ban": false
    }
  }
}
```

### Example Scenario

1. **User violates rule**: User posts 5 spam messages in 1 hour
2. **Rule triggers**: User gets banned for 1 hour
3. **Admin unbans user**: Administrator manually unbans the user
4. **User posts again**: User immediately posts more spam messages
5. **Cooldown active**: Rule does not trigger again due to 24-hour cooldown
6. **After cooldown**: User can trigger the rule again after 24 hours

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/configuration/rules/](https://getstream.io/moderation/docs/node/configuration/rules/).

---

# Filters

Filters let you act on content that matches words, domains, emails, or regex patterns. The action (flag, remove, mask, and the others on a [policy](https://getstream.io/moderation/docs/node/configuration/policies/#rule-actions)) is set when you attach the filter.

To use filters, you first create a filter, then attach it to a moderation policy.

## Filter Types

| Type             | `type` value       | Description                                                                       |
| ---------------- | ------------------ | --------------------------------------------------------------------------------- |
| Word Blocklist   | `word`             | Exact word matching (case-insensitive). Supports leet speak and plural detection. |
| Domain Blocklist | `domain`           | Blocks URLs by domain suffix matching. Ignores scheme and path.                   |
| Domain Allowlist | `domain_allowlist` | Only allows URLs from listed domains. Blocks everything else.                     |
| Email Blocklist  | `email`            | Blocks exact email addresses.                                                     |
| Email Allowlist  | `email_allowlist`  | Only allows listed email addresses. Blocks everything else.                       |
| Regex            | `regex`            | Pattern matching with regular expressions. Max 100 patterns per filter.           |

### 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`.
With **confusable folding** enabled, lookalike letters count as the plain letter. With **substring matching** enabled, the word can match inside a longer token. Both are off unless you set them on the filter.

### 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

## Create a Blocklist

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

```js label="Node.js"
// 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

| key                           | required | type    | description                                                                                                  |
| ----------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| name                          | true     | string  | Unique name for the blocklist (max 255 characters).                                                          |
| words                         | true     | array   | List of words, domains, emails, or regex patterns (max 10,000 entries).                                      |
| type                          | false    | string  | Filter type: `word` (default), `domain`, `domain_allowlist`, `email`, `email_allowlist`, or `regex`.         |
| is_leet_check_enabled         | false    | boolean | Detect leet speak bypass attempts (e.g., `h4ck3r` → `hacker`). Word type only.                               |
| is_plural_check_enabled       | false    | boolean | Detect singular/plural forms (e.g., `cat` matches `cats`). Word type only.                                   |
| is_confusable_folding_enabled | false    | boolean | Fold lookalike characters to plain letters (for example a Cyrillic `а` matches a Latin `a`). Word type only. |
| is_substring_matching_enabled | false    | boolean | Match the word inside a longer token, not only as a whole word. Word type only. Default off.                 |
| team                          | false    | string  | Team ID for multi-tenant blocklists.                                                                         |

## Update a Blocklist

Replace the word list or settings of an existing blocklist.

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

## List Blocklists

```js label="Node.js"
const response = await client.listBlockLists();
```

## Get a Blocklist

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

## Delete a Blocklist

```js label="Node.js"
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.

```js label="Node.js"
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" },
    ],
  },
});
```

## Text normalization

Before filters run, HTML entities are turned back into characters (decimal, hex, and named, with or without a trailing semicolon) and invisible characters such as zero-width spaces are removed. A word list containing `spam` therefore matches `visit &#115;&#112;&#97;&#109; now`, and a regex `(?i)https?://` matches an entity-encoded URL.

The stored message is not rewritten. See [Text Normalization](https://getstream.io/moderation/docs/node/guides/text-normalization/) for the full list of entity forms, invisible code points, and what is **not** decoded (percent-encoding, fullwidth letters, homoglyphs).

## Limits

| Limit                            | Value                                           |
| -------------------------------- | ----------------------------------------------- |
| Max blocklists per app           | 1,000 (20,000 when team blocklists are enabled) |
| Max blocklists per team          | 4                                               |
| Max words per blocklist          | 10,000                                          |
| Max words across all blocklists  | 200,000                                         |
| Max regex patterns per blocklist | 100                                             |
| Max characters per word          | 40                                              |
| Max characters per regex pattern | 60                                              |

Some of these limits can be raised on request. Contact support.

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/configuration/filters/](https://getstream.io/moderation/docs/node/configuration/filters/).

---

# Evaluations

Evaluations let you run a **fixed batch of content** through a [moderation policy](https://getstream.io/moderation/docs/node/configuration/policies/) and see how it is handled. Re-run the same set after you change rules, filters, or LLM settings to see what improved or drifted.

Use evaluations in the [dashboard](https://getstream.io/signin/?product=moderation) (**Moderation → Configuration → Evaluations**) or from the server-side SDKs.

## Concepts

| Term               | Meaning                                                                                                                                                            |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Evaluation set** | Content you provide, up to 1000 items, saved under a name. Each later run sends that same content through the policy.                                              |
| **Run**            | One execution of every item in the set against live moderation. Runs are asynchronous: you start one, then poll until it finishes.                                 |
| **Baseline**       | The first completed run of a set. Later runs are scored against it (or against seeded production outcomes, see [Replay](#replay-vs-a-single-policy)).              |
| **Replay**         | A set with no `config_key`. Each item is re-run under the policy it was originally moderated under.                                                                |
| **Scored row**     | A row compared with a previous run or with expected labels and action. A difference is a change from that baseline. Unscored rows only record what the policy did. |

### Replay vs a single policy

When you create a set you pick how rows are executed:

- **A specific policy.** Every item runs against that policy's current configuration.
- **Replay.** Omit `config_key`. Seeded items keep the policy they originally ran under. Deleted policies are skipped for those rows.

Pasted (hand-written) content has no original policy, so it always needs a policy selected.

### How scoring works

1. The **first completed run** is the baseline. It is not scored against anything.
2. Later runs compare each row's labels and recommended action to the baseline (or, for replay sets seeded from production, to the original production outcome stored on the row).
3. Rows with **no expectations** have empty expected labels and an empty expected action. They are safe or unlabeled rows you included so you can see what the policy did. They are not scored, and they stay out of the totals.

A difference from the baseline is a change, not automatically a mistake. Tightening a policy on purpose shows up the same way. The API records `label_mismatch` or `action_mismatch` on `failure_reason`, and `passed: false`, for that change. `provider_error` means the check failed. `policy_not_found` means the row's policy was deleted.

## API

These methods are **server-side only**. They are not available from client-side SDKs.

>
> **Note:** Every run is billed as production moderation. Poll the run until `status` is terminal (`completed`, `error`, or `cancelled`). There is no cancel method. A run stuck in `pending`/`running` for more than about 15 minutes is marked `error` so a new run can start.
>

### Create an evaluation set

`POST /api/v2/moderation/policy_tests/sets`

Provide **either** `rows` **or** `seed`, not both. Names are unique per app.

The example below samples the newest production content for a policy. To paste items instead, pass `rows` (each with a `text` field). To replay each item under its original policy, omit `config_key`.

```js label="Node.js"
const response = await client.moderation.createPolicyTestSet({
  name: "Hate-speech sample",
  config_key: "chat:messaging",
  seed: { labels: [], limit: 100 },
});
```

#### Request parameters

| Name         | Required | Type   | Description                                                                                                                                                                 |
| ------------ | -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`       | yes      | string | Display name. Unique within the app.                                                                                                                                        |
| `config_key` | no       | string | Policy to run every row against. Omit for replay.                                                                                                                           |
| `team`       | no       | string | Team scope for the policy (multi-tenancy).                                                                                                                                  |
| `mode`       | no       | string | `labels` or `check`. If omitted, the server picks `labels` when the Labels API is enabled for the org, otherwise `check`.                                                   |
| `seed`       | one of   | object | Sample newest production content. Labels-mode sets sample stored label results; check-mode sets sample reviewed AI-text review-queue items. Mutually exclusive with `rows`. |
| `rows`       | one of   | array  | Explicit items, max 1000. Each `text` is required, max 20,000 characters. Mutually exclusive with `seed`.                                                                   |

`seed` fields:

| Name     | Required | Type     | Description                                                                                        |
| -------- | -------- | -------- | -------------------------------------------------------------------------------------------------- |
| `limit`  | yes      | number   | How many items to sample, newest first. `1` to `1000`.                                             |
| `labels` | no       | string[] | Only sample records that carry any of these labels. Empty (or omitted) samples everything. Max 20. |

Row fields (when using `rows`, and also returned on seeded sets):

| Name                 | Type     | Description                                                                          |
| -------------------- | -------- | ------------------------------------------------------------------------------------ |
| `text`               | string   | Content to moderate.                                                                 |
| `labels`             | string[] | Expected labels (optional).                                                          |
| `recommended_action` | string   | Expected action (optional).                                                          |
| `policy`             | string   | Original policy key. Used on replay when `config_key` is empty.                      |
| `content_type`       | string   | When `username`, labels-mode runs dispatch through the username classification path. |

#### Response

| Name  | Type   | Description      |
| ----- | ------ | ---------------- |
| `set` | object | The created set. |

If seeding matches no production data, the request fails. Broaden `labels` or moderate more content first.

### List evaluation sets

`GET /api/v2/moderation/policy_tests/sets`

Each set in `sets` may include `last_run` so you can show last-run status and pass rate without a second request.

```js label="Node.js"
const response = await client.moderation.listPolicyTestSets({ limit: 50 });
```

#### Request parameters

| Name     | Required | Type   | Description                                       |
| -------- | -------- | ------ | ------------------------------------------------- |
| `limit`  | no       | number | Page size. Default is the store default, max 200. |
| `offset` | no       | number | Offset for pagination.                            |

#### Response

| Name   | Type  | Description                  |
| ------ | ----- | ---------------------------- |
| `sets` | array | Evaluation sets for the app. |

### Get an evaluation set

`GET /api/v2/moderation/policy_tests/sets/{id}`

Returns `set` (including `rows`), `recent_runs` (newest first, capped at 10), and `baseline_run_id` once the first run has completed.

```js label="Node.js"
const response = await client.moderation.getPolicyTestSet({ id: "pts_..." });
```

#### Request parameters

| Name | Required | Type   | Description                     |
| ---- | -------- | ------ | ------------------------------- |
| `id` | yes      | string | The evaluation set to retrieve. |

#### Response

| Name              | Type   | Description                                                  |
| ----------------- | ------ | ------------------------------------------------------------ |
| `set`             | object | The set, including rows.                                     |
| `recent_runs`     | array  | Retained run history, newest first.                          |
| `baseline_run_id` | string | Earliest completed run. Absent until the first run finishes. |

### Delete an evaluation set

`DELETE /api/v2/moderation/policy_tests/sets/{id}`

Cascades to runs and results. Fails if a run is still `pending` or `running`.

```js label="Node.js"
await client.moderation.deletePolicyTestSet({ id: "pts_..." });
```

#### Request parameters

| Name | Required | Type   | Description                   |
| ---- | -------- | ------ | ----------------------------- |
| `id` | yes      | string | The evaluation set to delete. |

### Start a run

`POST /api/v2/moderation/policy_tests/sets/{id}/runs`

The body is empty. Only one run may be in progress per set. When a new run is created, the oldest terminal runs beyond the 10-run cap are deleted.

```js label="Node.js"
const response = await client.moderation.startPolicyTestRun({ id: "pts_..." });
```

#### Request parameters

| Name | Required | Type   | Description                    |
| ---- | -------- | ------ | ------------------------------ |
| `id` | yes      | string | The evaluation set to execute. |

#### Response

| Name  | Type   | Description                                      |
| ----- | ------ | ------------------------------------------------ |
| `run` | object | The new run, typically with `status: "pending"`. |

### Get a run (and results)

`GET /api/v2/moderation/policy_tests/runs/{id}`

Poll this while `status` is `pending` or `running`. `rows_completed` / `rows_total` track progress. Per-row `results` are **omitted until the run is terminal**, so polling stays cheap.

```js label="Node.js"
const response = await client.moderation.getPolicyTestRun({ id: "ptr_..." });
```

#### Request parameters

| Name | Required | Type   | Description          |
| ---- | -------- | ------ | -------------------- |
| `id` | yes      | string | The run to retrieve. |

#### Response

| Name      | Type   | Description                                              |
| --------- | ------ | -------------------------------------------------------- |
| `run`     | object | The run, including progress and metrics when available.  |
| `results` | array  | Per-row results. Present only once the run has finished. |

#### Run object

| Field               | Type   | Description                                                                |
| ------------------- | ------ | -------------------------------------------------------------------------- |
| `id`                | string | Run id.                                                                    |
| `set_id`            | string | Parent set.                                                                |
| `status`            | string | `pending`, `running`, `completed`, `error`, or `cancelled`.                |
| `config_key`        | string | Policy snapshot used for this run.                                         |
| `config_updated_at` | string | When that policy was last updated, if it exists.                           |
| `rows_total`        | number | Items in the set.                                                          |
| `rows_completed`    | number | Items processed so far.                                                    |
| `metrics`           | object | Set on non-baseline completed runs. Pass/fail totals plus per-label drift. |
| `error_message`     | string | Present when `status` is `error`.                                          |
| `triggered_by`      | string | Who started the run.                                                       |
| `started_at`        | string | When the worker picked up the run.                                         |
| `completed_at`      | string | When it reached a terminal status.                                         |

`metrics.totals`:

| Field      | Description                                 |
| ---------- | ------------------------------------------- |
| `rows`     | All rows.                                   |
| `scored`   | Rows included in pass/fail.                 |
| `unscored` | Rows recorded without a verdict.            |
| `passed`   | Scored rows that matched the baseline/seed. |
| `failed`   | Scored rows that drifted or errored.        |

`metrics.by_label` maps each label to `{ same, changed }`. `changed` counts rows where that label was added or dropped versus the baseline. Rows where the label was absent in both runs are not counted.

#### Result object (terminal runs)

| Field             | Type     | Description                                                                   |
| ----------------- | -------- | ----------------------------------------------------------------------------- |
| `row_index`       | number   | Index in the set.                                                             |
| `message_text`    | string   | The item's text.                                                              |
| `expected_labels` | string[] | Baseline or seeded labels.                                                    |
| `expected_action` | string   | Baseline or seeded recommended action.                                        |
| `actual_labels`   | string[] | Labels this run produced.                                                     |
| `actual_action`   | string   | Recommended action this run produced.                                         |
| `scored`          | boolean  | Whether the row received a verdict.                                           |
| `passed`          | boolean  | `true`/`false` when scored; `null` when not.                                  |
| `failure_reason`  | string   | `label_mismatch`, `action_mismatch`, `provider_error`, or `policy_not_found`. |
| `severity`        | string   | AI-text severity from the provider, display only. Not part of pass/fail.      |

Compare two runs client-side: fetch both, join on `row_index`.

## Billing and retention

Each item in a run executes real moderation calls (LLM, NLP, image checks, and so on) at standard rates, the same as production traffic.

Each set keeps the last 10 completed runs. Starting another after that deletes the oldest run and its per-row results. In-flight runs are not deleted.

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/configuration/evaluations/](https://getstream.io/moderation/docs/node/configuration/evaluations/).

---

# Multitenancy

Many applications with chat functionality serve multiple customers or organizations. For example, platforms like Slack or SaaS applications like InVision need to ensure that messages remain private between different customer organizations. Stream Chat addresses this through multi-tenant mode, which organizes users into separate teams that operate independently. For more details on multitenancy setup, see our [Multitenancy](https://getstream.io/docs/platform/multi-tenancy/) documentation.

This guide explains how you can provide moderation for your customers (tenants) with team-level policies. The APIs let you build a dashboard where a tenant manages their own policies and reviews flagged content for their team.

## Limitations and Prerequisites

- Multi-tenancy is only supported on chat.

## Create Moderation Policy

You can create moderation configs at the team level by setting the `team` field in the [`UpsertConfig`](https://getstream.io/moderation/docs/node/configuration/policies/#upsert-config) API.
The following policy is used for messages sent to the `messaging` channel type in team `team-a`.

> **Warning:** Only team admins and moderators can manage team-level policies

### Server Side Integration

The server-side integration provides full control over moderation configs and is typically used for:

- Initial setup of team moderation policies
- Bulk updates to moderation rules
- Administrative operations

```js label="Node.js"
await client.moderation.upsertConfig({
  key: "chat:messaging",
  team: "team-a",
  ai_text_config: {
    rules: [{ label: "SEXUAL_HARASSMENT", action: "flag" }],
  },
  ai_image_config: {
    rules: [
      { label: "Non-Explicit Nudity", action: "flag", min_confidence: 50 },
    ],
  },
});
```

### Client Side Integration

Client side access to API allows you to give control to your customers (tenants) to manage their own moderation policies. This is particularly useful when:

- Building a self-service moderation dashboard
- Allowing teams to customize their moderation settings
- Providing real-time moderation management

```js label="JavaScript"
const client = new StreamChat("api_key");
await client.connectUser({ id: "user-from-team-a" }, token);

await client.moderation.upsertConfig({
  key: "chat:messaging",
  team: "team-a",
  ai_text_config: {
    rules: [{ label: "SEXUAL_HARASSMENT", action: "flag" }],
  },
  ai_image_config: {
    rules: [{ label: "Non-Explicit Nudity", action: "flag" }],
  },
});
```

>
> **Note:** Please check [AI Text Supported Harm Categories](https://getstream.io/moderation/docs/node/engines/ai-text/#supported-harms-and-categories) and [AI Image Supported Harm Categories](https://getstream.io/moderation/docs/node/engines/image-moderation/#supported-categories) for the list of supported harm categories.
>

## Moderation Policy Scopes

The scope of moderation policies is determined by the combination of the config key and team field. Here's a detailed breakdown:

| Config Key                    | Team Field | Scope                                                        | Use Case                            |
| ----------------------------- | ---------- | ------------------------------------------------------------ | ----------------------------------- |
| `chat`                        |            | Applies to all channels across all teams                     | Global moderation policies          |
| `chat`                        | `team-a`   | Applies to all channels in team-a                            | Team-wide policies                  |
| `chat:messaging`              |            | Applies to messaging channels across all teams               | Channel-type specific policies      |
| `chat:messaging`              | `team-a`   | Applies to messaging channels in team-a                      | Team-specific channel type policies |
| `chat:messaging:<channel_id>` |            | Applies to channel with id `channel_id` irrespective of team | Channel-specific policies           |
| `chat:messaging:<channel_id>` | `team-a`   | Applies to channel with id `channel_id` in team-a            | Team-specific channel policies      |

## Query Moderation Policies

You can query moderation configs at the team level to:

- Audit existing moderation policies
- Review team-specific settings
- Monitor policy changes

### Using Server side integration

The server-side query provides comprehensive access to all moderation configs:

```js label="Node.js"
// Get all the moderation configs for all the teams
const { configs, next } = await client.moderation.queryModerationConfigs({
  limit: 2,
});

// Get all the moderation configs for the team `team-a`
const { configs: teamConfigs, next: teamNext } =
  await client.moderation.queryModerationConfigs({
    filter: { team: "team-a" },
    sort: [{ field: "created_at", direction: -1 }],
    limit: 2,
  });
```

### Using Client side integration

Client-side queries are restricted to the team context of the authenticated user:

```js label="JavaScript"
// Get all the moderation configs for the team that the user belongs to
const { configs, next } = await client.moderation.queryModerationConfigs({
  limit: 2,
});
```

## Query Review Queue

The review queue is a crucial component of the moderation system that allows teams to:

- Review flagged content
- Take action on moderated messages
- Track moderation history
- Maintain audit trails

You can query the review queue at the team level to using [`QueryReviewQueue`](https://getstream.io/moderation/docs/node/content-moderation/review-queue/#query-review-queue) API.

### Server Side Integration

Server-side access provides complete control over the review queue:

```js label="Node.js"
// Get all the review queue for all the teams
const { items, next } = await client.moderation.queryReviewQueue({
  limit: 2,
});

// Get all the review queue for the team `team-a`
const { items: teamItems, next: teamNext } =
  await client.moderation.queryReviewQueue({
    filter: { teams: "team-a" },
    sort: [{ field: "created_at", direction: -1 }],
    limit: 2,
  });

// Get all the review queue for the team `team-a` and `team-b`
const { items: multiTeamItems, next: multiTeamNext } =
  await client.moderation.queryReviewQueue({
    filter: { teams: { $in: ["team-a", "team-b"] } },
    sort: [{ field: "created_at", direction: -1 }],
    limit: 2,
  });
```

### Client Side Integration

The client-side review queue access enables building custom moderation dashboards:

```js label="JavaScript"
// Get all the review queue for all the teams that the user belongs to.
const { items, next } = await client.moderation.queryReviewQueue({
  limit: 2,
});

// Get all the review queue for the team `team-a`
// This will return all the review queue for the team `team-a`, only if the user belongs to `team-a`
const { items, next } = await client.moderation.queryReviewQueue({
  filter: { team: "team-a" },
  sort: [{ field: "created_at", direction: -1 }],
  limit: 2,
});
```

> **Tip:** Consider implementing pagination when displaying review queue items to improve performance and user experience. The `next` parameter can be used to fetch subsequent pages of results.

## Team level blocklists

> **Note:** Team level blocklists are behind a feature flag and are not enabled by default. Please reach out to support if you are interested in enabling this feature.

Team level blocklists gives your customers the ability to manage blocklists for their team. These blocklists can be used in moderation policies to flag or remove messages that contain specific words or phrases.

CRUD APIs to maintain team level blocklists are accessible on client side integration. This means that you can build a custom moderation dashboard for your teams to maintain the blocklists. Its important to note that team level blocklists can only be created/updated/deleted by team admins and moderators who have the following permissions:

- `CreateBlockList`
- `UpdateBlockList`
- `ReadBlockLists`
- `DeleteBlockList`

### Limitations

- Maximum 4 blocklists per team
- Maximum 20,000 blocklists per app (including global blocklists)
- Maximum 200,000 words in total across all blocklists of an app

> **Tip:** Since global (non-team) blocklists can be used in team-level moderation configs, it's recommended to maintain global blocklists for common scenarios shared across teams.

### Create a Team Level Blocklist

You can create a blocklist specific to a team using the following code:

###

```js label="Node.js"
await client.createBlockList({
  name: "myblocklist",
  team: "team-a",
  words: ["bad-word-1", "bad-word-2"],
  type: "word",
});
```

### Update a Team Level Blocklist

To update an existing team blocklist:

```js label="Node.js"
await client.updateBlockList({
  name: "myblocklist",
  words: ["test3", "test4"],
  team: "team-a",
});
```

### Delete a Team Level Blocklist

To delete a team blocklist:

```js label="Node.js"
await client.deleteBlockList({
  name: "myblocklist",
  team: "team-a",
});
```

### List Blocklists

You can list both global and team-specific blocklists:

```js label="Node.js"
// List global blocklists
const globalBlocklists = await client.listBlockLists();

// List team specific blocklists
const teamBlocklists = await client.listBlockLists({ team: "team-a" });
```

### Using Blocklists in Team Level Moderation Configuration

You can use both global and team level blocklists in your team's policy:

```js label="Node.js"
await client.moderation.upsertConfig({
  key: "chat:messaging",
  team: "team-a",
  block_list_config: {
    rules: [
      // team level blocklist
      {
        name: "my_team_blocklist",
        team: "team-a",
        action: "remove",
      },
      // global blocklist
      {
        name: "my_global_blocklist",
        action: "flag",
      },
    ],
  },
});
```

## Dashboard support

The Stream dashboard does not give each tenant a login. You create team policies and team blocklists there yourself, or you build that for tenants with the APIs above, scoped by `team`.

From the [dashboard](https://getstream.io/signin/?product=moderation):

### Create Team Level Moderation Policy

You can create a team level moderation policy from the dashboard as following:

- Navigate to "Policies" page in left sidebar
- Click on "+ Add New" button, which will open a modal to create a new moderation policy
- Select "Chat" as product
- On this modal, you will see an input field to assign a team to the policy

Once you press "Save" button, the policy will be created for the team you selected.

In the policies list, you will see a team column which will show the team to which the policy belongs.

### Team Level Blocklists

You can create a team blocklist from the dashboard as following:

- Navigate to "Policies" page in left sidebar
- Select a team policy where you want to add the blocklist
- Scroll down to "Blocklists & Regex Filters" section
- Click on "+ Add New" button, which will open a modal to create a new blocklist
- On this modal, you will see a checkbox to mark this blocklist as team level blocklist

The team blocklists will be shown in the moderation policy as following:

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/configuration/multitenancy/](https://getstream.io/moderation/docs/node/configuration/multitenancy/).

---

# Flooding

Flood detection identifies users sending large volumes of repeated or near-duplicate messages in a short window and appends flood labels and escalated actions to the moderation response. It runs per user, per moderation policy, and covers two independent detectors that can be enabled separately or together:

- **Identical** — fires when a user sends the same message repeatedly. Comparison is exact after normalization (lowercase, punctuation and extra whitespace stripped).
- **Similar** — fires when a user sends near-duplicate messages that vary by small edits, such as typos, punctuation, or whitespace changes. Similarity is measured with a configurable strictness.

Each detector fires once the user reaches `threshold` matching messages within `time_window`.

## Configuration

Attach a `flood_config` block to a moderation policy via the [Upsert Config](https://getstream.io/moderation/docs/node/configuration/policies/#upsert-config) API. Both detectors are opt-in and can be configured with different thresholds and actions.

```js label="Node.js"
await client.moderation.upsertConfig({
  key: "chat:messaging",
  flood_config: {
    identical: {
      enabled: true,
      threshold: 5,
      time_window: "30m",
      action: "flag",
    },
    similar: {
      enabled: true,
      threshold: 5,
      time_window: "30m",
      similarity_distance: 5,
      action: "remove",
    },
    allowlist: ["gg", "well played"],
  },
});
```

### Fields

| Field                         | Type               | Required     | Description                                                                                                                   |
| ----------------------------- | ------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `identical.enabled`           | boolean            | false        | Turn identical-message detection on for this policy.                                                                          |
| `identical.threshold`         | integer (2 to 100) | when enabled | Number of matching messages that triggers a flood verdict.                                                                    |
| `identical.time_window`       | string             | when enabled | Rolling window over which the counter accumulates. One of `15s`, `30s`, `1m`, `2m`, `3m`, `5m`, `10m`, `15m`, `30m`, `1h`.    |
| `identical.action`            | string             | when enabled | Action applied on trigger. One of `flag`, `remove`.                                                                           |
| `similar.enabled`             | boolean            | false        | Turn similar-message detection on for this policy.                                                                            |
| `similar.threshold`           | integer (2 to 100) | when enabled | Number of near-matching messages that triggers a flood verdict.                                                               |
| `similar.time_window`         | string             | when enabled | Same values as `identical.time_window`.                                                                                       |
| `similar.similarity_distance` | integer (1 to 16)  | when enabled | How close two messages must be to count as similar. Lower is stricter (fewer false positives, more misses); higher is looser. |
| `similar.action`              | string             | when enabled | Same values as `identical.action`.                                                                                            |
| `allowlist`                   | string array       | false        | Benign phrases exempted from flood detection. Up to 100 entries, up to 200 characters each.                                   |

Enabling either detector without both `threshold` and `time_window` fails validation on upsert.

Policy `flood_config` is always per user. To count the same text across users, or to skip short copy, use a `flood_identical` [rule](https://getstream.io/moderation/docs/node/configuration/rules/#flood-identical-and-similar) instead (`track_across_users`, `min_text_length`).

## Allowlist

`allowlist` exempts benign phrases, such as game shout-outs or common greetings, from flood detection. Matching is exact after normalization (lowercase, punctuation and extra whitespace stripped), so `gg`, `GG!!!`, and `gg` with surrounding whitespace all match an entry `gg`, but a longer message like `gg buy crypto` does not.

The exemption applies only to flood detection. A phrase that both appears in the allowlist and matches a blocklist, AI text rule, or other provider is still actioned by those providers. Short entries such as `gg` are kept. Identical-message counting skips text shorter than 3 characters unless the message also has an image or video.

## Detection Labels and Actions

When a detector fires, the moderation response reflects the verdict:

- One of the following labels is appended to `labels`:
  - `flood_identical` — identical-message detection triggered.
  - `flood_similar` — similar-message detection triggered.
- `recommended_action` is the stricter of the flood action and any other provider's action. A `remove` from another provider stays `remove`.
- `harm_type` is set to `spam` if it was not already set.

`identical.action` and `similar.action` are only `flag` or `remove`.

## Grouping Flood Webhooks

Once a user crosses the threshold, every later matching message in the window is flagged on its own and creates its own review queue item, so a single flood sends one `review_queue_item.new` webhook per flagged message.

To handle a flood once, read `flood_group_id` from the flood flag in the webhook payload. Its value is the `entity_id` of the first message flagged in that flood, and every later flagged message in the same flood carries the same value:

```jsonc
{
  "type": "review_queue_item.new",
  "review_queue_item": { "entity_id": "msg-4", "entity_creator_id": "u1", ... },
  "flags": [
    {
      "type": "flood",
      "entity_id": "msg-4",
      "labels": ["flood_identical"],
      "result": [
        {
          "labels": ["flood_identical"],
          "action": "flag",
          "custom_result": { "flood_group_id": "msg-3" }
        }
      ]
    }
  ]
}
```

A message whose `flood_group_id` equals its own `entity_id` starts a flood; any other value means it belongs to a flood you have already received.

Groups follow the detector that fired:

- **Identical** — one group per user and message content.
- **Similar** — one group per user. Two different near-duplicate floods from the same user within one `time_window` share a group.

A group lasts one `time_window` from its first flagged message. A flood that continues or restarts after that gets a new `flood_group_id`.

`flood_group_id` is set on flags created by policy `flood_config` through moderation checks. It is not included on `moderation_rule.triggered` webhooks from flood [rules](https://getstream.io/moderation/docs/node/configuration/rules/#flood-identical-and-similar).

## Across users

`flood_config` on a policy counts per user. To count the same text from anyone in the app, add a `flood_identical` rule and set `track_across_users` to `true`. That counter is total occurrences, not distinct users. `flood_similar` stays per user. See [Flood identical and similar](https://getstream.io/moderation/docs/node/configuration/rules/#flood-identical-and-similar).

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/configuration/flooding/](https://getstream.io/moderation/docs/node/configuration/flooding/).

---

# Webhooks

Webhooks provide a powerful way to implement custom logic for moderation. Delivery retries, signature verification and the IP allowlist are covered in the [webhooks guide](https://getstream.io/docs/platform/webhooks/).

## Configure webhook URL

You can configure the webhook URL from the Stream [dashboard](https://getstream.io/signin/?product=moderation).

1. Go to the [dashboard](https://getstream.io/signin/?product=moderation)
2. Select the app for which you want to receive webhook events
3. Click on "Preferences" under the "Moderation" section in the left navigation
4. Set the webhook URL on that page

## Webhook events

The webhook url will receive following events

- `review_queue_item.new`
  - This event notifies you of new content available for review. The content could be a message, activity, reaction, or even a user profile.
  - This event is triggered when content is flagged for the first time. Consequently, you'll also receive the associated flags as part of the payload.
- `review_queue_item.updated`
  - This event notifies you when existing flagged content receives additional flags or when a moderator performs an action on flagged content.
  - The payload includes the new flags or details of the action performed.
- `moderation_check.completed`
  - This event notifies you when the Moderation Check has been completed.
  - This event is triggered for both flag and non-flag actions.
  - This event is fired when the moderation check for an entity has finished (after sync and async checks). It is emitted even when no flags were raised.
  - The payload includes the entity identifiers and the final `recommended_action`.
- `moderation_rule.triggered`
  - This event notifies you when a moderation rule from the Rule Builder is triggered.
  - This event is triggered when rule conditions are met and actions are executed.
  - Available for `user`, `content`, and `call` rule types.
  - For call rules, includes `violation_number` to track escalation sequences.
  - The payload includes rule information, triggered actions, and entity details.
  - Aggregation rules (keyframes, closed captions, keyframe OCR) include `matched_contents` when the request supplied `content_ids`.
  - Use this event to get notified only for the harms or conditions you configured on a rule. See [Rule-Triggered Webhooks](https://getstream.io/moderation/docs/node/content-moderation/webhooks/#rule-triggered-webhooks).
- `moderation.text_analysis.complete`
  - Fired on every [Analyze](https://getstream.io/moderation/docs/node/content-moderation/check/#analyze) call that included text.
  - Carries the same per-text verdicts as the Analyze HTTP response (`action` or `error` per label).
  - For that Analyze origin, this event replaces `review_queue_item.*` and `moderation_check.completed`.
- `moderation.image_analysis.complete`
  - Fired on every Analyze call that included images.
  - Carries the same per-image verdicts as the Analyze HTTP response.
  - For that Analyze origin, this event replaces `review_queue_item.*` and `moderation_check.completed`.
- `moderation.analysis.failed`
  - Fired only after Analyze has already returned `201` `pending` and Stream could not finish the listed work.
  - Carries `content_ids` only. Provider-level field errors stay on `*.complete` as `error`, not on this event.
  - Treat the listed ids as unscreened and resubmit them.
- `moderation.flagged`
  - Fired when content is flagged.
- `moderation.custom_action`
  - Fired when a moderator runs a custom action from the review queue.
- `moderation.mark_reviewed`
  - Fired when a moderator marks an item reviewed.
- `moderation.intent_detected`
  - Fired when an intent topic on the policy matches.
- `appeal.created`
  - Fired when a user submits an appeal.
- `appeal.accepted`
  - Fired when a moderator accepts an appeal.
- `appeal.rejected`
  - Fired when a moderator rejects an appeal.
- `call.moderation_warning`
  - Video event. Fired when a call rule warns a participant.
- `call.moderation_blur`
  - Video event. Fired when a call rule blurs a participant's video.
- `export.moderation_logs.success` and `export.moderation_logs.error`
  - Fired when a moderation-log export finishes or fails.
- `export.review_queue.success`
  - Fired when a review-queue export finishes.
- `export.bulk_image_moderation.success`
  - Fired when a bulk image moderation job finishes.

### `review_queue_item.new`

Sent when content is flagged for the first time, by AI, a blocklist, a user, or a moderator. If the same content is flagged again, you receive `review_queue_item.updated`. New flags are in the payload's `flags` property. For Stream Chat, this replaces the legacy `message.flagged` event.

The `review_queue_item.new` event payload is structured as follows:

```json
{
  "review_queue_item": {
    --> See ReviewQueueItem shape in the table below
  },
  "flags": [
    --> See ModerationEventFlag shape in the table below
  ],
  "action": {
    --> See ModerationEventActionLog shape in the table below
  },
  "type": "review_queue_item.new",
  "created_at": "timestamp",
  "received_at": "timestamp"
}
```

### `review_queue_item.updated`

The `review_queue_item.updated` event payload is structured as follows:

```json
{
  "review_queue_item": {
    --> See ReviewQueueItem shape in the table below
  },
  "flags": [
    --> See ModerationEventFlag shape in the table below
  ],
  "action": {
    --> See ModerationEventActionLog shape in the table below
  },
  "type": "review_queue_item.updated",
  "created_at": "timestamp",
  "received_at": "timestamp"
}
```

### `moderation_check.completed`

The `moderation_check.completed` event payload is structured as follows:

```json
{
  "type": "moderation_check.completed",
  "created_at": "timestamp",
  "entity_id": "user123-iyVcizkX4KhoiOJf2YOS5",
  "entity_type": "stream:chat:v1:message",
  "recommended_action": "flag",
  "review_queue_item_id": "03eab71c-d2bf-418b-982a-15efcfdebb47"
}
```

This event contains the following fields:

| Key                    | Type     | Description                                                            |
| ---------------------- | -------- | ---------------------------------------------------------------------- |
| `type`                 | string   | The event type, which is always "moderation_check.completed"           |
| `created_at`           | datetime | Timestamp when the moderation check was completed                      |
| `entity_id`            | string   | Unique identifier of the entity that was moderated                     |
| `entity_type`          | string   | Type of the entity that was moderated (e.g., "stream:chat:v1:message") |
| `recommended_action`   | string   | Action recommended by the moderation system ("flag" or "remove")       |
| `review_queue_item_id` | string   | Unique identifier of the associated review queue item                  |

### `moderation_rule.triggered`

The `moderation_rule.triggered` event payload is structured as follows:

```json
{
  "type": "moderation_rule.triggered",
  "created_at": "2026-01-20T23:45:04.485362361Z",
  "rule": {
    "id": "0450e7d6-9386-4eb9-a720-f3999979989c",
    "name": "Nudity or hate speech not allowed from men",
    "type": "call",
    "description": "Detects inappropriate content in video calls"
  },
  "violation_number": 1,
  "entity_id": "default:default_test-4013",
  "entity_type": "stream:v1:call",
  "user_id": "test-user-2025b49e-ef45-473f-bb90-4f8f679c8581",
  "triggered_actions": ["mute_video", "call_warning"],
  "review_queue_item_id": "abc123"
}
```

This event contains the following fields:

| Key                    | Type     | Description                                                                                           | Possible Values                                                                                |
| ---------------------- | -------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `type`                 | string   | The event type, which is always "moderation_rule.triggered"                                           | `"moderation_rule.triggered"`                                                                  |
| `created_at`           | datetime | Timestamp when the rule was triggered                                                                 |                                                                                                |
| `rule`                 | object   | Object containing rule information                                                                    |                                                                                                |
| `rule.id`              | string   | Unique identifier for the rule                                                                        |                                                                                                |
| `rule.name`            | string   | Human-readable rule name                                                                              |                                                                                                |
| `rule.type`            | string   | Rule type                                                                                             | `"call"`, `"user"`, or `"content"`                                                             |
| `rule.description`     | string   | Rule description                                                                                      |                                                                                                |
| `violation_number`     | int      | (Call rules only) The violation number that triggered this event (1st violation, 2nd violation, etc.) | Only present for call rules. For user and content rules, this field is not included.           |
| `entity_id`            | string   | The ID of the entity that triggered the rule                                                          | For call rules: call CID (e.g., `"default:default_test-4013"`). For content rules: message ID. |
| `entity_type`          | string   | The type of entity that triggered the rule                                                            | For call rules: `"stream:v1:call"`. For content rules: `"stream:chat:v1:message"`.             |
| `user_id`              | string   | The ID of the user who triggered the rule                                                             |                                                                                                |
| `triggered_actions`    | array    | Array of action types that were executed                                                              | Examples: `["mute_video", "call_warning"]`, `["ban"]`, `["flag"]`                              |
| `review_queue_item_id` | string   | (Optional) The review queue item ID if the violation was flagged for review                           | Only present if the rule action includes flagging for review                                   |
| `app_id`               | int      | Application ID the rule belongs to                                                                    |                                                                                                |
| `scope`                | array    | (Optional) The rule's `config_keys`                                                                   | Omitted when the rule is application-wide                                                      |
| `threshold`            | int      | (Optional) The count configured on the condition that fired, not the live counter                     | Omitted for conditions without a count                                                         |
| `time_window`          | string   | (Optional) The configured window of that condition                                                    | For example `"10m"`                                                                            |
| `category`             | string   | (Optional) The `category` sent on the Labels API request                                              | Only present on Labels API events (`entity_type` `"moderation:label"`)                         |
| `matched_user_ids`     | array    | (Optional) Users who sent the content since the previous webhook                                      | Only on cross-user `webhook_only` flood rules                                                  |

**Note:** Webhook events are sent once per rule per violation number per entity. For call rules with action sequences, if multiple keyframes or closed captions trigger the same rule with the same violation number, only one webhook event is sent.

Flood rules with `webhook_only` send one event each time the count reaches a multiple of the threshold. See [Rule-Triggered Webhooks](#rule-triggered-webhooks).

On the Labels API, `matched_contents` entries are typed `message` or `username` (up to the 20 newest, text cut at 300 characters), and flood rules carry the triggering content as one entry. Flood rules with `webhook_only` send one event per threshold multiple.

When an aggregation rule fires, `matched_contents` lists the items that crossed the threshold. Each entry has `type` (`image` or `text`), `id` (from `content_ids`), and `published_at`. Image rows carry `classifications` and `confidence` (or `ocr_classifications` and `severity` for OCR rules). Text rows carry `classifications` and `severity`.

### `moderation.text_analysis.complete`

Fired once per async Analyze request that included texts. The `texts` map uses the same shape as the [Analyze](https://getstream.io/moderation/docs/node/content-moderation/check/#analyze) HTTP response.

```json
{
  "type": "moderation.text_analysis.complete",
  "entity_type": "listing",
  "entity_id": "listing_42",
  "entity_creator_id": "user_42",
  "config_key": "catalog-v1",
  "review_queue_item_id": "rqi_abc",
  "texts": {
    "caption": {
      "id": "cap_42",
      "action": "flag",
      "classifications": [{ "name": "INSULT", "severity": "high" }],
      "severity": "high",
      "language": "en"
    }
  },
  "custom": { "vendor_id": "v_acme" }
}
```

| Key                    | Type   | Description                                                                                          |
| ---------------------- | ------ | ---------------------------------------------------------------------------------------------------- |
| `type`                 | string | Always `"moderation.text_analysis.complete"`                                                         |
| `entity_type`          | string | Canonical entity type from the request. A subtype such as `external:call:keyframe` is not echoed     |
| `entity_id`            | string | Echo of the request `entity_id`                                                                      |
| `entity_creator_id`    | string | Echo of the request `entity_creator_id`                                                              |
| `config_key`           | string | Policy that was applied                                                                              |
| `review_queue_item_id` | string | Review-queue row id when one was created                                                             |
| `texts`                | object | Per-label verdicts. Each value is an Analyze text field (`id`, `action` or `error`, classifications) |
| `custom`               | object | Echo of the request `custom` metadata                                                                |

### `moderation.image_analysis.complete`

Fired once per async Analyze request that included images.

```json
{
  "type": "moderation.image_analysis.complete",
  "entity_type": "listing",
  "entity_id": "listing_42",
  "entity_creator_id": "user_42",
  "config_key": "catalog-v1",
  "review_queue_item_id": "rqi_abc",
  "images": {
    "main_photo": {
      "id": "img_42_main",
      "action": "flag",
      "confidence": 0.924,
      "classifications": [
        {
          "name": "Explicit Nudity",
          "confidence": 0.924,
          "subclassifications": [
            { "name": "Female Nudity", "confidence": 0.91 }
          ]
        }
      ]
    }
  },
  "custom": { "vendor_id": "v_acme" }
}
```

| Key                    | Type   | Description                                                                                           |
| ---------------------- | ------ | ----------------------------------------------------------------------------------------------------- |
| `type`                 | string | Always `"moderation.image_analysis.complete"`                                                         |
| `entity_type`          | string | Canonical entity type from the request                                                                |
| `entity_id`            | string | Echo of the request `entity_id`                                                                       |
| `entity_creator_id`    | string | Echo of the request `entity_creator_id`                                                               |
| `config_key`           | string | Policy that was applied                                                                               |
| `review_queue_item_id` | string | Review-queue row id when one was created                                                              |
| `images`               | object | Per-label verdicts. Each value is an Analyze image field (`id`, `action` or `error`, classifications) |
| `custom`               | object | Echo of the request `custom` metadata                                                                 |

### `moderation.analysis.failed`

Fired only after Analyze has already acknowledged the request with `201` `pending`. Stream could not emit a usable `*.complete` for the listed items. This is not a clean verdict.

```json
{
  "type": "moderation.analysis.failed",
  "entity_type": "listing",
  "entity_id": "listing_42",
  "entity_creator_id": "user_42",
  "config_key": "catalog-v1",
  "content_ids": {
    "caption": "cap_42",
    "main_photo": "img_42_main"
  },
  "custom": { "vendor_id": "v_acme" }
}
```

| Key                 | Type   | Description                                                                                                      |
| ------------------- | ------ | ---------------------------------------------------------------------------------------------------------------- |
| `type`              | string | Always `"moderation.analysis.failed"`                                                                            |
| `entity_type`       | string | Canonical entity type from the request                                                                           |
| `entity_id`         | string | Echo of the request `entity_id`                                                                                  |
| `entity_creator_id` | string | Echo of the request `entity_creator_id`                                                                          |
| `config_key`        | string | Policy the request targeted                                                                                      |
| `content_ids`       | object | Echo of the request `content_ids` for the unscreened work. May be modality-scoped if only texts or images failed |
| `custom`            | object | Echo of the request `custom` metadata                                                                            |

Retry only the listed `content_ids`. A sibling `*.complete` can still arrive for the other modality.

## Rule-triggered webhooks

Use the Rule Builder to receive a webhook only when a chosen condition matches, for example a specific harm label. Stream sends [`moderation_rule.triggered`](#moderation_ruletriggered) for that rule. Other messages do not produce this event.

This is the scoped alternative to subscribing to every review-queue item. Pair it with `webhook_only` when you want a notification, or with a user/content action when you also want Stream to enforce something.

### How it works

1. Create a [rule](https://getstream.io/moderation/docs/node/configuration/rules/) whose conditions describe the harms (or other signals) you care about.
2. Set the rule action to `webhook_only`, or to a user/content action such as `flag_user`.
3. Subscribe an event hook to `moderation_rule.triggered` with product `moderation`.

When a check evaluates that rule and the conditions pass, Stream sends one `moderation_rule.triggered` event. Rule actions run in addition to the action already configured on the policy for that label.

### Content rule: notify on a harm label

A `content` rule with `text_content` evaluates the current message, activity, or comment. It fires as soon as the listed labels are present.

```json
{
  "name": "High-profile harms",
  "description": "Notify when selected harm labels are detected",
  "rule_type": "content",
  "enabled": true,
  "config_keys": ["chat:messaging", "chat:livestream"],
  "conditions": [
    {
      "type": "text_content",
      "text_content_params": {
        "harm_labels": ["UNDERAGE_USER", "SCAM"]
      }
    }
  ],
  "action": {
    "type": "webhook_only"
  }
}
```

| Field                             | Description                                                                       |
| --------------------------------- | --------------------------------------------------------------------------------- |
| `rule_type`                       | `"content"` evaluates the current piece of content.                               |
| `config_keys`                     | Policies this rule applies to. An empty list applies the rule app-wide.           |
| `text_content_params.harm_labels` | Labels that satisfy the condition. Any listed label is enough.                    |
| `text_content_params.severity`    | Optional minimum severity (`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`).                  |
| `action.type`                     | `"webhook_only"` sends the event and does not apply a further enforcement action. |

Create or update the rule with `POST /api/v2/moderation/moderation_rule`. Enable the Rule Builder on the same config:

```json
{
  "key": "chat:messaging",
  "rule_builder_config": {
    "enabled": true
  }
}
```

```js label="Node.js"
await client.moderation.upsertModerationRule({
  name: "High-profile harms",
  description: "Notify when selected harm labels are detected",
  config_keys: ["chat:messaging", "chat:livestream"],
  enabled: true,
  rule_type: "content",
  conditions: [
    {
      type: "text_content",
      text_content_params: {
        harm_labels: ["UNDERAGE_USER", "SCAM"],
      },
    },
  ],
  action: { type: "webhook_only" },
});
```

Other conditions on a content rule work the same way: `blocklist_match`, `contains_url`, image `harm_labels`, and so on. See [Rules](https://getstream.io/moderation/docs/node/configuration/rules/).

### User rule: act on the account

A `user` rule with `text_rule` counts matching labels for one user over a time window. Use this when the signal should follow the account rather than a single piece of content.

```json
{
  "name": "Repeat high-severity insult",
  "rule_type": "user",
  "enabled": true,
  "config_keys": ["chat:messaging"],
  "conditions": [
    {
      "type": "text_rule",
      "text_rule_params": {
        "threshold": 1,
        "time_window": "1h",
        "harm_labels": ["INSULT"],
        "severity": "HIGH"
      }
    }
  ],
  "action": {
    "type": "flag_user"
  }
}
```

`threshold: 1` fires on the first matching message. Increase it to require a repeated pattern. The same `moderation_rule.triggered` event is sent when the rule fires.

### Flood rule: notify on repeated copy

A `flood` rule with `webhook_only` notifies you about repeated identical or similar text without acting on the messages. It fires once each time the count reaches a multiple of `threshold` (with a threshold of 100: at copy 100, 200, 300...), not on every copy past it. Flood rules with a content action (`flag`, `remove`, `shadow_block`) are unchanged and still act on every copy at or past the threshold.

With `track_across_users`, the count is copies of the same text from anyone, and each webhook lists the accounts that sent it since the previous webhook in `matched_user_ids`. This catches coordinated spam from many accounts that each post only once or twice.

```json
{
  "name": "Scam ring",
  "rule_type": "flood",
  "enabled": true,
  "config_keys": ["custom:game-chat-family", "custom:game-chat-standard"],
  "conditions": [
    {
      "type": "flood_identical",
      "flood_identical_params": {
        "threshold": 20,
        "time_window": "10m",
        "track_across_users": true
      }
    }
  ],
  "action": {
    "type": "webhook_only"
  }
}
```

With this rule, 60 accounts posting the same text within 10 minutes produce three webhooks, each with the 20 accounts behind its copies. Accounts in a final run below the next multiple are not reported when the window ends.

### Labels API: threshold webhooks

The [Labels API](https://getstream.io/moderation/docs/node/content-moderation/labels/) also evaluates rules, so a per-player threshold can send a webhook while the API keeps returning labels synchronously. A request is evaluated when:

- it sends `user_id` and `policy`, and is not a `dry_run`;
- the rule is enabled, uses `webhook_only`, and lists that policy in `config_keys` (application-wide rules are not evaluated on this path);
- every condition has a time window and is one of `text_rule`, `content_count_rule`, `user_identical_content_count`, `flood_identical`, or `flood_similar`.

Counts are kept per `user_id` and per request `category`, and separately for messages and usernames (`content_type: username`). Policies listed on one rule share the count. A non-flood rule fires at most once per time window per player; flood rules fire once per threshold multiple as described above. Nothing is written to the user, the review queue, or bans, and the Labels response is never changed.

```json
{
  "name": "Repeated scam",
  "rule_type": "user",
  "enabled": true,
  "config_keys": ["custom:game-chat-family", "custom:game-chat-standard"],
  "conditions": [
    {
      "type": "text_rule",
      "text_rule_params": {
        "threshold": 3,
        "time_window": "30m",
        "harm_labels": ["SCAM"]
      }
    }
  ],
  "action": {
    "type": "webhook_only"
  }
}
```

A Labels API fire looks like this:

```json
{
  "type": "moderation_rule.triggered",
  "created_at": "2026-10-26T15:20:11.104Z",
  "rule": {
    "id": "a021b779-4430-4139-b76a-843095c72735",
    "name": "Scam ring",
    "type": "flood",
    "description": ""
  },
  "entity_id": "msg-1204",
  "entity_type": "moderation:label",
  "user_id": "1-234",
  "category": "brawlstars",
  "app_id": 12345,
  "scope": ["custom:game-chat-family", "custom:game-chat-standard"],
  "threshold": 20,
  "time_window": "10m",
  "triggered_actions": ["webhook_only"],
  "matched_contents": [
    {
      "type": "message",
      "id": "msg-1204",
      "text": "Free gems at YT_Scammer",
      "published_at": "2026-10-26T15:20:11.101Z"
    }
  ],
  "matched_user_ids": ["1-101", "1-102", "1-234"]
}
```

### Subscribe to rule events

Configure the hook in the [dashboard](https://getstream.io/signin/?product=moderation) (**Moderation → Preferences → Webhook & SNS/SQS**) or via `event_hooks` on the app:

```json
{
  "hook_type": "webhook",
  "enabled": true,
  "product": "moderation",
  "event_types": ["moderation_rule.triggered"],
  "webhook_url": "https://example.com/moderation/rules"
}
```

`product` must be `moderation` (or `all`). If `event_types` omits `moderation_rule.triggered`, the event is dropped.

The payload is described under [`moderation_rule.triggered`](#moderation_ruletriggered).

## Shapes

### **ReviewQueueItem Shape**

This shape contains the following fields:

| Key                                               | Type     | Description                                                                                                                                                                                | Possible Values                                                                                                                                                                                                                                                                          |
| ------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                                              | string   | Unique identifier of the review queue item                                                                                                                                                 |                                                                                                                                                                                                                                                                                          |
| `created_at`                                      | datetime | Timestamp when the review queue item was created                                                                                                                                           |                                                                                                                                                                                                                                                                                          |
| `updated_at`                                      | datetime | Timestamp when the review queue item was last updated                                                                                                                                      |                                                                                                                                                                                                                                                                                          |
| `entity_type`                                     | string   | Describes the type of entity under review                                                                                                                                                  | Default types include: <ul> <li>chat message: `stream:chat:v1:message`</li> <li>feeds activity: `stream:feeds:v2:activity`</li> <li>feeds reaction: `stream:feeds:v2:reaction`</li> <li>user: `stream:user`</li></ul> For custom moderation, the `entity_type` can be any unique string. |
| `entity_id`                                       | string   | The id of the message, activity or reaction                                                                                                                                                |                                                                                                                                                                                                                                                                                          |
| `moderation_payload`                              | object   | exact content which was sent for auto moderation E.g., `{ texts: ["fuck you"], images: ["https://sampleimage.com/test.jpg"], videos: [] }`                                                 |                                                                                                                                                                                                                                                                                          |
| `status`                                          | string   | Review queue item status. This is not the Check API status (`completed` / `pending`).                                                                                                      | <ul><li>`partial` when sync results are ready and async checks are still running</li><li>`complete` when the checks have finished</li><li>`flagged` when the item is in the queue because it was flagged</li></ul>                                                                       |
| `recommended_action`                              |          | Action recommended by stream moderation engines for the entity/content.                                                                                                                    | Possible values are as following: <ul><li>`flag` Stream moderation recommended flagging the content for manual review</li> <li>`remove` Stream moderation recommended removing the content.</li></ul>                                                                                    |
| `completed_at`                                    | datetime | Timestamp when all the moderation engines finished assessing the content                                                                                                                   |                                                                                                                                                                                                                                                                                          |
| `languages`                                       | array    |                                                                                                                                                                                            |                                                                                                                                                                                                                                                                                          |
| `severity`                                        | int      |                                                                                                                                                                                            |                                                                                                                                                                                                                                                                                          |
| `ai_text_severity`                                | string   |                                                                                                                                                                                            | Possible values are as following: <ul><li>`NONE`</li> <li>`LOW`</li><li>`MEDIUM`</li><li>`HIGH`</li><li>`CRITICAL`</li></ul>                                                                                                                                                             |
| `reviewed_at`                                     | datetime | Time at which the entity was reviewed                                                                                                                                                      |                                                                                                                                                                                                                                                                                          |
| `reviewed_by`                                     | string   | Id of the moderator who reviewed the item. This value is set when moderator takes an action on review queue item from dashboard                                                            |                                                                                                                                                                                                                                                                                          |
| `message` (only applicable to Chat product)       | object   | Chat message object under review                                                                                                                                                           |                                                                                                                                                                                                                                                                                          |
| `call` (only applicable to Video call moderation) | object   | Call object from which moderated frames are taken                                                                                                                                          |                                                                                                                                                                                                                                                                                          |
| `entity_creator`                                  | object   | The user who created the entity under review. In case of chat, its the user who sent the message under review. In case of activity feeds, its the actor of the activity/reaction           |                                                                                                                                                                                                                                                                                          |
| `entity_creator_id`                               | string   | The id of the user who created the entity under review. In case of chat, its the user who sent the message under review. In case of activity feeds, its the actor of the activity/reaction |                                                                                                                                                                                                                                                                                          |
| `flags`                                           | array    | List of reasons the item was flagged for moderation.                                                                                                                                       |                                                                                                                                                                                                                                                                                          |
| `flags_count`                                     | int      | Count of flags returned                                                                                                                                                                    |                                                                                                                                                                                                                                                                                          |
| `bans`                                            | array    | List of bans administered to the user                                                                                                                                                      |                                                                                                                                                                                                                                                                                          |
| `config_key`                                      | string   | Policy key for the moderation policy                                                                                                                                                       |                                                                                                                                                                                                                                                                                          |

### ModerationEventFlag Shape

This shape contains an array of flags associated with the moderation event. Each flag is represented as follows:

| Key                    | Type   | Description                                                                                                                                | Possible Values                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`                 | string | Type of the flag. This represents the name of moderation provider which created the flag.                                                  | <ul><li>`ai_image`</li><li>`user_report` When user flags another user</li><li>`automod_platform_circumvention`</li><li>`block_list`</li><li>`ai_text`</li><li>`automod` When user is flagged from Stream’s internal rules. Currently we have 1 rule setup: if more than 3 content from same user is flagged by moderation engines, then automatically flag the user as well. So user ends up in users list page on dashboard</li><li>`automod_toxicity`</li></ul> |
| `reason`               | string | Description of the reason for the flag                                                                                                     |                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `created_at`           | string | Timestamp when the flag was created                                                                                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `updated_at`           | string | Timestamp when the flag was updated                                                                                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `labels`               | array  | Classification labels for the content under review from moderation engine (e.g., ai_text, ai_image etc) which created this flag            |                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `result`               | object | Complete result object from moderation engine.                                                                                             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `entity_type`          | string | Describes the type of entity under review                                                                                                  | Default types include: <ul> <li>chat message: `stream:chat:v1:message`</li> <li>feeds activity: `stream:feeds:v2:activity`</li> <li>feeds reaction: `stream:feeds:v2:reaction`</li> <li>user: `stream:user`</li></ul> For custom moderation, the `entity_type` can be any unique string.                                                                                                                                                                          |
| `entity_id`            | string | The id of the message, activity or reaction                                                                                                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `moderation_payload`   | object | exact content which was sent for auto moderation E.g., `{ texts: ["fuck you"], images: ["https://sampleimage.com/test.jpg"], videos: [] }` |                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `review_queue_item_id` | string | Unique identifier of the review queue item                                                                                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `user_id`              | string | Id of the user that reported the content                                                                                                   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |

### ModerationEventActionLog Shape

This shape logs actions taken during the moderation event:

| Key              | Type     | Description                                                               | Possible Values                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ---------------- | -------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`             | string   | uuid for action log                                                       | Unique identifier for the action log                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `created_at`     | datetime | Timestamp when this action was performed                                  |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `type`           | string   | Type of action performed on the review queue item.                        | <ul><li>`delete_message`</li><li>`delete_activity`</li><li>`delete_reaction`</li><li>`delete_user`</li><li>`ban`</li><li>`custom`</li><li>`unban`</li><li>`restore`</li><li>`unblock` (deprecated, use `restore`)</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `user_id`        | string   | Id of the user (or moderator) who performed the action                    |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `reason`         | string   | Reason attached by moderator for the action. This can be any string value |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `custom`         | object   | Additional data regarding the action.                                     | In case of `ban` type action, custom object will contain following properties: <ul><li>`timeout` `{int}` Duration in minutes</li><li>`shadow` `{bool}` Shadow block. Only applicable to chat moderation</li><li>`channel_ban_only` `{bool}` Whether the ban applies only to the channel. Only applicable to chat moderation</li><li>`channel_cid` `{string}` Channel CID in which user is banned. Only applicable to chat moderation</li></ul> In case of `delete_user` action, custom object will contain following properties:<ul><li>`mark_messages_deleted` `{bool}`</li><li>`hard_delete` `{bool}`</li><li>`delete_conversations` `{bool}`</li></ul> In case of `delete_reaction` or `delete_message` action, custom object will contain following properties: <ul><li>`hard_delete` `{bool}`</li></ul> |
| `target_user_id` | string   | This is same as entity creator id of the review queue item.               |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

### Moderation Check Completed Event Payload Structure

When a moderation check completes, the webhook payload is structured as follows:

```json
{
  "entity_id": "string",
  "entity_type": "string",
  "recommended_action": "keep | flag | remove",
  "review_queue_item_id": "string",
  "type": "moderation_check.completed",
  "created_at": "timestamp",
  "received_at": "timestamp"
}
```

This shape contains the following fields:

| Key                    | Type     | Description                                                                                       | Possible Values                                                                                                                                                                                                                                                                          |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entity_id`            | string   | The id of the entity that was moderated (e.g., message id, activity id, reaction id, or user id). |                                                                                                                                                                                                                                                                                          |
| `entity_type`          | string   | Describes the type of entity that was moderated.                                                  | Default types include: <ul> <li>chat message: `stream:chat:v1:message`</li> <li>feeds activity: `stream:feeds:v2:activity`</li> <li>feeds reaction: `stream:feeds:v2:reaction`</li> <li>user: `stream:user`</li></ul> For custom moderation, the `entity_type` can be any unique string. |
| `recommended_action`   | string   | Final action recommended by Stream’s moderation engines for the entity/content.                   | Possible values are as following: <ul><li>`keep` No further action is recommended</li><li>`flag` Stream moderation recommends flagging the content for manual review</li><li>`remove` Stream moderation recommends removing the content</li></ul>                                        |
| `review_queue_item_id` | string   | Unique identifier of the associated review queue item created for this moderation check.          |                                                                                                                                                                                                                                                                                          |
| `type`                 | string   | Event type                                                                                        | `moderation_check.completed`                                                                                                                                                                                                                                                             |
| `created_at`           | datetime | Timestamp when the event was created                                                              |                                                                                                                                                                                                                                                                                          |
| `received_at`          | datetime | Timestamp when the event was received by your webhook endpoint                                    |                                                                                                                                                                                                                                                                                          |

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/content-moderation/webhooks/](https://getstream.io/moderation/docs/node/content-moderation/webhooks/).

---

# Content

Send text, images, video, or audio to Stream, and Stream checks it against your [policy](https://getstream.io/moderation/docs/node/configuration/policies/) and returns `keep`, `flag`, or `remove`. If your own model already classified the content, send its results instead so moderators can review them in the review queue.

## Which API should I use?

Four endpoints accept content. Pick the one that matches what you want back.

|                  | [Check](#check)                                                            | [Analyze](#analyze)                                                                      | [Custom Check](#custom-check)                                                      | [Labels](https://getstream.io/moderation/docs/node/content-moderation/labels/)             |
| ---------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| **Use it when**  | You want Stream to moderate a whole entity and return one action           | You need a verdict per named field (`title`, `description`), or you have image bytes     | Your own model already classified the content and you want moderators to review it | You only want classification labels for a text and will act on them yourself |
| **Content**      | `texts`, `images` (max 30), `videos`, `audios` (max 10), and `other_media` | Named text fields, plus image bytes over HTTP multipart. No video or audio               | Text, image, or video, plus your own flags                                         | Only text                                                                    |
| **Result**       | One `recommended_action` for the whole entity                              | Per-field `action` on `texts` and `images`                                               | A review queue item                                                                | `labels`, `harm_type`, `severity`, and `recommended_action`                  |
| **Review queue** | An item is created whenever the action isn't `keep`                        | Stateful mode only (when you send entity fields). Stateless mode returns verdicts inline | Always                                                                             | Never                                                                        |
| **Async**        | Image, video, and audio checks can finish async (`status: pending`)        | Optional: `async_response: true` delivers results by webhook                             | No                                                                                 | No                                                                           |
| **SDKs**         | All server-side SDKs                                                       | All server-side SDKs for texts. Image bytes are HTTP only                                | All server-side SDKs                                                               | All server-side SDKs                                                         |

Examples below use the server-side SDKs. See the setup guides for [Node](https://github.com/GetStream/stream-node), [Python](https://github.com/GetStream/stream-py), [Go](https://github.com/GetStream/getstream-go), [Java](https://github.com/GetStream/stream-sdk-java), [PHP](https://github.com/GetStream/getstream-php), [Ruby](https://github.com/GetStream/getstream-ruby), or [.NET](https://github.com/GetStream/getstream-net).

Stream polls (in Chat and Feeds) don't need an API call: their text is moderated automatically with a polls policy. See [Polls](#polls).

## Check

Submit text, image URLs, video, and audio. Get back one `recommended_action` (`keep`, `flag`, or `remove`) and a review-queue item you can show on a custom dashboard.

1. Create a [policy](https://getstream.io/moderation/docs/node/configuration/policies/) with engines and actions
2. Call `check` with your entity ids and `config_key`
3. Apply `recommended_action` in your product
4. Review flagged items in the [dashboard](https://getstream.io/signin/?product=moderation) or via the [review queue](https://getstream.io/moderation/docs/node/content-moderation/review-queue/) API

### API Usage

>
> **Info:** In the context of the Moderation API, the term "entity" refers to a piece of content that you send for moderation. This can be text, images, video, audio, or a mix.
>

```js label="Node.js"
const response = await client.moderation.check({
  entity_type: "entity_type",
  entity_id: "entity_id",
  entity_creator_id: "entity_creator_id",
  moderation_payload: {
    texts: ["this is bullshit", "f*ck you as***le"],
    images: ["example.com/test.jpg"],
  },
  config_key: "config_key",
});
```

### Request Params

| key                | required | type   | description                                                                                                                                                                                                                                                         |
| ------------------ | -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| entity_type        | true     | string | This is identifier for the type of content you are sending for moderation. This helps with categorizing content on dashboard. E.g., if you have multiple products then you can set unique entity_type for content coming from each product. It could be any string. |
| entity_id          | true     | string | Unique identifier for entity                                                                                                                                                                                                                                        |
| entity_creator_id  | true     | string | Unique identifier for user who created this entity. Generally this is the user id of the app user.                                                                                                                                                                  |
| moderation_payload | false    | object | Texts, images (max 30), videos, audios (max 10), and other media. For comments, `custom` can carry [comment context](#comment-context-in-the-review-queue) for the review queue. `custom` is limited to 10KB; larger payloads are rejected with HTTP 413.           |
| config_key         | false    | string | Key of the config to be used for moderation. See [Configuration](https://getstream.io/moderation/docs/node/configuration/policies/) for details.                                                                                                                                  |
| country_code       | false    | string | ISO 3166-1 alpha-2 (for example `US`, `DE`). Invalid values return `400`. Gives the AI text engine country context for the post.                                                                                                                                    |

### Response

| key                | type                       | description                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------------ | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| status             | `completed` or `pending`   | `pending` means async checks are still running. `completed` means the check finished. The response also includes `triggered_rules`, `task_id` when a task is running, and `test_mode` when you sent a test check. A test check can also include `intent_matched_topic`, `intent_score`, `intent_score_threshold`, and `intent_would_fire`.                                                                                                                              |
| task_id            | string                     | Id of the task running the async moderation. You can check the status of the task itself using [GetTask](https://getstream.io/docs/platform/async-operations/) endpoint.                                                                                                                                                                                                                                                                                                                    |
| recommended_action | “flag” , “remove” , “keep” | Final result of moderation which suggest what action should be taken for moderated entity. <ul><li>“flag” suggests that the content needs manual review either on Stream dashboard or custom dashboard you may have</li> <li>“remove” suggests that this content should be removed from the platform. You will be able to access/review this content from Stream dashboard </li> <li>“keep” suggests that this content is safe and doesn’t contain any harms</li> </ul> |
| item               | object                     | This is basically a json representation of the review queue item accessible on Stream dashboard. You can use this to compose your own dashboard UI.                                                                                                                                                                                                                                                                                                                     |

### Comment context in the review queue

When the entity is a comment, moderators decide faster if they can see what it was posted on and the conversation before it. Send that context in `moderation_payload.custom` and the dashboard's review queue shows it next to the flagged comment:

- A content card: what the comment was posted on (type, id, title, tags, subtitle, description, link, thumbnail)
- The thread: the top-level comment, the latest earlier replies and the moderated comment, highlighted with its action (Flagged, Removed, Shadow blocked, Blocked)

The format works for any product: a video, a news article, a marketplace listing. The dashboard recognizes it by shape, not by `entity_type`: a numeric `schemaVersion` marks it. Without one, `custom` shows as a plain list of keys and values.

```js label="Node.js"
await client.moderation.check({
  entity_type: "comment",
  entity_id: "a_r7",
  entity_creator_id: "driver_dan",
  moderation_payload: {
    texts: ["Cyclists can all go back where they came from"],
    custom: {
      schemaVersion: 1,
      depth: 1,
      content: {
        id: "news-48213",
        type: "article",
        title: "City council approves new bike lanes downtown",
        subtitle: "Local news",
        tags: [
          { key: "section", label: "Section", values: ["Transport"] },
          {
            key: "topics",
            label: "Topics",
            values: ["City council", "Cycling"],
          },
        ],
        description: "The plan adds 12 km of protected lanes over two years...",
        url: "https://example.com/news/bike-lanes",
        imageUrl: "https://example.com/news/bike-lanes.jpg",
      },
      thread: {
        topLevel: {
          id: "a_top",
          user: { id: "cyclist_jen", name: "Jen" },
          text: "Finally. I have been waiting for this for years.",
          createdAt: "2026-10-06T08:12:00Z",
        },
        earlierReplyCount: 7,
        earlierReplies: [
          {
            id: "a_r6",
            user: { id: "driver_dan", name: "Dan" },
            text: "Good luck finding parking now.",
            createdAt: "2026-10-06T08:40:00Z",
          },
        ],
      },
    },
  },
  config_key: "config_key",
});
```

The moderated comment itself is not part of `custom`: its text comes from `texts` and its author from `entity_creator_id`. Keys inside `custom` are camelCase.

| key                      | type                | description                                                                                                                                                            |
| ------------------------ | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| schemaVersion            | positive integer    | Required. Version of this format, set to `1`. Stream bumps it only when the shape changes. Newer versions still render, best-effort                                    |
| contextVersion           | any                 | Optional. Your own version of the context data, for your purposes. The dashboard never reads it                                                                        |
| depth                    | `0` or `1`          | `0` for a top-level comment, `1` for a reply. Threads are one level deep. When omitted, the comment is treated as a reply if `thread.topLevel` is set                  |
| content.id               | string              | Your id for the content, shown next to the type so moderators can copy it                                                                                              |
| content.type             | string              | Free-form kind of content: `video`, `article`, `listing`, ...                                                                                                          |
| content.title            | string              | Title of the content                                                                                                                                                   |
| content.subtitle         | string              | Shown after the tags, on one line under the title                                                                                                                      |
| content.tags             | array of tag groups | `{ key, label, values }`. Groups show on one line, separated by `·`, values within a group by commas. Hovering a value shows its group `label`. `key` is not displayed |
| content.description      | string              | Longer description, truncated at 150 characters with a "Show more" toggle                                                                                              |
| content.url              | string              | Link to the content, opened from the card. Only `http` and `https` URLs are shown                                                                                      |
| content.imageUrl         | string              | Thumbnail. Only `http` and `https` URLs are shown                                                                                                                      |
| thread.topLevel          | comment             | The comment a reply sits under. Omit it for a top-level comment                                                                                                        |
| thread.earlierReplies    | array of comments   | Replies posted before the moderated one, oldest first. Send the latest few, not the whole thread                                                                       |
| thread.earlierReplyCount | integer             | Total replies before the moderated one. When it is larger than `earlierReplies`, the dashboard shows "Showing last X of N earlier replies"                             |
| thread comment           | object              | Each thread comment has an `id`, a `user` (`{ id, name, image }`, `name` and `image` optional), its `text` and an optional `createdAt` timestamp (ISO 8601)            |

Every field except `schemaVersion` is optional, and unknown keys are ignored. A malformed `tags` value drops only the tags, never the rest of the context.

This section covers what moderators see. To let the AI Text (LLM) engine read the same data when it decides on the comment, list the keys in the policy's `llm_config`; see [Context from custom data](https://getstream.io/moderation/docs/node/engines/ai-llm-text/#context-from-custom-data).

## Analyze

Submit named text fields and get a keep / flag / remove decision **per label**. Use it when you need a verdict per field instead of one action for the whole entity.

Server-side only. Call `analyze` the same way as `check` for named `texts`. At least one text field or image is required.

Raw image bytes are **not** in the SDK. Send them with an HTTP `multipart/form-data` request: one JSON `payload` part plus `image:<label>` file parts. That is the only way to attach bytes today.

### Modes

**Stateful vs stateless.** Send `entity_type`, `entity_id`, and `entity_creator_id` together to persist a review-queue row (when content is flagged) and evaluate rules. Omit all three for a stateless call: verdicts only, no queue, no webhooks. `config_key` is required when stateless. Partial entity fields return `400`.

`entity_type` is yours (`listing`, `external:call`). Types that start with `stream:` are reserved. You may add a subtype for routing (`external:call:keyframe`); webhooks echo the canonical type (`external:call`).

**Sync vs async.** Default is sync: verdicts in the HTTP body. Set `async_response: true` (stateful only) to get `status: "pending"` and receive `moderation.text_analysis.complete` / `moderation.image_analysis.complete` webhooks instead. Do not send `async_response: true` without entity fields.

### Calling Analyze

```js label="Node.js"
const response = await client.moderation.analyze({
  entity_type: "listing",
  entity_id: "listing_42",
  entity_creator_id: "user_42",
  config_key: "catalog-v1",
  content_ids: { caption: "cap_42" },
  texts: { caption: "Vintage watch, mint condition" },
});
```

### Image bytes (HTTP only)

`client.moderation.analyze` sends the JSON fields above. It cannot attach files. To send raw image bytes, `POST` `multipart/form-data` yourself (max 10 images, 250 KB each by default, 20 MB for the whole request):

```bash
curl -X POST "https://chat.stream-io-api.com/api/v2/moderation/analyze?api_key=${API_KEY}" \
  -H "Authorization: ${TOKEN}" \
  -H "stream-auth-type: jwt" \
  -F 'payload={"entity_type":"listing","entity_id":"listing_42","entity_creator_id":"user_42","config_key":"catalog-v1","texts":{"caption":"Vintage watch, mint condition"},"content_ids":{"caption":"cap_42","main_photo":"img_42_main"}};type=application/json' \
  -F "image:main_photo=@frame.jpg;type=image/jpeg"
```

### Analyze request

| key                  | required                     | type             | description                                                                                                                                       |
| -------------------- | ---------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| entity_type          | with the other entity fields | string           | Caller-defined type. Required with `entity_id` and `entity_creator_id`. Omit all three for stateless mode                                         |
| entity_id            | with the other entity fields | string           | Your identifier for this content                                                                                                                  |
| entity_creator_id    | with the other entity fields | string           | User id of the content creator                                                                                                                    |
| config_key           | stateless: yes               | string           | Policy key. Optional in stateful mode (resolved from `entity_type`). Unknown keys return `422`                                                    |
| texts                | no                           | object           | Named text fields, keyed by your label. Max 20 keys, each 1 to 64 characters                                                                      |
| content_ids          | no                           | object           | Per-field ids keyed by the same labels as `texts` or `image:<label>`. Echoed as `id` on each verdict. Values: 1 to 128 chars, `A-Z a-z 0-9 . _ -` |
| content_published_at | no                           | string (RFC3339) | When the content was produced. Used as the score for aggregation-rule windows                                                                     |
| custom               | no                           | object           | Metadata stored on the review-queue item and echoed on webhooks                                                                                   |
| async_response       | no                           | bool             | Stateful only. When `true`, HTTP is `pending` and verdicts arrive via [webhooks](https://getstream.io/moderation/docs/node/content-moderation/webhooks/)        |
| country_code         | no                           | string           | ISO 3166-1 alpha-2 (for example `US`, `DE`). Invalid values return `400`. Gives the AI text engine country context for the post.                  |

**Images:** HTTP only. Each file part is named `image:<label>`. Max 10 images, 250 KB each by default, 20 MB for the whole request. The SDK `analyze` method does not accept file parts.

### Analyze response

Successful calls return **201**.

| key      | type                             | description                                                                                        |
| -------- | -------------------------------- | -------------------------------------------------------------------------------------------------- |
| status   | `complete`, `partial`, `pending` | `complete` if every field was screened. `partial` if some have `error`. `pending` is the async ack |
| texts    | object                           | Per-text verdicts keyed by your label. Absent on async pending                                     |
| images   | object                           | Per-image verdicts keyed by your label                                                             |
| duration | string                           | Server wall-clock duration                                                                         |

Each text or image field:

| key                 | description                                                                                        |
| ------------------- | -------------------------------------------------------------------------------------------------- |
| id                  | Echo of `content_ids[<label>]` when you sent one                                                   |
| action              | `keep`, `flag`, or `remove`. **Omitted** when `error` is set. Never treat a missing action as keep |
| classifications     | Text: `{ name, severity }`. Image: `{ name, confidence, subclassifications }`                      |
| severity            | Text only. Highest severity across classifications (`low`, `medium`, `high`, `critical`)           |
| language            | Text only. Detected language code                                                                  |
| confidence          | Image only. Highest confidence (0 to 1)                                                            |
| ocr_classifications | Image only. Text labels extracted from the image (`name`, `severity`)                              |
| error               | Field could not be screened. Retry this label only                                                 |

```json
{
  "status": "complete",
  "texts": {
    "caption": {
      "id": "cap_42",
      "action": "flag",
      "classifications": [{ "name": "INSULT", "severity": "high" }],
      "severity": "high",
      "language": "en"
    }
  },
  "images": {
    "main_photo": {
      "id": "img_42_main",
      "action": "keep"
    }
  }
}
```

If some fields fail, `status` is `partial` (still 201). Retry only the labels with `error`. If nothing could be screened, the API returns **503** with a standard error envelope, not this body. Bad input is **400**. A missing policy is **422**.

Async pending body:

```json
{ "status": "pending", "duration": "112.84ms" }
```

Wait for [Analyze webhook events](https://getstream.io/moderation/docs/node/content-moderation/webhooks/#moderationtext_analysiscomplete). A provider error stays on `*.complete` as field `error`. `moderation.analysis.failed` means Stream could not finish the listed `content_ids` after the pending ack. Treat those ids as unscreened.

## Custom Check

Custom Check lets you submit results from your own AI model, for a Stream Chat message or your own content, so moderators can review them in the dashboard.

### Add Custom Flags to a Chat Message

Custom Flags can be added to a Chat message. This enables you to submit your own AI moderation results of a chat message for review by moderators on the Dashboard.

```js label="Node.js"
await client.moderation.customCheck({
  entity_type: "stream:chat:v1:message",
  entity_id: messageId,
  entity_creator_id: "user_id",
  flags: [
    {
      type: "custom_check_image",
      reason: "Image was NSFW",
      labels: ["NSFW"],
    },
    {
      type: "custom_check_text",
      reason: "Text was harmful",
      labels: ["harmful"],
    },
    {
      type: "custom_check_video",
      reason: "Video contains copyright material",
      labels: ["copyright-violation"],
    },
  ],
});
```

### Add Custom Check Flags to the Custom Content

The Custom Check endpoint enables you to submit your own AI moderation results for the custom content for review by moderators on the Dashboard.

```js label="Node.js"
await client.moderation.customCheck({
  entity_type: "entity_type",
  entity_id: "entity_id",
  entity_creator_id: "entity_creator_id",
  moderation_payload: {
    texts: ["offensive"],
  },
  flags: [
    {
      type: "custom_check_text",
      reason: "Text was offensive",
      custom: {
        explaination:
          "custom is a nullable field allowing you to attach a custom object to the flag for your specific use cases or requirements",
      },
    },
  ],
});
```

### Request Params

| key                | required | type                                                            | description                                                                                        |
| ------------------ | -------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| entity_type        | true     | string                                                          | This is identifier for the type of the entity. This helps with categorizing Content.               |
| entity_id          | true     | string                                                          | Unique identifier for entity.                                                                      |
| entity_creator_id  | true     | string                                                          | Unique identifier for user who created this entity. Generally this is the user id of the app user. |
| moderation_payload | true     | object                                                          | Entity or content to be moderated                                                                  |
| flags              | true     | array                                                           | List of custom flags                                                                               |
| flag.type          | true     | "custom_check_text", "custom_check_image", "custom_check_video" | Type of a custom flag                                                                              |

### Response

| key    | type       | description                                                                                                                                         |
| ------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| status | `complete` | Custom check stores the review item as `complete`. Check itself uses `completed` or `pending`. Analyze uses `complete`, `partial`, or `pending`.    |
| id     | string     | id of the review queue item.                                                                                                                        |
| item   | object     | This is basically a json representation of the review queue item accessible on Stream dashboard. You can use this to compose your own dashboard UI. |

## Polls

Stream moderates the text of polls as users write it: the question, the description, the options, options suggested by other users, and free-text answers. Set up a polls policy and poll writes that carry text are checked before they are stored, with no extra API calls from your app.

> **Warning:** Poll moderation counts towards your text moderation quota.
>

### What gets moderated

| Poll write                                    | Texts checked                          | Review queue entity type |
| --------------------------------------------- | -------------------------------------- | ------------------------ |
| Create a poll                                 | Question, description and every option | `stream:v1:poll`         |
| Update a poll (full or partial)               | The poll's texts after the update      | `stream:v1:poll`         |
| Add an option (including a user's suggestion) | The new option                         | `stream:v1:poll`         |
| Edit an option                                | The option's new text                  | `stream:v1:poll`         |
| Cast a vote with a free-text answer           | The answer                             | `stream:v1:poll_vote`    |

Votes on an option carry no text and are not moderated. An update that leaves every text unchanged (for example, closing the poll) is not checked either. A partial update is checked on the texts that will actually be stored.

Each review queue item is filed under the user who made the write: the poll's creator for a create, the user who made an update, the suggesting user for a suggested option, and the voter for an answer. One user has one open item per poll. A later write by that same user updates the item and replaces its payload, including `poll_operation`. A different user gets a separate item.

### Set up a polls policy

1. Navigate to the [Stream Dashboard](https://getstream.io/signin/?product=moderation).
2. Go to **Moderation** → **Policies** and create a policy with the **Polls** type.
3. Leave the name as `default` to create `polls:default`, which applies to every poll write in the app. A named policy (`polls:<name>`) applies only where your server passes its key (see [Use a different policy from your server](#use-a-different-policy-from-your-server)).
4. Add the engines you want: AI text, LLM text, blocklists, regex filters and allowlists. A polls policy does not include image, video, audio or flooding.

Without a polls policy, poll writes are not moderated.

### Actions

A polls policy maps each rule to one of two actions:

| Action   | What happens to the write                                                                      |
| -------- | ---------------------------------------------------------------------------------------------- |
| `flag`   | The write is stored and visible, and a review queue item is created for a moderator to review. |
| `remove` | The write is rejected and nothing is stored. A review queue item is still created.             |

`shadow`, `mask` and `mask_flag` are treated as `flag`: the write is stored and a review item is opened. `bounce`, `bounce_flag` and `bounce_remove` reject the write the same way `remove` does, but a bounce does not open a review item. Any other action leaves the write stored.

Only that `remove` verdict rejects the write. If the check cannot be completed, the write is stored.

#### Handling a removed write

A removed write fails with HTTP status `400` and error code `73`, so your app can tell the user their poll, option or answer was not accepted:

```json
{
  "code": 73,
  "message": "poll moderation failed: content blocked",
  "StatusCode": 400
}
```

For server-side requests, the error's `details` also names what matched: `action`, `text_harms` (AI and LLM labels) and `blocklists_matched`. Client-side requests never receive those details.

Users with `bypass_moderation` set are never checked. When a polls policy applies, each text is limited to 10,000 characters. A longer text is rejected with an input error and is not checked.

### Use a different policy from your server

Server-side requests can pass `config_key` (and `config_team`) on any poll write to use a named policy instead of `polls:default`, for example `polls:kids-mode`. A `config_key` that does not exist is rejected. The write is not checked against `polls:default` instead. Client-side requests cannot choose a policy: the field is ignored, so users cannot opt themselves out of `polls:default`.

### Review poll content

Poll items appear in the [review queue](https://getstream.io/moderation/docs/node/content-moderation/review-queue/) like any other content. The dashboard shows the live poll, marks the flagged question, description, option or answer, and shows a removed write on its own, because that text was never stored. A poll attached to a chat message is shown with that message. A poll on a feed, or one that was never posted, is shown by itself.

Each poll moderation check records what the write was and, for option writes, which option, under `moderation_payload.custom`:

| Field            | Value                                                                    |
| ---------------- | ------------------------------------------------------------------------ |
| `poll_id`        | The poll's ID.                                                           |
| `poll_operation` | `create_poll`, `update_poll`, `add_option`, `update_option` or `answer`. |
| `option_id`      | The option an `add_option` or `update_option` write targeted.            |

`moderation_payload.text_ordered_keys` labels each entry of `moderation_payload.texts` as `name`, `description`, `option` or `answer`.

#### Actions on poll items

| Action               | Use on                | What it does                                                                                                                                                                                                                                       |
| -------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `delete_poll`        | `stream:v1:poll`      | Deletes the whole poll, with every option and vote. Only the item filed by the poll's creator can do this, including after that creator's later edit replaces the item's payload. An item filed by someone else cannot be used to delete the poll. |
| `delete_poll_option` | `stream:v1:poll`      | Deletes one option and keeps the rest of the poll. Pass `option_id` when the item covers the whole poll. An item for a single option already names it.                                                                                             |
| `delete_poll_answer` | `stream:v1:poll_vote` | Deletes a free-text answer and keeps the poll and other votes. Supported for polls on chat messages.                                                                                                                                               |

All three deletes are permanent: poll content cannot be restored. Moderators can also mark poll items reviewed, ban the user who wrote the content, or escalate the item.

`delete_poll_option` and `delete_poll_answer` refuse when the stored content no longer holds the text that was checked. A removed edit leaves the original option or answer in place, and that original is not deleted. An answer also cannot be deleted once its poll is closed, or when the poll is not on a chat message.

See [Actions](https://getstream.io/moderation/docs/node/content-moderation/actions/) for how to submit them.

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/content-moderation/check/](https://getstream.io/moderation/docs/node/content-moderation/check/).

---

# Labels

## Overview

The Labels API is a server-side text classification endpoint that returns raw moderation labels for a piece of text. It is designed for integrations that need the classification signal on its own - without creating review-queue items, flags, or actions. Webhooks are sent only for [rules](#rule-webhooks) you scope to the request's policy.

Use it when you want to label text and decide yourself what to do with the result: filter content, route it, tag it for analytics, or feed it into your own downstream systems. For the full automated moderation workflow (review queue, actions, appeals), use the [Moderation Check](https://getstream.io/moderation/docs/node/content-moderation/check/) endpoint instead. To compare Labels with Check, Analyze, and Custom Check, see [Which API should I use?](https://getstream.io/moderation/docs/node/content-moderation/check/#which-api-should-i-use)

### Storage model

Calls to the Labels API are **stateless by default**. The request is classified by your configured providers (see [Provider Routing](#provider-routing)), the response is returned synchronously, and the content, labels, and classification are **not persisted** by Stream.

Optional storage is available for organizations that need to query labels historically (for analytics, trend analysis, investigations, or custom dashboards). When storage is enabled, results containing at least one label are persisted and can be queried via the `queryLabelResults` method. Content that returns zero labels is not stored.

>
> **Note:** Storage is an opt-in capability for high-volume use cases and is not enabled by default. Please [contact us](mailto:support@getstream.io) if you want persistence turned on for your organization. When storage is disabled, the classification endpoint works normally and the query endpoint returns empty pages.
>

---

## Provider Routing

The classification endpoint runs different providers depending on the request. No setup is required for the default path — send text, get labels.

| Mode              | Trigger                                       | Provider                                                                                                                                                       |
| ----------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Default (NLP)** | No `policy`, `content_type` omitted or `text` | Stream's managed NLP text classifier.                                                                                                                          |
| **Custom policy** | `policy` set on the request                   | Whatever the policy configures — LLM-based classifier, NLP, blocklists, or a combination. See [Policies](https://getstream.io/moderation/docs/node/configuration/policies/). |
| **Username**      | `content_type: "username"`                    | Username-optimized text classifier.                                                                                                                            |

To customize classification (custom LLM prompts, specific blocklists, your own harm taxonomy), define a [policy](https://getstream.io/moderation/docs/node/configuration/policies/) and pass its key as `policy` on the request.

---

## Classify Content

Classifies a single piece of text and returns labels synchronously. Server-side only.

```js label="Node.js"
const response = await client.moderation.labels({
  content: "you are a fucking idiot",
  content_type: "message",
  category: "chat",
  content_id: "msg-123",
  user_id: "user-42",
});
```

### Request Params

| Field          | Required | Type                      | Description                                                                                                                                                                    |
| -------------- | -------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `content`      | yes      | string (max 20,000 chars) | The text to classify.                                                                                                                                                          |
| `content_type` | no       | string                    | One of `text` (default), `message`, or `username`. Stored alongside the result so stored queries can filter by source. `username` routes to the username-optimized classifier. |
| `category`     | no       | string (max 128)          | Free-form tag for grouping results. Filterable on the query endpoint.                                                                                                          |
| `content_id`   | no       | string (max 256)          | Your own identifier for the content being moderated (e.g. a message id). Echoed back on the response and stored for correlation.                                               |
| `user_id`      | no       | string (max 256)          | Identifier for the user who authored the content. Enables filtering stored results by user.                                                                                    |
| `policy`       | no       | string (max 128)          | Policy key to use instead of the default NLP classifier. Must match `^[\w-:]*$`. See [Policies](https://getstream.io/moderation/docs/node/configuration/policies/).                          |

### Response

```json
{
  "labels": ["insult", "vulgarity"],
  "harm_type": "hateful",
  "directed_at": "user",
  "recommended_action": "keep",
  "severity": "low",
  "language": "en",
  "content_id": "msg-123",
  "masked_content": "you are a ******* *****",
  "duration": "119.85ms"
}
```

| Field                | Description                                                                                                                                                                                                                                                                                                                |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `labels`             | Specific violation labels detected in the content (e.g. `insult`, `threat`, `vulgarity`). Always lowercase. An empty array means no violations were detected.                                                                                                                                                              |
| `harm_type`          | High-level type of the content: `hate_speech` (explicitly violent or discriminatory), `hateful` (insults, aggression, body-shaming), `undesirable` (spam, flood, ads), `criticism` (negative but not hateful), `neutral`, `positive`, or `none`. Flood detection can also return `spam`. Always lowercase.                 |
| `directed_at`        | Who the content is aimed at, when it can be inferred: `user` (the author or another user), `user_family`, `single_person` (a named third person), `group`, `everyone`, `author_of_comment` (the writer themselves, important for self-harm), `haters`, `entity` (a company or brand), or `none`. Omitted when unavailable. |
| `recommended_action` | Suggested action for the content: `keep`, `flag`, or `remove`.                                                                                                                                                                                                                                                             |
| `severity`           | Severity of the detected harm: `none`, `low`, `medium`, `high`, or `critical`.                                                                                                                                                                                                                                             |
| `language`           | Detected language code (ISO 639-1), e.g. `en`, `fr`, `es`.                                                                                                                                                                                                                                                                 |
| `content_id`         | Echoed from the request for correlation.                                                                                                                                                                                                                                                                                   |
| `masked_content`     | Returned only when a blocklist rule with a `mask` action rewrote the content. Contains the original text with matched tokens replaced by mask characters.                                                                                                                                                                  |
| `duration`           | Time spent running the classifier.                                                                                                                                                                                                                                                                                         |

>
> **Info:** All enum-style values returned by this API (`labels`, `harm_type`, `directed_at`, `recommended_action`, `severity`, `language`) are lowercase. Filters on the query endpoint use the same lowercase values.
>

### Rule webhooks

When the request sends `user_id` and `policy`, the Labels API also evaluates `webhook_only` rules scoped to that policy and sends `moderation_rule.triggered` when a player crosses a threshold, for example three scam messages in 30 minutes, or the same text from 20 accounts. Counts are kept per `user_id` and `category`, and separately for messages and usernames. The response is the same whether or not a rule fires. See [Rule-Triggered Webhooks](https://getstream.io/moderation/docs/node/content-moderation/webhooks/#labels-api-threshold-webhooks).

### Error handling

- Provider errors (rate limits, upstream timeouts) surface as errors. Content is not silently returned as `keep` when classification fails.
- Requesting a `policy` that doesn't exist returns a `400` error.
- The endpoint is server-side only. Client-side tokens are rejected.

---

## Query Stored Results

Query persisted label results with filtering, sorting, and pagination. Requires storage to be enabled on the organization — see [Storage model](#storage-model).

```js label="Node.js"
const response = await client.moderation.queryLabelResults({
  filter: {
    category: "chat",
    language: "en",
    harm_type: "hateful",
    date_range: "2026-04-01_2026-04-23",
  },
  sort: [{ field: "created_at", direction: -1 }],
  limit: 25,
});
```

### Available Filters

For details on each operator, see [Query Syntax Operators](https://getstream.io/docs/platform/query-syntax-operators/).

| Filter               | Operators  | Description                                                                       |
| -------------------- | ---------- | --------------------------------------------------------------------------------- |
| `category`           | `eq`, `in` | Filter by category tag set on the request.                                        |
| `language`           | `eq`, `in` | Filter by detected language.                                                      |
| `content_type`       | `eq`, `in` | Filter by the `content_type` sent on the request (`text`, `message`, `username`). |
| `harm_type`          | `eq`, `in` | Filter by harm category.                                                          |
| `labels`             | `eq`, `in` | Filter by label name — `eq` matches a single label, `in` matches any of a list.   |
| `recommended_action` | `eq`, `in` | Filter by recommended action.                                                     |
| `severity`           | `eq`, `in` | Filter by severity.                                                               |
| `policy`             | `eq`       | Filter by policy key.                                                             |
| `content_id`         | `eq`       | Look up results for a specific content id.                                        |
| `user_id`            | `eq`, `in` | Filter by author user id.                                                         |
| `date_range`         | —          | Date range in `YYYY-MM-DD_YYYY-MM-DD` format.                                     |

### Response

```json
{
  "label_results": [
    {
      "id": "30dff5ac-6b80-486c-9da1-fcb938849642",
      "created_at": "2026-04-16T10:30:00Z",
      "content": "you are a fucking idiot",
      "masked_content": "you are a ******* *****",
      "content_type": "message",
      "category": "chat",
      "labels": ["insult", "vulgarity"],
      "harm_type": "hateful",
      "directed_at": "user",
      "recommended_action": "keep",
      "severity": "low",
      "language": "en",
      "content_id": "msg-123",
      "user_id": "user-42"
    }
  ],
  "next": "...",
  "prev": "..."
}
```

Use `next` / `prev` for cursor-based pagination.

---

## Labels vs Check

|                                             | Labels                     | [Moderation Check](https://getstream.io/moderation/docs/node/content-moderation/check/) |
| ------------------------------------------- | -------------------------- | ------------------------------------------------------------------------- |
| **Purpose**                                 | Text classification signal | Full moderation workflow                                                  |
| **Creates review-queue items**              | No                         | Yes                                                                       |
| **Triggers actions (flag, remove, bounce)** | No                         | Yes                                                                       |
| **Webhooks**                                | No                         | Yes                                                                       |
| **Storage**                                 | Opt-in                     | Stored in the review queue when the action isn't `keep`                   |

Use Labels when you want the classification result and will handle the rest yourself. Use Check when you want Stream to run the end-to-end moderation workflow.

---

## Rate Limits

Limits follow the standard [rate limit tiers](https://getstream.io/docs/platform/rate-limits/):

| Endpoint            | Default limit                       |
| ------------------- | ----------------------------------- |
| `labels`            | High tier (10,000 requests/window)  |
| `queryLabelResults` | Normal tier (1,000 requests/window) |

If your workload requires higher throughput, [contact us](mailto:support@getstream.io) to arrange a per-organization override.

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/content-moderation/labels/](https://getstream.io/moderation/docs/node/content-moderation/labels/).

---

# Flag, Mute & Ban

## Overview

Stream provides moderation APIs for flagging content, muting users, banning users, and blocking users. These actions integrate with the moderation review queue and [dashboard](https://getstream.io/signin/?product=moderation). All endpoints use the v2 moderation API and are available through Stream's server-side SDKs.

Not every action works outside Stream's products. Flag, ban, and bypass also work for your own (standalone) content and users. Mute, block, and channel bans only take effect inside Stream Chat, Feeds, and Video.

| Action                             | Standalone content and users                               | Stream Chat, Feeds, Video |
| ---------------------------------- | ---------------------------------------------------------- | ------------------------- |
| [Flag](#flag)                      | Yes. Any `entity_type`; custom types need server-side auth | Yes                       |
| [Ban](#ban)                        | Yes. Stream records the ban; your app enforces it          | Yes. Stream enforces it   |
| [Channel ban](#channel-scoped-ban) | No                                                         | Stream Chat only          |
| [Mute](#mute)                      | No                                                         | Yes                       |
| [Block](#block)                    | No                                                         | Yes                       |
| [Bypass](#bypass-moderation)       | Yes. Skips Check for the user's content                    | Yes                       |

---

## Flag

Flagging allows users or moderators to report content for review. Flagged content is automatically added to the moderation review queue. You can flag messages, users, activities, reactions, or any custom entity type.

### Flag Content

Use the `flag` method to report an entity for moderation review. You can attach a reason, custom metadata, and a moderation payload containing the content to be reviewed.

```js label="Node.js"
await client.moderation.flag({
  entity_type: "stream:chat:v1:message",
  entity_id: messageId,
  entity_creator_id: creatorId,
  reason: "spam",
  custom: { user_comment: "This user is spamming the channel" },
  user_id: moderatorId,
});
```

**Request parameters**

| key                | required | type   | description                                                                                                                                                  |
| ------------------ | -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| entity_type        | true     | string | Type of entity being flagged. Examples: `stream:chat:v1:message`, `stream:user`, `stream:feeds:v2:activity`, `stream:feeds:v2:reaction`, or any custom type. |
| entity_id          | true     | string | Unique identifier of the entity being flagged.                                                                                                               |
| entity_creator_id  | false    | string | User ID of the entity creator.                                                                                                                               |
| reason             | false    | string | Reason for flagging. Use a slug or keyword for easy filtering.                                                                                               |
| custom             | false    | object | Custom metadata to attach to the flag.                                                                                                                       |
| moderation_payload | false    | object | Content to be reviewed (texts, images, videos). Displayed on the dashboard.                                                                                  |
| user_id            | false    | string | User ID of the person flagging (required for server-side usage).                                                                                             |

**Response**

| key     | type   | description                                      |
| ------- | ------ | ------------------------------------------------ |
| item_id | string | ID of the review queue item created by the flag. |

### Flag a User

To flag a user rather than a message, set `entity_type` to `stream:user` and provide the target user's ID as `entity_id`.

```js label="Node.js"
await client.moderation.flag({
  entity_type: "stream:user",
  entity_id: targetUserId,
  reason: "harassment",
  user_id: moderatorId,
});
```

### Query Moderation Flags

Query flags with filtering, sorting, and pagination. This allows you to retrieve flags matching specific criteria.

```js label="Node.js"
const response = await client.moderation.queryModerationFlags({
  filter: { entity_type: "stream:chat:v1:message" },
  sort: [{ field: "created_at", direction: -1 }],
  limit: 20,
});
```

**Request parameters**

| key    | required | type   | description              |
| ------ | -------- | ------ | ------------------------ |
| filter | false    | object | Filter conditions.       |
| sort   | false    | array  | Sort parameters.         |
| limit  | false    | number | Maximum flags to return. |
| next   | false    | string | Pagination cursor.       |

---

## Mute

>
> **Info:** Mute only takes effect inside Stream Chat, Feeds, and Video. For your own app, store mutes in your own system.
>

Muting allows users to silence other users. Muted users' messages are still delivered via WebSocket but not via push notifications (APN/Firebase). Implementing UI logic for muted users (hiding or displaying differently) is left to the developer.

### Mute User

Mute one or more users. You can optionally set a timeout after which the mute automatically expires.

```js label="Node.js"
await client.moderation.mute({
  target_ids: ["user_to_mute"],
  user_id: mutingUserId,
  timeout: 60,
});
```

**Request parameters**

| key        | required | type   | description                                                       |
| ---------- | -------- | ------ | ----------------------------------------------------------------- |
| target_ids | true     | array  | List of user IDs to mute.                                         |
| user_id    | false    | string | User ID of the person performing the mute.                        |
| timeout    | false    | number | Mute duration in minutes. If not set, the mute has no expiration. |

### Unmute User

Remove a mute from one or more users.

```js label="Node.js"
await client.moderation.unmute({
  target_ids: ["user_to_unmute"],
  user_id: unmutingUserId,
});
```

---

## Ban

Banning stops a user from posting. An app-wide ban works for any user: Stream records it on the user (`banned`, `ban_expires`) and sends a `user.banned` webhook. Stream Chat and Feeds enforce it for you; in your own app, read the ban state or handle the webhook and block the user yourself. Stream Chat users can also be banned from a single channel. Bans support timeouts (temporary bans), shadow banning, IP banning, and optional message deletion.

### Ban User

Ban a user from the entire app. You can optionally specify a timeout for temporary bans, a reason, and whether to delete the user's messages.

```js label="Node.js"
await client.moderation.ban({
  target_user_id: "user_to_ban",
  banned_by_id: moderatorId,
  reason: "Repeated spam",
  timeout: 1440,
});
```

**Request parameters**

| key             | required | type    | description                                                                                                           |
| --------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
| target_user_id  | true     | string  | User ID to ban.                                                                                                       |
| banned_by_id    | false    | string  | User ID of the moderator performing the ban.                                                                          |
| channel_cid     | false    | string  | Channel CID for channel-scoped bans (e.g., `messaging:general`). Omit for app-wide bans.                              |
| reason          | false    | string  | Reason for the ban.                                                                                                   |
| timeout         | false    | number  | Ban duration in minutes. If not set, the ban is permanent.                                                            |
| shadow          | false    | boolean | When true, the user is shadow banned. Their messages are only visible to themselves.                                  |
| ip_ban          | false    | boolean | When true, also bans the user's last known IP address. Automatically applies a 30-day timeout unless overridden.      |
| delete_messages | false    | string  | Delete the user's messages. Values: `soft` (removes from client, retained on server) or `hard` (permanently deleted). |

### Channel-Scoped Ban

Stream Chat only. Ban a user from a specific channel by providing the `channel_cid` parameter. The user will still be able to use the rest of the app.

```js label="Node.js"
await client.moderation.ban({
  target_user_id: "user_to_ban",
  banned_by_id: moderatorId,
  channel_cid: "messaging:general",
  reason: "Trolling in this channel",
  timeout: 60,
});
```

### Shadow Ban

Shadow banning allows a user to continue posting, but their messages are only visible to themselves. Other users will not see the shadow-banned user's messages. This is useful for handling disruptive users without alerting them.

```js label="Node.js"
await client.moderation.ban({
  target_user_id: "user_to_shadow_ban",
  banned_by_id: moderatorId,
  reason: "Disruptive behavior",
  shadow: true,
});
```

### Unban User

Remove a ban from a user. For channel-scoped bans, provide the `channel_cid` parameter.

```js label="Node.js"
await client.moderation.unban({
  target_user_id: "user_to_unban",
  created_by: moderatorId,
});
```

### Query Banned Users

List bans with the metadata that is intentionally not returned by `queryUsers` — the moderator who issued the ban (`banned_by`), the original `reason`, when it expires, and the channel CID for channel-scoped bans. Use this when you need to render a "who banned this user and why" view, build a moderation dashboard, or audit ban history.

>
> **Note:** `queryUsers` returns only the ban _state_ (`banned`, `ban_expires`) on the user object — `banned_by` and `reason` are not part of the user payload by design. Use `queryBannedUsers` to retrieve them. This endpoint is part of the Chat product API; bans are app-wide, so it works for any app that has Chat enabled regardless of which product applied the ban.
>

Client-side the endpoint is restricted to a single channel: a request without a `channel_cid` filter is rejected, so app-wide bans can only be listed server-side. Both regular and shadow bans are returned, and so are bans that have already expired unless `exclude_expired_bans` is set.

```swift label="Swift"
// Client-side the query is always scoped to a channel. The iOS SDK adds the
// channel_cid filter, so anything you pass narrows down that channel's bans.
let channelId = ChannelId(type: .messaging, id: "general")
let chat = chatClient.makeChat(for: channelId)

// All of the channel's bans
let bans = try await chat.queryBannedUsers()
for ban in bans {
    // BannedUser: user, bannedBy, cid, createdAt, expiresAt, reason, isShadowBan
    print("\(ban.user.id) banned by \(ban.bannedBy?.id ?? "unknown"): \(ban.reason ?? "no reason")")
}

// Bans a specific moderator created, newest first, expired ones left out.
// Filter keys: userId, bannedById, createdAt, reason. Only createdAt is sortable.
let query = BannedUserListQuery(
    filter: .equal(.bannedById, to: moderatorId),
    sort: [.init(key: .createdAt, isAscending: false)],
    pagination: Pagination(pageSize: 20),
    excludeExpiredBans: true
)
let recentBans = try await chat.queryBannedUsers(with: query)

// The same query with controllers
chatClient.channelController(for: channelId).queryBannedUsers(with: query) { result in
    // Handle the Result<[BannedUser], Error>
}
```

```js label="Node.js"
// All app-wide bans
const response = await client.queryBannedUsers({
  payload: {
    filter_conditions: { banned_by_id: { $eq: moderatorId } },
    sort: [{ field: "created_at", direction: -1 }],
    limit: 20,
    exclude_expired_bans: true,
  },
});

// Bans for a specific user
const userBans = await client.queryBannedUsers({
  payload: {
    filter_conditions: { user_id: { $eq: "user_to_ban" } },
  },
});

// Channel-scoped bans
const channelBans = await client.queryBannedUsers({
  payload: {
    filter_conditions: { channel_cid: { $eq: "messaging:general" } },
  },
});
```

**Request parameters**

| key                  | required | type    | description                                                                                                                                                                   |
| -------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filter_conditions    | true     | object  | Filter conditions. Supported keys include `user_id`, `banned_by_id`, `channel_cid`, `reason`, `created_at`, `expires`. Operators: `$eq`, `$in`, `$gt`, `$gte`, `$lt`, `$lte`. |
| sort                 | false    | array   | Sort parameters (max 1). Typically sort by `created_at`.                                                                                                                      |
| limit                | false    | number  | Number of records to return (max 300).                                                                                                                                        |
| offset               | false    | number  | Number of records to skip (max 10000).                                                                                                                                        |
| exclude_expired_bans | false    | boolean | When `true`, omits bans whose `expires` timestamp is in the past.                                                                                                             |
| user_id              | false    | string  | Server-side actor making the request.                                                                                                                                         |

**Response**

| key  | type  | description                                                   |
| ---- | ----- | ------------------------------------------------------------- |
| bans | array | List of bans. Each entry contains the fields described below. |

Each entry in `bans`:

| key        | type   | description                                                                |
| ---------- | ------ | -------------------------------------------------------------------------- |
| user       | object | The banned user.                                                           |
| banned_by  | object | The moderator who applied the ban (the answer to "who banned this user?"). |
| reason     | string | Reason supplied when the ban was created.                                  |
| expires    | string | Expiration timestamp for temporary bans. Absent for permanent bans.        |
| shadow     | bool   | `true` for shadow bans.                                                    |
| channel    | object | Present for channel-scoped bans; contains the channel CID and metadata.    |
| created_at | string | When the ban was applied.                                                  |

---

## Block

Blocking only takes effect inside Stream Chat, Feeds, and Video, and it is not a moderation method. Call `blockUsers` on the common client (`client.blockUsers` in Node, `client.block_users` in Python, `client.common.block_users` in Ruby, `client.BlockUsers` in Go, `client.blockUsers` in Java and PHP). The body is `blocked_user_id` and `user_id`.

```js label="Node.js"
await client.blockUsers({
  blocked_user_id: "user_to_block",
  user_id: blockingUserId,
});
```

---

## Bypass Moderation

Enable or disable moderation bypass for a specific user, allowing them to skip content moderation checks. This is a server-side only operation intended for trusted users whose content should not be subject to automated moderation. Bypass applies to the user's Stream Chat and Feeds content and to [Check](https://getstream.io/moderation/docs/node/content-moderation/check/) calls for any entity type, where `entity_creator_id` is the user. See [Bypass Moderation](https://getstream.io/moderation/docs/node/guides/bypass-moderation/) for permission-based bypass in Stream Chat.

```js label="Node.js"
await client.moderation.bypass({
  target_user_id: "trusted_user_id",
  enabled: true,
});
```

**Request parameters**

| key            | required | type    | description                                  |
| -------------- | -------- | ------- | -------------------------------------------- |
| target_user_id | true     | string  | User ID to enable or disable bypass for.     |
| enabled        | true     | boolean | `true` to enable bypass, `false` to disable. |

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/content-moderation/flag-mute-ban/](https://getstream.io/moderation/docs/node/content-moderation/flag-mute-ban/).

---

# Review Queue

## Overview

The Review Queue is the central hub for moderators. It contains content flagged by automated moderation engines or reported by users. Moderators review items in the queue and take actions such as approve, delete, and ban. `submit_action` is how you apply a decision to an item; see [Actions](https://getstream.io/moderation/docs/node/content-moderation/actions/).

In the dashboard, the **Inbox** tab shows items waiting for review and the **Reviewed** tab shows items a moderator has already acted on.

## Query Review Queue

Use this endpoint to retrieve items from the review queue. It supports filtering by content type, review status, moderation category, and more. You can also sort results, paginate through them, and lock items to prevent multiple moderators from reviewing the same item simultaneously.

`POST /api/v2/moderation/review_queue`

`filter` is a map. Built-in keys:

`id`, `created_at`, `updated_at`, `reviewed_at`, `completed_at`, `archived_at`, `escalated_at`, `date_range`, `type`, `status`, `entity_type`, `entity_id`, `entity_creator_id`, `entity_creator_name`, `content_text`, `queue_type`, `language`, `teams`, `latest_moderator_action`, `user_report_reason`, `recommended_action`, `reviewed`, `appeal`, `appeal_status`, `appeal_id`, `flagged_user_id`, `has_image`, `has_video`, `has_text`, `has_audio`, `flags_count`, `severity`, `confidence_score`, `bounce_count`, `category`, `label`, `reporter_type`, `reporter_id`, `config_key`, `ai_text_severity`, `channel_cid`, `channel_id`, `escalated`, `escalated_by`, `escalation_priority`, `escalation_reason`

Any other key is matched against `moderation_payload.custom`. `filter_config.filterable_custom_keys` lists the custom keys the app exposes as chips.

`content_text` is special: `$q` is a keyword search (terms ANDed, no adjacency). `$eq` and `$in` match the text exactly and are unindexed, so scope them with `date_range`.

Sort is allowed on `created_at` only. The response field is `items`. Pass `next` back to load the following page.

To review only flagged content and skip items the engines already removed, filter on `recommended_action`:

```js
const response = await client.moderation.queryReviewQueue({
  filter: { recommended_action: "flag", reviewed: false },
  sort: [{ field: "created_at", direction: -1 }],
});
```

In the dashboard, set the **Action** filter to `flag` and bookmark the URL.

```js label="Node.js"
const response = await client.moderation.queryReviewQueue({
  filter: {
    entity_type: "stream:chat:v1:message",
    reviewed: false,
  },
  sort: [{ field: "created_at", direction: -1 }],
  limit: 20,
});
```

### Filter Parameters

| Key                | Type     | Description                                                                                                             |
| ------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| id                 | string   | Filter by specific review queue item ID.                                                                                |
| created_at         | datetime | Filter by creation date.                                                                                                |
| updated_at         | datetime | Filter by last update date.                                                                                             |
| status             | string   | Review queue item status: `complete`, `partial`, or `flagged`.                                                          |
| entity_type        | string   | Filter by entity type (e.g., `stream:chat:v1:message`, `stream:user`, `stream:feeds:v2:activity`).                      |
| entity_id          | string   | Filter by entity ID.                                                                                                    |
| entity_creator_id  | string   | Filter by the user who created the content.                                                                             |
| reviewed           | boolean  | Filter by review status. `false` for unreviewed items.                                                                  |
| has_text           | boolean  | Filter items containing flagged text.                                                                                   |
| has_image          | boolean  | Filter items containing flagged images.                                                                                 |
| has_video          | boolean  | Filter items containing flagged video.                                                                                  |
| category           | string   | Filter by moderation engine: `ai_text`, `ai_image`, `automod_toxicity`, `automod_platform_circumvention`, `block_list`. |
| label              | string   | Filter by classification label, such as `SPAM` or `HATRED`.                                                             |
| recommended_action | string   | `keep`, `flag`, `remove`, `shadow`, `bounce`, `bounce_flag`, `bounce_remove`, `mask`, or `mask_flag`.                   |
| reporter_type      | string   | Who flagged the item: `moderator`, `user`, `automod`, or `serverside`.                                                  |
| reporter_id        | string   | Filter by specific reporter user ID.                                                                                    |
| date_range         | string   | Filter by date range. Format: `"2026-01-01T00:00:00_2026-12-31T00:00:00"`.                                              |
| appeal             | boolean  | Filter items that have (`true`) or don't have (`false`) an appeal.                                                      |
| appeal_status      | string   | Filter by appeal status: `submitted`, `accepted`, `rejected`.                                                           |
| user_report_reason | string   | Filter items flagged by users with a given reason.                                                                      |

### Request Parameters

| Key           | Required | Type    | Description                                                                                     |
| ------------- | -------- | ------- | ----------------------------------------------------------------------------------------------- |
| filter        | false    | object  | Filter conditions (see above).                                                                  |
| sort          | false    | array   | Sort parameters. Supported fields: `id`, `created_at`, `updated_at`.                            |
| limit         | false    | number  | Maximum items to return (default 20).                                                           |
| next          | false    | string  | Cursor for pagination.                                                                          |
| lock_items    | false    | boolean | When true, locks returned items to prevent other moderators from reviewing them simultaneously. |
| lock_count    | false    | number  | Number of items to lock (1-25). Only used with `lock_items`.                                    |
| lock_duration | false    | number  | Lock duration in seconds.                                                                       |
| stats_only    | false    | boolean | When true, returns only queue statistics without items.                                         |

### Response

| Key   | Type   | Description                                |
| ----- | ------ | ------------------------------------------ |
| items | array  | List of review queue items.                |
| next  | string | Next cursor for pagination.                |
| stats | object | Queue statistics (counts by content type). |

## Get Review Queue Item

Retrieve a specific review queue item by its ID. This returns the full item details including the entity content, moderation flags, and any actions already taken.

`GET /api/v2/moderation/review_queue/{id}`

```js label="Node.js"
const response = await client.moderation.getReviewQueueItem({ id: "item_id" });
```

### Request Parameters

| Key | Required | Type   | Description               |
| --- | -------- | ------ | ------------------------- |
| id  | true     | string | The review queue item ID. |

### Response

| Key  | Type   | Description                              |
| ---- | ------ | ---------------------------------------- |
| item | object | The review queue item with full details. |

## Moderator feedback

`POST /api/v2/moderation/submit_moderation_feedback` records that a classification was wrong. It does not change the item. `message`, `published_at`, and `reference` are required.

```js
await client.moderation.submitModerationFeedback({
  message: "the moderated text",
  published_at: "2026-10-20T13:13:38Z",
  reference: "provider-reference",
  current_labels: ["HATRED"],
  current_recommended_action: "remove",
  expected_labels: ["INSULT"],
  expected_recommended_action: "flag",
});
```

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/content-moderation/review-queue/](https://getstream.io/moderation/docs/node/content-moderation/review-queue/).

---

# Custom Views

## Overview

A custom view is a saved set of [review queue](https://getstream.io/moderation/docs/node/content-moderation/review-queue/) filters and sort order, stored server-side under a name. Instead of re-applying the same filters at the start of every shift, a moderator opens the view and lands on exactly the slice of the queue they own.

Views come in two kinds:

| Type              | Wire value          | Dashboard label         | Who can see it                                                       |
| ----------------- | ------------------- | ----------------------- | -------------------------------------------------------------------- |
| Personal view     | `personal_view`     | Personal (only you)     | Only the moderator who created it, plus users who can manage queues. |
| Operational queue | `operational_queue` | Shared (all moderators) | Every moderator in the app.                                          |

Personal views serve one moderator's own workflow. A moderator who owns image review keeps a view filtered to `has_image: true` with `category: ai_image`, while someone working appeals keeps one on `appeal_status: submitted`. Neither has to rebuild those filters at the start of a shift.

Operational queues serve team structure. A Trust & Safety lead defines "User-reported harassment" (`reporter_type: user`, `label: harassment`) and "Automod removals to spot-check" (`reporter_type: automod`, `recommended_action: remove`) once, and the whole team works out of the same two surfaces instead of each moderator filtering by hand.

>
> **Info:** Custom views require moderation v2 to be enabled on your app. The endpoints below are the same ones the Stream dashboard uses.
>

## Managing Views in the Dashboard

Most teams manage saved views in the dashboard. Open the [Stream Dashboard](https://getstream.io/signin/?product=moderation), go to **Moderation > Content Queue**, apply the filters you want, then save them as a view.

The save dialog asks for a name and a visibility: **Personal (only you)** or **Shared (all moderators)**. The shared option is only selectable for users whose role can manage operational queues.

Saved views appear in the sidebar with an item count next to each one.

## Create a View

Creating a view stores the filters, sort, name, and description. The `type` field decides whether the view is private to the caller or shared with the team.

`POST /api/v2/moderation/queues`

```js label="Node.js"
const response = await client.moderation.createQueue({
  name: "Flagged images",
  type: "personal_view",
  description: "Unreviewed image content flagged by the AI image engine",
  user_id: "moderator-1",
  filters: {
    entity_type: "stream:chat:v1:message",
    has_image: true,
    category: "ai_image",
  },
  sort: [{ field: "created_at", direction: -1 }],
});
```

### Request Parameters

| Key         | Required | Type   | Description                                                                                         |
| ----------- | -------- | ------ | --------------------------------------------------------------------------------------------------- |
| name        | true     | string | Display name for the view. Max 255 characters.                                                      |
| type        | true     | string | `personal_view` or `operational_queue`.                                                             |
| description | false    | string | Free-text description shown alongside the view. Max 512 characters.                                 |
| filters     | false    | object | Review queue filter conditions. Accepts the same keys as the `filter` object on Query Review Queue. |
| sort        | false    | array  | Sort parameters. Supported fields: `id`, `created_at`, `updated_at`.                                |
| user_id     | false    | string | The acting moderator. Required on server-side requests, ignored on client-side requests.            |

### Response

| Key   | Type   | Description                                     |
| ----- | ------ | ----------------------------------------------- |
| queue | object | The created view, including its generated `id`. |

## List Views

Returns every view visible to the calling moderator: their own personal views, plus all operational queues. Users whose role can manage operational queues additionally see other moderators' personal views, so views left behind by a departed moderator stay manageable.

`GET /api/v2/moderation/queues`

```js label="Node.js"
const response = await client.moderation.listQueues({ user_id: "moderator-1" });
```

### Request Parameters

| Key     | Required | Type   | Description                                                                          |
| ------- | -------- | ------ | ------------------------------------------------------------------------------------ |
| user_id | false    | string | The acting moderator, passed as a query parameter. Required on server-side requests. |

### Response

| Key    | Type  | Description                                                         |
| ------ | ----- | ------------------------------------------------------------------- |
| queues | array | Views visible to the calling moderator, each with its `item_count`. |

## Get a View

`GET /api/v2/moderation/queues/{id}`

```js label="Node.js"
const response = await client.moderation.getQueue({
  id: "queue-id",
  user_id: "moderator-1",
});
```

### Request Parameters

| Key     | Required | Type   | Description                                        |
| ------- | -------- | ------ | -------------------------------------------------- |
| id      | true     | string | The view ID, in the path.                          |
| user_id | false    | string | The acting moderator, passed as a query parameter. |

## Update a View

Updates are partial: omitted fields are left unchanged. The `type` field cannot be changed after creation. To move a personal view to a shared queue, create a new operational queue with the same filters and delete the old one.

`PATCH /api/v2/moderation/queues/{id}`

```js label="Node.js"
const response = await client.moderation.updateQueue({
  id: "queue-id",
  name: "Flagged images (EU)",
  user_id: "moderator-1",
  filters: {
    entity_type: "stream:chat:v1:message",
    has_image: true,
    category: "ai_image",
    label: "nudity",
  },
});
```

### Request Parameters

| Key         | Required | Type   | Description                                                        |
| ----------- | -------- | ------ | ------------------------------------------------------------------ |
| id          | true     | string | The view ID, in the path.                                          |
| name        | false    | string | New display name. Max 255 characters.                              |
| description | false    | string | New description. Max 512 characters.                               |
| filters     | false    | object | Replaces the stored filters entirely. This is not a per-key merge. |
| sort        | false    | array  | Replaces the stored sort order entirely.                           |
| user_id     | false    | string | The acting moderator. Required on server-side requests.            |

A personal view can only be updated by the moderator who created it, or by a user whose role can manage operational queues.

## Delete a View

Deleting a view is a soft delete: the view stops appearing in listings. Review queue items are never touched, because a view is only a saved filter over them.

Note that delete is a `POST`, not an HTTP `DELETE`.

`POST /api/v2/moderation/queues/{id}/delete`

```js label="Node.js"
const response = await client.moderation.deleteQueue({
  id: "queue-id",
  user_id: "moderator-1",
});
```

### Request Parameters

| Key     | Required | Type   | Description                                             |
| ------- | -------- | ------ | ------------------------------------------------------- |
| id      | true     | string | The view ID, in the path.                               |
| user_id | false    | string | The acting moderator. Required on server-side requests. |

As with updates, a personal view can only be deleted by its creator or by a user who can manage operational queues.

## Filters

The `filters` object accepts the same keys as the `filter` object on [Query Review Queue](https://getstream.io/moderation/docs/node/content-moderation/review-queue/), including `entity_type`, `entity_creator_id`, `category`, `label`, `recommended_action`, `reporter_type`, `has_image`, and `appeal_status`. See that page for the full list.

Note the field name is `filters` here, plural, while Query Review Queue takes a singular `filter`.

Three keys are dropped when a view is saved, even if you send them:

| Key           | Why it is dropped                                                                                  |
| ------------- | -------------------------------------------------------------------------------------------------- |
| `reviewed`    | Controlled at read time by the Inbox and Reviewed tabs, so it has no meaning as stored state.      |
| `archived_at` | Also a read-time toggle, for the same reason.                                                      |
| `date_range`  | A saved absolute date range goes stale immediately. Pick the range when you open the view instead. |

This is why a view saved from the **Reviewed** tab still opens on **Inbox**. The tab is not part of what gets stored.

## Item Counts

Each view carries an `item_count`. Counts are computed by a background task and served from cache, so a freshly created view returns a count computed inline on first read, while an existing view's count can lag behind the live queue by a short interval.

Treat `item_count` as an indicator of queue depth, not as a precise number to reconcile against.

## Limits and Permissions

| Constraint                            | Value                                                                                                |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Views per app                         | 10 by default, counting personal views and operational queues together. Contact support to raise it. |
| Create or read a personal view        | Requires the `QueryModerationReviewQueue` permission.                                                |
| Create, update, delete a shared queue | Requires the `ManageOperationalQueues` permission.                                                   |

Creating a view past the per-app cap returns a `400` naming the limit. Attempting to modify someone else's personal view without permission to manage queues returns a `403`.

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/content-moderation/custom-views/](https://getstream.io/moderation/docs/node/content-moderation/custom-views/).

---

# Actions

## Submit Action

`submit_action` applies a moderator's decision to a review queue item: delete content, ban a user, mark the item reviewed, restore content, and more.

Actions also run without a moderator. Each policy rule sets the action an engine applies when content matches, such as `flag`, `remove`, `bounce`, or `mask`. See [Automatic actions](#automatic-actions).

`POST /api/v2/moderation/submit_action`

```js label="Node.js"
await client.moderation.submitAction({
  action_type: "mark_reviewed",
  item_id: "review_queue_item_id",
  user_id: moderatorId,
});
```

### Request Parameters

| Key                | Required | Type   | Description                                                                                   |
| ------------------ | -------- | ------ | --------------------------------------------------------------------------------------------- |
| action_type        | true     | string | The action to take. See supported action types below.                                         |
| item_id            | false    | string | Review queue item ID. Required for most actions.                                              |
| user_id            | false    | string | User ID of the moderator performing the action.                                               |
| ban                | false    | object | Ban-specific parameters (used with `ban` action type).                                        |
| unban              | false    | object | Unban-specific parameters (used with `unban` action type).                                    |
| delete_message     | false    | object | Delete message parameters.                                                                    |
| delete_activity    | false    | object | Delete activity parameters.                                                                   |
| delete_poll        | false    | object | Delete poll parameters: `reason`.                                                             |
| delete_poll_option | false    | object | Delete poll option parameters: `reason`, `option_id`.                                         |
| delete_poll_answer | false    | object | Delete poll answer parameters: `reason`.                                                      |
| restore            | false    | object | Restore parameters (used with `restore` action type).                                         |
| unblock            | false    | object | Unblock parameters. Deprecated. Use `restore`.                                                |
| custom             | false    | object | Custom action parameters (used with `custom` action type).                                    |
| reject_appeal      | false    | object | Reject appeal parameters.                                                                     |
| appeal_id          | false    | string | Appeal ID (for appeal-related actions).                                                       |
| decision_reason    | false    | string | Not a top-level field. Set it inside `restore`, `unban`, `mark_reviewed`, or `reject_appeal`. |

### Response

| Key  | Type   | Description                    |
| ---- | ------ | ------------------------------ |
| item | object | The updated review queue item. |

### Supported Action Types

Some actions only work on content stored in Stream Chat, Stream Feeds, or Stream Video. Actions marked **Any** also work for your own (standalone) entity types.

| Action Type          | Works with         | Description                                                                                                                                       |
| -------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| mark_reviewed        | Any                | Mark the item as reviewed without taking further action (content is safe).                                                                        |
| flag                 | Any                | Flag an entity from the review action. Custom entity types need server-side auth.                                                                 |
| ban                  | Any                | Ban the content creator. Supports shadow, IP, and temporary bans. Channel bans are Stream Chat only.                                              |
| unban                | Any                | Unban a previously banned user. Also accepts appeals automatically.                                                                               |
| bypass               | Any                | Turn moderation bypass on or off for the user.                                                                                                    |
| escalate             | Any                | Escalate the item for higher-level review.                                                                                                        |
| de_escalate          | Any                | De-escalate a previously escalated item.                                                                                                          |
| reject_appeal        | Any                | Reject a user's appeal against a moderation decision.                                                                                             |
| custom               | Any                | Trigger a custom action (sends a webhook to your server). See [Custom Action](#custom-action).                                                    |
| delete_message       | Stream Chat        | Delete a flagged chat message.                                                                                                                    |
| delete_user_messages | Stream Chat        | Delete messages created by the user.                                                                                                              |
| delete_poll          | Stream polls       | Delete the poll from the review item filed by its creator. See [Moderate poll text](https://getstream.io/moderation/docs/node/content-moderation/check/#polls). |
| delete_poll_option   | Stream polls       | Delete one option of a poll and keep the rest. The option must still hold the text that was checked.                                              |
| delete_poll_answer   | Stream Chat        | Delete a free-text poll answer on a chat message. Refused when that text has changed, or the poll is closed.                                      |
| delete_activity      | Stream Feeds       | Delete a flagged activity.                                                                                                                        |
| delete_comment       | Stream Feeds       | Delete a flagged comment.                                                                                                                         |
| delete_reaction      | Stream Feeds       | Delete a flagged reaction (Feeds v2).                                                                                                             |
| restore              | Stream Chat, Feeds | Restore previously deleted content. Also accepts appeals automatically.                                                                           |
| unblock              | Stream Chat, Feeds | Deprecated. Use `restore`.                                                                                                                        |
| shadow_block         | Stream Chat, Feeds | Shadow-block content (hidden from others but visible to the creator).                                                                             |
| unmask               | Stream Chat, Feeds | Clear a mask applied to the content.                                                                                                              |
| delete_user          | Stream users       | Delete the user who created the content.                                                                                                          |
| kick_user            | Stream Video       | Remove a user from a call.                                                                                                                        |
| end_call             | Stream Video       | End an active video call.                                                                                                                         |

### Delete Message

Stream Chat only. Delete a flagged chat message from the review queue.

```js label="Node.js"
await client.moderation.submitAction({
  action_type: "delete_message",
  item_id: "review_queue_item_id",
  user_id: moderatorId,
});
```

### Ban User

Ban the creator of flagged content. `timeout` is minutes. A channel ban (Stream Chat only) sets `channel_cid` and `channel_ban_only: true`. `delete_messages` is `soft`, `pruning`, or `hard`. Rule-builder bans are different: `ban_options.duration` is seconds.

A ban without `channel_cid` works for any user, including users of your own app. Stream records it on the user (`banned`, `ban_expires`) and sends a `user.banned` webhook. Stream Chat and Feeds enforce it for you. In your own app, read the ban state or handle the webhook and block the user yourself.

```js label="Node.js"
await client.moderation.submitAction({
  action_type: "ban",
  item_id: "review_queue_item_id",
  ban: {
    reason: "Repeated harassment",
    timeout: 1440,
    channel_cid: "messaging:general",
    channel_ban_only: true,
  },
  user_id: moderatorId,
});
```

### Ban from Future Channels

Stream Chat only. Set `ban_from_future_channels: true` on a `ban` action to also auto-apply the ban to any new channels created later by the same user who created the channel the target is being banned from. This is useful when a community owner repeatedly creates new channels and you want a known offender kept out without re-banning them every time. The ban is applied automatically as the channel creator opens additional channels and remains in effect until removed via an `unban` with `remove_future_channels_ban: true`.

```js label="Node.js"
await client.moderation.submitAction({
  action_type: "ban",
  item_id: "review_queue_item_id",
  ban: {
    reason: "Repeated harassment",
    ban_from_future_channels: true,
  },
  user_id: moderatorId,
});
```

To remove a previously applied future-channels ban, submit an `unban` action with `remove_future_channels_ban: true`:

```js label="Node.js"
await client.moderation.submitAction({
  action_type: "unban",
  item_id: "review_queue_item_id",
  unban: {
    remove_future_channels_ban: true,
  },
  user_id: moderatorId,
});
```

### Restore Content

Restore previously deleted content. This is typically used when content was incorrectly removed. If the item has an associated appeal, the appeal is automatically accepted.

Restore works for Stream Chat messages and Stream Feeds activities, comments, and reactions. Stream doesn't store standalone content, so it can't restore it.

```js label="Node.js"
await client.moderation.submitAction({
  action_type: "restore",
  item_id: "review_queue_item_id",
  restore: { decision_reason: "Content was incorrectly flagged" },
  user_id: moderatorId,
});
```

### Custom Action

Trigger a custom action that sends a `moderation.custom_action` webhook to your server. Use this to integrate your own moderation workflows. The event carries `action_id` (the `custom.id` you sent), `action_options`, and the `review_queue_item`. For Stream Chat messages it also includes `message`.

```js label="Node.js"
await client.moderation.submitAction({
  action_type: "custom",
  item_id: "review_queue_item_id",
  custom: {
    id: "notify_user",
    options: { notification: "Your content has been reviewed" },
  },
  user_id: moderatorId,
});
```

### Remove standalone content

Stream doesn't store your own content (a listing title, a profile bio), so the delete actions can't remove it. They only accept Stream Chat, Feeds, and Video entity types. To remove standalone content from the review queue:

1. Send a `custom` action, for example with `id: "delete_listing"`.
2. Handle the `moderation.custom_action` webhook and delete the content in your own system, using `review_queue_item.entity_id`.
3. Send `mark_reviewed` for the item so it leaves the queue.

## Customize review queue buttons

The action buttons in the dashboard review queue are `action_config` records, one per button and entity type. Create or update one with `POST /api/v2/moderation/action_config`. List them with `GET /api/v2/moderation/action_config`, delete one with `DELETE /api/v2/moderation/action_config/{id}`, or send a batch with `POST /api/v2/moderation/action_config/bulk` and `POST /api/v2/moderation/action_config/bulk_delete`.

```js
await client.moderation.upsertActionConfig({
  entity_type: "stream:chat:v1:message",
  order: 1,
  action: "delete_message",
  description: "Delete message",
});
```

`entity_type` and `action` are required. `description` is the button label. `order` is 0-100. Omit `id` to create a button; send `id` to update one. A button can use the `custom` action, which is how you add a button for your own entity types (for example, a "Delete listing" button that fires `moderation.custom_action`).

## Automatic actions

Each rule in a [policy](https://getstream.io/moderation/docs/node/configuration/policies/) sets the action an engine applies when content matches. These are not `submit_action` types. They run at moderation time, before a moderator sees anything.

| Action          | What happens                                                                                                      | Review queue |
| --------------- | ----------------------------------------------------------------------------------------------------------------- | ------------ |
| `keep`          | Nothing. The content is published.                                                                                | No           |
| `flag`          | The content is published and sent to moderators.                                                                  | Yes          |
| `remove`        | The content is blocked. Other users never see it.                                                                 | Yes          |
| `shadow`        | The content is stored but shown only to its author, who doesn't know it was hidden.                               | Yes          |
| `bounce`        | The content is returned to the sender to edit and is not stored. Sending the same content again bounces it again. | No           |
| `bounce_flag`   | Like `bounce`, but if the sender sends the same content again, it is published and flagged.                       | On resend    |
| `bounce_remove` | Like `bounce`, but if the sender sends the same content again, it is removed.                                     | On resend    |
| `mask`          | Matched words are replaced with asterisks and the content is published. Blocklist and regex rules only.           | No           |
| `mask_flag`     | Like `mask`, and the content is also flagged so moderators can see the original.                                  | Yes          |

Stream Chat and Feeds apply these actions for you. With the [Check API](https://getstream.io/moderation/docs/node/content-moderation/check/), Stream returns the action as `recommended_action` and your app applies it.

### Bounce

Bounce gives the sender a chance to fix a message instead of sending it to moderators. A bounced message is returned with an explanation, the sender edits it, and the edited message is moderated again. Bounced messages are **not stored** and don't appear in the dashboard.

Use `bounce_flag` for borderline content: the sender can still send it unchanged, and a moderator reviews it. Use `bounce_remove` for content that should never be published.

Set a bounce action on AI Text, blocklist, or regex rules in the [dashboard](https://getstream.io/signin/?product=moderation) **Policies** page.

The Stream Chat UI SDKs show a warning next to a bounced message. Tapping it lets the sender edit, send anyway (if permitted), or delete the message. These SDK versions handle bounced messages out of the box:

- **React Chat SDK** (≥ [v12.6.0](https://github.com/GetStream/stream-chat-react/releases/tag/v12.6.0))
- **React Native Chat SDK** (≥ [v5.43.0](https://github.com/GetStream/stream-chat-react-native/releases/tag/v5.43.0))
- **iOS Chat SDK** (≥ [4.41.0](https://github.com/GetStream/stream-chat-swift/releases/tag/4.41.0))
- **Android Chat SDK** (≥ [v5.5.0](https://github.com/GetStream/stream-chat-android/releases/tag/v5.5.0))
- **Flutter Chat SDK** (≥ [9.7.0](https://github.com/GetStream/stream-chat-flutter/releases/tag/9.7.0))

Without a UI SDK, read the `moderation` object on the send message response. When `action` is `bounce`, show `original_text` back to the sender so they can edit it:

```json {7-10}
{
  "message": {
    "type": "error",
    "text": "The message original text",
    "user_id": "user_id",
    // other message data
    "moderation": {
      "action": "bounce",
      "original_text": "The message original text"
    }
  }
}
```

### Mask

Mask hides sensitive text, such as phone numbers, while the content stays published. With `mask_flag`, readers see the masked text while moderators review the original.

For example, add a regex blocklist that matches phone numbers (`(?m)(\+?\d{1,2}\s?)?(\(?\d{3}\)?[\s.-]?)?\d{3}[\s.-]?\d{4}`) and set its action to `mask_flag`:

| Original message                    | Stored and shown to everyone        |
| ----------------------------------- | ----------------------------------- |
| `Text me at 555-123-4567 after 6pm` | `Text me at ************ after 6pm` |

The moderator sees the original message in the review queue and can remove it, or use **Unmask** to restore the original text.

Mask works for Stream Chat messages and Stream Feeds v3 activities and comments. It is not supported for Feeds v2. Add the `mask_flag` rule to your policy's `block_list_config`:

```js label="JavaScript"
await client.moderation.upsertConfig({
  key: "chat",
  block_list_config: {
    enabled: true,
    rules: [{ name: blocklistName, action: "mask_flag", team: "" }],
  },
});
```

For Feeds, use the same rule on the `feeds` policy (or `feeds:{group_id}` / `feeds:{group_id}:{feed_id}`). When an activity or comment matches the blocklist:

- The stored `text` is replaced with the masked version, so every reader, including the author, sees the censored text.
- The original text is returned in `moderation.original_text` in the response of the add or update call. Moderators can always see the original text in the review queue.
- With `mask_flag`, the item is flagged (`moderation_action: "flag"` on the activity, `moderation.action: "flag"` on the comment) and shows up in the review queue.

Moderators can use the **Unmask** action in the review queue to restore the original text.

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/content-moderation/actions/](https://getstream.io/moderation/docs/node/content-moderation/actions/).

---

# Appeals

## Overview

The Appeal API allows users to submit appeals against moderation decisions and enables moderators to review and decide on those appeals. Appeals can be submitted against review queue items (such as deleted messages, activities, or reactions) or against user bans (both global and channel-specific bans).

## Submit Appeal

This endpoint allows users to submit an appeal against a moderation decision. You can appeal against:

- **Deleted Content**
- **Blocked content**
- **User Bans**: Appeals against user bans (both global bans and channel-specific bans)

For each appeal, there must be an associated review queue item or a user ban. When appealing against content, only the user who created the content can submit an appeal. When appealing against a user ban, only the banned user can submit an appeal.

```js label="Node.js"
await client.moderation.appeal({
  appeal_reason: "I believe my message was wrongfully blocked",
  entity_id: contentEntityId,
  entity_type: "stream:chat:v1:message",
  attachments: ["imageurl"],
  user_id: userId,
});
```

### Request Parameters

| key           | required | type   | description                                                                                                                                                                            |
| ------------- | -------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| entity_id     | true     | string | Unique identifier of the entity being appealed. For user bans, this should be the user ID. For content, this should be the message/activity/reaction ID.                               |
| entity_type   | true     | string | Type of entity being appealed. Examples: `stream:chat:v1:message`, `stream:feeds:v2:activity`, `stream:feeds:v2:reaction`, `stream:user` (for user bans), or your own type (`listing`) |
| channel_cid   | false    | string | Only used when `entity_type` is `stream:user`. Identifies which ban is being appealed: omit to appeal the global ban, or set it to appeal that channel's ban.                          |
| appeal_reason | true     | string | Explanation for why the content is being appealed. Required. Maximum 500 characters; longer reasons are rejected.                                                                      |
| attachments   | false    | array  | Array of attachment URLs (e.g., images) providing evidence for the appeal. Maximum 10 attachments.                                                                                     |

### Response

| key       | type   | description                                   |
| --------- | ------ | --------------------------------------------- |
| appeal_id | string | Unique identifier of the created appeal item. |

### Appeal Rules and Restrictions

#### Appeals Against Content

Users can appeal Stream Chat messages, Stream Feeds activities, reactions, and comments, and your own (standalone) entity types. Any content that has a review queue item can be appealed: send its `entity_type` and `entity_id`.

- Only the user who created the entity can appeal against actions taken on it
- You cannot appeal if the item is unreviewed and just flagged (unless the recommended action is "remove")
- You cannot appeal against shadow-banned content
- You cannot appeal if the content is not deleted (for reviewed Stream Chat and Feeds items). Standalone entity types have no such check, since Stream doesn't store that content
- You cannot appeal if an appeal already exists for the item

#### Appeals Against User Bans

- Only the banned user can appeal against their own ban
- Use `channel_cid` to identify which ban you're appealing: omit it to appeal the global ban, or set it to appeal a specific channel's ban. The specific ban named by `channel_cid` (or the global ban, if omitted) must currently be active.
  - If `channel_cid` is omitted and the user has no global ban but has exactly one active channel ban, that channel ban is resolved automatically (for clients that predate this parameter). If the user has active bans in more than one channel, `channel_cid` is required — the request is rejected as ambiguous otherwise.
- You cannot submit a new appeal if a submitted appeal already exists **for that same ban** — but a user can hold multiple simultaneous open appeals across different bans at once (e.g. the global ban and several channel bans), up to a maximum of **10 simultaneously open ban appeals per user**
- Once a ban appeal is decided (accepted or rejected), the same ban can be appealed again if the user is banned on it again later

### Example: Appeal Against User Ban

```js label="Node.js"
await client.moderation.appeal({
  appeal_reason: "Appeal to unban me",
  entity_id: userId,
  entity_type: "stream:user",
  attachments: ["imageurl"],
  user_id: userId,
});
```

### Example: Appeal Against a Channel-Specific Ban

To appeal a ban that only applies to one channel (rather than the global ban), set `channel_cid`:

```js label="Node.js"
await client.moderation.appeal({
  appeal_reason: "I was wrongly banned from this channel",
  entity_id: userId,
  entity_type: "stream:user",
  channel_cid: "messaging:general",
  user_id: userId,
});
```

A user banned both globally and in one or more channels can submit an independent appeal for each ban — the global ban and every channel ban are appealed and decided separately.

## Query Appeals

This endpoint allows you to query appeals with filters, sorting, and pagination. Client-side requests only return the signed-in user's own appeals, unless that user's role has the `ViewAppeals` permission. Use server-side requests for moderator tools that need to see all appeals.

```js label="Node.js"
await client.moderation.queryAppeals({
  filter: {
    id: { $eq: "appeal_id" },
  },
  sort: [{ field: "created_at", direction: -1 }],
  limit: 20,
});
```

### Request Parameters

| key    | required | type   | description                                   |
| ------ | -------- | ------ | --------------------------------------------- |
| filter | false    | object | Filter conditions for appeals (see below)     |
| sort   | false    | array  | Sorting parameters for appeals                |
| limit  | false    | number | Maximum number of appeals to return           |
| next   | false    | string | Cursor for pagination (from previous request) |

### Supported Filters

You can filter appeals by the following fields:

| field       | type     | description                                                  |
| ----------- | -------- | ------------------------------------------------------------ |
| id          | string   | Filter by specific appeal ID                                 |
| user_id     | string   | Filter by user ID who created the appeal                     |
| entity_type | string   | Filter by entity type (e.g., `stream:chat:v1:message`)       |
| entity_id   | string   | Filter by entity ID                                          |
| status      | string   | Filter by appeal status: `submitted`, `accepted`, `rejected` |
| created_at  | datetime | Filter by creation date                                      |
| updated_at  | datetime | Filter by last update date                                   |

### Response

| key   | type   | description                         |
| ----- | ------ | ----------------------------------- |
| items | array  | List of appeal items                |
| next  | string | Next cursor for pagination (if any) |

## Get Appeal

This endpoint allows you to retrieve a specific appeal item by its ID. When used from the client-side, users can only retrieve their own appeals.

```js label="Node.js"
await client.moderation.getAppeal({ id: "appeal_id" });
```

### Request Parameters

| key | required | type   | description                     |
| --- | -------- | ------ | ------------------------------- |
| id  | true     | string | Unique identifier of the appeal |

### Response

| key  | type   | description                   |
| ---- | ------ | ----------------------------- |
| item | object | Appeal item with full details |

The appeal item includes:

- `id`: Appeal ID
- `user`: User who created the appeal
- `entity_type`: Type of entity being appealed
- `entity_id`: ID of the entity being appealed
- `channel_cid`: For content appeals, the channel the entity belongs to (if applicable). For `stream:user` appeals, identifies which ban is being appealed — empty for the global ban.
- `appeal_reason`: Appeal Reason/explanation
- `status`: Appeal status (`submitted`, `accepted`, `rejected`)
- `decision_reason`: Reason provided by moderator (if decided)
- `attachments`: Array of attachment URLs
- `created_at`: When the appeal was created
- `updated_at`: When the appeal was last updated

## Resolve an appeal

The [Submit Action](https://getstream.io/moderation/docs/node/content-moderation/actions/#submit-action) endpoint can be used to accept or reject appeals when taking moderation actions. Most moderation actions automatically accept an appeal if one exists for the review queue item.

### Accepting Appeals

The following actions automatically accept an appeal if one exists:

- `unban`: Unbanning a user
- `mark_reviewed`: Marking an item as reviewed
- `restore`: Restoring deleted, blocked, or shadow-blocked content
- `unblock`: Deprecated. Use `restore`

When performing these actions, you can optionally provide a `decision_reason` to explain why the appeal was accepted:

```js label="Node.js"
// Approve appeal while unbanning user
await client.moderation.submitAction({
  action_type: "unban",
  appeal_id: "appeal_id",
  unban: {
    decision_reason: "I am unbanning a user",
    // channel_cid: "messaging:general", // optional: unban in this channel only
  },
  user_id: moderatorId,
});

// Approve appeal while restoring content
await client.moderation.submitAction({
  action_type: "restore",
  item_id: "item_id",
  restore: { decision_reason: "I am restoring content" },
  user_id: moderatorId,
});
```

### Rejecting Appeals

To reject an appeal, use the `reject_appeal` action type:

```js label="Node.js"
await client.moderation.submitAction({
  action_type: "reject_appeal",
  appeal_id: "appeal_id",
  reject_appeal: {
    decision_reason: "I am rejecting your appeal",
  },
  user_id: moderatorId,
});
```

### Request Parameters for Appeal Actions

| key             | required | type   | description                                                                                                            |
| --------------- | -------- | ------ | ---------------------------------------------------------------------------------------------------------------------- |
| action_type     | true     | string | Type of action: `unban`, `restore`, `mark_reviewed`, or `reject_appeal`. `unblock` is deprecated; use `restore`.       |
| item_id         | false    | string | Review queue item ID (required for most actions, except `reject_appeal` and `unban` without review queue item)         |
| appeal_id       | false    | string | Appeal ID (required for `reject_appeal`, optional for other actions - will be inferred from `item_id` if not provided) |
| decision_reason | false    | string | Not a top-level field. Set it inside `unban`, `restore`, `mark_reviewed`, or `reject_appeal`.                          |
| action_params   | false    | object | Action-specific parameters (e.g., `unban`, `restore`, `unblock`, `reject_appeal`)                                      |

### Appeal Status Values

Appeals can have the following statuses:

- `submitted`: The appeal has been submitted and is awaiting review
- `accepted`: The appeal has been accepted by a moderator
- `rejected`: The appeal has been rejected by a moderator

The `decided_by` field is automatically populated with the moderator's user ID when an appeal is accepted or rejected. This field is not shown to users but is tracked internally for audit purposes.

## Bulk action

`POST /api/v2/moderation/appeals/bulk_action` applies one action to many appeals. Send 1 to 100 `appeal_ids`. `action_type` is `unban`, `restore`, `mark_reviewed`, or `reject_appeal`. `unblock` is accepted and deprecated; use `restore`.

```js
await client.moderation.bulkActionAppeals({
  action_type: "restore",
  appeal_ids: ["appeal_1", "appeal_2"],
  restore: { decision_reason: "Restored after review" },
  user_id: moderatorId,
});
```

## Filter by Appeal in Query Review Queue

The [Query Review Queue](https://getstream.io/moderation/docs/node/content-moderation/review-queue/#query-review-queue) endpoint supports filtering by appeal-related fields. This allows you to:

- Filter review queue items that have appeals
- Filter by appeal status
- Filter by specific appeal ID

This is particularly useful for implementing moderation dashboards where you want to show items with pending appeals separately from other items.

### Appeal Filters in Query Review Queue

| filter        | type    | description                                                                 |
| ------------- | ------- | --------------------------------------------------------------------------- |
| appeal        | boolean | Filter items that have an appeal (`true`) or don't have an appeal (`false`) |
| appeal_status | string  | Filter items by appeal status: `submitted`, `accepted`, `rejected`          |
| appeal_id     | string  | Filter items by specific appeal ID                                          |

### Example: Query Review Queue Items with Appeals

```js label="Node.js"
// Query items with submitted appeals
await client.moderation.queryReviewQueue({
  filter: {
    appeal: true,
    appeal_status: "submitted",
  },
  sort: [{ field: "created_at", direction: -1 }],
  limit: 20,
});

// Query items with a specific appeal
await client.moderation.queryReviewQueue({
  filter: {
    appeal_id: { $eq: "appeal_id" },
  },
  sort: [{ field: "created_at", direction: -1 }],
  limit: 20,
});
```

Instead of moving review queue items from "Reviewed" to "Inbox" or vice versa, you can query review queue items with appeal status filters. This approach avoids potential problems that could arise from changing the status of review queue items and provides a more flexible way to organize your moderation workflow.

## Complete Workflow Example

Here's a complete example of the appeal workflow:

1. **User submits an appeal** against deleted content:

```jsx
const appealResponse = await client.moderation.appeal(
  {
    appealReason: "This message was deleted by mistake. Please restore it.",
    entityID: "message_id",
    entityType: "stream:chat:v1:message",
    attachments: [],
  },
  { user_id: userId },
);

console.log("Appeal ID:", appealResponse.appeal_id);
```

2. **Moderator queries appeals** to see pending appeals:

```jsx
const appeals = await client.moderation.queryAppeals({
  filter: {
    status: "submitted",
  },
  sort: [{ field: "created_at", direction: -1 }],
  limit: 50,
});
```

3. **Moderator reviews the appeal** and decides to accept it by restoring the content:

```jsx
await client.moderation.submitAction(
  {
    action_type: "restore",
    item_id: "review_queue_item_id",
    restore: {},
    decision_reason: "The content was deleted by mistake. Appeal accepted.",
  },
  { user_id: moderatorId },
);
```

4. **User queries their appeals** to see the decision:

```jsx
const myAppeals = await client.moderation.queryAppeals(
  {
    filter: {},
    sort: [{ field: "created_at", direction: -1 }],
    limit: 20,
  },
  { user_id: userId },
);
```

5. **User gets specific appeal details**:

```jsx
const appeal = await client.moderation.getAppeal(appealResponse.appeal_id, {
  user_id: userId,
});
console.log("Appeal status:", appeal.item.status);
console.log("Decision reason:", appeal.item.decision_reason);
```

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/content-moderation/appeals/](https://getstream.io/moderation/docs/node/content-moderation/appeals/).

---

# Logs & Analytics

Query moderation logs to audit who took which action. Flag counts use `entity_creator_id`. There is no export, analytics, or usage-stats endpoint. Use `queryReviewQueue` and `queryModerationLogs` instead.

## Query Moderation Logs

`POST /api/v2/moderation/logs`

Query moderation action logs with filtering, sorting, and pagination. Logs record every moderation action taken -- who did what, when, and on which content.

```js label="Node.js"
const response = await client.moderation.queryModerationLogs({
  filter: { type: "delete_message" },
  sort: [{ field: "created_at", direction: -1 }],
  limit: 50,
});
```

### Request Parameters

| Key    | Required | Type   | Description                              |
| ------ | -------- | ------ | ---------------------------------------- |
| filter | false    | object | Filter conditions for logs.              |
| sort   | false    | array  | Sort parameters (e.g., by `created_at`). |
| limit  | false    | number | Maximum number of logs to return.        |
| next   | false    | string | Cursor for pagination.                   |

### Response

| Key  | Type   | Description                                                                                             |
| ---- | ------ | ------------------------------------------------------------------------------------------------------- |
| logs | array  | List of moderation log entries. Each entry includes action type, actor, target, timestamp, and details. |
| next | string | Next cursor for pagination.                                                                             |

## Get Flag Count

`POST /api/v2/moderation/flag_count`

Get the number of moderation flags created against a specific user's content. Useful for building moderation dashboards and identifying repeat offenders.

```js label="Node.js"
const response = await client.moderation.getFlagCount({
  entity_creator_id: "user_123",
});
```

### Request Parameters

| Key         | Required | Type   | Description                       |
| ----------- | -------- | ------ | --------------------------------- |
| user_id     | true     | string | User ID to get flag count for.    |
| entity_type | false    | string | Optionally filter by entity type. |

### Response

| Key   | Type   | Description                                   |
| ----- | ------ | --------------------------------------------- |
| count | number | Total number of flags for the specified user. |

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/content-moderation/logs-and-analytics/](https://getstream.io/moderation/docs/node/content-moderation/logs-and-analytics/).

---

# Moderate any content

Stream's moderation APIs can be used to moderate custom content such as user profiles, avatars, and other content types. This guide shows you how to use Stream's moderation APIs to moderate custom content.

The overall process of moderating custom content is as follows:

1. Create a moderation policy
2. Submit content for moderation
3. Process the recommended action
4. Monitor results in the [Dashboard](https://getstream.io/signin/?product=moderation)
5. Receive notifications of dashboard actions

```mermaid
flowchart TD
    A[Create Moderation Policy] -->|Configure policy settings| B[Submit Content]
    B -->|Use Check API| C[Receive Recommendation]
    C -->|Analyze result| D{Take Action}
    D -->|Flag| E[Review Queue]
    D -->|Remove| F[Content removed]
    D -->|Shadow| G[Shown only to the author]
    E --> H[View in Dashboard]
    F --> H
    G --> H
    H -->|Actions taken| I[Webhook Notifications]

    style A fill:#e1f3ff
    style B fill:#e1f3ff
    style C fill:#e1f3ff
    style D fill:#ffe1e1
    style E fill:#f0e1ff
    style F fill:#f0e1ff
    style G fill:#f0e1ff
    style H fill:#e1ffe4
    style I fill:#fff3e1
```

Let's go through each step in detail.

## Create a moderation policy

A moderation policy is a set of rules that define how content should be moderated in your application.
See [Configuration](https://getstream.io/moderation/docs/node/configuration/policies/) for details on setting up moderation policies.

## Submit custom content to the moderation Check API

You can use the moderation Check API to submit custom content to the moderation engine and receive a recommended action.

```js label="Node.js"
const response = await client.moderation.check({
  entity_type: "entity_type",
  entity_id: "entity_id",
  entity_creator_id: "entity_creator_id",
  moderation_payload: {
    texts: ["this is bullshit", "f*ck you as***le"],
    images: ["example.com/test.jpg"],
  },
  config_key: "custom:my-content-platform-1",
});

console.log(response.recommended_action); // keep | flag | remove | shadow
```

In this example:

- `entity_type` is the type of the entity you are moderating. You can provide any generic identifier for the entity type e.g., `user:profile`, `user:avatar`, `user:cover_image`, etc.
- `entity_id` is the unique identifier for the entity you are moderating.
- `entity_creator_id` is the unique identifier for the creator of the entity you are moderating.
- `texts` is the array of texts you want to moderate.
- `images` is the array of images you want to moderate.
- `custom:my-content-platform-1` is the unique identifier for the moderation policy you created earlier.

## Query Flagged Content

You can use the moderation QueryReviewQueue API to query flagged content. This is useful if you want to review the flagged content in your app.

```js label="Node.js"
const response = await client.moderation.queryReviewQueue({
  filter: { entity_type: "entity_type" },
  sort: [{ field: "created_at", direction: -1 }],
  next: null,
});
```

## Monitoring Moderated Content

You can monitor flagged or removed content from the dashboard. There is one content queue. Filter it by entity type when you want users, text, or media.

The available actions are:

- **Mark Reviewed**: This action indicates that you have reviewed the content and determined it doesn't require further action. It helps keep track of which contents have been addressed by moderators.
- **Delete**: We provide Delete action button out-of-the-box, but actual logic to delete the content needs to be handled by your backend via webhook.

>
> **Tip:** We also provide a way to support more custom actions for your application on Stream Dashboard. Please get in touch with us at [Stream Support Team](https://getstream.io/contact/support/) if you need this feature.
>

## Webhook Integration

You can receive webhook notifications for actions taken on the content from the dashboard. Please refer to the [Webhook Integration](https://getstream.io/moderation/docs/node/content-moderation/webhooks/) guide for more details. E.g., if moderator presses delete button for specific content on the dashboard, you will receive a webhook notification with the action details. And accordingly you can delete the content from your platform.

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/integrations/custom-content/](https://getstream.io/moderation/docs/node/integrations/custom-content/).

---

# Live video and audio

Live video and audio moderation watches a livestream or a call as it happens and acts when a rule matches. The rules read video keyframes and audio transcriptions (closed captions).

## How it works

Live video and audio rules differ from user and content rules:

1. **Real-Time Analysis**: Video keyframes and audio transcriptions are analyzed in real-time during active sessions (calls, livestreams, etc.)
2. **Consecutive Violations**: Rules track consecutive violations within a single session (not across time windows)
3. **Escalating Actions**: Actions escalate based on violation number (1st violation, 2nd violation, etc.)
4. **Immediate Execution**: Actions are executed immediately when conditions are met, affecting the live session

## Configure via API

Create a live video rule with the server-side SDKs:

```js label="Node.js"
await client.moderation.upsertModerationRule({
  name: "Inappropriate Content Detection",
  description:
    "Detects and responds to inappropriate content in live video and audio",
  rule_type: "call",
  enabled: true,
  cooldown_period: "5m",
  logic: "OR",
  conditions: [
    {
      type: "keyframe_rule",
      keyframe_rule_params: {
        harm_labels: ["NUDITY", "VIOLENCE"],
        threshold: 3,
        time_window: "1m",
        min_confidence: 0.75,
      },
    },
    {
      type: "closed_caption_rule",
      closed_caption_rule_params: {
        threshold: 2,
        time_window: "1m",
        llm_harm_labels: {
          HATE_SPEECH:
            "Content that promotes hatred, discrimination, or violence",
        },
      },
    },
  ],
  action_sequences: [
    {
      violation_number: 1,
      actions: ["mute_video", "call_warning"],
      call_options: { warning_text: "Please keep your video appropriate" },
    },
    { violation_number: 2, actions: ["mute_audio", "mute_video"] },
    { violation_number: 3, actions: ["kick_user"] },
  ],
});
```

## Video Keyframe Condition

Keyframe rules analyze video frames captured during live sessions to detect visual content violations.

**Parameters:**

- `harm_labels`: Array of harm labels to detect (e.g., `["NUDITY", "VIOLENCE", "WEAPONS"]`)
- `threshold`: Number of consecutive violations required before triggering (e.g., `3`)
- `min_confidence`: Optional minimum confidence, from 0 to 1. `0.75` means 75%. Omit it to use the image-engine default of 50 on the 0–100 scale.

**Example:**

```json
{
  "type": "keyframe_rule",
  "keyframe_rule_params": {
    "harm_labels": ["NUDITY", "VIOLENCE"],
    "threshold": 3,
    "min_confidence": 0.75
  }
}
```

This rule triggers when a user's video contains 3 consecutive keyframes with nudity or violence detected, with a minimum confidence score of 75%. A keyframe that does not match resets that count to 0.

## Closed Caption Condition

Closed caption rules analyze audio transcriptions from live sessions to detect spoken content violations.

**LLM Harm Labels (Configurable):**

When [LLM configurability](https://getstream.io/moderation/docs/node/engines/ai-llm-text/) is enabled, you can use detailed harm labels with custom descriptions:

**Example with LLM Labels:**

```json
{
  "type": "closed_caption_rule",
  "closed_caption_rule_params": {
    "threshold": 2,
    "llm_harm_labels": {
      "HATE_SPEECH": "Content that promotes hatred, discrimination, or violence against groups",
      "THREAT": "Content containing threats of violence or harm against individuals or groups"
    }
  }
}
```

**NLP Harm Labels:**

With the [AI Text (NLP)](https://getstream.io/moderation/docs/node/engines/ai-text/) engine, you can use simple string arrays:
`["HATE_SPEECH", "THREAT", "SPAM"]`

**Example with NLP Labels:**

```json
{
  "type": "closed_caption_rule",
  "closed_caption_rule_params": {
    "threshold": 2,
    "harm_labels": ["HATE_SPEECH", "THREAT"]
  }
}
```

This rule triggers when a user's speech contains 2 consecutive violations of hate speech or threats. A caption that does not match resets that count to 0.

## Action Sequences (Escalation)

Call rules use **action sequences** to define escalating responses based on violation number. Unlike user and content rules that use a single action, call rules can have different actions for each violation level.

**Key Concepts:**

- **Violation Number**: Tracks how many times this specific rule has been triggered for a user in the current session
- **Action Sequences**: Define different actions for each violation number (1st violation, 2nd violation, etc.)
- **Simultaneous Actions**: Multiple actions within the same sequence execute at the same time
- **Rule-Level Cooldown**: Prevents the same rule from triggering repeatedly within the cooldown period

**Example Action Sequence:**

```json
{
  "action_sequences": [
    {
      "violation_number": 1,
      "actions": ["mute_video", "call_warning"],
      "call_options": {
        "warning_text": "Please keep your video appropriate"
      }
    },
    {
      "violation_number": 2,
      "actions": ["mute_audio", "mute_video"]
    },
    {
      "violation_number": 3,
      "actions": ["kick_user"]
    }
  ]
}
```

**How Escalation Works:**

1. **First Violation**: User receives a warning and video is muted
2. **Second Violation**: User's audio and video are muted
3. **Third Violation**: User is kicked from the call

**Rule-Level Cooldown:**

The cooldown period prevents the same rule from triggering repeatedly. Once a rule triggers and executes an action sequence, it enters a cooldown period (configurable: 5s, 10s, 1m, 5m, or 10m). During this cooldown, the rule will not trigger again, even if conditions are met.

## Cross-Call Violation Tracking

While action sequences handle escalation within a single call, you may also want to take action against users who accumulate violations **across multiple calls**. The `call_violation_count` condition lets you create a **user rule** that triggers when a user reaches a threshold of call rule violations within a time window.

For example, you can ban a user who triggers these rules 5 times across any calls within a 24-hour period.

### Configure via API

```js label="Node.js"
await client.moderation.upsertModerationRule({
  name: "Ban Repeat Call Offenders",
  rule_type: "user",
  enabled: true,
  cooldown_period: "24h",
  logic: "AND",
  conditions: [
    {
      type: "call_violation_count",
      call_violation_count_params: { threshold: 5, time_window: "24h" },
    },
  ],
  action: { type: "ban_user" },
});
```

**Parameters:**

- `threshold`: Number of call rule violations required to trigger (e.g., `5`)
- `time_window`: Time window to track violations. Supported values: `"30m"`, `"1h"`, `"24h"`, `"7d"`, `"30d"`

**How It Works:**

- Every time a call rule's action sequence executes (any violation number), a global counter is incremented for the user
- The counter tracks violations across **all calls** and **all call rules**, not just a single session
- When a user rule with `call_violation_count` is evaluated, it checks whether the user's total call violations within the time window meet or exceed the threshold
- This allows combining in-call escalation (action sequences) with cross-call enforcement (user rules)

## Available Call Actions

Call rules support the following actions:

### Mute Video

Disables the user's video stream.

```json
{
  "actions": ["mute_video"]
}
```

**Note:** The `mute_video` action automatically mutes only video (audio remains unmuted). No additional options are required or used.

### Mute Audio

Disables the user's audio/microphone.

```json
{
  "actions": ["mute_audio"]
}
```

**Note:** The `mute_audio` action automatically mutes only audio (video remains unmuted). No additional options are required or used.

### Mute User (Audio and Video)

Mutes both audio and video simultaneously by specifying both actions.

```json
{
  "actions": ["mute_audio", "mute_video"]
}
```

**Note:** To mute both audio and video, include both `mute_audio` and `mute_video` in the actions array. Each action is executed independently with its default behavior.

### Blur Video

Blurs the user's video feed (visual censorship).

```json
{
  "actions": ["call_blur"]
}
```

**Note:** The `call_blur` action blurs the video feed. No additional options are required or used.

### End Call

Terminates the entire call for all participants.

```json
{
  "actions": ["end_call"]
}
```

**Note:** The `end_call` action terminates the call for all participants. No additional options are required or used.

### Kick User

Removes the user from the call (others continue).

```json
{
  "actions": ["kick_user"]
}
```

**Note:** The `kick_user` action removes the user from the call. No additional options are required or used.

### Warning

Sends a warning message to the user.

```json
{
  "actions": ["call_warning"],
  "call_options": {
    "warning_text": "Please follow community guidelines"
  }
}
```

**Options:**

- `warning_text`: Warning message to display to the user (required)

### Webhook Only

Sends a webhook event without executing any call actions. Useful for logging or external integrations.

```json
{
  "actions": ["webhook_only"]
}
```

## Webhook Events

When a call rule is triggered, a webhook event is automatically sent. To configure webhook URL and subscribe to events, navigate to Moderation > Advanced Filters > Preferences > Webhook & Event Configuration. Select the `moderation_rule.triggered` event to receive call rule trigger events.

**Event Type:** `moderation_rule.triggered`

**Event Structure:**

```json
{
  "type": "moderation_rule.triggered",
  "created_at": "2026-01-20T23:45:04.485362361Z",
  "rule": {
    "id": "0450e7d6-9386-4eb9-a720-f3999979989c",
    "name": "Nudity or hate speech not allowed from men",
    "type": "call",
    "description": "Detects inappropriate content in video calls"
  },
  "violation_number": 1,
  "entity_id": "default:default_test-4013",
  "entity_type": "stream:v1:call",
  "user_id": "test-user-2025b49e-ef45-473f-bb90-4f8f679c8581",
  "triggered_actions": ["mute_video", "call_warning"],
  "review_queue_item_id": "abc123"
}
```

**Fields:**

- `type`: Always `"moderation_rule.triggered"` for rule builder events
- `created_at`: ISO 8601 timestamp when the event was created
- `rule`: Object containing rule information
  - `id`: Unique identifier for the rule
  - `name`: Human-readable rule name
  - `type`: Rule type (`"call"`, `"user"`, or `"content"`)
  - `description`: Rule description
- `violation_number`: (Call rules only) The violation number that triggered this event (1st violation, 2nd violation, etc.)
- `entity_id`: The ID of the entity that triggered the rule (for call rules, this is the call CID)
- `entity_type`: The type of entity (for call rules, this is `"stream:v1:call"`)
- `user_id`: The ID of the user who triggered the rule
- `triggered_actions`: Array of action types that were executed (e.g., `["mute_video", "call_warning"]`)
- `review_queue_item_id`: (Optional) The review queue item ID if the violation was flagged for review

**Note:** Webhook events are sent once per rule per violation number per entity. If multiple keyframes or closed captions trigger the same rule with the same violation number, only one webhook event is sent.

## Your own video

If Stream does not host the video, send keyframes and captions yourself. See [Your own live video](https://getstream.io/moderation/docs/node/integrations/your-own-video/).

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/integrations/live-video-and-audio/](https://getstream.io/moderation/docs/node/integrations/live-video-and-audio/).

---

# Your own live video

Send keyframes and captions from your own video pipeline to the Check API. Use entity type `external:call`. The same live video rules that run on Stream-hosted calls (`stream:v1:call`) run on these checks. Create those rules on [Live video and audio](https://getstream.io/moderation/docs/node/integrations/live-video-and-audio/).

1. Extract keyframes (images) and closed captions (text) in your pipeline.
2. Send them to Check with `entity_type: "external:call"`.
3. Stream evaluates them against your keyframe and closed-caption rules.
4. A match sends `moderation_rule.triggered` and `review_queue_item.new`.

`content_published_at` is the time the frame or caption was produced. Stream stores it on the flag so a reviewer can line it up with your timeline.

## Send a keyframe

```js label="Node.js"
const response = await client.moderation.check({
  entity_type: "external:call",
  entity_id: "my-room-12345",
  entity_creator_id: "user-abc",
  content_published_at: new Date(),
  moderation_payload: {
    images: ["https://your-cdn.com/keyframe-001.jpg"],
  },
});
```

## Send a caption

```js label="Node.js"
const response = await client.moderation.check({
  entity_type: "external:call",
  entity_id: "my-room-12345",
  entity_creator_id: "user-abc",
  content_published_at: new Date(),
  moderation_payload: {
    texts: ["transcribed audio segment"],
  },
});
```

## Handling actions

Stream does not join your video session, so it cannot mute, blur, or kick a participant. Use `flag_content` or `webhook_only` on the rule, and enforce the decision on your own infrastructure when the webhook arrives.

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/integrations/your-own-video/](https://getstream.io/moderation/docs/node/integrations/your-own-video/).

---

# Stream Chat

Integrating moderation in Stream Chat is a straightforward process that requires no code changes. You simply need to configure moderation policies through the dashboard, and Stream will automatically handle content moderation for your chat application. This guide will walk you through setting up moderation policies and monitoring flagged content through the [Stream dashboard](https://getstream.io/signin/?product=moderation).

## Configure Moderation Policy

A moderation policy is a set of rules that define how content should be moderated in your application. See [Configuration](https://getstream.io/moderation/docs/node/configuration/policies/) for details on setting up moderation policies.

## Auto Moderation on Message

### Client side integration

A Chat UI SDK applies the configured policy to messages automatically. No client code is required.

### Server side integration

If you are using the SendMessage API from server side, then by default messages will be skipped for moderation. You can enable moderation for messages by setting the `force_moderation` option to `true`.

>
> **Warning:** `force_moderation` is **server-side only** and ignored when sent from a client-side SDK.
>

```js label="Node.js"
const { message } = await client.chat.sendMessage({
  type: channelType,
  id: channelId,
  message: { text, attachments, user_id: sentBy },
  force_moderation: true,
});
```

If moderation removes the message, SendMessage does not return an error. The message object has `type` `error` instead.
The `moderation` object in the response includes the action taken and detailed information about why the message was moderated. The example response is as following:

```json {4-10}
{
  "message": {
    "id": "2b56e00f-4149-465f-b1e7-62d892788f85",
    "type": "error",
    "text": "Message was blocked by moderation policies",
    "moderation": {
      "action": "remove",
      "original_text": "F*** you motherf***er",
      "text_harms": ["insult"],
      "blocklists_matched": ["profanity-list"]
    },
    "user": {
      "id": "little-lake-2",
      "name": "little-lake-2",
      ...
    },
    "cid": "messaging:first",
    "created_at": "2026-10-20T13:13:38.071535Z",
    "updated_at": "2026-10-20T13:13:38.071535Z",
    "shadowed": false,
    ...
  },
  "duration": "136.06ms"
}
```

The `moderation` object contains the following fields:

| Field                | Type     | Description                                                                                                                       |
| -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `action`             | string   | `keep`, `flag`, `mask`, `mask_flag`, `shadow`, `remove`, `bounce`, `bounce_flag`, or `bounce_remove`. There is no severity field. |
| `original_text`      | string   | The original message text before moderation                                                                                       |
| `text_harms`         | string[] | NLP or LLM text labels (for example `["insult"]`)                                                                                 |
| `image_harms`        | string[] | Labels from AI image moderation (e.g., `["nudity", "violence"]`)                                                                  |
| `blocklists_matched` | string[] | Names of blocklists that matched (e.g., `["profanity-list", "spam-words"]`)                                                       |

>
> **Info:** The detailed moderation labels (`text_harms`, `image_harms`, `blocklists_matched`) are only included in **server-side** responses. Client-side responses only include `action` and `original_text`.
>

When a message is removed, no `message.new` WebSocket event is sent. Other users in the channel do not see it.

## Policy keys

Chat looks up the most specific policy key, then falls back:

- `chat:messaging:channel_id` for one channel
- `chat:messaging` for every channel of that type
- `chat` for every chat channel

Poll text uses `polls:default`. See [Moderate poll text](https://getstream.io/moderation/docs/node/content-moderation/check/#polls).

## User-Driven Actions

In addition to automated moderation, Stream's Chat SDK provides methods for users to take moderation actions against other users. These actions help maintain community standards by allowing users to report inappropriate behavior or content. For detailed information on effects of these actions, please check the documentation for [Chat Moderation Tools](https://getstream.io/chat/docs/javascript/moderation/). Here we cover some basic examples on how to use these actions.

### Flag User

Users can flag another user with a reason. This will trigger a review in the moderation dashboard.

If you are using [Chat UI SDK](https://getstream.io/chat/sdk/), users can flag the user from user actions menu.

If you have your own custom UI, you can use the following API to flag the user:

```js label="Node.js"
await client.moderation.flag({
  entity_type: "stream:user",
  entity_id: "user_id",
  reason: "reason",
  user_id: "user_id", // User ID who is flagging the user, required only for server-side integration.
});
```

### Flag Message

Users can flag a message, which will trigger a review in the moderation dashboard.

If you are using [Chat UI SDK](https://getstream.io/chat/sdk/), users can flag the message from message actions menu.

If you have your own custom UI, you can use the following API to flag the message:

```js label="Node.js"
await client.moderation.flag({
  entity_type: "stream:chat:v1:message",
  entity_id: "message_id",
  reason: "reason",
  user_id: "user_id", // User ID who is flagging the message, required only for server-side integration.
});
```

### Ban User

A user with moderator permissions can ban a user from the chat.
For more details, please check the documentation for [Banning Users](https://getstream.io/chat/docs/javascript/moderation/#ban).

```js label="Node.js"
await client.moderation.ban({
  target_user_id: "target_user_id",
  banned_by_id: "user_id", // User ID who is banning the user.
});
```

### Unban User

A user with moderator permissions can unban a user from the chat.

```js label="Node.js"
await client.moderation.unban({
  target_user_id: "target_user_id",
});
```

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/integrations/stream-chat/](https://getstream.io/moderation/docs/node/integrations/stream-chat/).

---

# Stream Feeds

Integrating moderation in Activity Feeds is straightforward and requires minimal code changes. Once you configure a moderation policy, Stream automatically moderates activities and comments as they are created or updated. This guide walks you through setting up moderation and monitoring flagged content.

## Configure Moderation Policy

A moderation policy defines how content should be moderated. You can configure your [policy](https://getstream.io/moderation/docs/node/configuration/policies/) through the [dashboard](https://getstream.io/signin/?product=moderation) or via the API. Activity and comment `custom` is included in the moderation payload, so [content custom-property rules](https://getstream.io/moderation/docs/node/configuration/rules/#custom-properties-stream-chat-and-feeds-only) match Feeds the same way they match Chat.

For Feeds v3, Stream picks a policy in this order:

1. `feed.custom.moderation_policy` -- if that exact config exists
2. `feeds:{group_id}:{feed_id}` -- individual feed
3. `feeds:{group_id}` -- feed group
4. `feeds` -- app-wide default

If `custom.moderation_policy` is missing, empty, or names a config that does not exist, Stream continues with the `feeds:...` keys. Activity or comment `custom.moderation_policy` is ignored for this assignment.

To set up an app-wide policy for all feeds content:

```js label="Node.js"
await client.moderation.upsertConfig({
  key: "feeds",
  ai_text_config: {
    rules: [
      { label: "SPAM", action: "flag" },
      { label: "HATRED", action: "remove" },
    ],
  },
  block_list_config: {
    rules: [{ name: "profanity_en", action: "remove" }],
  },
  ai_image_config: {
    rules: [
      { label: "Non-Explicit Nudity", action: "flag", min_confidence: 50 },
    ],
  },
});
```

You can also configure policies per feed group (e.g., `feeds:user` for user feeds, `feeds:timeline` for timeline feeds) to apply different moderation rules to different feed types.

### Assign a named policy to a feed

To share one policy across many feeds without cloning feed groups, upsert a config under any key (for example `pm:acme`) and set that key on each feed. The field is writable on create and update.

```js label="Node.js"
await feed.update({
  custom: {
    moderation_policy: "pm:acme",
  },
});
```

## Auto-Moderation on Activities

Once the policy is configured, activities are automatically moderated when created or updated. No additional code is needed -- just add activities as you normally would.

Server-side requests skip moderation by default. Set `force_moderation: true` to moderate an activity or comment created from your backend.

>
> **Warning:** `force_moderation` is **server-side only** and ignored when sent from a client-side SDK.
>

When an activity contains content that violates your policy, Stream takes the configured action:

- **remove** -- the activity is removed and appears in the review queue
- **flag** -- the activity is published but flagged for review
- **bounce** -- the activity is rejected entirely and not saved
- **shadow** -- the activity is hidden from other users but visible to the creator
- **mask_flag** (blocklists only) -- blocklisted words in the text are replaced with asterisks, and the activity is published and flagged for review. See [Mask Sensitive Content](https://getstream.io/moderation/docs/node/content-moderation/actions/#mask)
- **mask** (blocklists only) -- blocklisted words in the text are replaced with asterisks, without flagging

The API response includes a `moderation` object with details about the action taken:

```json
{
  "id": "activity-123",
  "type": "post",
  "text": "the activity text",
  "moderation": {
    "action": "remove",
    "original_text": "the activity text",
    "text_harms": ["HATRED"],
    "blocklists_matched": ["profanity_en"]
  }
}
```

Feeds returns `ModerationV2Response`. It does not include `status` or `recommended_action`.

| Field                | Type     | Description                                                                                          |
| -------------------- | -------- | ---------------------------------------------------------------------------------------------------- |
| `action`             | string   | `keep`, `flag`, `remove`, `shadow`, `bounce`, `bounce_flag`, `bounce_remove`, `mask`, or `mask_flag` |
| `original_text`      | string   | Text before masking                                                                                  |
| `text_harms`         | string[] | NLP or LLM labels, such as `HATRED` or `SPAM`                                                        |
| `image_harms`        | string[] | Image labels, such as `Explicit`                                                                     |
| `blocklists_matched` | string[] | Blocklists that matched                                                                              |

## Auto-Moderation on Comments

Comments are also automatically moderated using the same policy. When a user adds a comment, Stream checks the content and applies the configured action.

If a comment is removed, other users do not see it. The response includes the moderation action:

```json
{
  "id": "comment-789",
  "text": "...",
  "moderation": {
    "action": "remove",
    "original_text": "...",
    "text_harms": ["HATRED"]
  }
}
```

>
> **Info:** Reactions (likes, etc.) are not auto-moderated, only activities and comments.
>

## Policy keys

Feeds looks up `feeds:{group}` and `feeds:{group}:{id}`. Set `custom.moderation_policy` on a feed to name an exact policy instead. Poll text uses `polls:default`.

## User-Driven Actions

In addition to automated moderation, users can flag content or other users for review.

### Flag a User

```js label="Node.js"
await client.moderation.flag({
  entity_type: "stream:user",
  entity_id: targetUserId,
  reason: "harassment",
  user_id: reportingUserId,
});
```

### Ban a User

```js label="Node.js"
await client.moderation.ban({
  target_user_id: targetUserId,
  banned_by_id: moderatorId,
  reason: "Repeated violations",
});
```

Banned users are prevented from reading feeds and creating activities or reactions.

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/integrations/stream-feeds/](https://getstream.io/moderation/docs/node/integrations/stream-feeds/).

---

# Stream Feeds - Legacy

>
> **Warning:** These docs are for Feeds v2, which is deprecated and considered a legacy product. You can find documentation for [Feeds v3 here](https://getstream.io/moderation/docs/node/integrations/stream-feeds/).
>

## Introduction

Moderation in Feeds is made possible through the work on the new moderation API. Moderation capabilities have been added to the Feeds API with the following features:

- Automatic moderation of new activities
- Automatic moderation of activities on update
- Automatic moderation of new reactions
- Automatic moderation of reactions on update
- Flagging activities
- Flagging reactions
- Flagging users
- Prevent banned users from reading a feed
- Prevent banned users from creating activities/reactions

## Prerequisites

- Since moderation in Feeds is behind a feature flag, make sure this is enabled for your app. Get in touch with [Stream Support Team](https://getstream.io/contact/support/) for this purpose.

## Create Moderation Policy

A moderation policy is a set of rules that define how content should be moderated in your application.
See [Configuration](https://getstream.io/moderation/docs/node/configuration/policies/) for details on setting up moderation policies.

## Setup Moderation Templates

Moderation templates are Feeds-specific and are needed because activities (or reactions) are generic in structure. The template is used to tell the API which part(s) of the activity should be subject to moderation and which type they are (text or image). As an example, your activities might look like this:

```json
{
  "actor": "jimmy",
  "verb": "post",
  "object": {
    "title": "this is the title",
    "body": "this is the body..."
  },
  "image": "https://example.com/post_image.png"
}
```

and you want to moderate the fields `object.title` , `object.body` and `image` you would create a moderation template like this, lets name it `mod_tmpl_1`

```json
{
  "data_types": {
    "object.title": "text",
    "object.body": "text",
    "image": "image"
  }
}
```

If you want to moderate reactions, you need to create a separate template for it. As an example, your reaction might look like this:

```json
{
  "text": "This is the reaction text",
  "attachments": ["https://example.com/post_image.png"]
}
```

and you want to moderate the fields `text` and `attachments`, you would create a moderation template like this, lets name it `moderation_template_reaction`

```json
{
  "data_types": {
    "text": "text",
    "attachments": "image"
  }
}
```

If you have activities that varies in structure (or reactions) you can create multiple templates to use for them as well.

It's important to understand that when it comes to moderation in feeds, the user will be determined by the `actor` on the activities and the `user_id` on reactions. The feeds moderation integration will automatically create users on the [moderation side](https://getstream.io/docs/platform/users/) to be able to track bans/blocks etc there. This is not to be confused with the [Feeds user](https://getstream.io/activity-feeds/docs/python/v2/users-introduction/) which is a separate entity.

### Create a Template via API

```js label="Node.js"
await client.moderation.v2UpsertTemplate({
  name: "mod_tmpl_1",
  config: {
    data_types: { text: "text", attachments: "image" },
    config_key: "feeds:default",
  },
});
```

### Query Templates

```js label="Node.js"
await client.moderation.v2QueryTemplates();
```

### Delete Template

```js label="Node.js"
await client.moderation.v2DeleteTemplate({ name: "mod_tmpl_1" });
```

## Client Side Feeds Integration

### Auto moderation of activities

To enable moderation of activities for client-side integration, you need to include the `required_moderation_template` (Moderation Template which you created for activities) in your [JWT token](https://getstream.io/docs/platform/authentication/) payload. This ensures that any activities created from the client are automatically moderated according to your policy. You must include this specific JWT token only for activities and not for reactions.

#### Generate JWT Token

Generate the token on your server with the Feeds API secret. Do not put the secret in a browser, a mobile app, or a public token debugger.

Use this payload:

```json
{
  "resource": "feed",
  "action": "write",
  "feed_id": "feed123",
  "user_id": "user123",
  "required_moderation_template": "mod_tmpl_1"
}
```

> **Important**: Replace `"mod_tmpl_1"` with the name of your specific moderation template.

Sign that payload with the server secret and pass the resulting token to the client SDK.

### Auto moderation of reactions

> **Important**: You need a different JWT Token for reactions for moderation to work with it. Don't confuse this with the token you generated above for the auto moderation of activities.

To enable moderation of reactions for client-side integration, you need to include the `required_moderation_template` (Moderation Template which you created for reactions) in your JWT token payload. This ensures that any activities created from the client are automatically moderated according to your policy. You must include this specific JWT token only for reactions and not for activities.

#### Generate JWT Token

Generate this token on your server as well. Use this payload:

```json
{
  "resource": "reactions",
  "action": "write",
  "feed_id": "feed123",
  "user_id": "user123",
  "required_moderation_template": "moderation_template_reaction"
}
```

> **Important**: Replace `"moderation_template_reaction"` with the name of your specific moderation template.

Sign that payload on the server and pass the token to the client SDK.

## Server Side Feeds Integration

### Auto Moderation of Activities

>
> **Info:** Moderation is not supported on batch activity inserts (the Feeds API doesn't support partial responses, and the moderation API doesn't have a batch endpoint for this yet)
>

Now that you have a **moderation config** and at least one **moderation template**, you can start automatically moderating content in your feeds. Auto-moderation allows you to proactively screen activities before they are added to feeds, helping maintain content quality and safety.

When an activity with a moderation template is added, Stream will:

1. Extract the content specified in the template (text fields, images, etc.)
2. Run it through the configured moderation policy
3. Take the appropriate action based on policy rules (block, flag, etc.)

To enable auto-moderation for activities, simply supply the `moderation_template` field in your activity object when making requests to the feeds API, like so:

>
> **Warning:** You need to supply the `moderation_template` field while adding the activity. Learn how to create moderation templates in the [Setup Moderation Templates](#setup-moderation-templates) section.
>

```json
{
  "actor": "jimmy",
  "verb": "post",
  "object": {
    "title": "this is the title",
    "body": "this is the body..."
  },
  "image": "https://example.com/post_image.png",
  "moderation_template": "mod_tmpl_1" // this points to the moderation template
}
```

Here are code examples showing how to add an activity with the `moderation_template` field:

```jsx {4} label="Node.js"
const response = await client.feed("user", "user-1").addActivity({
  verb: "eat",
  object: "object",
  moderation_template: "moderation_template_activity",
  a: "buy followers now",
  text: "buy followers now",
  attachment: {
    images: ["image1", "image2"],
  },
  foreign_id: "random_foreign_id",
  time: new Date(),
});
console.log(response.moderation.recommended_action); // "remove"
console.log(response.moderation.status); // "complete"
```

### Auto moderation of reactions

To add a reaction with moderation, you need to supply the `moderation_template` field in the request.

```jsx label="Node.js"
const responseReaction = await client.reactions.add(
  "comment",
  responseActivity.id,
  {
    text: "buy followers now",
    moderation_template: "moderation_template_reaction",
  },
);
console.log(responseReaction.moderation.response.recommended_action); // "remove"
console.log(responseReaction.moderation.response.status); // "complete"
```

## User-Driven Actions

Flag a Feeds user, activity, or reaction with the moderation `flag` method. The old Feeds client helpers (`flagUser`, `flagActivity`, `flagReaction`) are not the moderation API.

```js
await client.moderation.flag({
  entity_type: "stream:feeds:v2:activity",
  entity_id: activityId,
  entity_creator_id: actorId,
  reason: "inappropriate_content",
  user_id: reporterId,
});
```

Use `stream:user` for a user and `stream:feeds:v2:reaction` for a reaction. The full samples are on [Flag, Mute, and Ban](https://getstream.io/moderation/docs/node/content-moderation/flag-mute-ban/).

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/integrations/stream-feeds-v2/](https://getstream.io/moderation/docs/node/integrations/stream-feeds-v2/).

---

# AI Text (LLM)

The LLM engine reads each message in context, so it catches harmful intent that keyword lists miss.

- Describe in plain language what you want the system to detect, and the engine will handle the rest.
- Share context about your application so the LLM can better understand the context in which users are interacting.
- Moderation considers both the message and its context, focusing on user intent rather than just keywords.
- Detects and blocks attempts to bypass moderation by splitting harmful content across multiple messages.

## Language Support

There is no fixed language list. The engine reads the message in whatever language it is written in, and your rules and app context can stay in English. Accuracy is highest in widely used languages. For less common languages, dialects, and heavy slang, test with real samples of your content in [Evaluations](https://getstream.io/moderation/docs/node/configuration/evaluations/) before you rely on automatic actions. If your users mainly write in specific languages, say so in the app context.

## How it works

The LLM moderation engine classifies content based on your configuration and recent conversation history. To set it up, you'll provide two key inputs:

**App Context**: A short description of your application and how users interact. This helps the LLM understand your platform's environment (e.g., casual chat, professional tone, teen audience).

**LLM Rules**: Clear harm categories written in plain language. For example, you might define what counts as SCAM, HATE SPEECH, or SEXUAL HARASSMENT in your community.

When a new message is sent, the engine considers:

- Your defined app context
- Your LLM rules
- The last few messages in the conversation

It then classifies the message against your rules and applies the configured action (`flag`, `shadow`, `remove`, `bounce`, or `keep`).

## Context from custom data

A comment often only makes sense next to what it replies to. "Hope he breaks the other one too" means one thing under an article about a record-breaking season and another under a video of a player's broken leg. To give the LLM that background, list the `moderation_payload.custom` keys it may read on the policy's `llm_config`:

| key                             | type             | description                                                                                                                                                                                                                          |
| ------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| context_custom_keys             | array of strings | Optional. Top-level keys of `moderation_payload.custom` passed to the LLM as context. Up to 10 keys, each 1-64 characters                                                                                                            |
| custom_keys_context_description | string           | Optional. Tells the LLM how to read that data, for example what each key holds and in which order. Up to 1000 characters, counted as UTF-8 bytes, so non-Latin text and emoji reach the limit sooner. Requires `context_custom_keys` |

The context is background only:

- Only the `texts` are moderated. Results, labels and flagged text always refer to them, never to the context.
- The LLM treats the context as data. It cannot change your rules, labels, severities or strictness, and instructions inside it are ignored.
- Only the listed keys are sent, and only the ones present on the item. Other keys in `custom` are not shown to the LLM. When none of the listed keys are present, the description is dropped too and the check runs as if no context were configured.
- The listed data is sent as JSON, capped at 4000 bytes. Longer data is cut off. The full `custom` is still stored on the review queue item and sent on webhooks unchanged. The [Check](https://getstream.io/moderation/docs/node/content-moderation/check/) limit of 10KB for `custom` still applies.
- It works for any `entity_type`. Chat messages and Feeds activities and comments pass their own custom fields as `moderation_payload.custom`, so for them the context has to be set on the message or activity itself.

Context can lower a match's severity without changing its label, for example when an article shows a comment is trash talk rather than a threat. For a lower severity to change the outcome, the label needs an action per severity, for example `high` to `remove` and `low` to `flag`. Set this with [LLM severity rules](https://getstream.io/moderation/docs/node/configuration/policies/#llm-severity-rules). Without them, the label's single action applies at every severity.

Upserting the policy replaces the whole `llm_config`, so an upsert without these fields clears them.

Configure the policy with the keys and how to read them:

```js label="Node.js"
await client.moderation.upsertConfig({
  key: "news-comments",
  llm_config: {
    enabled: true,
    app_context:
      "Comment sections under sports articles and videos. Trash talk about teams and performances is normal and allowed; attacks on people are not.",
    context_custom_keys: ["content", "thread"],
    custom_keys_context_description:
      "content is the article or video the comment is posted under. thread.topLevel is the comment being replied to; thread.earlierReplies are earlier replies, oldest first.",
    rules: [
      {
        label: "HARASSMENT",
        description:
          "Insulting, demeaning or bullying another user, player, coach or referee as a person",
        action: "flag",
      },
      {
        label: "VIOLENCE",
        description:
          "Threats, wishing injury or death on someone, or encouraging people to show up at someone's home",
        action: "remove",
      },
    ],
  },
});
```

Then send the item with its surroundings in `custom`:

```js label="Node.js"
await client.moderation.check({
  entity_type: "comment",
  entity_id: "comment-123",
  entity_creator_id: "user-42",
  config_key: "news-comments",
  moderation_payload: {
    texts: [
      "bet, see everyone at his place after the game, I'll bring friends",
    ],
    custom: {
      schemaVersion: 1,
      content: {
        type: "video",
        title: "Controversial late call by referee decides the game",
      },
      thread: {
        topLevel: {
          id: "comment-100",
          user: { id: "user-7" },
          text: "That ref lives at 22 Oak Ridge Drive, someone should pay him a visit",
        },
        earlierReplies: [
          {
            id: "comment-110",
            user: { id: "user-9" },
            text: "He deserves whatever he gets",
          },
        ],
      },
    },
  },
});
```

On its own the comment reads as harmless. With the thread as context the LLM returns `remove` with the `VIOLENCE` label, and the flagged text is only the comment. `schemaVersion` is not listed in `context_custom_keys`, so the LLM never sees it.

The `content` and `thread` keys above use the [comment context](https://getstream.io/moderation/docs/node/content-moderation/check/#comment-context-in-the-review-queue) format, so the same `custom` also shows the article and thread to moderators in the review queue. The two features are independent: the review queue reads `custom` by its shape, the LLM reads only the keys you list.

## Configuration

```js
await client.moderation.upsertConfig({
  key: "chat:messaging",
  llm_config: {
    app_context:
      "A social chat app for adults. Casual tone is fine. Threats and scams are not.",
    rules: [
      {
        label: "SCAM",
        description: "Fraud, phishing, or requests for payment credentials.",
        action: "remove",
      },
      {
        label: "HATE_SPEECH",
        description: "Hatred, discrimination, or violence against a group.",
        action: "flag",
      },
    ],
    severity_descriptions: {
      low: "Rude but not targeting a person.",
      high: "A direct attack or a credible threat.",
    },
  },
});
```

LLM rule actions are `keep`, `flag`, `shadow`, `remove`, `bounce`, `bounce_flag`, and `bounce_remove`. `severity_rules` on a rule map `low`, `medium`, `high`, and `critical` to an action. `queryModerationRules` returns `default_llm_labels` with the starter descriptions.

You can set up the same fields in the [dashboard](https://getstream.io/signin/?product=moderation).

1. In the dashboard, navigate to **Moderation → Policies**.
2. Select the policy you want to update.
3. Navigate to **AI (LLM) Text**.
4. Add your app context and harm labels, then define prompts for each label.

Context keys and their description are set through the API (`llm_config.context_custom_keys` and `custom_keys_context_description`).

Starter labels are `SCAM`, `SEXUAL_HARASSMENT`, `HATE_SPEECH`, `PII`, and `PLATFORM_BYPASS`. You can edit or remove any of them, or add your own.

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/engines/ai-llm-text/](https://getstream.io/moderation/docs/node/engines/ai-llm-text/).

---

# AI Text (NLP)

Stream's NLP text engine classifies content across multiple languages to detect harmful content with high accuracy and contextual understanding.

## Language Support

The NLP engine detects the language of the text automatically.

Six languages are maintained directly and are available by default:

- English
- French
- Spanish
- Portuguese
- German
- Italian

These 32 languages are available on request. The text is translated to English and moderated with the English rules, so accuracy is close to the maintained languages. Dialects, such as Arabizi for Arabic, are not covered. [Contact support](https://getstream.io/contact/support/) to enable one.

- Arabic
- Hebrew
- Russian
- Ukrainian
- Chinese
- Japanese
- Korean
- Thai
- Hindi
- Indonesian
- Vietnamese
- Bengali
- Turkish
- Irish
- Catalan
- Polish
- Czech
- Greek
- Romanian
- Danish
- Dutch
- Croatian
- Finnish
- Estonian
- Swedish
- Norwegian
- Hungarian
- Latvian
- Lithuanian
- Slovak
- Slovenian
- Swahili

## Configuration

Set up the NLP engine with `ai_text_config` on a [policy](https://getstream.io/moderation/docs/node/configuration/policies/). Each rule names a label and either one `action` for every match or `severity_rules` with an action per severity. Labels are uppercase strings from [Supported harms and categories](#supported-harms-and-categories), such as `INSULT` and `HATRED`. `SPAM` is allowed. `HARASSMENT` is not a label.

```js
await client.moderation.upsertConfig({
  key: "chat:messaging",
  ai_text_config: {
    enabled: true,
    rules: [
      // One action for every match
      { label: "INSULT", action: "flag" },
      // Labels without severity can only take one action
      { label: "PLATFORM_BYPASS", action: "flag" },
      // An action per severity
      {
        label: "HATRED",
        severity_rules: [
          { severity: "low", action: "flag" },
          { severity: "medium", action: "flag" },
          { severity: "high", action: "remove" },
          { severity: "critical", action: "remove" },
        ],
      },
    ],
  },
});
```

NLP actions are `keep`, `flag`, `mask`, `mask_flag`, `shadow`, `remove`, `bounce`, `bounce_flag`, and `bounce_remove`. See [Automatic actions](https://getstream.io/moderation/docs/node/content-moderation/actions/#automatic-actions) for what each one does.

How the NLP engine differs from the [LLM engine](https://getstream.io/moderation/docs/node/engines/ai-llm-text/):

- Labels come from a fixed list. You can't add your own labels or describe them in plain language.
- There is no app context or rule description. The engine classifies each text on its own.
- When a rule has `severity_rules`, they decide the action. A severity with no matching entry falls back to the rule's `action`, if set.
- Upserting `ai_text_config` replaces the whole rule list.

## Severity Levels

The NLP engine grades harmful labels at four severity levels:

| Severity   | Meaning                                                                                           |
| ---------- | ------------------------------------------------------------------------------------------------- |
| `low`      | May be offensive or inappropriate.                                                                |
| `medium`   | Could cause harm or distress, but is not urgent or severe.                                        |
| `high`     | Likely to cause significant harm, such as hate speech or discrimination against protected groups. |
| `critical` | An immediate threat to the safety or well-being of people, such as content that incites violence. |

Content that isn't harmful has no severity. Severity is graded per label, so one message can be `low` for `VULGARITY` and `high` for `THREAT`. Set an action per severity in the dashboard policy editor, or with `severity_rules` on the rule, as in the [configuration example](#configuration). For example, flag low-severity insults for review and remove high and critical ones.

### Labels without severity

Some labels describe a topic or a behavior rather than a degree of harm, so the engine never grades them. These labels have no severity levels: you can only match them by label and set one action. `severity_rules` don't apply to them, and the dashboard doesn't show severity options for them.

| Label                  | Description                                                                                                                                                                |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ADS`                  | Promotional messages for products, services, events, or personal brands, including collaboration requests, direct sales, profile promotion, promo codes, and ticket sales. |
| `BOYCOTT`              | Urging people to stop buying, using, or supporting a company's products or services.                                                                                       |
| `CYBERSECURITY`        | Discussion of digital security topics, such as data breaches.                                                                                                              |
| `ENCOURAGEMENT`        | Messages giving support to a person or an entity.                                                                                                                          |
| `FAIRPLAY`             | Messages expressing fairness and respect for the spirit of the rules, such as "GG".                                                                                        |
| `FINANCE`              | Discussion of money and economic issues.                                                                                                                                   |
| `FLOOD`                | Messages meant to disrupt a conversation with senseless or repetitive content: ASCII art, repeated emojis or words, stylized text, or all caps.                            |
| `FORBIDDEN_LANGUAGE`   | Messages written in a language that is not allowed for your app. Contact support to configure the allowed languages.                                                       |
| `FORBIDDEN_LINK`       | Messages containing a link on your blocked list. Contact support to configure the list.                                                                                    |
| `GEOPOLITICAL`         | Comments about politics, especially international relations.                                                                                                               |
| `HEALTH_CONCERNS`      | Reports of negative physical reactions, health concerns, or safety risks, for example related to a product.                                                                |
| `LINK`                 | A link to another page or site.                                                                                                                                            |
| `NEGATIVE_CRITICISM`   | Criticism of someone's content or actions without the intent to harm them.                                                                                                 |
| `PEDOPHILIA_REFERENCE` | References to child sexual abuse, excluding first-person statements of intent.                                                                                             |
| `PII`                  | Personally identifiable information, such as email addresses, phone numbers, physical addresses, bank details, national IDs, license plates, or social handles.            |
| `POLITICS`             | Comments about governments, political parties, and political figures.                                                                                                      |
| `SPAM`                 | Unwanted messages sent repeatedly to many people. Detected from timing and repetition across messages, not from one message alone.                                         |
| `SUPPORTIVE`           | Appreciation for a user or their content.                                                                                                                                  |
| `TERRORISM_REFERENCE`  | Mentions of terrorist acts, organizations, or people, without supporting them.                                                                                             |
| `UNDERAGE_USER`        | A user saying, or implying, that they are underage. The age threshold (under 13, 16, or 18) is configurable.                                                               |
| `USELESS`              | Messages with no meaningful content, such as "first!".                                                                                                                     |

`FLOOD`, `PII`, and `ADS` cover several kinds of content (for example, an email address and a phone number are both `PII`), and rules always match the parent label.

## Supported Harms and Categories

The NLP engine returns the labels below, which have [severity levels](#severity-levels), the [labels without severity](#labels-without-severity), and [custom labels](#custom-labels) when they are enabled for your app. Examples for each label follow the table.

| Label                | Description                                                                                                                           |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `ABLEISM`            | Discrimination or prejudice against people living with mental, psychological, or physical disabilities.                               |
| `BODY_SHAMING`       | Discrimination or prejudice targeting someone's physical appearance or body modifications.                                            |
| `COUNTERFEITING`     | Promoting or selling counterfeit or fake goods.                                                                                       |
| `DATING`             | Interest in pursuing a romantic or sexual relationship.                                                                               |
| `DOXXING`            | Publishing, or threatening to publish, someone's personal information or intimate content without consent.                            |
| `DRUG_EXPLICIT`      | Talking about or encouraging the use of drugs.                                                                                        |
| `EXTREMISM`          | Promoting or glorifying extremist ideologies, violent movements, or radicalization.                                                   |
| `HATRED`             | Fundamental hostility meant to insult or injure a person, group, or entity.                                                           |
| `INSULT`             | Disrespectful or abusive language targeting an individual.                                                                            |
| `LGBTQIAPLUS_PHOBIA` | Discrimination or prejudice against members of the LGBTQIA+ community.                                                                |
| `MISOGYNY`           | Discrimination or prejudice against women, including hateful patriarchal or transphobic attitudes.                                    |
| `MORAL_HARASSMENT`   | Abusive behavior meant to undermine and humiliate a person.                                                                           |
| `PEDOPHILIA`         | Content exhibiting or promoting sexual attraction to minors.                                                                          |
| `PLATFORM_BYPASS`    | Inviting users to leave the platform and continue the conversation elsewhere.                                                         |
| `RACISM`             | Discrimination or prejudice based on race or ethnicity.                                                                               |
| `REPUTATION_HARM`    | Comments meant to damage the reputation of a person or an entity.                                                                     |
| `SCAM`               | Deceptive messages meant to trick people out of money, personal information, or account access.                                       |
| `SELF_HARM`          | Distress, intent to harm oneself, or suicidal thoughts.                                                                               |
| `SEXTING`            | Playful or respectful sexual comments between adults. Unlike sexual harassment, it is not violent or degrading.                       |
| `SEXUALLY_EXPLICIT`  | Talking about or describing sexual acts or genitals.                                                                                  |
| `SEXUAL_HARASSMENT`  | Inappropriate sexual comments or unwelcome advances, from flirtatious remarks to violent sexual fantasies.                            |
| `TERRORISM`          | Support for intimidation or coercion through the threat or use of violence.                                                           |
| `THREAT`             | Comments meant to intimidate or scare someone by promising to harm them mentally or physically.                                       |
| `TROLLING`           | Confusing or manipulative messages posted to provoke a reaction.                                                                      |
| `VULGARITY`          | Offensive or obscene language, not necessarily aimed at anyone.                                                                       |
| `WEAPON_EXPLICIT`    | Talking about or encouraging the use of weapons. Context matters: weapons in games are treated differently from real-world promotion. |

### Hatred

Hatred includes expressions of intense dislike or ill will towards individuals or groups.

Examples:

- Low Severity
  - _We don't care._
  - _Get a life._
  - _Go buy a brain._
  - _Learn how to write._
  - _You need therapy._
  - _You are a nasty person._
  - _More woke bullshit._
  - _He's batshit crazy._
  - _Who gives a fuck?_
  - _Why the fuck are you still speaking?_
- Medium Severity
  - _You piss me off._
  - _The grown-ups are talking. Go play with your Lego._
  - _You disgust me!_
  - _You have no balls._
  - _Don't hesitate to dislike this video._
  - _Bruh, you can't even speak English._
  - _Grow a pair._
  - _You're revealing your LOW IQ levels._
  - _I hate you._
  - _Stop talking bullshit._
  - _There are no more "real" men left in this country._
- High Severity
  - _Go back to where you came from._
  - _You are a danger to the West._
  - _You libtards say, "Oh, it was an accident."_
  - _Who else doesn't give a shit about his life?_
  - _Go back to your little hole._
  - _I don't give a shit about anything YOU post._
  - _Not just us, pal; everyone hates you._
  - _You are dead to me, bitch._
  - _Who cares about you, terrorist? 💣_
  - _Lazy women find suckers to do the work they should have done._

### Insult

Insults are expressions that demean or belittle others.

Examples:

- Low Severity
  - _Are you stupid or something?_
  - _He is a fool._
  - _You're a clown._
  - _Stupid player!_
  - _Shut up, please._
  - _She's garbage._
  - _Bunch of losers._
  - _Screw you!_
  - _Get the fuck out!_
  - _Cry more._
  - _You're dumber than a box of rocks._
- Medium Severity
  - _🖕🏻🖕🏻🖕🏻_
  - _You fucking bastard._
  - _Fuck you._
  - _You're a dumbass._
  - _She is the A-hole._
  - _Her name is GOLD DIGGER._
  - _What a tosser._
  - _She is a manipulative bitch._
  - _What a fucking cockhead._
  - _You're such a bellend._
- High Severity
  - _What a bunch of fucktards._
  - _Shut the fuck up._
  - _She's a total whore._
  - _You all are cocksuckers._
  - _This motherfucker is driving me crazy._
  - _You son of a bitch._
  - _Get screwed, man._
  - _Kiss my ass._
  - _Go eat a bag of dicks._
  - _She's nothing but a whore._

### Body-shaming

Body-shaming involves criticizing or mocking someone's physical appearance.

Examples:

- Low Severity
  - _This guy stinks._
  - _She still looks hideous._
  - _She looks like she smells._
  - _You are ugly._
  - _That girl isn't even pretty._
  - _OMG, those hands 🤮🤮🤮._
  - _You're scary to look at._
  - _You smell like a 💨._
  - _Why don't you get rid of those nasty-looking dreadlocks?_
  - _Don't be mad because I'm prettier than you._
- Medium Severity
  - _She looks like a man to me._
  - _Your voice is annoying._
  - _Go lose some weight, dude!_
  - _You have no boobs._
  - _You sound like a man._
  - _Why are you so fat?_
  - _You are too fat._
  - _Butter face._
  - _You must have a tiny penis._
  - _Your teeth are yellow._
- High Severity
  - _You are a big fat turd face._
  - _Her coochie probably smells like a landfill._
  - _Don't talk to me if you're overweight._
  - _This is proof that gingers have no soul. 😞_
  - _When's your weight loss surgery for your fat?_
  - _Mr. Donut needs to go on a diet._
  - _You can't hide your fat with body positivity._
  - _His face makes me vomit._
  - _He needs to lose at least 200 pounds; he's way overweight._
  - _Look like you smell like cheese._

### Reputation Harm

Reputation harm involves damaging someone's reputation through false or malicious statements.

Examples:

- Low Severity
  - _You're greenwashing again._
  - _I'm sure the umpire has been paid to ignore the fouls._
- High Severity
  - _He is in cahoots with pedophiles._
  - _This company finances terrorism._

### Doxxing

Doxxing is the act of publicly revealing private information about an individual without their consent.

Examples:

- _Post her photos and address._
- _His address is 520 South San Julian St._
- _What's the cop's full name? I will post his home address on social media, and then people can go get street justice._
- _I'm leaking your number in the telegram._
- _Guys, go leak @mrx's address._

### Racism

Racism includes discriminatory or prejudiced comments based on race or ethnicity.

Examples:

- _They need to go back to their own country._
- _That's why I hate black people._
- _CHINESE CRAP!!_
- _Of course, it's black 🦍; nothing too gets surprised._
- _Entitled immigrants are the worst._
- _Don't hire stupid Mexicans._
- _You look like a monkey._
- _Fucking gypsies who spoil everything._
- _Gas them Jews._
- _Go back to the cotton fields._
- _You speak ching chong._
- _Islam is the problem everywhere._

### LGBTQIAPLUS_PHOBIA

LGBTQIAPLUS_phobia includes negative or hostile comments towards LGBTQIAPLUS individuals.

Examples:

- _That man will never be a woman. #Freak_
- _He is very gay._
- _Wow, definitely a fag._
- _Stop being gay._
- _Fuck 🏳️._
- _Alphabet people are sick._
- _A trans woman is just a man._
- _Your video is as gay as you look._
- _Bro, stop with your sissy stories!_
- _Dude, such a homo._

### Misogyny

Misogyny includes comments that express hatred or prejudice against women.

Examples:

- _Women ☕._
- _Women should be quiet..._
- _Don't care, didn't ask, plus you're a woman._
- _Women are evil._
- _Women have no value anymore._
- _This is why women should not be in charge of anything, much less vote._
- _Men are superior to women._
- _Go back to the kitchen._
- _Sadly, the only thing 90% of you women today are good for is sex..._
- _I also think women should be submissive to their husbands._

### Ableism

Ableism includes discriminatory or prejudiced comments based on physical or mental disabilities.

Examples:

- _This kid is retarded._
- _She belongs in an asylum._
- _You're brain dead._
- _You have a debilitating level of autism._
- _Lady, you're demented._
- _Do you have mental health issues?!_
- _If you paid $600 for that, you have special needs. SMH._
- _I'm sick of her; she's absolutely sick in the head; her mom was right; she's ill._
- _The vaccine definitely made you autistic._
- _He's a little gimp; can't stand him._

### Threat

Threats include statements expressing an intention to cause harm or violence to someone.

Examples:

- _I would beat him so badly._
- _I would have slapped her._
- _I would kick him._
- _If my son did something like this, I'd shoot him._
- _I'll break your worthless jaw anytime, anywhere._
- _We'll kill your wife too._
- _I would love to whoop your ass so badly. I'd literally punch your face until I hit the ground._
- _I just want to punch him in the forehead._
- _I'd definitely beat your ass._
- _I'm gonna kick you in the nuts._

### Self Harm

Self-harm includes expressions of intent to harm oneself or indications of self-destructive behavior.

Examples:

- _I think I'll kill myself soon. Honestly, at this point in my life, I don't see myself getting any better. Every single day is getting harder, and I regret so much being an orphan at this young age. I wish I were someone's favorite person and that I could talk to someone about how I really feel, but I just know nobody cares. At the end of the day, I feel like everyone's going to tell me that it's not that serious, but I just cannot take it anymore. 💔_
- _I feel depressed and need someone to talk to, please._
- _I'm really going to end my life._
- _I've been having suicidal thoughts._
- _Lately, I'm at my lowest._

### Sexual Harassment

Sexual harassment includes unwelcome comments or advances of a sexual nature.

Examples:

- _Milf alert._
- _She's got a nice ass._
- _You can sit on my face :P._
- _He's going to bang her good tonight._
- _I just masturbate._
- _You suck the best cock._
- _He likes it up the bum._
- _Spread your legs._
- _Kiss my balls._
- _You have nice tits._

### Moral Harassment

Moral harassment includes comments that aim to degrade or humiliate someone.

Examples:

- _They deserve to die._
- _Shoot the bitch._
- _Hope they die a slow death._
- _He should rot in hell._
- _Off with his head._
- _I hope they break your wrist._
- _Shoot them._
- _Kay, why is?_
- _Hang him._
- _He should be killed._

### Terrorism & Violent Extremism

Terrorism and violent extremism include support or promotion of terrorist activities or ideologies.

Examples:

- _Heil Hitler!_
- _Hitler was right._
- _An Austrian painter was a good guy._
- _I'm a school shooter._
- _You deserve another 🛫🏢🏢💣💣._

### Pedophilia

Pedophilia includes comments that express sexual interest in minors.

Examples:

- _I like to fuck minors._
- _If her age is on the clock, then she can suck this cock._
- _Me playing with small boys' dicks._
- _I'm masturbating to child porn._
- _I know you're not legal, but I still think you're sexy._

### SCAM

Scam includes fraudulent schemes or deceptive practices.

Examples:

- _Send me a private message; you have won a prize._
- _Message me now; I have something for you, okay?_
- _Send me a friend request or message me, handsome._
- _I've got 4 tickets available; PM if interested._

### FLOOD

Flood includes excessive or repetitive posting of messages.

Examples:

- _▔▔▔▔▔▔▔▔▔▔▔ ╲🔴🔵 ▕╮╭┻┻╮╭┻┻╮╭▕╮╲ ▕╯┃╭╮┃╭╮┃╰▕╯╭▏ ▕╭┻┻┻┛┗┻┻┛ ╰▏ ▕╰━━━┓┈┈┈╭╮▕╭╮▏ ▕╭╮╰┳┳┳┳╯╰╯▕╰╯▏ ▕╰╯┈┗┛┗┛┈╭╮._

### Forbidden Link

Forbidden link includes sharing links to prohibited or harmful websites.

Examples:

- _If you want to know more, you can check this website: example-website.com._

### Useless

Useless comments include irrelevant or trivial messages that do not contribute to the conversation.

Examples:

- _First ❤️._
- _2NDDDD._
- _This is the 666th comment._
- _I'm the first to comment._
- _I'm the 3rd._

### Ads

Ads include promotional messages or advertisements.

Examples:

- _Follow my page._
- _Subscribe to me; my YouTube name is Artymonx_plaz._

### Platform Bypass

Platform bypass includes attempts to move the conversation to another platform.

Examples:

- _Can we talk on Snap? It's better._
- _Go Telegram?_
- _FROG, DO YOU HAVE DISCORD?_

### Negative Criticism

Negative criticism includes harsh or unconstructive comments.

Examples:

- _Shame on you!_
- _Boring af._
- _This guy is overrated._
- _This is not funny at all._
- _Daughter is disrespectful._
- _I hope you aren't actually that naive or ignorant._
- _That chick is annoying._
- _They look ridiculous._
- _People are so entitled._
- _Another waste of time with a cut-off video._

### Boycott

Boycott includes calls to avoid or stop supporting certain products or companies.

Examples:

- Low Severity
  - _It's an Israeli product; we have to boycott this._
  - _We're not buying; boycott all brands that support Zionism!_
  - _But I will boycott this company as it owns this fashion brand._
  - _Don't buy them!_
- High Severity
  - _Boycott this brand; free Palestine._
  - _Stop buying from this brand._

### PII

PII includes sharing personally identifiable information without consent.

Examples:

- _17yo 5"9🧍🏾._
- _I msg 6827851099; Insta: duckedoffn3ro; I'm not texting first; princess treatment or nothing, and I'm never on here, so 🤷🏽._
- _Text me +1 774-578-1448 since I can't text here._
- _My Fortnite account is jerryy_69; I'll add my Insta later tonight; I'm hella introverted, so I gotta get close to you; my number is 559-373-8181; text me if you want._
- _Hi, my email address is `user@example.com`._

### Underage User

Underage user includes statements indicating that the user is below the minimum age. The threshold is configurable: under 13, 16, or 18. [Contact support](https://getstream.io/contact/support/) to change it for your app.

Examples:

- _I'm not thirteen yet._
- _I'm in 8th grade, but I'm still 12._
- _I go to elementary school._
- _I'm about to turn 11._

### Link

Link includes sharing URLs or hyperlinks.

Examples:

### Dating

Dating includes comments expressing romantic interest or seeking relationships.

Examples:

- _I'm looking for a relationship too, and you're very beautiful._
- _I am single; what about you?_
- _Do you want to be my girlfriend?_

### Politics

Politics includes comments related to political matters or figures.

Examples:

- _I sent a direct message to her and never got a response. She is protecting Trudeau and Singh._
- _Are you saying Trump has been outsmarted by Biden? If this is what Sleepy Joe can do,... just think what Putin can do._
- _Five more weeks of this; they might implode, and a hung parliament, the prize escaped them._
- _PM Modi's Kolkata Roadshow touches 3 destinations linked to iconic figures._
- _This means they would need to form a coalition with one of the populist parties, such as the Economic Freedom Fighters, or uMkhonto weSizwe, or the center-right Democratic Alliance party._

### Geopolitical

Geopolitical includes comments related to international relations or global issues.

Examples:

- _ACAB._
- _#FreePalestine now 🇵🇸._
- _Defund the police and government._
- _❤️❤️❤️❤️🇮🇱🇮🇱🇮🇱._
- _Genocide in Gaza._

### Terrorism Reference

Terrorism reference includes mentions of terrorist organizations or activities.

Examples:

- _Hezbollah is a Lebanese Shia Islamist political party._
- _Actually, PAFF claimed the attack on their official channel on Telegram._
- _✈️🏢._

### Vulgarity

Vulgarity includes the use of crude or offensive language.

Examples:

- Low Severity
  - _Bitch, try me._
  - _I need this af._
  - _Oh shit._
  - _That's a chickenshit call._
  - _She bought some shitty used car._
- High Severity
  - _Stop dickriding._
  - _She likes saying pussy pink._
  - _Rihanna said I'm tired of meat riders._
  - _Nah, there's 🍆🚴 than there's this._
  - _I'm so over dick riders and fakes._

### Sexually Explicit

Sexually explicit includes comments that are sexually graphic or suggestive.

Examples:

- Low Severity
  - _Freeze your butt off time._
  - _Pornography is for adults only._
  - _Maybe she only wants to be friends with benefits._
  - _The new Olympic mascot looks like a vagina._
  - _If you don't want children, just use a condom._
- High Severity
  - _She probably has a secret OnlyFans account._
  - _It's a website that sells dildos._
  - _Someone's getting a blow job tonight 🙄._
  - _Nude content?_
  - _He probably watches hentai; don't listen to him._

### Drug Explicit

Drug explicit includes comments related to drug use or trafficking.

Examples:

- Low Severity
  - _He gave up the marijuana, I hear._
  - _I said doctors are the biggest drug dealers._
  - _Drug trafficking?_
  - _I don't know why rappers name themselves after things like Xanax._
  - _There's a dispensary next to the gas station._
- High Severity
  - _Was it meth or weed?_
  - _Go smoke a joint and realize it'll all be okay._
  - _That's a packet of heroin._
  - _I heard they got coke that was laced with fentanyl._
  - _24g of coke._

### Weapon Explicit

Weapon explicit includes comments related to weapons or their use.

Examples:

- Low Severity
  - _I've got pepper spray to defend myself._
  - _Should have brought a bag of airsoft guns to that place._
  - _You can buy a gun for under $200?_
  - _Somebody has stuck a knife in me..._
  - _Just bring the machete._
- High Severity
  - _Atomic bomb._
  - _You need a rifle and backhoe._
  - _Maybe a shotgun would be better._
  - _I use a Glock._
  - _Did he actually nuke the moon?_

### Counterfeiting

Counterfeiting (`COUNTERFEITING`) includes promoting or selling fake goods.

Examples:

- _Selling 1:1 replica designer bags, same quality as the store._
- _DM me for cheap fake sneakers, nobody can tell the difference._

### Extremism

Extremism (`EXTREMISM`) includes promoting or glorifying extremist ideologies, violent movements, or radicalization.

Examples:

- _Join the movement, it's time to take the country back by force._

### Sexting

Sexting (`SEXTING`) includes playful or respectful sexual comments between adults. Unlike sexual harassment, it is not violent or degrading.

Examples:

- _Send me something spicy tonight._
- _Want to see what I'm wearing? Show me yours first._

### Trolling

Trolling (`TROLLING`) includes confusing or manipulative messages posted to provoke a reaction.

Examples:

- _Imagine still playing this dead game, lol._
- _Cry harder, this thread is hilarious._

### Spam

Spam (`SPAM`) is unwanted content sent repeatedly to many people. It is detected from timing and repetition across messages, so no single message is an example on its own.

### Forbidden Language

Forbidden language (`FORBIDDEN_LANGUAGE`) matches messages written in a language that is not allowed for your app. Contact support to configure the allowed languages.

### Pedophilia Reference

Pedophilia reference (`PEDOPHILIA_REFERENCE`) includes references to child sexual abuse, excluding first-person statements of intent.

Examples:

- _The coach was arrested for abusing kids on his team._

### Health Concerns

Health concerns (`HEALTH_CONCERNS`) includes reports of negative physical reactions, health concerns, or safety risks, for example related to a product.

Examples:

- _Your product gave me a rash, I'm never using it again._

### Custom labels

These labels are only returned when they are enabled for your app. On other apps you can select them in a policy, but they never match. [Contact support](https://getstream.io/contact/support/) to enable them.

| Label                          | Description                                                                        |
| ------------------------------ | ---------------------------------------------------------------------------------- |
| `DANGEROUS_BEHAVIOR_PROMOTION` | Encouraging or glorifying dangerous or harmful behavior.                           |
| `MARKETPLACE_FALSE_CLAIMS`     | False or misleading claims about items, sellers, or listings.                      |
| `MARKETPLACE_GAMIFICATION`     | Attempts to manipulate marketplace mechanics, such as bids, ratings, or giveaways. |

### Topical labels

`CYBERSECURITY`, `FINANCE`, `ENCOURAGEMENT`, `SUPPORTIVE`, and `FAIRPLAY` describe what a message is about rather than a harm. Use them to route or tag content, for example to send finance talk on a marketplace to review. A result with only these labels is treated like a neutral one.

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/engines/ai-text/](https://getstream.io/moderation/docs/node/engines/ai-text/).

---

# Image Moderation

Stream's image moderation engine detects harmful or inappropriate images. By default it runs asynchronously: images are processed in the background so they don't add latency, and actions are applied as soon as the analysis is complete. To get the verdict in the same request instead, [moderate images synchronously](#synchronous-moderation).

## Supported Categories

These are the categories shown in the dashboard image policy editor. Set an action and a confidence threshold per category, and narrow a category to some of its subcategories with `subclassifications`.

The subcategories depend on the image classifier enabled for your app, so your app uses one of the two lists below. The dashboard always shows the list that applies to your app.

### Subcategories (list A)

| Category                                          | Subcategory                    | What it detects                                                                                                                      |
| ------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| Explicit                                          | CSAM                           | Child sexual abuse material, including computer-generated images. Always act on it immediately and report it where the law requires. |
|                                                   | Sexual Activity                | Explicit sexual acts between people.                                                                                                 |
|                                                   | Graphic Nudity                 | Explicit, non-artistic nudity: fully exposed genitals, buttocks, or breasts in a sexual context.                                     |
|                                                   | Adult Toys                     | Items designed for sexual stimulation.                                                                                               |
| Non-Explicit Nudity of Intimate parts and Kissing | Partial Nudity                 | Partially or barely covered breasts or buttocks.                                                                                     |
|                                                   | Suggestive Poses & Erotica     | Erotic content or sexually suggestive poses without explicit nudity.                                                                 |
|                                                   | Revealing Attire               | Highly revealing clothing, such as lingerie or swimwear, in a sexual pose or context.                                                |
|                                                   | Bare Male Chest                | A bare male torso, or one visible through sheer fabric. Excludes opaque tank tops and babies.                                        |
|                                                   | Nudity in Art or Education     | Nudity in a clearly artistic (painting, sculpture) or educational (anatomy diagram) context.                                         |
| Swimwear or Underwear                             | Female Swimwear or Underwear   | Women in swimwear or visible underwear. Excludes sports bras.                                                                        |
|                                                   | Male Swimwear or Underwear     | Men in swimwear or visible underwear with nothing on top.                                                                            |
| Violence                                          | Extreme Violence & Gore        | Graphic violence: severe injuries, mutilation, corpses, or large amounts of blood.                                                   |
|                                                   | Physical Violence              | Non-graphic fights or assaults. Excludes regulated combat sports and video games.                                                    |
|                                                   | Weapons                        | Weapons used or shown in a threatening context. Excludes games, sports, art, and law enforcement.                                    |
| Visually Disturbing                               | Self Harm                      | Self-harm or suicide, or content that glorifies it.                                                                                  |
|                                                   | Visually Disturbing            | Shocking but non-gory content, such as accidents or emaciated bodies.                                                                |
|                                                   | Body Waste                     | Human or animal waste.                                                                                                               |
| Drugs & Tobacco                                   | Drugs & Controlled Substances  | Illegal drugs, drug paraphernalia such as syringes or bongs, or drug use.                                                            |
|                                                   | Tobacco & Vaping               | Smoking or vaping, or prominently shown tobacco and vaping products.                                                                 |
| Alcohol                                           | Alcohol                        | Drinking alcohol or prominently shown open containers. Excludes sealed bottles and background presence.                              |
| Rude Gestures                                     | Offensive Gestures             | Hand gestures widely seen as offensive or obscene, such as the middle finger.                                                        |
| Gambling                                          | Gambling                       | Casino games, slot machines, or sports betting.                                                                                      |
| Hate Symbols                                      | Hate Speech & Symbols          | Symbols, text, or imagery tied to hate or terrorist groups. Excludes religious or cultural symbols outside a hateful context.        |
| PII                                               | Sensitive Personal Information | Clearly legible sensitive information, such as ID cards or credit cards.                                                             |
| QR Code                                           | QR Code                        | A QR code, which can send users to an external URL.                                                                                  |

### Subcategories (list B)

| Category                                          | Subcategories                                                                                                                                                                         |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Explicit                                          | Exposed Male Genitalia, Exposed Female Genitalia, Exposed Buttocks or Anus, Exposed Female Nipple, Explicit Sexual Activity, Sex Toys                                                 |
| Non-Explicit Nudity of Intimate parts and Kissing | Bare Back, Exposed Male Nipple, Partially Exposed Buttocks, Partially Exposed Female Breast, Implied Nudity, Obstructed Female Nipple, Obstructed Male Genitalia, Kissing on the Lips |
| Swimwear or Underwear                             | Female Swimwear or Underwear, Male Swimwear or Underwear                                                                                                                              |
| Violence                                          | Weapons, Weapon Violence, Physical Violence, Self-Harm, Blood & Gore, Explosions and Blasts                                                                                           |
| Visually Disturbing                               | Emaciated Bodies, Corpses, Air Crash                                                                                                                                                  |
| Drugs & Tobacco                                   | Pills, Smoking                                                                                                                                                                        |
| Alcohol                                           | Drinking, Alcoholic Beverages                                                                                                                                                         |
| Rude Gestures                                     | Middle Finger                                                                                                                                                                         |
| Hate Symbols                                      | Nazi Party, White Supremacy, Extremist                                                                                                                                                |
| Gambling, PII, QR Code                            | No subcategories                                                                                                                                                                      |

Images have no severity levels: each category is matched by its confidence score. `queryModerationRules` returns your app's subcategories as `ai_image_subclassifications`.

To moderate text inside images, such as a phone number in a screenshot, add `ocr_rules`. Extracted text is classified with the [AI Text](https://getstream.io/moderation/docs/node/engines/ai-text/) labels.

## Supported Formats

Image moderation accepts the following formats:

- JPEG (`.jpg`, `.jpeg`)
- PNG (`.png`)
- GIF (`.gif`)\*. For animated GIFs, only the first frame is moderated.
- WebP (`.webp`)\*
- SVG (`.svg`)\*
- HEIC/HEIF (`.heic`, `.heif`)\*\*

\* Converted to JPEG or PNG for moderation only. The stored file is not changed.

\*\* Converted to JPEG when uploaded to Stream's CDN, so the stored file is a JPEG and is moderated as one. HEIC/HEIF images hosted outside Stream's CDN are not moderated.

The following MIME types are accepted:

- `image/jpeg`, `image/jpg`
- `image/png`
- `image/gif`
- `image/webp`
- `image/svg+xml`

The format is detected from the file contents, falling back to the `Content-Type` header. Images in other formats are not moderated. This includes BMP, which can be uploaded to Stream's CDN but is not converted, as well as TIFF and AVIF. To keep unsupported uploads out entirely in Stream Chat, configure the app's image upload allowlist or blocklist from the [dashboard](https://getstream.io/signin/?product=moderation). This is a Stream Chat upload setting, not part of the Moderation API; for standalone moderation, filter file types in your own upload flow.

## Confidence Scores

For each category, set a confidence threshold between 1 and 100. An action triggers only when the engine's confidence for that category is at or above the threshold.

- A **higher** threshold (80-90) only matches highly confident detections. It catches less and produces fewer false positives.
- A **lower** threshold (40-50) catches more, including borderline images, and produces more false positives.

For strict enforcement, such as explicit content on a platform for teens, lower the threshold so more is detected. For categories where false positives hurt more than misses, raise it. Start with the default (50) and adjust from what you see in the review queue.

## Configuration

Set up image moderation with `ai_image_config` on a [policy](https://getstream.io/moderation/docs/node/configuration/policies/). `min_confidence` is required on every image rule. The scale is 0-100 and the default is 50. A higher value flags less: 90 only matches highly confident detections.

```js
await client.moderation.upsertConfig({
  key: "chat:messaging",
  ai_image_config: {
    rules: [
      { label: "Explicit", action: "remove", min_confidence: 70 },
      { label: "Violence", action: "flag", min_confidence: 50 },
    ],
    ocr_rules: [{ label: "PII", action: "flag" }],
  },
});
```

Image rule actions are `flag`, `shadow`, `remove`, `bounce`, `bounce_flag`, and `bounce_remove`. `subclassifications` narrows a label to its L2 children. `queryModerationRules` returns `ai_image_label_definitions` and `ai_image_subclassifications` for the exact strings.

## Send images

Send image URLs in `moderation_payload.images` (up to 30) with the [Check API](https://getstream.io/moderation/docs/node/content-moderation/check/#check). Stream Chat and Feeds send attached images for you.

```js
const response = await client.moderation.check({
  entity_type: "listing",
  entity_id: "listing-123",
  entity_creator_id: "user-42",
  config_key: "marketplace",
  moderation_payload: {
    images: ["https://cdn.example.com/listings/123/photo-1.jpg"],
  },
});
```

To send image bytes instead of URLs, use [Analyze](https://getstream.io/moderation/docs/node/content-moderation/check/#image-bytes-http-only).

### Images on your own CDN

Image moderation works with any CDN, as long as Stream's servers can download the image with a plain `GET`. Signed URLs work if they are still valid when Stream fetches them. Private S3 objects use a `stream+s3://` URL. `client.moderation.checkS3Access()` checks that the configured IAM role can read them; pass `s3_url` to test one object.

To moderate a large set of existing images, `client.moderation.bulkImageModeration({ csv_file })` takes a CSV of image URLs and returns a `task_id`. Completion arrives as `export.bulk_image_moderation.success`.

## How It Works

By default, image moderation is asynchronous:

1. The image is accepted immediately to maintain low latency.
2. Analysis begins in the background, and the Check response has `status: "pending"`.
3. The engine evaluates the image against all configured categories.
4. If a confidence threshold is met, the configured action is applied. Stream Chat and Feeds update the message or post.
5. Flagged images appear in the review queue, and a `review_queue_item.new` webhook is sent.

### Synchronous moderation

To hold an image until it's checked, turn on **Process images synchronously** in the dashboard image policy, or set `async: false` on `ai_image_config`. Check then returns the image verdict in its response, and Stream Chat applies the action before the message is delivered.

```js
await client.moderation.upsertConfig({
  key: "marketplace",
  ai_image_config: {
    async: false,
    rules: [{ label: "Explicit", action: "remove", min_confidence: 50 }],
  },
});
```

Synchronous moderation adds the analysis time to the request. An image that was already moderated on upload reuses that verdict.

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/engines/image-moderation/](https://getstream.io/moderation/docs/node/engines/image-moderation/).

---

# Video Moderation

Stream's video moderation engine samples frames from an uploaded video and scores each frame with the same AI categories you use for images. The video takes the strictest frame verdict. Analysis runs asynchronously so the upload is not held back.

Results are returned as `ai_video`. Existing video rules, the review queue, webhooks, and billing keep working.

## How it works

When a video is uploaded:

1. The video is accepted immediately.
2. Stream samples frames evenly across the whole video (default one frame per second). If the video is long, the sample rate is thinned so the full video is still covered.
3. Each frame is scored against your video policy rules (the same label and confidence model as image moderation).
4. The video action is the strictest frame action. Labels from every flagged frame are combined.
5. The message or post is updated when analysis finishes.
6. Flagged videos appear in the [content review queue](https://getstream.io/moderation/docs/node/content-moderation/review-queue/). Open **Moderation > Review Queue** in the [dashboard](https://getstream.io/signin/?product=moderation).

You can change how densely frames are sampled in the [dashboard](https://getstream.io/signin/?product=moderation) video policy.

## Supported categories

These are the categories shown in the dashboard video policy editor. Video uses the [image moderation](https://getstream.io/moderation/docs/node/engines/image-moderation/#supported-categories) categories, without PII and QR Code, and has no subcategories:

- Explicit
- Non-Explicit Nudity of Intimate parts and Kissing
- Swimwear or Underwear
- Violence
- Visually Disturbing
- Drugs & Tobacco
- Alcohol
- Rude Gestures
- Gambling
- Hate Symbols

Set a confidence threshold per category (1 to 100). Higher values flag less. A threshold of 90 only matches highly confident frames, which means fewer flags and fewer false positives.

## Supported formats

Video moderation accepts most common video containers and codecs, including:

- MP4 (`.mp4`, `.m4v`)
- QuickTime (`.mov`), including iPhone recordings in HEVC (H.265) and HDR
- WebM (`.webm`)
- Matroska (`.mkv`)
- AVI (`.avi`)
- MPEG (`.mpg`, `.mpeg`, `.ts`)
- 3GP (`.3gp`)
- FLV (`.flv`)
- WMV (`.wmv`)

Supported video codecs include H.264, H.265 (HEVC), VP8, VP9, AV1, MPEG-2, MPEG-4 Part 2, and ProRes.

The format is detected from the file contents, not the extension. The file must include duration metadata. Videos without it are not moderated. To keep unsupported uploads out entirely in Stream Chat, configure the app's file upload allowlist or blocklist from the [dashboard](https://getstream.io/signin/?product=moderation). This is a Stream Chat upload setting, not part of the Moderation API; for standalone moderation, filter file types in your own upload flow.

## Configuration

Set an action for each category you care about on `ai_video_config`, with a required `min_confidence` on a 0-100 scale, the same shape as image rules. Video and image are set separately in the policy, so video settings don't affect image moderation. Live calls use `video_call_rule_config`, not this field.

```js
await client.moderation.upsertConfig({
  key: "chat:messaging",
  ai_video_config: {
    rules: [
      { label: "Explicit", action: "remove", min_confidence: 70 },
      { label: "Violence", action: "flag", min_confidence: 50 },
    ],
  },
});
```

Actions are `flag`, `shadow`, `remove`, `bounce`, `bounce_flag`, and `bounce_remove`. Use `flag` for borderline frames and `remove` for content that should not stay up.

Send video URLs in `moderation_payload.videos` with the [Check API](https://getstream.io/moderation/docs/node/content-moderation/check/#check). Stream Chat and Feeds send attached videos for you.

```js
const response = await client.moderation.check({
  entity_type: "listing",
  entity_id: "listing-123",
  entity_creator_id: "user-42",
  config_key: "marketplace",
  moderation_payload: {
    videos: ["https://cdn.example.com/listings/123/tour.mp4"],
  },
});
// response.status is "pending" until the video is analyzed
```

## Limitations

- **Analysis is always asynchronous.** The verdict arrives a few seconds to a few minutes after the request, depending on length. The `async` field on `ai_video_config` is ignored for video, and `force_sync` on Check skips video entirely, so don't use either to wait for a verdict.
- Very long videos are sampled more sparsely so the whole file is still covered.

### Hold a video until it's checked

Stream Chat and Feeds publish the video right away and update the message or post if it is flagged or removed. To keep a video hidden until it's confirmed safe in your own app:

1. Store the video as pending and don't show it to other users.
2. Call Check with the video. The response has `status: "pending"`.
3. Handle the `moderation_check.completed` [webhook](https://getstream.io/moderation/docs/node/content-moderation/webhooks/). It carries `entity_id`, `entity_type`, and `recommended_action`.
4. Publish the video when `recommended_action` is `keep`, and remove or hold it for review otherwise.

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/engines/ai-video-file-moderation/](https://getstream.io/moderation/docs/node/engines/ai-video-file-moderation/).

---

# Audio Moderation

Stream's audio moderation engine transcribes uploads and classifies the transcript. Voice messages, voice notes, and other audio attachments are processed asynchronously so the upload is not held back.

Transcription covers the languages listed below. Classification uses the text engine you attach: the [NLP engine's languages](https://getstream.io/moderation/docs/node/engines/ai-text/#language-support), or the [LLM engine](https://getstream.io/moderation/docs/node/engines/ai-llm-text/#language-support), which has no fixed language list.

## Language Support

Audio moderation supports the languages that the transcription service recognizes. The system automatically identifies the spoken language and transcribes accordingly. The following languages are officially supported:

>
> **Tip:** Languages outside this list may still transcribe, but with reduced accuracy. If audio in a specific language is important to your use case, we recommend validating quality on a sample before rolling out.
>

- Afrikaans
- Arabic
- Armenian
- Azerbaijani
- Belarusian
- Bosnian
- Bulgarian
- Catalan
- Chinese
- Croatian
- Czech
- Danish
- Dutch
- English
- Estonian
- Finnish
- French
- Galician
- German
- Greek
- Hebrew
- Hindi
- Hungarian
- Icelandic
- Indonesian
- Italian
- Japanese
- Kannada
- Kazakh
- Korean
- Latvian
- Lithuanian
- Macedonian
- Malay
- Marathi
- Maori
- Nepali
- Norwegian
- Persian
- Polish
- Portuguese
- Romanian
- Russian
- Serbian
- Slovak
- Slovenian
- Spanish
- Swahili
- Swedish
- Tagalog
- Tamil
- Thai
- Turkish
- Ukrainian
- Urdu
- Vietnamese
- Welsh

## Supported Formats

Audio moderation accepts the following file extensions:

- `.mp3`
- `.mpga`
- `.mpeg`
- `.mp4`
- `.m4a`
- `.wav`
- `.webm`

The following MIME types are accepted:

- `audio/mpeg`, `audio/mp3`
- `audio/mp4`, `audio/x-m4a`
- `audio/wav`, `audio/wave`, `audio/x-wav`, `audio/vnd.wave`
- `audio/webm`
- `video/mp4` (for MP4 containers that carry audio)
- `application/octet-stream` (the default for many CDNs and S3 buckets)

Uploads with a MIME type outside this allowlist are skipped without moderating. To keep unsupported uploads out entirely in Stream Chat, configure the app's file upload allowlist or blocklist from the [dashboard](https://getstream.io/signin/?product=moderation). This is a Stream Chat upload setting, not part of the Moderation API; for standalone moderation, filter file types in your own upload flow.

## Limitations

- Each request can include a maximum of 10 audio attachments. Requests with more attachments are rejected before transcription.
- Audio files must be no larger than 25 MB. Larger files are skipped without moderating.
- Audio moderation runs asynchronously, so audio is accepted immediately without any latency. It will take a few seconds or minutes for moderation to complete. Once the moderation is complete, the audio will be either blocked or flagged depending on the configured rules.
- Only spoken content is analyzed. Music, ambient noise, and other non-speech audio are moderated only to the extent that the transcription model surfaces recognizable words.

## Configuration

Audio has its own configuration. Text policy rules do not apply to transcripts until you put them on `ai_audio_config`. Put NLP rules in `ai_text_config` or LLM rules in `llm_config`. The top-level `rules` array is the legacy fallback, used only when the matching engine config is empty. Audio moderation stays off until at least one rule with an action is set on `ai_audio_config`.

```js
await client.moderation.upsertConfig({
  key: "chat:messaging",
  ai_audio_config: {
    ai_text_config: {
      rules: [{ label: "HATRED", action: "flag" }],
    },
  },
});
```

See [AI Text (NLP)](https://getstream.io/moderation/docs/node/engines/ai-text/) or [AI Text (LLM)](https://getstream.io/moderation/docs/node/engines/ai-llm-text/) for labels and actions.

## Send audio

Send audio files, not transcripts. Put up to 10 audio URLs in `moderation_payload.audios` on a [Check](https://getstream.io/moderation/docs/node/content-moderation/check/#check) call; Stream downloads, transcribes, and classifies each one. Stream Chat voice messages and Feeds audio attachments are sent for you.

```js
const response = await client.moderation.check({
  entity_type: "voice_note",
  entity_id: "voice-note-123",
  entity_creator_id: "user-42",
  config_key: "chat:messaging",
  moderation_payload: {
    audios: ["https://cdn.example.com/voice/123.m4a"],
  },
});
// response.status is "pending" until transcription and classification finish
```

The audio URL must be downloadable with a plain `GET`. The result arrives with the `moderation_check.completed` and `review_queue_item.new` [webhooks](https://getstream.io/moderation/docs/node/content-moderation/webhooks/). Like video, audio is always asynchronous, and `force_sync` on Check skips it.

If you already have your own transcript, send it in `moderation_payload.texts` instead. It is moderated by your text rules, not your audio rules.

## How It Works

When an audio file is uploaded:

1. The audio is accepted immediately to maintain low latency.
2. Transcription begins asynchronously in the background.
3. The resulting transcript is evaluated against the harm categories configured on the audio configuration.
4. If a rule matches, its action is applied.
5. The message or post is updated based on moderation results.
6. Flagged audio appears in the Review Queue with the audio URL and transcript attached, so moderators can read what was said before deciding.

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/engines/ai-audio-file-moderation/](https://getstream.io/moderation/docs/node/engines/ai-audio-file-moderation/).

---

# Usernames & Images

Check usernames and profile images before you create or update a user.

> **Warning:** This endpoint usage will be counted towards your text and image moderation quota.
>

## Overview

User profile moderation allows you to check both usernames and profile images using a single API endpoint and unified policy configuration. You can:

- **Moderate usernames** using AI (LLM), custom blocklists, or pattern-based detection
- **Moderate profile images** with the image engine and OCR
- **Combine multiple providers** for layered protection
- **Configure once** - the same policy handles both usernames and images

### User profile policies vs. username policies

There are two kinds of policy for user profiles. Pick one based on what you need to check:

|                    | User profile policy (`user_profile:default`)                                                                | Username policy (`username:<name>`)                                                                                              |
| ------------------ | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Use it when**    | You want to check a username and a profile image together, with the same policy                             | You only check usernames and want the fastest, cheapest check                                                                    |
| **Checks**         | Username text and profile images                                                                            | Username text only                                                                                                               |
| **API**            | [Check](https://getstream.io/moderation/docs/node/content-moderation/check/) with `entity_type: "stream:v1:user_profile"` | [Labels](https://getstream.io/moderation/docs/node/content-moderation/labels/) with `content_type: "username"` and `policy: "username:<name>"` |
| **Engines**        | AI text (LLM or NLP), blocklists, image engine, and OCR                                                     | A username-tuned classifier plus blocklists, which run first                                                                     |
| **Severity rules** | Supported                                                                                                   | Not supported: one action per label                                                                                              |
| **Review queue**   | Flagged profiles appear as user profile items                                                               | No; results are returned inline                                                                                                  |

### Configuring User Profile Moderation

Username and profile image moderation can operate in different modes depending on your configuration. You can combine multiple moderation providers (LLM, blocklists, OCR, etc.) for comprehensive protection.

#### Step 1: Configure Your Moderation Policy

1. Navigate to the [Stream Dashboard](https://getstream.io/signin/?product=moderation)
2. Go to **Moderation** → **Policies**
3. Select or create a policy for user profile moderation (e.g., `User Profile`)
4. Configure the providers you want to use

## Username Moderation

Before creating or updating a user profile, you can check if the username complies with basic moderation rules to help maintain a safe environment for your users.

### AI Text - Recommended

- Most advanced detection using Large Language Models
- Catches nuanced violations and creative circumvention
- Out-of-the-box labels provided include PROFANITY, HATE_SPEECH, IMPERSONATION, SCAM, MISLEADING_IDENTITY

These labels cover the most common moderation scenarios and help you get started quickly. You can customize actions for each label or add your own.

### AI Text (NLP)

With the NLP engine, usernames are classified against their own label set. The engine reads the whole string in context, so a term that is harmful on its own (such as "plug") isn't flagged when it's clearly part of something harmless (such as "spark_plug"). Usernames have no severity levels: set one action per label.

| Label                | Description                                                                                                                                                        |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `BODY_SHAMING`       | Mocks, degrades, or attacks physical appearance or weight.                                                                                                         |
| `DRUG_EXPLICIT`      | Promotes or references illegal drugs, narcotics, or drug dealing.                                                                                                  |
| `EXTREMISM`          | Promotes terrorist organizations, violent extremism, or radicalization.                                                                                            |
| `INSULT`             | Direct, targeted profanity or degrading insults.                                                                                                                   |
| `LGBTQIAPLUS_PHOBIA` | Slurs, mockery, or hate speech aimed at the LGBTQIA+ community.                                                                                                    |
| `MISOGYNY`           | Hatred, prejudice, or harmful stereotypes about women.                                                                                                             |
| `PII`                | Sensitive personal information, such as a phone number, email address, physical address, or government ID. A plain first and last name is `PII_REAL_NAME` instead. |
| `PII_REAL_NAME`      | A person's real first and last name. Username policies only.                                                                                                       |
| `RACISM`             | Racial slurs, stereotypes, or hate speech based on race or ethnicity.                                                                                              |
| `SEXUALLY_EXPLICIT`  | Explicit sexual acts, crude anatomical references, or pornography.                                                                                                 |

### Blocklists

- Create custom blocklists in Moderation → Advanced Filters
- Fast pattern matching for known bad words
- Uses substring matching for usernames (e.g., blocking "bad" matches "baduser123")

### Check Username

For a low-latency username check, call `POST /api/v2/moderation/labels`. `content` is required. Set `content_type` to `username` and `policy` to a key that starts with `username:` (for example `username:default`). Blocklists answer first. The response `recommended_action` is `keep`, `flag`, or `remove`.

```js
const response = await client.moderation.labels({
  content: "username_to_check",
  content_type: "username",
  policy: "username:default",
});

if (response.recommended_action === "keep") {
  // Username is acceptable
}
```

The samples below are the general `check` path, for a full user-profile policy rather than the username fast path.

```js label="JavaScript"
const response = await client.moderation.check({
  entity_type: "stream:v1:user_profile",
  entity_id: userId,
  entity_creator_id: userId,
  moderation_payload: { texts: ["username_to_check"] },
  config_key: "user_profile:default",
});

// Response will indicate if the username is acceptable
if (response.recommended_action === "keep") {
  // Username is acceptable, proceed with user creation/update
} else {
  // Username violates moderation rules, ask user to choose a different name
}
```

## Profile Image Moderation

You can moderate images using Stream's AI Image Moderation Engine. This helps detect inappropriate or harmful image content before it's published on your platform.

### Check Profile Images

```js label="JavaScript"
const response = await client.moderation.check({
  entity_type: "stream:v1:user_profile",
  entity_id: userId,
  entity_creator_id: userId,
  moderation_payload: { images: ["https://example.com/profile.jpg"] },
  config_key: "user_profile:default",
});

// Handle the moderation result
if (response.recommended_action === "keep") {
  // Image is safe to use as profile picture
} else {
  // Image violates moderation rules
}
```

## Dashboard Integration

When LLM or blocklists are configured for usernames, or when image moderation is enabled, flagged content appears in your moderation dashboard.

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/engines/usernames-and-images/](https://getstream.io/moderation/docs/node/engines/usernames-and-images/).

---

# Build a Moderation Dashboard

Stream offers a built-in [moderation dashboard](https://getstream.io/signin/?product=moderation) to assist you in moderating content. However, you also have the option to create a custom moderation dashboard tailored to your product's needs. Stream provides all the necessary APIs that are used to build the moderation dashboard.

This guide will walk you through the process of building your own moderation dashboard using Stream's moderation APIs.

Start by setting up moderation for your content:

- [Moderate your own content](https://getstream.io/moderation/docs/node/integrations/custom-content/)
- [Stream Chat](https://getstream.io/moderation/docs/node/integrations/stream-chat/)
- [Stream Feeds](https://getstream.io/moderation/docs/node/integrations/stream-feeds/)
- [Stream Feeds - Legacy](https://getstream.io/moderation/docs/node/integrations/stream-feeds-v2/)

Once you have set up moderation for your use case, you can use the following APIs to build your own moderation dashboard.

There are three types of moderation UI you can build:

- UI to list flagged content
- UI to take action on flagged content
- UI to configure moderation policy

## Build UI for Review Queue

Use the `QueryReviewQueue` API to list flagged content in your own dashboard.

### Text Review Queue

You can use following code to query all the flagged contents in the review queue.

```js label="JavaScript"
const response = await client.moderation.queryReviewQueue(
  { entity_type: "stream:chat:v1:message", has_text: true },
  [{ field: "created_at", direction: -1 }],
  { next: null },
);
```

The `entity_type` is the type of content you are moderating. For example:

- If you are moderating chat messages, the `entity_type` would be `stream:chat:v1:message`.
- Feeds v2 activities use `stream:feeds:v2:activity`. Feeds v3 activities use `stream:feeds:v3:activity`.
- Feeds v2 comments use `stream:feeds:v2:reaction`. Feeds v3 comments use `stream:feeds:v3:comment`.
- If you are moderating custom content, the `entity_type` would be the type of your custom content.

`response.items` will contain the list of flagged items. Here, "item" refers to [review queue item](https://getstream.io/moderation/docs/node/content-moderation/review-queue/).

The following is an example of how to build a UI to list flagged content in the review queue.

The API secret stays on your server. The browser calls your backend, and the backend calls `queryReviewQueue`.

```jsx
import React, { useState, useEffect } from "react";

const ReviewQueueList = () => {
  const [items, setItems] = useState([]);

  useEffect(() => {
    const fetchData = async () => {
      const response = await fetch("/api/moderation/review-queue");
      const body = await response.json();
      setItems(body.items);
    };

    fetchData();
  }, []);

  return (
    <ul>
      {items.map((item) => (
        <li key={item.id}>
          <p>
            <strong>ID:</strong> {item.id}
          </p>
          <p>
            <strong>Texts:</strong> {item.moderation_payload.texts.join(", ")}
          </p>
          <p>
            <strong>Images:</strong> {item.moderation_payload.images.join(", ")}
          </p>
          <p>
            <strong>Videos:</strong> {item.moderation_payload.videos.join(", ")}
          </p>
          <p>
            <strong>Message:</strong> {item.message}
          </p>
          <p>
            <strong>Entity Creator:</strong> {item.entity_creator}
          </p>
          <p>
            <strong>Entity ID:</strong> {item.entity_id}
          </p>
          <p>
            <strong>Entity Type:</strong> {item.entity_type}
          </p>
          <p>
            <strong>Flags:</strong>{" "}
            {item.flags.map((flag) => flag.type).join(", ")}
          </p>
          <p>
            <strong>Recommended Action:</strong> {item.recommended_action}
          </p>
          <p>
            <strong>Created At:</strong> {item.created_at}
          </p>
        </li>
      ))}
    </ul>
  );
};
```

You can iterate over item.flags to get the list of moderation engines that flagged the content.

```js label="JavaScript"
for (const flag of item.flags) {
  console.log(flag.type); // moderation engine type
  console.log(flag.labels); // list of labels or harm types detected
  console.log(flag.custom); // more details about the flag
}
```

### Media Review Queue

You can use following code to query all the flagged messages with images in the review queue.

```js label="JavaScript"
const response = await client.moderation.queryReviewQueue(
  { entity_type: "stream:chat:v1:message", has_image: true },
  [{ field: "created_at", direction: -1 }],
  { next: null },
);
```

### Blocked Content

You can use following code to query all the blocked contents in the review queue.

```js label="JavaScript"
const response = await client.moderation.queryReviewQueue(
  { entity_type: "stream:chat:v1:message", recommended_action: "remove" },
  [{ field: "created_at", direction: -1 }],
  { next: null },
);
```

### Reviewed Content

You can use following code to query all the reviewed contents in the review queue.

```js label="JavaScript"
const response = await client.moderation.queryReviewQueue(
  { entity_type: "stream:chat:v1:message", reviewed: true },
  [{ field: "created_at", direction: -1 }],
  { next: null },
);
```

You can find more details about the `QueryReviewQueue` API [here](https://getstream.io/moderation/docs/node/content-moderation/review-queue/#query-review-queue).

## Build UI to Take Action on Review Queue Items

Use the `SubmitAction` API to act on review queue items from your own dashboard. For example, add a button that marks flagged content as reviewed:

```jsx
const markAsReviewed = async (itemId: string) => {
    await client.moderation.submitAction("mark_reviewed", itemId)
}

<Button onClick={() => markAsReviewed("item_id")}>Mark as Reviewed</Button>
```

Please refer to the [SubmitAction](https://getstream.io/moderation/docs/node/content-moderation/actions/#submit-action) API for more examples as listed below:

- [Ban a user](https://getstream.io/moderation/docs/node/content-moderation/actions/#ban-user)
- [Delete Chat Message](https://getstream.io/moderation/docs/node/content-moderation/actions/#delete-message)
- [Delete Feeds Activity](https://getstream.io/moderation/docs/node/content-moderation/actions/#submit-action)
- [Delete User](https://getstream.io/moderation/docs/node/content-moderation/actions/#submit-action)
- [Delete Feeds Reaction](https://getstream.io/moderation/docs/node/content-moderation/actions/#submit-action)
- [Unban User](https://getstream.io/moderation/docs/node/content-moderation/actions/#submit-action)
- [Restore Chat Message or Activity or Reaction](https://getstream.io/moderation/docs/node/content-moderation/actions/#restore-content)
- [Unblock Message](https://getstream.io/moderation/docs/node/content-moderation/actions/#submit-action)

## Build UI to Configure Moderation Policy

Stream provides a `UpsertConfig` API to configure moderation policy. You can use this API to build your own moderation dashboard to configure moderation policy.

Please refer to the [UpsertConfig](https://getstream.io/moderation/docs/node/configuration/policies/#upsert-config) API for more details.

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/guides/build-moderation-dashboard/](https://getstream.io/moderation/docs/node/guides/build-moderation-dashboard/).

---

# Bypass Moderation

Bypass user from moderation lets you exempt specific users from content moderation checks. This is useful for trusted users, such as moderators, bots, or staff accounts, whose content should be published without going through moderation pipelines.

There are three approaches:

1. **Permission-based bypass**: Grant the `SkipMessageModeration` permission to a role. This works for Chat only.
2. **User bypass flag**: Set the `bypass_moderation` flag on a user via the Dashboard or API. This works for Chat, Feeds, Comments, and the Check API.
3. **Server-side writes**: Content created from your backend skips moderation unless you set `force_moderation: true`. This works for Chat, Feeds, and Comments.

## Permission-Based Bypass (Chat Only)

Stream's permission system lets you grant the `SkipMessageModeration` action to specific roles. When a user with this permission sends a message, moderation is skipped entirely.

This approach is scoped to Chat message sending and requires the role-based permission system to be enabled on your app.

To grant `SkipMessageModeration` to a role in the [dashboard](https://getstream.io/signin/?product=moderation):

1. Open your app and go to **Settings → Roles & Permissions**
2. Select the **Role** (e.g., `admin`, or a custom `trusted_user` role)
3. Under **Chat**, pick the channel type (e.g., `messaging`) and open **Message moderation**
4. Check **Skip Message Moderation**
5. Click **Save**

Once assigned, any user with that role will bypass moderation when sending messages in channels of the selected channel type.

## User Bypass Flag (Chat, Feeds, Comments & Check)

The `bypass_moderation` flag can be set on individual users. When enabled, moderation is skipped for all content the user creates across Chat messages, Feeds activities, and Feed comments, and for [Check](https://getstream.io/moderation/docs/node/content-moderation/check/) calls where the user is the `entity_creator_id`, whatever the entity type.

### Enable or Disable Bypass

1. Navigate to **Settings → Users**
2. Find the user you want to manage
3. Click on the value in the **bypass_moderation** column to open a toggle
4. Toggle the switch to enable or disable bypass for that user
5. Confirm the change

Changes take effect immediately for any new content the user creates.

The same flag is `POST /api/v2/moderation/bypass` with `target_user_id` and `enabled`.

```js
await client.moderation.bypass({
  target_user_id: "user-123",
  enabled: true,
});
```

### Filter Users by Bypass Status

On the **Settings → Users** page, use the filter sidebar and select the `bypass_moderation` filter to quickly find all users with bypass enabled or disabled.

### Behavior When Bypass Is Enabled

When `bypass_moderation` is `true` for a user:

- **Chat messages**: Sent immediately without running any moderation rules (AI text, blocklists, image moderation, etc.)
- **Feeds activities**: Published immediately without moderation
- **Feed comments**: Posted immediately without moderation
- **Check API**: Returns without running any engines, for any entity type
- **Audit log**: An audit log entry is created with `BypassModeration: true` to maintain observability

Bypass does **not** affect:

- Manual flags raised by other users
- Actions taken by human moderators
- Ban or shadow-ban status

## Server-side writes and `force_moderation`

Content created from your backend skips moderation by default. Set `force_moderation: true` to moderate a server-side write.

`force_moderation` is **server-side only** and ignored when sent from a client-side SDK.

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/guides/bypass-moderation/](https://getstream.io/moderation/docs/node/guides/bypass-moderation/).

---

# Client Configuration

Stream's server-side SDKs ship with default HTTP settings designed for typical use. The shared pool and timeout knobs are documented on [Connection pooling](https://getstream.io/docs/platform/connection-pooling/). For high-traffic applications or specific network environments, you may need to tune these settings.

## Default Settings

Every server SDK defaults to a 30 second request timeout, a 10 second connect timeout, 100 connections per host, a 55 second idle timeout, and 3 retries. The [connection pooling](https://getstream.io/docs/platform/connection-pooling/) page is the source for those defaults and for the per-language constructors. The snippets below show how to override them.

## Customizing Settings

### Node

```js label="Node.js"
import { Agent } from "undici";

const client = new StreamClient("YOUR_API_KEY", "YOUR_API_SECRET", {
  timeout: 10000, // Request timeout in milliseconds
  agent: new Agent({
    keepAliveTimeout: 30000, // Keep-alive timeout in ms
    keepAliveMaxTimeout: 60000, // Max keep-alive timeout in ms
    connections: 50, // Max concurrent connections per host
    pipelining: 1, // HTTP pipelining
  }),
});
```

| Option    | Type   | Default | Description                                                       |
| --------- | ------ | ------- | ----------------------------------------------------------------- |
| `timeout` | number | 30000   | Request timeout in milliseconds. Default is 30 seconds.           |
| `agent`   | Agent  | Default | Custom Undici agent for connection pooling and keep-alive tuning. |

### Python

```python label="Python"
client = Stream(
    api_key="YOUR_API_KEY",
    api_secret="YOUR_API_SECRET",
    timeout=10.0,  # Request timeout in seconds
)
```

| Parameter | Type  | Default | Description                 |
| --------- | ----- | ------- | --------------------------- |
| `timeout` | float | 30.0    | Request timeout in seconds. |

The Python SDK uses `httpx.Client` internally with a pool of 10 connections per host. For advanced pooling, extend the base client with a custom `httpx.Client`.

### Go

```go label="Go"
// Create HTTP client with persistent connections and tuned settings
transport := &http.Transport{
    DialContext: (&net.Dialer{
        Timeout:   30 * time.Second,
        KeepAlive: 30 * time.Second,
    }).DialContext,
    MaxIdleConns:        100,
    MaxIdleConnsPerHost: 100,
    IdleConnTimeout:     90 * time.Second,
    TLSHandshakeTimeout: 10 * time.Second,
}

httpClient := &http.Client{
    Transport: transport,
    Timeout:   30 * time.Second,
}

client, err := getstream.NewClient("YOUR_API_KEY", "YOUR_API_SECRET",
    getstream.WithTimeout(30 * time.Second),
    getstream.WithHTTPClient(httpClient),
)
if err != nil {
    panic(err)
}
```

| Option                   | Default             | Description                                     |
| ------------------------ | ------------------- | ----------------------------------------------- |
| `WithTimeout(duration)`  | 30s                 | Request timeout.                                |
| `WithHTTPClient(client)` | Default http.Client | Custom HTTP client with full transport control. |
| `WithLogger(logger)`     | Default logger      | Custom logger for debugging.                    |

**Transport settings:**

| Setting                 | Default | Recommended | Description                                                  |
| ----------------------- | ------- | ----------- | ------------------------------------------------------------ |
| `DialContext.Timeout`   | 30s     | 30s         | TCP connection establishment timeout.                        |
| `DialContext.KeepAlive` | 30s     | 30s         | TCP keep-alive probe interval.                               |
| `MaxIdleConns`          | 100     | 100-200     | Max idle connections across all hosts.                       |
| `MaxIdleConnsPerHost`   | 2       | 50-100      | Max idle connections per host. Increase for high throughput. |
| `IdleConnTimeout`       | 90s     | 90s         | How long idle connections stay in the pool.                  |
| `TLSHandshakeTimeout`   | 10s     | 10s         | TLS handshake timeout.                                       |

### Java

```java label="Java"
// Via properties
Properties props = new Properties();
props.put("io.getstream.apiKey", "YOUR_API_KEY");
props.put("io.getstream.apiSecret", "YOUR_API_SECRET");
props.put("io.getstream.timeout", "15000");  // Request timeout in milliseconds

var client = new StreamSDKClient(props);
```

| Property               | Env Variable         | Default | Description                                             |
| ---------------------- | -------------------- | ------- | ------------------------------------------------------- |
| `io.getstream.timeout` | `STREAM_API_TIMEOUT` | 10000   | Request timeout in milliseconds (OkHttp `callTimeout`). |

The Java SDK uses OkHttp with a connection pool of 5 idle connections and 59-second idle timeout. For custom pooling, provide a configured `StreamHTTPClient` instance.

### PHP

```php label="PHP"
use GuzzleHttp\Client as GuzzleClient;

// Custom Guzzle client with tuned settings
$httpClient = new GuzzleClient([
    'timeout' => 15,           // Request timeout in seconds
    'connect_timeout' => 5,    // Connection timeout in seconds
]);

$client = (new ClientBuilder())->apiKey('YOUR_API_KEY')
    ->apiSecret('YOUR_API_SECRET')
    ->httpClient($httpClient)
    ->build();
```

| Setting           | Default    | Description                                                                                       |
| ----------------- | ---------- | ------------------------------------------------------------------------------------------------- |
| `timeout`         | 30s        | Request timeout in seconds.                                                                       |
| `connect_timeout` | 10s        | TCP connection timeout in seconds.                                                                |
| Retry on 429      | 3 attempts | Automatic exponential backoff with jitter on [rate limit](https://getstream.io/docs/platform/rate-limits/) responses. |

### Ruby

```ruby label="Ruby"
client = GetStreamRuby::Client.new(
  api_key: "YOUR_API_KEY",
  api_secret: "YOUR_API_SECRET",
  timeout: 15,  # Request timeout in seconds
)
```

| Parameter | Default    | Description                                                  |
| --------- | ---------- | ------------------------------------------------------------ |
| `timeout` | 30s        | Request timeout in seconds.                                  |
| Retry     | 3 attempts | Exponential backoff (0.05s base, 2x factor, 0.5 randomness). |

### .NET

```csharp label="C#"
// The .NET SDK uses HttpClient with framework defaults.
// For production tuning, configure via IHttpClientFactory:
builder.Services.AddHttpClient("stream", client =>
{
    client.Timeout = TimeSpan.FromSeconds(15);
})
.ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler
{
    PooledConnectionLifetime = TimeSpan.FromMinutes(2),
    PooledConnectionIdleTimeout = TimeSpan.FromMinutes(1),
    MaxConnectionsPerServer = 50,
});
```

| Setting                    | Default   | Description                                        |
| -------------------------- | --------- | -------------------------------------------------- |
| `Timeout`                  | 30s       | Request timeout.                                   |
| `PooledConnectionLifetime` | Unlimited | How long a connection lives before being replaced. |
| `MaxConnectionsPerServer`  | Unlimited | Max connections per server.                        |

## Recommendations for High-Traffic Applications

- **Increase `MaxIdleConnsPerHost`** (Go) or equivalent — the default of 2 per host is too low for high-throughput moderation workloads.
- **Set explicit timeouts** when a call should return faster than the 30 second default.
- **Enable connection reuse** — all SDKs enable keep-alive by default. Avoid creating new client instances per request.
- **Monitor for connection exhaustion** — if you see connection errors under load, increase pool sizes.
- **Use a single client instance** — instantiate the Stream client once and reuse it across your application. All SDKs are thread-safe / goroutine-safe.

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/guides/client-configuration/](https://getstream.io/moderation/docs/node/guides/client-configuration/).

---

# Text Normalization

Before any engine runs — word and regex [filters](https://getstream.io/moderation/docs/node/configuration/filters/), domain lists, AI text, LLM rules, or the review queue — Stream decodes the text to the form a browser would render, then strips invisible characters. Engines therefore match the **decoded** string, not the raw payload.

It applies to Chat messages, Feeds activities and comments, and the [Check](https://getstream.io/moderation/docs/node/content-moderation/check/) API. The stored message is unchanged: only the copy sent to moderation is normalized, so users still see exactly what was sent.

## Why this exists

A common bypass is to entity-encode a blocked word or URL so a plain rule never sees it, while the client still renders the real text:

```text
visit &#115;&#112;&#97;&#109; now
see &#104;&#116;&#116;&#112;&#115;&#58;&#47;&#47;evil.example/path
```

Those used to miss a word list containing `spam` and a regex like `(?i)https?://`. They now decode to `visit spam now` and `see https://evil.example/path`, and the same plain rules match.

## What decoding covers

HTML character references are resolved, including the forms browsers accept without a trailing semicolon.

| Form                  | Example input               | After decode          |
| --------------------- | --------------------------- | --------------------- |
| Decimal               | `&#104;&#116;&#116;&#112;`  | `http`                |
| Hex                   | `&#x68;&#x74;&#x74;&#x70;`  | `http`                |
| Hex, uppercase prefix | `&#X68;`                    | `h`                   |
| Decimal, no semicolon | `&#104&#116&#116&#112`      | `http`                |
| Hex, no semicolon     | `&#x68&#x74&#x74&#x70`      | `http`                |
| Named                 | `https&colon;//example.com` | `https://example.com` |
| Named, no semicolon   | `https&colon//example.com`  | `https://example.com` |
| Standard named        | `a &lt; b &amp; c`          | `a < b & c`           |
| Nested amp-encoding   | `&amp;#104;`                | `h`                   |
| Triple-encoded amp    | `&amp;amp;#104;`            | `h`                   |

Nested encoding is unwound for several passes (`&amp;#104;` → `&#104;` → `h`), which covers the usual double- and triple-encoded chains.

Named entities are matched case-insensitively when the lowercase HTML name exists (`&COLON;` → `:`, `&sol;` → `/`). A name that is itself a distinct HTML entity keeps that code point (`&Colon;` is `∷`, not `:`). Unknown names such as `&zzzxnotanentity;` are left as-is.

Ampersands that are not part of an entity are left alone (`A & B`).

## Zero-width and invisible characters

After decode, these code points are **removed** (not replaced with a space). Encoded forms such as `&#8203;` or `&#x200B;` are decoded first, then stripped, so `h&#8203;t&#8203;t&#8203;p` and a literal `h` + U+200B + `ttp` both become `http`.

| Category                                        | Code points                                                                             |
| ----------------------------------------------- | --------------------------------------------------------------------------------------- |
| Zero-width                                      | U+200B (ZWSP), U+200C (ZWNJ), U+200D (ZWJ), U+2060 (word joiner), U+FEFF (BOM / ZWNBSP) |
| Soft hyphen / joiners                           | U+00AD, U+034F (CGJ), U+180E (Mongolian vowel separator)                                |
| Bidirectional marks                             | U+200E, U+200F, U+061C                                                                  |
| Bidirectional embeddings / overrides / isolates | U+202A–U+202E, U+2066–U+2069                                                            |
| Invisible operators                             | U+2061–U+2064                                                                           |
| Line / paragraph separators                     | U+2028, U+2029                                                                          |
| Interlinear annotation                          | U+FFF9–U+FFFB                                                                           |

## What this means for your rules

You can write filters against the **rendered** text.

- A word list containing `spam` matches `visit &#115;&#112;&#97;&#109; now`.
- A regex `(?i)https?://` matches an entity-encoded URL.
- A [domain](https://getstream.io/moderation/docs/node/configuration/filters/#domain-matching) list matches the host after decode (and after the usual host canonicalization: lowercase, IDN / Punycode, fullwidth dots).

If you added encoding-aware regexes to catch `&#\d+;` / `&amp;#` chains, those are no longer required for this bypass. Prefer a plain URL regex or a domain list. Keeping the encoding regex is only useful if you still want to flag the _presence_ of entity syntax itself.

>
> **Info:** Review-queue items store the **normalized** text the engines evaluated, so [dashboard](https://getstream.io/signin/?product=moderation) review and webhooks show `https://evil.example/path`, not the encoded source. The Chat / Feeds message the user sent is stored as they typed it.
>

## What is not covered

This pre-pass does **not** decode or fold:

| Bypass                                    | Example                       | What to do                                                                                                  |
| ----------------------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Percent-encoding                          | `%68%74%74%70://evil.example` | Still needs a dedicated regex if you care about this form                                                   |
| Unicode NFKC / fullwidth                  | `ｈｔｔｐ://evil.example`     | Not folded here                                                                                             |
| Homoglyphs (Cyrillic / Greek look-alikes) | `ѕсam` vs `scam`              | Not folded by this pre-pass                                                                                 |
| Leetspeak                                 | `h4ck3r` vs `hacker`          | Enable leet detection on that [word list](https://getstream.io/moderation/docs/node/configuration/filters/#word-matching) |
| Base64 or other encodings                 | `aHR0cDovL2V2aWw=`            | Not decoded                                                                                                 |

Word lists still match whole words (case-insensitive). Adjacent punctuation is ignored; `house` does not match `lighthouse`.

## Examples

```text
Input:  see &#104;&#116;&#116;&#112;&#115;&#58;&#47;&#47;evil.example/path
Output: see https://evil.example/path

Input:  &#104&#116&#116&#112://evil.example
Output: http://evil.example

Input:  &#60&#62&#38 missing semicolons
Output: <>& missing semicolons

Input:  h&#8203;t&#x200B;tp&colon;//evil.example
Output: http://evil.example

Input:  visit &amp;#115;&amp;#112;&amp;#97;&amp;#109; now
Output: visit spam now
```

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/node/guides/text-normalization/](https://getstream.io/moderation/docs/node/guides/text-normalization/).