Flag Message

Report inappropriate messages to moderators using the Android SDK flagging system

Quick Reference for AI Agents & Developers

// Get available flag reasons
CometChat.getFlagReasons(object : CometChat.CallbackListener<MutableList<FlagReason?>>() {
    override fun onSuccess(reasons: MutableList<FlagReason?>?) {
        // Display reasons to user
    }
    override fun onError(e: CometChatException) { }
})

// Flag a message
val flagDetail = FlagDetail().apply {
    reasonId = "spam"
    remark = "Promotional content"
}
CometChat.flagMessage(messageId, flagDetail, object : CometChat.CallbackListener<String?>() {
    override fun onSuccess(response: String?) { }
    override fun onError(e: CometChatException?) { }
})

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:

Kotlin

CometChat.getFlagReasons(object : CometChat.CallbackListener<MutableList<FlagReason?>>() {
    override fun onSuccess(reasons: MutableList<FlagReason?>?) {
        Log.d(TAG, "Flag reasons fetched: $reasons")
        // Use reasons to populate your report dialog UI
        reasons?.forEach { reason ->
            Log.d(TAG, "Reason ID: ${reason?.id}, Title: ${reason?.reason}")
        }
    }

    override fun onError(e: CometChatException) {
        Log.e(TAG, "Error fetching flag reasons: ${e.message}")
    }
})

Java

CometChat.getFlagReasons(new CometChat.CallbackListener<List<FlagReason>>() {
    @Override
    public void onSuccess(List<FlagReason> reasons) {
        Log.d(TAG, "Flag reasons fetched: " + reasons);
        // Use reasons to populate your report dialog UI
        for (FlagReason reason : reasons) {
            Log.d(TAG, "Reason ID: " + reason.getId() + ", Title: " + reason.getReason());
        }
    }

    @Override
    public void onError(CometChatException e) {
        Log.e(TAG, "Error fetching flag reasons: " + e.getMessage());
    }
});

Response

The response is a list of FlagReason objects containing:

Property	Type	Description
id	String	Unique identifier for the reason
reason	String	Display text for the reason

Flag a Message

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

Kotlin

val messageId = 123L  // ID of the message to flag

val flagDetail = FlagDetail().apply {
    reasonId = "spam"  // Required: ID from getFlagReasons()
    remark = "This message contains promotional content"  // Optional
}

CometChat.flagMessage(messageId, flagDetail, object : CometChat.CallbackListener<String?>() {
    override fun onSuccess(response: String?) {
        Log.d(TAG, "Message flagged successfully: $response")
    }

    override fun onError(e: CometChatException?) {
        Log.e(TAG, "Message flagging failed: ${e?.message}")
    }
})

Java

long messageId = 123L;  // ID of the message to flag

FlagDetail flagDetail = new FlagDetail();
flagDetail.setReasonId("spam");  // Required: ID from getFlagReasons()
flagDetail.setRemark("This message contains promotional content");  // Optional

CometChat.flagMessage(messageId, flagDetail, new CometChat.CallbackListener<String>() {
    @Override
    public void onSuccess(String response) {
        Log.d(TAG, "Message flagged successfully: " + response);
    }

    @Override
    public void onError(CometChatException e) {
        Log.e(TAG, "Message flagging failed: " + e.getMessage());
    }
});

Parameters

Parameter	Type	Required	Description
messageId	long	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

Response

{
  "message": "Message {id} has been flagged successfully."
}

Complete Example

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

Kotlin

class ReportMessageHandler {
    private var flagReasons: List<FlagReason?> = emptyList()

    // Load flag reasons (call this on app init or when needed)
    fun loadFlagReasons(callback: (List<FlagReason?>) -> Unit) {
        CometChat.getFlagReasons(object : CometChat.CallbackListener<MutableList<FlagReason?>>() {
            override fun onSuccess(reasons: MutableList<FlagReason?>?) {
                flagReasons = reasons ?: emptyList()
                callback(flagReasons)
            }

            override fun onError(e: CometChatException) {
                Log.e(TAG, "Failed to load flag reasons: ${e.message}")
                callback(emptyList())
            }
        })
    }

    // Get reasons for UI display
    fun getReasons(): List<FlagReason?> = flagReasons

    // Flag a message with selected reason
    fun flagMessage(
        messageId: Long,
        reasonId: String,
        remark: String? = null,
        callback: (Boolean, String?) -> Unit
    ) {
        val flagDetail = FlagDetail().apply {
            this.reasonId = reasonId
            remark?.let { this.remark = it }
        }

        CometChat.flagMessage(messageId, flagDetail, object : CometChat.CallbackListener<String?>() {
            override fun onSuccess(response: String?) {
                callback(true, response)
            }

            override fun onError(e: CometChatException?) {
                callback(false, e?.message)
            }
        })
    }
}

// Usage
val reportHandler = ReportMessageHandler()

// Load reasons when app initializes
reportHandler.loadFlagReasons { reasons ->
    // Display reasons in UI for user to select
}

// When user submits the report
reportHandler.flagMessage(123L, "spam", "User is sending promotional links") { success, message ->
    if (success) {
        showToast("Message reported successfully")
    }
}

Best Practices

Load Flag Reasons on App Init

Fetch flag reasons once during app initialization and cache them locally. This reduces API calls and provides instant access when users need to report messages.

Provide Clear UI for Reporting

Display flag reasons in a user-friendly dialog or bottom sheet. Include the optional remark field to allow users to provide additional context about why they’re reporting the message.

Confirm Before Flagging

Show a confirmation dialog before submitting the flag to prevent accidental reports. Explain to users that flagged messages will be reviewed by moderators.

Handle Duplicate Flags Gracefully

If a user tries to flag the same message multiple times, handle the error gracefully and inform them the message has already been reported.

Troubleshooting

Moderation Not Enabled

Symptom: getFlagReasons() or flagMessage() fails with “Moderation is not enabled” error.

Cause: Moderation feature is not enabled for your app in the CometChat Dashboard.

Solution: Enable moderation in the CometChat Dashboard under Moderation > Settings. Configure flag reasons under Advanced Settings.

Invalid Reason ID

Symptom: flagMessage() fails with “Invalid reason ID” error.

Cause: The reasonId provided doesn’t match any configured flag reasons.

Solution: Always use reason IDs from the getFlagReasons() response. Verify the reason ID exists in your Dashboard configuration.

Message Already Flagged

Symptom: flagMessage() fails with “Message already flagged” error.

Cause: The user has already flagged this message previously.

Solution: Inform the user that they’ve already reported this message. Consider disabling the flag button for previously flagged messages.

---

Next Steps

Flagged Messages

Review and manage flagged messages in the Dashboard

AI Moderation

Automatically detect and filter inappropriate content

Block Users

Allow users to block other users from contacting them

Delete Message

Delete messages from conversations