> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-rn-guide-message-privately.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Flag Message

> Learn how to flag and report inappropriate messages for moderation review in your Flutter application using CometChat SDK.

<Accordion title="AI Integration Quick Reference">
  ```dart theme={null}
  // 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}");
    },
  );
  ```
</Accordion>

## Overview

Flagging messages allows users to report inappropriate content to moderators or administrators. When a message is flagged, it appears in the [CometChat Dashboard](https://app.cometchat.com) under **Moderation > Flagged Messages** for review.

<Note>
  **Available via:** SDK | [REST API](https://api-explorer.cometchat.com) | [Dashboard](https://app.cometchat.com)
</Note>

<Note>
  For a complete understanding of how flagged messages are reviewed and managed, see the [Flagged Messages](/moderation/flagged-messages) documentation.
</Note>

## Prerequisites

Before using the flag message feature:

1. Moderation must be enabled for your app in the [CometChat Dashboard](https://app.cometchat.com)
2. Flag reasons should be configured under **Moderation > Advanced Settings**

## How It Works

```mermaid theme={null}
sequenceDiagram
    participant User
    participant App
    participant SDK
    participant CometChat
    participant Dashboard

    User->>App: Reports message
    App->>SDK: getFlagReasons()
    SDK-->>App: Available reasons
    App->>User: Show reason picker
    User->>App: Select reason + remark
    App->>SDK: flagMessage(id, flagDetail)
    SDK->>CometChat: Flag message
    CometChat-->>SDK: Success response
    SDK-->>App: Message flagged
    CometChat->>Dashboard: Message in Flagged queue
```

## Get Flag Reasons

Before flagging a message, retrieve the list of available flag reasons configured in your Dashboard:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    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}");
      },
    );
    ```
  </Tab>
</Tabs>

### Response

The response is a list of `FlagReason` objects containing:

| Property      | Type        | Description                                |
| ------------- | ----------- | ------------------------------------------ |
| `id`          | `String`    | Unique identifier for the reason           |
| `name`        | `String`    | Display name for the reason                |
| `description` | `String?`   | Optional description of the reason         |
| `createdAt`   | `DateTime?` | Timestamp when the reason was created      |
| `updatedAt`   | `DateTime?` | Timestamp when the reason was last updated |

<Accordion title="Error">
  | Parameter | Type     | Description                  | Sample Value                                                   |
  | --------- | -------- | ---------------------------- | -------------------------------------------------------------- |
  | `code`    | `String` | Error code identifier        | `"ERR_CHAT_API_FAILURE"`                                       |
  | `message` | `String` | Human-readable error message | `"Failed to fetch flag reasons."`                              |
  | `details` | `String` | Additional technical details | `"An unexpected error occurred while processing the request."` |
</Accordion>

## Flag a Message

To flag a message, use the `flagMessage()` method with the message ID and a `FlagDetail` object:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    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}");
      },
    );
    ```
  </Tab>
</Tabs>

### Parameters

| Parameter             | Type         | Required | Description                                     |
| --------------------- | ------------ | -------- | ----------------------------------------------- |
| `messageId`           | `int`        | Yes      | The ID of the message to flag                   |
| `flagDetail`          | `FlagDetail` | Yes      | Contains flagging details                       |
| `flagDetail.reasonId` | `String`     | Yes      | ID of the flag reason (from `getFlagReasons()`) |
| `flagDetail.remark`   | `String?`    | No       | Additional context or explanation from the user |

<Accordion title="Response">
  **On Success** — A `String` message confirming the message has been flagged:

  | Parameter | Type     | Description                  | Sample Value                                   |
  | --------- | -------- | ---------------------------- | ---------------------------------------------- |
  | `message` | `String` | Success confirmation message | `"Message 123 has been flagged successfully."` |
</Accordion>

<Accordion title="Error">
  | Parameter | Type     | Description                  | Sample Value                                                   |
  | --------- | -------- | ---------------------------- | -------------------------------------------------------------- |
  | `code`    | `String` | Error code identifier        | `"ERR_CHAT_API_FAILURE"`                                       |
  | `message` | `String` | Human-readable error message | `"Failed to flag the message."`                                |
  | `details` | `String` | Additional technical details | `"An unexpected error occurred while processing the request."` |
</Accordion>

## Complete Example

Here's a complete implementation showing how to build a report message flow:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    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");
    }
    ```
  </Tab>
</Tabs>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Receive Messages" icon="inbox" href="/sdk/flutter/receive-messages">
    Handle incoming messages and real-time events
  </Card>

  <Card title="Delete Message" icon="trash" href="/sdk/flutter/delete-message">
    Remove messages from conversations
  </Card>

  <Card title="AI Moderation" icon="shield-check" href="/sdk/flutter/ai-moderation">
    Automate content moderation with AI
  </Card>

  <Card title="Delivery & Read Receipts" icon="check-double" href="/sdk/flutter/delivery-read-receipts">
    Track message delivery and read status
  </Card>
</CardGroup>