### Toxic User Detection Rule Example (JSON)

Source: https://getstream.io/moderation/docs/engines/rule-builder

An example rule configuration designed to detect and ban users exhibiting toxic behavior, such as hate speech or excessive profanity. It uses 'OR' logic to combine conditions and includes IP banning to prevent account circumvention.

```json
{
  "name": "Toxic User Detection",
  "description": "Bans users who consistently post harmful content",
  "team": "moderation",
  "config_keys": [],
  "id": "toxic-user",
  "rule_type": "user",
  "enabled": true,
  "cooldown_period": "7d",
  "logic": "OR",
  "conditions": [
    {
      "type": "text_rule",
      "text_rule_params": {
        "threshold": 5,
        "time_window": "24h",
        "llm_harm_labels": {
          "HATE_SPEECH": "Content that promotes hatred, discrimination, or violence against groups",
          "HARASSMENT": "Unwanted behavior intended to disturb or upset",
          "THREAT": "Content containing threats of violence or harm against individuals or groups"
        }
      }
    },
    {
      "type": "text_rule",
      "text_rule_params": {
        "threshold": 50,
        "time_window": "24h",
        "blocklist_match": ["profanity_en_2020_v1"]
      }
    }
  ],
  "action": {
    "type": "ban_user",
    "ban_options": {
      "duration": 604800,
      "reason": "Toxic behavior detected",
      "shadow_ban": false,
      "ip_ban": true
    }
  }
}
```

--------------------------------

### Complete Moderation Rule Example (JSON)

Source: https://getstream.io/moderation/docs/engines/rule-builder

Provides a comprehensive example of a moderation rule, detailing its structure including conditions, logic, and actions. This rule is designed to detect spam and ban users based on specific criteria.

```json
{
  "name": "Spam Detection",
  "description": "Detects and bans users for spam behavior",
  "team": "moderation",
  "config_keys": ["chat:messaging", "chat:support"],
  "id": "spam-detection",
  "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
    }
  }
}
```

--------------------------------

### Toxic User Detection Rule Example

Source: https://getstream.io/moderation/docs/engines/rule-builder

An example rule that identifies and bans users engaging in toxic behavior, including hate speech and profanity.

```APIDOC
## Toxic User Detection Rule

### Description
This rule identifies users who consistently engage in harmful behavior over time, targeting both hate speech and excessive profanity, and bans them.

### Method
Not applicable (Rule configuration)

### Endpoint
Not applicable (Rule configuration)

### Parameters
#### Request Body (Rule Configuration)
- **name** (string) - Required - The name of the rule.
- **description** (string) - Optional - A description of the rule.
- **team** (string) - Required - The team responsible for this rule.
- **config_keys** (array) - Optional - Configuration keys associated with the rule.
- **id** (string) - Required - A unique identifier for the rule.
- **rule_type** (string) - Required - The type of rule, should be `user`.
- **enabled** (boolean) - Required - Whether the rule is currently enabled.
- **cooldown_period** (string) - Required - The cooldown period after a rule is triggered before it can be triggered again for the same user.
- **logic** (string) - Required - The logic to combine conditions (`AND` or `OR`).
- **conditions** (array) - Required - A list of conditions that must be met for the rule to trigger.
  - **type** (string) - Required - The type of condition (e.g., `text_rule`).
  - **text_rule_params** (object) - Required - Parameters for the text rule.
    - **threshold** (integer) - Required - The number of messages that trigger the rule.
    - **time_window** (string) - Required - The time frame to monitor messages.
    - **llm_harm_labels** (object) - Optional - Specifies harmful content categories to detect.
      - **HATE_SPEECH** (string) - Description of hate speech.
      - **HARASSMENT** (string) - Description of harassment.
      - **THREAT** (string) - Description of threats.
    - **blocklist_match** (array) - Optional - A list of blocklist IDs to match against.
- **action** (object) - Required - The action to take when the rule is triggered.
  - **type** (string) - Required - The type of action (e.g., `ban_user`).
  - **ban_options** (object) - Required for `ban_user` action.
    - **duration** (integer) - Required - Ban duration in seconds.
    - **reason** (string) - Required - Reason for the ban.
    - **shadow_ban** (boolean) - Optional - Whether to shadow ban.
    - **ip_ban** (boolean) - Optional - Whether to ban the IP address.

### Request Example
```json
{
  "name": "Toxic User Detection",
  "description": "Bans users who consistently post harmful content",
  "team": "moderation",
  "config_keys": [],
  "id": "toxic-user",
  "rule_type": "user",
  "enabled": true,
  "cooldown_period": "7d",
  "logic": "OR",
  "conditions": [
    {
      "type": "text_rule",
      "text_rule_params": {
        "threshold": 5,
        "time_window": "24h",
        "llm_harm_labels": {
          "HATE_SPEECH": "Content that promotes hatred, discrimination, or violence against groups",
          "HARASSMENT": "Unwanted behavior intended to disturb or upset",
          "THREAT": "Content containing threats of violence or harm against individuals or groups"
        }
      }
    },
    {
      "type": "text_rule",
      "text_rule_params": {
        "threshold": 50,
        "time_window": "24h",
        "blocklist_match": ["profanity_en_2020_v1"]
      }
    }
  ],
  "action": {
    "type": "ban_user",
    "ban_options": {
      "duration": 604800,
      "reason": "Toxic behavior detected",
      "shadow_ban": false,
      "ip_ban": true
    }
  }
}
```

### Response
#### Success Response (200)
Details about the rule configuration.

#### Response Example
```json
{
  "message": "Rule configured successfully"
}
```

### What it does
- **First condition**: Triggers if a user posts 5 or more messages containing hate speech, harassment, or threats within 24 hours.
- **Second condition**: Triggers if a user posts 50 or more messages that match the profanity blocklist within 24 hours.
- **Logic**: Uses "OR" logic, meaning either condition can trigger the rule.
- **Action**: Bans the user for 7 days (604,800 seconds) and also bans their IP address to prevent them from creating new accounts.

### When to use this rule
- Communities with strict content policies.
- Platforms that need to quickly remove toxic users.
- Situations where you want to prevent users from circumventing bans with new accounts.
```

