Flag Message

Guide to flagging messages for moderation review using the CometChat iOS SDK.

Quick Reference for AI Agents & Developers

• Get flag reasons: CometChat.getFlagReasons(onSuccess:onError:)
• Flag message: CometChat.flagMessage(messageId:detail:onSuccess:onError:)
• Review flagged: CometChat Dashboard → Moderation → Flagged Messages
• Related: Moderation · AI Moderation · Messaging Overview

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:

Requirement	Location
Enable Moderation	CometChat Dashboard > App Settings
Configure Flag Reasons	Dashboard > Moderation > Advanced Settings

How It Works

---

Get Flag Reasons

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

Swift

CometChat.getFlagReasons { reasons in
    print("Flag reasons: \(reasons)")
    for reason in reasons {
        print("ID: \(reason.id ?? "")")
    }
} onError: { error in
    print("Error: \(error?.errorDescription)")
}

Sample Payloads - Get Flag Reasons

Request

Method: CometChat.getFlagReasons(onSuccess:onError:)

No parameters required.

Success Response

Response Summary:

Parameter	Type	Value
count	Int	3

Flag Reasons Array (example IDs - actual values from Dashboard):

Index	ID	Type
0	"spam"	FlagReason
1	"harassment"	FlagReason
2	"hate_speech"	FlagReason

FlagReason Object Properties:

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

Error Response

Object Type: CometChatException

Parameter	Type	Value
errorCode	String	"ERR_FEATURE_NOT_ACCESSIBLE"
errorDescription	String	"Moderation feature is not available. To enable this feature, please upgrade your plan."

---

Flag a Message

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

Swift

let flagDetail = FlagDetail(
    messageId: 12345,
    reasonId: "spam",
    remark: "This message contains promotional content"
)

CometChat.flagMessage(messageId: 12345, detail: flagDetail) { response in
    print("Message flagged: \(response)")
} onError: { error in
    print("Error: \(error?.errorDescription)")
}

Sample Payloads - Flag Message

Request

Method: CometChat.flagMessage(messageId:detail:onSuccess:onError:)

Parameter	Type	Value
messageId	Int	12345
reasonId	String	"spam"
remark	String	"This message contains promotional content"

FlagDetail Object:

Parameter	Type	Required	Description
messageId	Int	YES	ID of message to flag
reasonId	String	YES	ID from getFlagReasons()
remark	String	NO	Additional context

Success Response

Response:

Parameter	Type	Value
message	String	"Message 12345 has been flagged successfully."

Error Response

Object Type: CometChatException

Parameter	Type	Value
errorCode	String	"ERR_FEATURE_NOT_ACCESSIBLE"
errorDescription	String	"Moderation feature is not available. To enable this feature, please upgrade your plan."

More Sample Payloads

Flag for Harassment

Request:

Parameter	Type	Value
messageId	Int	12345
reasonId	String	"harassment"
remark	String	"Inappropriate behavior towards other users"

Swift Code:

let flagDetail = FlagDetail(
    messageId: 12345,
    reasonId: "harassment",
    remark: "Inappropriate behavior towards other users"
)
CometChat.flagMessage(messageId: 12345, detail: flagDetail) { response in
    print("Message flagged: \(response)")
} onError: { error in
    print("Error: \(error?.errorDescription)")
}

Flag for Hate Speech

Request:

Parameter	Type	Value
messageId	Int	12345
reasonId	String	"hate_speech"
remark	String	"Contains offensive language"

Swift Code:

let flagDetail = FlagDetail(
    messageId: 12345,
    reasonId: "hate_speech",
    remark: "Contains offensive language"
)
CometChat.flagMessage(messageId: 12345, detail: flagDetail) { response in
    print("Message flagged: \(response)")
} onError: { error in
    print("Error: \(error?.errorDescription)")
}

---

Implementation Flow

Step	Action	Method
1	Load flag reasons on app init	CometChat.getFlagReasons()
2	Cache reasons for UI	Store in array/state
3	Show reason picker to user	Display cached reasons
4	User selects reason + remark	Capture selection
5	Submit flag	CometChat.flagMessage()
6	Review in Dashboard	Moderation > Flagged

---

Complete Example

Swift

class ReportMessageHandler {
    private var flagReasons: [FlagReason] = []
    
    func loadFlagReasons(completion: @escaping ([FlagReason]) -> Void) {
        CometChat.getFlagReasons { [weak self] reasons in
            self?.flagReasons = reasons
            completion(reasons)
        } onError: { error in
            completion([])
        }
    }
    
    func flagMessage(messageId: Int, reasonId: String, remark: String?) {
        let flagDetail = FlagDetail(
            messageId: messageId,
            reasonId: reasonId,
            remark: remark ?? ""
        )
        
        CometChat.flagMessage(messageId: messageId, detail: flagDetail) { response in
            print("Success: \(response)")
        } onError: { error in
            print("Error: \(error?.errorDescription ?? "")")
        }
    }
}

---

Common Error Codes

Error Code	Description	Resolution
ERR_NOT_LOGGED_IN	User is not logged in	Login first
ERR_MESSAGE_NOT_FOUND	Message doesn’t exist	Verify message ID
ERR_INVALID_REASON_ID	Invalid flag reason ID	Use ID from getFlagReasons()
ERR_FEATURE_NOT_ACCESSIBLE	Moderation not enabled	Enable in Dashboard or upgrade plan