Skip to main content
Quick Reference for AI Agents & Developers
// Get available flag reasons
const reasons = await CometChat.getFlagReasons();

// Flag a message with a reason
const payload = { reasonId: "spam", remark: "Promotional content" };
await CometChat.flagMessage("MESSAGE_ID", payload);
Required: Moderation enabled in Dashboard → Moderation → Advanced Settings

​
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 | UI Kits
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().then(
  (reasons) => {
    console.log("Flag reasons retrieved:", reasons);
    // reasons is an array of { id, reason } objects
    // Use these to populate your report dialog UI
  },
  (error) => {
    console.log("Failed to get flag reasons:", error);
  }
);

​
Response

The response is an array of flag reason objects: 
[
  { "id": "spam", "reason": "Spam or misleading" },
  { "id": "harassment", "reason": "Harassment or bullying" },
  { "id": "hate_speech", "reason": "Hate speech" },
  { "id": "violence", "reason": "Violence or dangerous content" },
  { "id": "inappropriate", "reason": "Inappropriate content" },
  { "id": "other", "reason": "Other" }
]

​
Flag a Message

To flag a message, use the flagMessage() method with the message ID and a payload containing the reason: 
const messageId = "MESSAGE_ID_TO_FLAG";
const payload = {
  reasonId: "spam",  // Required: ID from getFlagReasons()
  remark: "This message contains promotional content"  // Optional
};

CometChat.flagMessage(messageId, payload).then(
  (response) => {
    console.log("Message flagged successfully:", response);
  },
  (error) => {
    console.log("Message flagging failed:", error);
  }
);

​
Parameters

ParameterTypeRequiredDescription
messageIdstringYesThe ID of the message to flag
payload.reasonIdstringYesID of the flag reason (from getFlagReasons())
payload.remarkstringNoAdditional context or explanation from the user

​
Response

{
  "success": true,
  "message": "Message with id {{messageId}} has been flagged successfully"
}

​
Complete Example

Here’s a complete implementation showing how to build a report message flow: 
class ReportMessageHandler {
  constructor() {
    this.flagReasons = [];
  }

  // Load flag reasons (call this on app init or when needed)
  async loadFlagReasons() {
    try {
      this.flagReasons = await CometChat.getFlagReasons();
      return this.flagReasons;
    } catch (error) {
      console.error("Failed to load flag reasons:", error);
      return [];
    }
  }

  // Get reasons for UI display
  getReasons() {
    return this.flagReasons;
  }

  // Flag a message with selected reason
  async flagMessage(messageId, reasonId, remark = "") {
    if (!reasonId) {
      throw new Error("Reason ID is required");
    }

    try {
      const payload = { reasonId };
      if (remark) {
        payload.remark = remark;
      }

      const response = await CometChat.flagMessage(messageId, payload);
      console.log("Message flagged successfully");
      return { success: true, response };
    } catch (error) {
      console.error("Failed to flag message:", error);
      return { success: false, error };
    }
  }
}

// Usage
const reportHandler = new ReportMessageHandler();

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

// When user wants to report a message
const reasons = reportHandler.getReasons();
// Display reasons in UI for user to select...

// When user submits the report
const result = await reportHandler.flagMessage(
  "message_123",
  "spam",
  "User is sending promotional links"
);

if (result.success) {
  showToast("Message reported successfully");
}
  • Cache flag reasons: Call getFlagReasons() once at app initialization or when the report dialog is first opened, then reuse the cached list. Avoid fetching reasons on every report action.
  • Require a reason: Always require users to select a reason before submitting a flag. This improves the quality of moderation data and helps moderators prioritize reviews.
  • Provide a remark field: Allow users to add optional context via the remark parameter. Additional details help moderators make faster, more informed decisions.
  • Confirm before submitting: Show a confirmation dialog before calling flagMessage() to prevent accidental reports.
  • Show feedback after flagging: Display a success message or toast after a message is flagged so the user knows their report was submitted.
  • getFlagReasons() returns an empty array: Ensure that flag reasons are configured in the CometChat Dashboard under Moderation > Advanced Settings. Moderation must also be enabled for your app.
  • flagMessage() fails with an error: Verify that the reasonId matches one of the IDs returned by getFlagReasons(). Also confirm that the messageId is valid and belongs to a conversation the logged-in user has access to.
  • Flagged messages not appearing in Dashboard: Check that moderation is enabled in your Dashboard settings. Flagged messages appear under Moderation > Flagged Messages.
  • Permission errors: The logged-in user must be a participant in the conversation containing the message they want to flag. Users cannot flag messages from conversations they are not part of.

​
Next Steps

Edit Message

Edit sent messages in one-on-one and group conversations

Delete Message

Delete messages for yourself or for all participants

Receive Messages

Listen for incoming messages in real time

Delivery & Read Receipts

Track message delivery and read status