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. All endpoints use the v2 moderation API and are available through Stream's server-side SDKs.

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.

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,
});

client.moderation().flag(
    entity_type="stream:chat:v1:message",
    entity_id=message_id,
    entity_creator_id=creator_id,
    reason="spam",
    custom={"user_comment": "This user is spamming the channel"},
    user_id=moderator_id,
)

client.Moderation().Flag(ctx, &getstream.FlagRequest{
    EntityType:      "stream:chat:v1:message",
    EntityID:        messageId,
    EntityCreatorID: getstream.PtrTo(creatorId),
    Reason:          getstream.PtrTo("spam"),
    Custom: map[string]interface{}{
        "user_comment": "This user is spamming the channel",
    },
    UserID: getstream.PtrTo(moderatorId),
})

client.moderation().flag(FlagRequest.builder()
    .entityType("stream:chat:v1:message")
    .entityID(messageId)
    .entityCreatorID(creatorId)
    .reason("spam")
    .custom(Map.of("user_comment", "This user is spamming the channel"))
    .userId(moderatorId)
    .build()).execute();

$client->moderation()->flag(new FlagRequest(
    entityType: 'stream:chat:v1:message',
    entityID: $messageId,
    entityCreatorID: $creatorId,
    reason: 'spam',
    custom: (object)['user_comment' => 'This user is spamming the channel'],
    userID: $moderatorId,
));

client.moderation.flag(GetStream::Generated::Models::FlagRequest.new(
  entity_type: "stream:chat:v1:message",
  entity_id: message_id,
  entity_creator_id: creator_id,
  reason: "spam",
  custom: { "user_comment" => "This user is spamming the channel" },
  user_id: moderator_id
))

