Skip to main content
// Get available flag reasons
CometChat.getFlagReasons(
  onSuccess: (List<FlagReason> reasons) {
    debugPrint("Flag reasons: $reasons");
  },
  onError: (CometChatException e) {
    debugPrint("Error: ${e.message}");
  },
);

// Flag a message
FlagDetail flagDetail = FlagDetail(
  reasonId: "spam",
  remark: "Optional additional context",
);

CometChat.flagMessage(messageId, flagDetail,
  onSuccess: (String response) {
    debugPrint("Message flagged: $response");
  },
  onError: (CometChatException e) {
    debugPrint("Error: ${e.message}");
  },
);

​
Overview

Flagging messages allows users to report inappropriate content to moderators or administrators. When a message is flagged, it appears in the CometChat Dashboard under Moderation > Flagged Messages for review.
Available via: SDK | REST API | Dashboard
For a complete understanding of how flagged messages are reviewed and managed, see the Flagged Messages documentation.

​
Prerequisites

Before using the flag message feature:
  1. Moderation must be enabled for your app in the CometChat Dashboard
  2. Flag reasons should be configured under Moderation > Advanced Settings

​
How It Works

​
Get Flag Reasons

Before flagging a message, retrieve the list of available flag reasons configured in your Dashboard: 
CometChat.getFlagReasons(
  onSuccess: (List<FlagReason> reasons) {
    print("Flag reasons fetched: $reasons");
    // Use reasons to populate your report dialog UI
    for (var reason in reasons) {
      print("Reason ID: ${reason.id}, Name: ${reason.name}");
    }
  },
  onError: (CometChatException e) {
    print("Error fetching flag reasons: ${e.message}");
  },
);

​
Response

The response is a list of FlagReason objects containing:
PropertyTypeDescription
idStringUnique identifier for the reason
nameStringDisplay name for the reason
descriptionString?Optional description of the reason
createdAtDateTime?Timestamp when the reason was created
updatedAtDateTime?Timestamp when the reason was last updated
ParameterTypeDescriptionSample Value
codeStringError code identifier"ERR_CHAT_API_FAILURE"
messageStringHuman-readable error message"Failed to fetch flag reasons."
detailsStringAdditional technical details"An unexpected error occurred while processing the request."

​
Flag a Message

To flag a message, use the flagMessage() method with the message ID and a FlagDetail object: 
int messageId = 123;  // ID of the message to flag

FlagDetail flagDetail = FlagDetail(
  reasonId: "spam",  // Required: ID from getFlagReasons()
  remark: "This message contains promotional content",  // Optional
);

CometChat.flagMessage(
  messageId,
  flagDetail,
  onSuccess: (String response) {
    print("Message flagged successfully: $response");
  },
  onError: (CometChatException e) {
    print("Message flagging failed: ${e.message}");
  },
);

​
Parameters

ParameterTypeRequiredDescription
messageIdintYesThe ID of the message to flag
flagDetailFlagDetailYesContains flagging details
flagDetail.reasonIdStringYesID of the flag reason (from getFlagReasons())
flagDetail.remarkString?NoAdditional context or explanation from the user
On Success — A String message confirming the message has been flagged:
ParameterTypeDescriptionSample Value
messageStringSuccess confirmation message"Message 123 has been flagged successfully."
ParameterTypeDescriptionSample Value
codeStringError code identifier"ERR_CHAT_API_FAILURE"
messageStringHuman-readable error message"Failed to flag the message."
detailsStringAdditional technical details"An unexpected error occurred while processing the request."

​
Complete Example

Here’s a complete implementation showing how to build a report message flow: 
class ReportMessageHandler {
  List<FlagReason> _flagReasons = [];

  // Load flag reasons (call this on app init or when needed)
  Future<List<FlagReason>> loadFlagReasons() async {
    final completer = Completer<List<FlagReason>>();
    
    CometChat.getFlagReasons(
      onSuccess: (List<FlagReason> reasons) {
        _flagReasons = reasons;
        completer.complete(reasons);
      },
      onError: (CometChatException e) {
        print("Failed to load flag reasons: ${e.message}");
        completer.complete([]);
      },
    );
    
    return completer.future;
  }

  // Get reasons for UI display
  List<FlagReason> getReasons() => _flagReasons;

  // Flag a message with selected reason
  Future<bool> flagMessage(
    int messageId,
    String reasonId, {
    String? remark,
  }) async {
    final completer = Completer<bool>();
    
    FlagDetail flagDetail = FlagDetail(
      reasonId: reasonId,
      remark: remark,
    );

    CometChat.flagMessage(
      messageId,
      flagDetail,
      onSuccess: (String response) {
        print("Message flagged successfully");
        completer.complete(true);
      },
      onError: (CometChatException e) {
        print("Failed to flag message: ${e.message}");
        completer.complete(false);
      },
    );
    
    return completer.future;
  }
}

// Usage
final reportHandler = ReportMessageHandler();

// Load reasons when app initializes
await reportHandler.loadFlagReasons();

// When user submits the report
final success = await reportHandler.flagMessage(
  123,
  "spam",
  remark: "User is sending promotional links",
);

if (success) {
  showToast("Message reported successfully");
}

​
Next Steps

Receive Messages

Handle incoming messages and real-time events

Delete Message

Remove messages from conversations

AI Moderation

Automate content moderation with AI

Delivery & Read Receipts

Track message delivery and read status