Flag Message - CometChat Docs

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:

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:

JavaScript
TypeScript

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

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

Response

On Success — getFlagReasons() returns an array of flag reason objects:Flag Reason Array (per item):

Parameter	Type	Description	Sample Value
`id`	string	Unique identifier for the flag reason	`"spam"`
`name`	string	Display name of the flag reason	`"Spam"`
`description`	string	Detailed description of the reason	`"Repeated, promotional, or irrelevant content"`
`createdAt`	number	Unix timestamp when reason was created	`1761627675`
`updatedAt`	number	Unix timestamp when reason was last updated	`1761627675`
`default`	boolean	Whether this is a default reason	`false`

Flag a Message

To flag a message, use the flagMessage() method with the message ID and a payload containing the reason:

JavaScript
TypeScript

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

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

Response

On Success — flagMessage() returns a success response:Response Object:

Parameter	Type	Description	Sample Value
`success`	boolean	Indicates if the flag operation succeeded	`true`
`message`	string	Confirmation message with flagged message ID	`"Message 25300 has been flagged successfully."`

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

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

Best Practices

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.

Troubleshooting

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

​Overview

​Prerequisites

​How It Works

​Get Flag Reasons

​Flag a Message

​Parameters

​Complete Example

​Next Steps

Edit Message

Delete Message

Receive Messages

Delivery & Read Receipts

Overview

Prerequisites

How It Works

Get Flag Reasons

Flag a Message

Parameters

Complete Example

Next Steps