--------------------------------

### Email Blocklist Filter Example

Source: https://getstream.io/moderation/docs/engines/blocklists-and-regex-filters

This filter blocks content containing specific email addresses. It matches exact email addresses only. For example, adding 'spam@example.com' to the blocklist will block any content containing that exact email.

--------------------------------

### Ban and Unban User (JavaScript)

Source: https://getstream.io/moderation/docs/api/flag-mute-ban

Provides examples of banning users in JavaScript, including temporary bans, IP bans, and channel-specific bans. It also shows how to remove bans globally or from a specific channel.

```javascript
// ban a user for 60 minutes from all channel
let data = await client.banUser("eviluser", {
  banned_by_id: userID, // ID of the user who is performing the ban (Server-side auth)
  timeout: 60,
  reason: "Banned for one hour",
});

// ban a user and their IP address for 24 hours
let data = await client.banUser("eviluser", {
  banned_by_id: userID,
  timeout: 24 * 60,
  ip_ban: true,
  reason: "Please come back tomorrow",
});

// ban a user from the livestream:fortnite channel
data = await channel.banUser("eviluser", {
  banned_by_id: userID,
  reason: "Profanity is not allowed here",
});

// remove ban from channel
data = await channel.unbanUser("eviluser");

// remove global ban
data = await authClient.unbanUser("eviluser");
```

--------------------------------

### Manage User Bans - Unreal Engine (C++)

Source: https://getstream.io/moderation/docs/api/flag-mute-ban

Illustrates how to ban and unban users in Unreal Engine using C++. Includes examples for global bans, channel bans, IP bans, and setting ban durations and reasons.

```cpp
// ban a user for 60 minutes from all channel
Client->BanUser(User, FTimespan::FromMinutes(60.), {TEXT("Banned for one hour")});

// ban a user and their IP address for 24 hours
Client->BanUser(User, FTimespan::FromHours(24.), {TEXT("Please come back tomorrow")}, true);

// ban a user from a specific channel
Channel->BanMember(User, {}, {TEXT("Profanity is not allowed here")});

// remove ban from channel
Channel->UnbanMember(User);

// remove global ban
Client->UnbanUser(User);
```

--------------------------------

### Query Moderation Rules using JavaScript SDK

Source: https://getstream.io/moderation/docs/engines/rule-builder

Illustrates how to retrieve moderation rules using the `queryModerationRules` API. Examples show querying all rules, filtering by name using autocomplete, retrieving only global rules, and fetching rules specific to certain configurations.

```javascript
// Query all rules
const allRules = await client.moderation.queryModerationRules({
  filter: {},
  sort: [{ field: "created_at", direction: -1 }],
  limit: 25,
});

// Query rules by name
const spamRules = await client.moderation.queryModerationRules({
  filter: {
    name: { $autocomplete: "spam" },
  },
});

// Query global rules only
const globalRules = await client.moderation.queryModerationRules({
  filter: {
    is_global: true,
  },
});

// Query config-specific rules
const configRules = await client.moderation.queryModerationRules({
  filter: {
    config_keys: { $in: ["chat:messaging"] },
  },
});
```

--------------------------------

### Shadow Ban User - Unity (C#)

Source: https://getstream.io/moderation/docs/api/flag-mute-ban

