Flag Message - CometChat Docs

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.

For a complete understanding of how flagged messages are reviewed and managed, see the Flagged Messages documentation.

Prerequisites

Before using the flag message feature:

Moderation must be enabled for your app in the CometChat Dashboard
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:

TypeScript
JavaScript

CometChat.getFlagReasons().then(
  (reasons: CometChat.FlagReason[]) => {
    console.log("Flag reasons retrieved:", reasons);
    // reasons is an array of { id, reason } objects
    // Use these to populate your report dialog UI
  },
  (error: CometChat.CometChatException) => {
    console.log("Failed to get flag reasons:", error);
  }
);

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 FlagReason objects, each with an id and reason string:

[
  { 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:

TypeScript
JavaScript

const messageId: string = "MESSAGE_ID_TO_FLAG";
const payload: { reasonId: string; remark?: string } = {
  reasonId: "spam",
  remark: "This message contains promotional content"
};

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

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

Parameter	Type	Required	Description
messageId	string	Yes	The ID of the message to flag
payload.reasonId	string	Yes	ID of the flag reason (from `getFlagReasons()`)
payload.remark	string	No	Additional context or explanation from the user

Response

The Promise resolves with a success confirmation object:

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

The flagged message is a BaseMessage object. You can identify it using getId(), getSender() (returns a User), and getType().

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

Next Steps

AI Moderation

Automate content moderation with AI

Delete a Message

Remove messages from conversations

Receive Messages

Listen for incoming messages in real time

Send Messages

Send text, media, and custom messages

​Overview

​Prerequisites

​How It Works

​Get Flag Reasons

​Response

​Flag a Message

​Parameters

​Response

​Complete Example

​Next Steps

AI Moderation

Delete a Message

Receive Messages

Send Messages

Overview

Prerequisites

How It Works

Get Flag Reasons

Response

Flag a Message

Parameters

Response

Complete Example

Next Steps