Report offensive messages

Chat SDK provides a mechanism for users to report offensive content in messages directly from their applications.

In each case, a user must provide a reason for flagging a given message. As a result of flagging, a reported message gets published on the dedicated administrative channel (with the ID of PUBNUB_INTERNAL_MODERATION_{channel_id}) and an event of the report type gets created.

As a developer, you can add custom logic that uses the emitted events and defines what an admin can later do with such reported messages. For example, an admin can delete an inappropriate message.

Message Persistence

To work with stored message data, you must enable Message Persistence for your app's keyset in the Admin Portal.

Under the hood

Flag/Report messages

report() lets you flag and report an inappropriate message to the admin.

All messages (events of type report) reported on a given channel are sent to a PUBNUB_INTERNAL_MODERATION_{channel_id} channel which is a child channel for the main one where a reported message was published. For example, an event on a message reported on the support channel will be sent to the PUBNUB_INTERNAL_MODERATION_support channel.

Method signature

This method takes the following parameters:

message.report(reason: string): Promise<any>

Input

Parameter	Type	Required	Default	Description
reason	string	Yes	n/a	Reason for reporting/flagging a given message.

Output

Type	Description
Promise<any>	Returned object with a value of any type.

Basic usage

Report the last message on the support channel as offensive.

// reference the "incident-management" channel
const channel = await chat.getChannel("support")
// get the last message on the channel
const lastMessage = (await channel.getHistory({count: 1})).messages[0]
// report the message to the admin and provide the reason
await message.report("This message contains profane words. Can you remove it?")

Get historical reported messages

getMessageReportsHistory() fetches a list of reported message events for a specified channel within optional time and count constraints, returning the events and a boolean indicating if there are more events to fetch.

This method prefixes the internal channel ID with a predefined string (INTERNAL_MODERATION_PREFIX) and calls the getEventsHistory method of the chat instance, passing along the constructed channel ID and any additional parameters.

Method signature

This method takes the following parameters:

channel.getMessageReportsHistory(params?: {
    startTimetoken?: string;
    endTimetoken?: string;
    count?: number;
}): Promise<{
    events: Event<"report">[];
    isMore: boolean;
}>

Input

Parameter	Type	Required	Default	Description
startTimetoken	string	No	n/a	The start timetoken for fetching the history of reported messages, which allows specifying the point in time where the history retrieval should begin.
endTimetoken	string	No	n/a	The end time token for fetching the history of reported messages, which allows specifying the point in time where the history retrieval should end.
count	number	No	undefined	The number of reported message events to fetch from the history.

Output

Parameter	Type	Description
Promise<>	object	Returned object containing these fields: events and isMore.
→ events	Event<"report">[]	An array of events where each event is of the type "report". These events represent the reported messages in the specified channel.
→ isMore	boolean	A boolean flag indicating whether there are more reported message events available apart from the ones fetched in the current operation.

Basic usage

Fetch historical messages reported on the support channel between the 1725100800000 (July 1, 2024, 00:00:00 UTC) and 1726780799000 (July 21, 2024, 23:59:59 UTC) timetokens.

// Example start and end timetokens
const startTimetoken = "1725100800000"; // July 1, 2024, 00:00:00 UTC in milliseconds
const endTimetoken = "1726780799000";   // July 21, 2024, 23:59:59 UTC in milliseconds

// asynchronously fetch the channel object and then get the reported messages history
async function fetchReportedMessagesHistory() {
    try {
        // reference the "chat" object and invoke the "getChannel()" method
        const channel = await chat.getChannel("support");

        // fetch the reported message history
        const { events, isMore } = await channel.getMessageReportsHistory({
            startTimetoken,
            endTimetoken
        });

show all 25 lines

Listen to report events

As an admin of your chat app, you can monitor all events emitted when someone reports an offensive message using the streamMessageReports() method.

You can use this method to create moderation dashboard alerts.

Events documentation

To read more about the events of type report, refer to the Chat events documentation.

Method signature

This method has the following parameters:

channel.streamMessageReports(
    callback: (event: Event<"report">) => void
): () => void

Input

Parameter	Type	Required	Default	Description
channel	string	No (events are sent by default to the PUBNUB_INTERNAL_MODERATION_{channel_id} channel)	n/a	Channel to listen for new report events.
type	string	No	n/a	Type of events. report is the type defined for all events emitted when an offensive message is flagged/reported.
callback	n/a	Yes	n/a	Callback function passed as a parameter. It defines the custom behavior to be executed whenever a report event type is detected on the specified channel.

Output

Type	Description
() => void	Function you can call to disconnect (unsubscribe) from the channel and stop receiving report events.

Basic usage

Print a notification for an offensive message reported on the support channel.

const channel = await chat.getChannel("support")
channel.streamMessageReports((event) => {
  console.log("Report event: ", event)
})

Flag/Report messages (deprecated)

DEPRECATED_report() lets you flag and report an inappropriate message to the admin. All reported messages (events of type report) are sent to one dedicated INTERNAL_ADMIN_CHANNEL channel (one "bucket" for all reported messages).

Method signature

This method takes the following parameters:

message.DEPRECATED_report(reason: string): Promise<any>

Input

Parameter	Type	Required	Default	Description
reason	string	Yes	n/a	Reason for reporting/flagging a given message.

Output

Type	Description
Promise<any>	Returned object with a value of any type.

Basic usage

Report the last message on the support channel as offensive.

// reference the "incident-management" channel
const channel = await chat.getChannel("support")
// get the last message on the channel
const lastMessage = (await channel.getHistory({count: 1})).messages[0]
// report the message to the admin and provide the reason
await message.DEPRECATED_report("This message contains profane words. Can you remove it?")