Provides examples for shadow banning users and members from a channel in Unity using C#. Supports permanent bans, temporary bans with reasons, and IP bans. Requires channel and user/member objects.

```csharp
// Dummy example to get IStreamUser to ban
var user = channel.Messages.First().User;

// Dummy example to get IStreamUser to ban
var channelMember = channel.Members.First();

// Shadow Ban a user from this channel permanently
await channel.ShadowBanUserAsync(user);

// Shadow Ban a member from this channel
await channel.ShadowBanMemberAsync(channelMember);

// Use any combination of optional parameters: reason, timeoutMinutes, isIpBan

// Shadow Ban a member from this channel permanently
await channel.ShadowBanMemberAsync(channelMember);

// Shadow Ban a member from this channel for 2 hours with a reason
await channel.ShadowBanMemberAsync(channelMember, "Banned for 2 hours for toxic behaviour.", 120);

// Shadow Ban a member IP from this channel for 2 hours without a reason
await channel.ShadowBanMemberAsync(channelMember, timeoutMinutes: 120, isIpBan: true);
```

--------------------------------

### Query Banned Users (Go)

Source: https://getstream.io/moderation/docs/api/flag-mute-ban

Fetches banned users from a specific channel using the Stream client in Go. This example demonstrates how to set the 'channel_cid' filter option for querying banned members.

```go
client.QueryBannedUsers(ctx, &QueryBannedUsersOptions{
	QueryOption: &QueryOption{Filter: map[string]interface{}{
		"channel_cid": "ChannelType:ChannelId",
	}},
})
```

--------------------------------

### Shadow Ban and Remove Shadow Ban User - PHP

Source: https://getstream.io/moderation/docs/api/flag-mute-ban

Demonstrates shadow banning and removing shadow bans for a user using the GetStream PHP SDK. These examples typically require user IDs and optionally specify the banning user's ID.

```php
$client->shadowBan($targetUser["id"], ["user_id" => $user2["id"]]);

$client->removeShadowBan($targetUser["id"], ["user_id" => $user2["id"]]);
```

--------------------------------

### Shadow Ban and Remove Shadow Ban User - JavaScript

Source: https://getstream.io/moderation/docs/api/flag-mute-ban

Provides examples of shadow banning and removing shadow bans for a user, both globally and from a specific channel, using the GetStream JavaScript SDK. It also shows how to perform a server-side shadow ban.

```javascript
// shadow ban a user from all channels
let data = await client.shadowBan("eviluser");

// shadow ban a user from a channel
data = await channel.shadowBan("eviluser");

// remove shadow ban from channel
data = await channel.removeShadowBan("eviluser");

// remove global shadow ban
data = await client.removeShadowBan("eviluser");

// server-side shadow ban
data = await client.shadowBan("eviluser", { banned_by_id: "regularUser" });
```

--------------------------------

### Shadow Ban and Remove Shadow Ban User - Ruby

Source: https://getstream.io/moderation/docs/api/flag-mute-ban

Shows how to shadow ban and remove shadow bans for a user using the GetStream Ruby SDK. The examples illustrate passing user IDs and optional parameters like `user_id`.

```ruby
client.shadow_ban(target_user["id"], user_id: server_user["id"])

client.remove_shadow_ban(target_user["id"], user_id: server_user["id"])
```

--------------------------------

### Query Banned Users (Unity C#)

Source: https://getstream.io/moderation/docs/api/flag-mute-ban

