Flag Message - CometChat Docs

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
Success Response
Error Response

Method: CometChat.getFlagReasons(onSuccess:onError:)No parameters required.

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

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
Success Response
Error Response

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

Response:

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

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
Flag for Hate Speech

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

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

​Overview

​Prerequisites

​How It Works

​Get Flag Reasons

​Flag a Message

​Implementation Flow

​Complete Example

​Common Error Codes

Overview

Prerequisites

How It Works

Get Flag Reasons

Flag a Message

Implementation Flow

Complete Example

Common Error Codes