await client.Moderation.FlagAsync(new FlagRequest
{
    EntityType = "stream:chat:v1:message",
    EntityID = messageId,
    EntityCreatorID = creatorId,
    Reason = "spam",
    Custom = new Dictionary<string, object>
    {
        { "user_comment", "This user is spamming the channel" }
    },
    UserID = 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.

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

client.moderation().flag(
    entity_type="stream:user",
    entity_id=target_user_id,
    reason="harassment",
    user_id=moderator_id,
)

client.Moderation().Flag(ctx, &getstream.FlagRequest{
    EntityType: "stream:user",
    EntityID:   targetUserId,
    Reason:     getstream.PtrTo("harassment"),
    UserID:     getstream.PtrTo(moderatorId),
})

client.moderation().flag(FlagRequest.builder()
    .entityType("stream:user")
    .entityID(targetUserId)
    .reason("harassment")
    .userId(moderatorId)
    .build()).execute();

$client->moderation()->flag(new FlagRequest(
    entityType: 'stream:user',
    entityID: $targetUserId,
    reason: 'harassment',
    userID: $moderatorId,
));

client.moderation.flag(GetStream::Generated::Models::FlagRequest.new(
  entity_type: "stream:user",
  entity_id: target_user_id,
  reason: "harassment",
  user_id: moderator_id
))

await client.Moderation.FlagAsync(new FlagRequest
{
    EntityType = "stream:user",
    EntityID = targetUserId,
    Reason = "harassment",
    UserID = moderatorId,
});

Query Moderation Flags

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

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

response = client.moderation().query_moderation_flags(
    filter={"entity_type": "stream:chat:v1:message"},
    sort=[{"field": "created_at", "direction": -1}],
    limit=20,
)

response, err := client.Moderation().QueryModerationFlags(ctx, &getstream.QueryModerationFlagsRequest{
    Filter: map[string]interface{}{
        "entity_type": "stream:chat:v1:message",
    },
    Sort: []getstream.SortParam{
        {Field: "created_at", Direction: getstream.PtrTo(-1)},
    },
    Limit: getstream.PtrTo(20),
})

var response = client.moderation().queryModerationFlags(QueryModerationFlagsRequest.builder()
    .filter(Map.of("entity_type", "stream:chat:v1:message"))
    .sort(List.of(SortParam.builder().field("created_at").direction(-1).build()))
    .limit(20)
    .build()).execute();

$response = $client->moderation()->queryModerationFlags(new QueryModerationFlagsRequest(
    filter: (object)['entity_type' => 'stream:chat:v1:message'],
    sort: [new SortParam(field: 'created_at', direction: -1)],
    limit: 20,
));

response = client.moderation.query_moderation_flags(GetStream::Generated::Models::QueryModerationFlagsRequest.new(
  filter: { "entity_type" => "stream:chat:v1:message" },
  sort: [GetStream::Generated::Models::SortParam.new(field: "created_at", direction: -1)],
  limit: 20
))

var response = await client.Moderation.QueryModerationFlagsAsync(new QueryModerationFlagsRequest
{
    Filter = new Dictionary<string, object>
    {
        { "entity_type", "stream:chat:v1:message" }
    },
    Sort = new List<SortParam>
    {
        new SortParam { 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

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.

client.Moderation().Mute(ctx, &getstream.MuteRequest{
    TargetIds: []string{"user_to_mute"},
    UserID:    getstream.PtrTo(mutingUserId),
    Timeout:   getstream.PtrTo(60),
})

client.moderation().mute(MuteRequest.builder()
    .targetIds(List.of("user_to_mute"))
    .userId(mutingUserId)
    .timeout(60)
    .build()).execute();

client.moderation.mute(GetStream::Generated::Models::MuteRequest.new(
  target_ids: ["user_to_mute"],
  user_id: muting_user_id,
  timeout: 60
))

await client.Moderation.MuteAsync(new MuteRequest
{
    TargetIds = new List<string> { "user_to_mute" },
    UserID = 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.

client.Moderation().Unmute(ctx, &getstream.UnmuteRequest{
    TargetIds: []string{"user_to_unmute"},
    UserID:    getstream.PtrTo(unmutingUserId),
})

client.moderation().unmute(UnmuteRequest.builder()
    .targetIds(List.of("user_to_unmute"))
    .userId(unmutingUserId)
    .build()).execute();

client.moderation.unmute(GetStream::Generated::Models::UnmuteRequest.new(
  target_ids: ["user_to_unmute"],
  user_id: unmuting_user_id
))

await client.Moderation.UnmuteAsync(new UnmuteRequest
{
    TargetIds = new List<string> { "user_to_unmute" },
    UserID = unmutingUserId,
});

Ban

Banning prevents a user from posting messages. Users can be banned from a specific channel or from the entire app. 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.

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

client.moderation().ban(
    target_user_id="user_to_ban",
    banned_by_id=moderator_id,
    reason="Repeated spam",
    timeout=1440,
)

client.Moderation().Ban(ctx, &getstream.BanRequest{
    TargetUserID: "user_to_ban",
    BannedByID:   getstream.PtrTo(moderatorId),
    Reason:       getstream.PtrTo("Repeated spam"),
    Timeout:      getstream.PtrTo(1440),
})

client.moderation().ban(BanRequest.builder()
    .targetUserID("user_to_ban")
    .bannedByID(moderatorId)
    .reason("Repeated spam")
    .timeout(1440)
    .build()).execute();

$client->moderation()->ban(new BanRequest(
    targetUserID: 'user_to_ban',
    bannedByID: $moderatorId,
    reason: 'Repeated spam',
    timeout: 1440,
));

client.moderation.ban(GetStream::Generated::Models::BanRequest.new(
  target_user_id: "user_to_ban",
  banned_by_id: moderator_id,
  reason: "Repeated spam",
  timeout: 1440
))

await client.Moderation.BanAsync(new BanRequest
{
    TargetUserID = "user_to_ban",
    BannedByID = 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

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.

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,
});

client.moderation().ban(
    target_user_id="user_to_ban",
    banned_by_id=moderator_id,
    channel_cid="messaging:general",
    reason="Trolling in this channel",
    timeout=60,
)

client.Moderation().Ban(ctx, &getstream.BanRequest{
    TargetUserID: "user_to_ban",
    BannedByID:   getstream.PtrTo(moderatorId),
    ChannelCID:   getstream.PtrTo("messaging:general"),
    Reason:       getstream.PtrTo("Trolling in this channel"),
    Timeout:      getstream.PtrTo(60),
})

client.moderation().ban(BanRequest.builder()
    .targetUserID("user_to_ban")
    .bannedByID(moderatorId)
    .channelCID("messaging:general")
    .reason("Trolling in this channel")
    .timeout(60)
    .build()).execute();

$client->moderation()->ban(new BanRequest(
    targetUserID: 'user_to_ban',
    bannedByID: $moderatorId,
    channelCID: 'messaging:general',
    reason: 'Trolling in this channel',
    timeout: 60,
));

client.moderation.ban(GetStream::Generated::Models::BanRequest.new(
  target_user_id: "user_to_ban",
  banned_by_id: moderator_id,
  channel_cid: "messaging:general",
  reason: "Trolling in this channel",
  timeout: 60
))

await client.Moderation.BanAsync(new BanRequest
{
    TargetUserID = "user_to_ban",
    BannedByID = moderatorId,
    ChannelCID = "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.

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

client.moderation().ban(
    target_user_id="user_to_shadow_ban",
    banned_by_id=moderator_id,
    reason="Disruptive behavior",
    shadow=True,
)

client.Moderation().Ban(ctx, &getstream.BanRequest{
    TargetUserID: "user_to_shadow_ban",
    BannedByID:   getstream.PtrTo(moderatorId),
    Reason:       getstream.PtrTo("Disruptive behavior"),
    Shadow:       getstream.PtrTo(true),
})

client.moderation().ban(BanRequest.builder()
    .targetUserID("user_to_shadow_ban")
    .bannedByID(moderatorId)
    .reason("Disruptive behavior")
    .shadow(true)
    .build()).execute();

$client->moderation()->ban(new BanRequest(
    targetUserID: 'user_to_shadow_ban',
    bannedByID: $moderatorId,
    reason: 'Disruptive behavior',
    shadow: true,
));

client.moderation.ban(GetStream::Generated::Models::BanRequest.new(
  target_user_id: "user_to_shadow_ban",
  banned_by_id: moderator_id,
  reason: "Disruptive behavior",
  shadow: true
))

await client.Moderation.BanAsync(new BanRequest
{
    TargetUserID = "user_to_shadow_ban",
    BannedByID = moderatorId,
    Reason = "Disruptive behavior",
    Shadow = true,
});

Unban User

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

client.Moderation().Unban(ctx, &getstream.UnbanRequest{
    TargetUserID: "user_to_unban",
    UnbannedByID: getstream.PtrTo(moderatorId),
})

client.moderation().unban(UnbanRequest.builder()
    .targetUserID("user_to_unban")
    .unbannedByID(moderatorId)
    .build()).execute();

client.moderation.unban(GetStream::Generated::Models::UnbanRequest.new(
  target_user_id: "user_to_unban",
  unbanned_by_id: moderator_id
))

Block

Blocking allows a user to block another user. This is a server-side operation.

client.Moderation().Block(ctx, &getstream.BlockRequest{
    TargetUserID: "user_to_block",
    UserID:       getstream.PtrTo(blockingUserId),
})

client.moderation().block(BlockRequest.builder()
    .targetUserID("user_to_block")
    .userId(blockingUserId)
    .build()).execute();

client.moderation.block(GetStream::Generated::Models::BlockRequest.new(
  target_user_id: "user_to_block",
  user_id: blocking_user_id
))

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.

client.moderation.bypass(GetStream::Generated::Models::BypassRequest.new(
  user_id: "trusted_user_id",
  bypass: true
))

Request parameters

key	required	type	description
user_id	true	string	User ID to enable/disable bypass for.
bypass	true	boolean	`true` to enable bypass, `false` to disable.

User Moderation Report

Retrieve a comprehensive moderation report for a user, including their flags, bans, mutes, and other moderation actions.

response, err := client.Moderation().GetUserModerationReport(ctx, &getstream.GetUserModerationReportRequest{
    UserID: "user_123",
})

var response = client.moderation().getUserModerationReport(GetUserModerationReportRequest.builder()
    .userId("user_123")
    .build()).execute();

response = client.moderation.get_user_moderation_report(GetStream::Generated::Models::GetUserModerationReportRequest.new(
  user_id: "user_123"
))

var response = await client.Moderation.GetUserModerationReportAsync(new GetUserModerationReportRequest
{
    UserID = "user_123",
});

Check Content

Review Queue