Retrieves banned users within a specified time frame using the Stream client in Unity (C#). This example demonstrates querying for users banned in the last 24 hours with custom limit and offset.

```csharp
// Get users banned in the last 24 hours
var request = new StreamQueryBannedUsersRequest
{
  CreatedAtAfterOrEqual = new DateTimeOffset().AddHours(-24),
  Limit = 30,
  Offset = 0,
};

var bannedUsersInfo = await Client.QueryBannedUsersAsync(request);
```

--------------------------------

### Immediate Text Filter Rule (JSON)

Source: https://getstream.io/moderation/docs/engines/rule-builder

This rule provides an example of an immediate text filter that blocks threatening content. It uses LLM-identified harm labels like 'TERRORISM' and 'THREAT' with a 'HIGH' severity, triggering a content block action.

```json
{
  "name": "Immediate Text Filter",
  "description": "Immediately blocks threatening content",
  "team": "moderation",
  "config_keys": [],
  "id": "immediate-text-filter",
  "rule_type": "content",
  "enabled": true,
  "logic": "OR",
  "conditions": [
    {
      "type": "text_content",
      "text_content_params": {
        "llm_harm_labels": {
          "TERRORISM": "Content related to terrorism, terrorist organizations, or terrorist activities",
          "THREAT": "Content containing threats of violence or harm against individuals or groups"
        },
        "severity": "HIGH"
      }
    }
  ],
  "action": {
    "type": "block_content",
    "remove_content_options": {
      "reason": "Immediate removal of threatening content"
    }
  }
}
```

--------------------------------

### Shadow Ban and Remove Shadow Ban User - Python

Source: https://getstream.io/moderation/docs/api/flag-mute-ban

Provides Python examples for shadow banning and removing shadow bans using the GetStream Python SDK. These operations often require the target user's ID and the ID of the user performing the action.

```python
client.shadow_ban(target_user["id"], user_id=server_user["id"])

client.remove_shadow_ban(target_user["id"], user_id=server_user["id"])
```

--------------------------------

### Query Review Queue Items with Appeal Filters (Javascript, Ruby)

Source: https://getstream.io/moderation/docs/api/appeal

This snippet shows how to query the review queue for items related to appeals. It supports filtering by the presence of an appeal, the appeal's status (submitted, accepted, rejected), or a specific appeal ID. The examples use Javascript and Ruby.

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

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

```ruby
# Query items with submitted appeals
client.moderation.query_review_queue(
  { appeal: true, appeal_status: "submitted" },
  { created_at: -1 },
  limit: 20
)

# Query items with a specific appeal
client.moderation.query_review_queue(
  { appeal_id: { $eq: "appeal_id" } },
  { created_at: -1 },
  limit: 20
)
```

--------------------------------

### Example Response for Moderated Message in JSON

Source: https://getstream.io/moderation/docs/quick-start/chat

This JSON object represents the response received when a message is blocked by moderation policies during server-side integration. The `message` object has a `type` of `error`, indicating it was blocked. It includes details about the moderation action taken and the original text that was flagged. No WebSocket events are triggered for such messages.

```json
{
  "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" },
    "user": {
      "id": "little-lake-2",
      "name": "little-lake-2",
      ...
    },
    "cid": "messaging:first",
    "created_at": "2024-11-21T13:13:38.071535Z",
    "updated_at": "2024-11-21T13:13:38.071535Z",
    "shadowed": false,
    ...
  },
  "duration": "136.06ms"
}
```

--------------------------------

### New User Spam Protection Rule Configuration (JSON)

Source: https://getstream.io/moderation/docs/engines/rule-builder

This JSON configuration defines a moderation rule to protect against spam from newly created accounts. It triggers if a new user posts multiple spam or scam messages within an hour and applies a shadow ban. This rule is useful for platforms with high bot activity or those wanting to vet new users.

```json
{
  "name": "New User Spam Protection",
  "description": "Shadow bans new users who post spam content",
  "team": "moderation",
  "config_keys": ["chat:messaging"],
  "id": "new-user-spam",
  "rule_type": "user",
  "enabled": true,
  "cooldown_period": "6h",
  "logic": "AND",
  "conditions": [
    {
      "type": "text_rule",
      "text_rule_params": {
        "threshold": 3,
        "time_window": "1h",
        "llm_harm_labels": {
          "SPAM": "Unsolicited promotional content or repetitive messages",
          "SCAM": "Fraudulent content, phishing attempts, or deceptive practices"
        }
      }
    },
    {
      "type": "user_created_within",
      "user_created_within_params": {
        "time_window": "24h"
      }
    }
  ],
  "action": {
    "type": "ban_user",
    "ban_options": {
      "duration": 3600,
      "reason": "New user spam detected",
      "shadow_ban": true,
      "ip_ban": false
    }
  }
}
```

--------------------------------

### Get Moderation Config

Source: https://getstream.io/moderation/docs/api

Retrieves the moderation configuration for a specified key.

```APIDOC
## GET /moderation/config/{key}

### Description
Retrieves the moderation configuration associated with a given key.

### Method
GET

### Endpoint
/moderation/config/{key}

### Parameters
#### Path Parameters
- **key** (string) - Required - The unique identifier for the configuration to retrieve.

### Response
#### Success Response (200)
- **key** (string) - The configuration key.
- **ai_text_config** (object) - Configuration for the AI Text engine.
- **block_list_config** (object) - Configuration for the block list.
- **ai_image_config** (object) - Configuration for image moderation.

#### Response Example
```json
{
  "key": "unique_config_key",
  "ai_text_config": {
    "rules": [
      { "label": "SCAM", "action": "flag" },
      {
        "label": "SEXUAL_HARASSMENT",
        "severity_rules": [
          { "severity": "low", "action": "flag" },
          { "severity": "medium", "action": "flag" },
          { "severity": "high", "action": "remove" },
          { "severity": "critical", "action": "remove" }
        ]
      }
    ]
  },
  "block_list_config": {
    "rules": [
      {
        "name": "blocklistname",
        "action": "remove"
      }
    ]
  },
  "ai_image_config": {
    "rules": [{ "label": "Non-Explicit Nudity", "action": "flag" }]
  }
}
```
```

--------------------------------

### Get Appeal

Source: https://getstream.io/moderation/docs/api/appeal

Retrieves a specific appeal item by its ID. Client-side users can only retrieve their own appeals.

```APIDOC
## Get Appeal

### Description
Retrieves a specific appeal item by its ID. When used from the client-side, users can only retrieve their own appeals.

### Method
GET

### Endpoint
/appeals/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Unique identifier of the appeal.

### Response
#### Success Response (200)
- **item** (object) - Appeal item with full details. Includes `id`, `user`, `entity_type`, `entity_id`, `appeal_reason`, `status`, `decision_reason`, `attachments`, `created_at`, `updated_at`.

#### Response Example
```json
{
  "item": {
    "id": "appeal_id_1",
    "user": "user_id_1",
    "entity_type": "stream:chat:v1:message",
    "entity_id": "message_id_1",
    "appeal_reason": "This message was unfairly flagged.",
    "status": "submitted",
    "decision_reason": null,
    "attachments": [],
    "created_at": "2023-01-01T10:00:00Z",
    "updated_at": "2023-01-01T10:00:00Z"
  }
}
```
```

--------------------------------

### Flag a Message in JavaScript, Python, Ruby, Go, and C#

Source: https://getstream.io/moderation/docs/api/flag-mute-ban

This snippet demonstrates how to flag a message for review using the Stream client library. It shows basic flagging and how to include a reason and custom data for more context. The flagged content appears in the Stream moderation review queue.

```javascript
// Flag a message
const flag = await client.flagMessage(messageId);

// Flag with a reason and custom data
const flag = await client.flagMessage(messageId, {
  reason: "spam",
  custom: {
    user_comment: "This user is spamming the channel.",
  },
});
```

```python
client.flag_message(msg["id"], user_id=server_user["id"])
```

```ruby
@client.flag_message(msg_id, user_id: server_user[:id])
```

```go
client.FlagMessage(ctx, msg.ID, user.ID)
```

```csharp
await flagClient.FlagMessageAsync(message.Id, user.Id);
```

--------------------------------

### Get Specific Appeal Details

Source: https://getstream.io/moderation/docs/api/appeal

Retrieves the detailed information for a specific appeal using its appeal ID.

```APIDOC
## GET /moderation/appeal/{appeal_id}

### Description
Retrieves details for a specific appeal.

### Method
GET

### Endpoint
`/moderation/appeal/{appeal_id}`

### Parameters
#### Path Parameters
- **appeal_id** (string) - Required - The ID of the appeal to retrieve.

### Response
#### Success Response (200)
- **item** (object) - The appeal object containing details like status and decision reason.
  - **status** (string) - The current status of the appeal.
  - **decision_reason** (string) - The reason for the moderation decision.

#### Response Example
```json
{
  "item": {
    "appeal_id": "appeal_id",
    "status": "accepted",
    "decision_reason": "The content was deleted by mistake. Appeal accepted."
  }
}
```
```

--------------------------------

### Unban User in Stream Chat (JavaScript)

Source: https://getstream.io/moderation/docs/quick-start/chat

Allows moderators to unban a user from the chat. This function requires the target user's ID and the ID of the user performing the unban.

```javascript
await client.unbanUser("target_user_id", {
  unbanned_by_id: "user_id", // User ID who is unbanning the user,
});
```

--------------------------------

### Ban User in Stream Chat (JavaScript)

Source: https://getstream.io/moderation/docs/quick-start/chat

Enables moderators to ban a user from the chat. This function requires the target user's ID and the ID of the user performing the ban.

```javascript
await client.banUser("target_user_id", {
  banned_by_id: "user_id", // User ID who is banning the user,
});
```

--------------------------------

### Query Banned Users with Sorting and Filtering (Java)

Source: https://getstream.io/moderation/docs/api/flag-mute-ban

Demonstrates how to query banned users with descending sort by creation date and filter by a specific channel. It also shows how to retrieve a page of bans created before or on a given date. This requires the Stream SDK for Java.

```java
QuerySorter<BannedUsersSort> sort = QuerySortByField.descByName("createdAt");
client.queryBannedUsers(filter, sort).enqueue(result -> {
  if (result.isSuccess()) {
    List<BannedUser> bannedUsers = result.data();
  } else {
    // Handle result.error()
  }
});

// Get the page of bans which where created before or equal date for the same channel
client.queryBannedUsers(filter, sort, null, null, null, null, null, new Date()).enqueue(result -> {
  if (result.isSuccess()) {
    List<BannedUser> bannedUsers = result.data();
  } else {
    // Handle result.error()
  }
});
```

--------------------------------

### Detect Identical Content Rule Configuration

Source: https://getstream.io/moderation/docs/engines/rule-builder

Configures a rule to track users sending the same content multiple times, useful for spam detection. It specifies a threshold and time window for triggering the rule. Content matching includes text and attachments, with intelligent detection for minor variations.

```json
{
  "type": "user_identical_content_count",
  "user_identical_content_count_params": {
    "threshold": 3,
    "time_window": "1h"
  }
}
```

--------------------------------

### Query Banned Users (Dart)

Source: https://getstream.io/moderation/docs/api/flag-mute-ban

Retrieves a list of banned users using the Stream client in Dart. This example demonstrates how to filter users by setting 'banned' to true.

```dart
// retrieve the list of banned users
await client.queryUsers(
  filter: Filter.equal('banned', true),
 );
```

--------------------------------

### Get Specific Appeal by ID (Javascript, Ruby)

Source: https://getstream.io/moderation/docs/api/appeal

Retrieves a specific appeal item using its unique identifier. Client-side usage is restricted to retrieving the user's own appeals. Requires the appeal ID as input.

```javascript
await client.moderation.getAppeal("appealId");
```

```ruby
client.moderation.get_appeal("appeal_id")
```

--------------------------------

### Manage User Bans and Unbans (Go)

Source: https://getstream.io/moderation/docs/api/flag-mute-ban

Provides functions to ban and unban users from specific channels or globally. Supports specifying reasons and expiration times for bans. Requires a context, target user ID, and banning user ID.

```go
// ban from channel
channel.BanUser(ctx, target.ID, bannedBy.ID, BanWithReason("spammer"), BanWithExpiration(60))

// ban globally
client.BanUser(ctx, target.ID, bannedBy.ID, BanWithReason("spammer"), BanWithExpiration(60))

// unban from channel
channel.UnBanUser(ctx, target.ID)

// unban globally
client.UnBanUser(ctx, target.ID)
```

--------------------------------

### Handling Bounce Actions Programmatically

Source: https://getstream.io/moderation/docs/guides/bounce-message

This section details how to programmatically handle bounce actions when not using a UI SDK. It explains how to detect bounce actions from API responses and guide users through the correction process.

```APIDOC
## Handling Bounce Actions Programmatically

If you are not utilizing a UI SDK, you can programmatically handle bounce responses using the **send message response API**. Bounce actions are indicated in the `moderation` object, which is part of the `message` object in the API response.

### API Response Example for Bounce Action

```json
{
  "message": {
    "type": "error",
    "text": "The message original text",
    "user_id": "user_id",
    "moderation": {
      "action": "bounce",
      "original_text": "The message original text"
    }
  }
}
```

### Steps to Handle Bounce Programmatically:

1.  **Detect the Bounce Action**:
    *   Check the `action` field within the `moderation` object in the API response.
    *   If the `action` field is set to `bounce`, the message has been returned to the sender for correction.

2.  **Return Feedback to the User**:
    *   Extract the `original_text` field from the `moderation` object to display the message to the user.
    *   Provide clear guidance on why the message was bounced and how to correct it.

    **Example UI prompt:**
    > "Your message could not be sent because it violates our content guidelines. Please adjust your message and try again."

3.  **Handle Resubmitted Messages**:
    *   When the user edits and resubmits, send the updated text back to the API for moderation.
    *   If the follow-up message passes moderation, it will be delivered successfully.
    *   If the follow-up message still violates guidelines, additional actions, such as **flag** or **block**, will be triggered based on your configured moderation rules.
```

--------------------------------

### Create Moderation Rule using JavaScript SDK

Source: https://getstream.io/moderation/docs/engines/rule-builder

Demonstrates how to create global and configuration-specific moderation rules using the `upsertModerationRule` API. This includes defining conditions based on text rules, LLM harm labels, thresholds, and time windows, as well as specifying actions like banning or flagging users.

```javascript
await client.moderation.upsertModerationRule({
  name: "Spam Detection",
  description: "Detects and bans users for spam behavior",
  team: "moderation",
  config_keys: [], // Empty array makes it global
  id: "spam-detection",
  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",
        },
      },
    },
  ],
  logic: "AND",
  action: {
    type: "ban_user",
    ban_options: {
      duration: 3600,
      reason: "Spam behavior detected",
      shadow_ban: false,
      ip_ban: false,
    },
  },
});

// Create a config-specific rule (applies only to specific configurations)
await client.moderation.upsertModerationRule({
  name: "Chat Specific Rule",
  description: "Rule that only applies to chat channels",
  team: "moderation",
  config_keys: ["chat:messaging", "chat:support"],
  id: "chat-toxicity",
  rule_type: "user",
  enabled: true,
  cooldown_period: "12h",
  conditions: [
    {
      type: "text_rule",
      text_rule_params: {
        threshold: 3,
        time_window: "1h",
        llm_harm_labels: {
          HATE_SPEECH:
            "Content that promotes hatred, discrimination, or violence against groups",
          HARASSMENT: "Unwanted behavior intended to disturb or upset",
        },
      },
    },
  ],
  logic: "AND",
  action: {
    type: "flag_user",
    flag_user_options: {
      reason: "Toxic behavior in chat channels",
    },
  },
});
```

--------------------------------

### Query Banned Users (PHP)

Source: https://getstream.io/moderation/docs/api/flag-mute-ban

Retrieves banned members from a specific channel using the Stream client in PHP. This example focuses on querying banned users by providing the channel's CID.

```php
$client->queryBannedUsers(["channel_cid" => "ChannelType:ChannelId"]);
```

--------------------------------

### Configure Complete Video Content Rule

Source: https://getstream.io/moderation/docs/engines/rule-builder

This configuration sets up a rule to immediately block inappropriate video content. It specifies the rule's metadata, conditions based on harmful labels, and the action to block the content with a given reason. This rule is designed for swift enforcement.

```json
{
  "name": "Immediate Video Filter",
  "description": "Immediately blocks inappropriate video content",
  "team": "moderation",
  "config_keys": [],
  "id": "immediate-video-filter",
  "rule_type": "content",
  "enabled": true,
  "logic": "OR",
  "conditions": [
    {
      "type": "video_content",
      "video_content_params": {
        "harm_labels": ["Explicit", "Violence"]
      }
    }
  ],
  "action": {
    "type": "block_content",
    "remove_content_options": {
      "reason": "Inappropriate video content detected"
    }
  }
}
```

--------------------------------

### Iterate Through Flags with JavaScript

Source: https://getstream.io/moderation/docs/quick-start/build-moderation-dashboard

This code snippet demonstrates how to iterate through the flags associated with a flagged item to get details about the moderation engines that flagged the content. It accesses properties like `type`, `labels`, and `custom` to provide more information about the flags.

```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
}
```

--------------------------------

### Shadow Ban and Remove Shadow Ban User - Unreal Engine (C++)

Source: https://getstream.io/moderation/docs/api/flag-mute-ban

Shows how to shadow ban and unban a user from channels or globally using the GetStream Unreal Engine C++ SDK. This involves calling specific methods on client and channel objects.

```cpp
// shadow ban a user from all channels
Client->ShadowBanUser(User);

// shadow ban a user from a channel
Channel->ShadowBanMember(User);

// remove shadow ban from channel
Channel->ShadowUnbanMember(User);

// remove global shadow ban
Client->ShadowUnbanUser(User);
```

--------------------------------

### Flag Message in Stream Chat (JavaScript)

Source: https://getstream.io/moderation/docs/quick-start/chat

Allows users to flag a message for review in the moderation dashboard. This function requires the message ID and an optional reason. For server-side integrations, the user ID flagging the message is also required.

```javascript
await client.moderation.flagMessage("message_id", "reason", {
  user_id: "user_id", // User ID who is flagging the message, required only for server-side integration only.
});
```

--------------------------------

### Query Review Queue Items - JavaScript

Source: https://getstream.io/moderation/docs/quick-start/build-moderation-dashboard

Queries the review queue for flagged messages with images. It specifies the entity type and a filter for images, sorted by creation date in descending order. The `next: null` parameter is used for initial pagination.

```javascript
const response = await client.moderation.queryReviewQueue(
  { entity_type: "stream:chat:v1:message", has_image: true },
  [{ field: "created_at", direction: -1 }],
  { next: null },
);
```

--------------------------------

### Query Review Queue (Client-Side)

Source: https://getstream.io/moderation/docs/api/multitenancy

Query the review queue for the teams the authenticated user belongs to. Allows filtering by a specific team if the user has access.

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

// Get all the review queue for all the teams that the user belongs to.
const { reviews, 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 { reviews, next } = await client.moderation.queryReviewQueue(
  {
    team: "team-a",
  },
  [{ field: "created_at", direction: -1 }],
  { limit: 2 },
);
```

--------------------------------

### Get Specific Appeal Details from Stream Moderation API

Source: https://getstream.io/moderation/docs/api/appeal

Retrieves detailed information about a specific appeal using its ID. Returns the appeal's status, decision reason, and other relevant data. Useful for displaying appeal outcomes to users.

```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);
```

--------------------------------

### Flag User Action (JavaScript)

Source: https://getstream.io/moderation/docs/quick-start/chat

Allows users to flag another user with a reason, triggering a review in the moderation dashboard. This is useful for custom UI implementations where the Chat UI SDK is not used. The user ID is required for server-side integration.

```javascript
await client.moderation.flagUser("user_id", "reason", {
  user_id: "user_id", // User ID who is flagging the user, required only for server-side integration only.
});
```

--------------------------------

### Manage User Bans - Dart

Source: https://getstream.io/moderation/docs/api/flag-mute-ban

Provides examples of banning and unbanning users in Dart using the Stream Chat SDK. Covers global bans, channel bans, IP bans, and setting ban durations and reasons.

```dart
// ban a user for 60 minutes from all channel
await client.banUser('eviluser', {
  'banned_by_id': userID, // ID of the user who is performing the ban (Server-side auth)
  'timeout': 60,
  'reason': 'Banned for one hour',
});

// ban a user and their IP address for 24 hours
 await client.banUser('eviluser', {
  'banned_by_id': userID,
  'timeout': 24*60,
  'ip_ban': true,
  'reason': 'Please come back tomorrow',
});

// ban a user from the livestream:fortnite channel
await channel.banMember(
  'banned_by_id': userID,
  'reason': 'Profanity is not allowed here',
});

// remove ban from channel
await channel.banMember('eviluser');

// remove global ban
await client.unbanUser('eviluser');
```

--------------------------------

### Flag a User in JavaScript, Python, and Go

Source: https://getstream.io/moderation/docs/api/flag-mute-ban

This code demonstrates how to flag a user for violating community guidelines. You can optionally provide a reason for the flag, which helps moderators understand the context. Flagged users can be reviewed and actioned through the Stream moderation dashboard.

```javascript
// Flag a user
const flag = await client.flagUser(userId);

// Flag with a reason
const flag = await client.flagUser(userId, {
  reason: "harassment",
});
```

```python
client.flag_user(user_id, user_id=flagging_user_id)
```

```go
client.FlagUser(ctx, targetUser.ID, flaggingUser.ID)
```

--------------------------------

### Shadow Ban and Remove Shadow Ban User - C#

Source: https://getstream.io/moderation/docs/api/flag-mute-ban

Demonstrates how to shadow ban and remove a shadow ban for a user using the GetStream C# SDK. It utilizes asynchronous methods and request objects to specify ban details.

```csharp
await userClient.ShadowBanAsync(new ShadowBanRequest
{
  TargetUserId = targetUser.Id,
  UserId = bannedBy.Id,
});

await userClient.RemoveShadowBanAsync(new ShadowBanRequest
{
  TargetUserId = targetUser.Id,
});
```

--------------------------------

### Flag User Action Configuration

Source: https://getstream.io/moderation/docs/engines/rule-builder

Configures an action to flag a user for manual review by moderators. This action includes a reason to help moderators understand why the user was flagged.

```json
{
  "type": "flag_user",
  "flag_user_options": {
    "reason": "Suspicious behavior pattern detected"
  }
}
```

--------------------------------

### Configure Moderation Settings (JavaScript, Ruby)

Source: https://getstream.io/moderation/docs/api

This snippet demonstrates how to upsert moderation configuration settings using the Stream client. It supports AI text, block list, and AI image moderation rules. The configuration key is mandatory and uniquely identifies the moderation setup.

```javascript
await client.moderation.upsertConfig({
  key: "unique_config_key",
  ai_text_config: {
    rules: [
      { label: "SCAM", action: "flag" },
      {
        label: "SEXUAL_HARASSMENT",
        severity_rules: [
          { severity: "low", action: "flag" },
          { severity: "medium", action: "flag" },
          { severity: "high", action: "remove" },
          { severity: "critical", action: "remove" },
        ],
      },
    ],
  },
  block_list_config: {
    rules: [
      {
        name: "blocklistname",
        action: "remove",
      },
    ],
  },
  ai_image_config: {
    rules: [{ label: "Non-Explicit Nudity", action: "flag" }],
  },
});
```

```ruby
client.moderation.upsert_config({
  key: "unique_config_key",
  ai_text_config: {
    rules: [
	    {label: "SCAM", action: "flag"},
        {label: "SEXUAL_HARASSMENT", severity_rules: [
            {severity: "low", action: "flag"},
            {severity: "medium", action: "flag"},
            {severity: "high", action: "remove"},
            {severity: "critical", action: "remove"}
        ]}
    ]
  },
  block_list_config: {
    rules: [
      {
        name: 'blocklistname',
        action: 'remove',
      },
    ],
  },
  ai_image_config: {
    rules: [{ label: 'Non-Explicit Nudity', action: 'flag' }],
  },
})
```