Required configuration

PubNub provides a flexible set of APIs for creating real-time in-app messaging applications. Moderation Dashboard makes some assumptions about how a chat application is designed. This document provides an overview of how to build a chat application that can work with Moderation Dashboard.

Reference moderated chat app

The moderated chat app is a sample React project that provides a reference and is a recommended starting point for all developers building new chat applications to check how an app should be configured to work with Moderation Dashboard.

Users

The Users view in the Moderation Dashboard is populated through user metadata. That's why a to-be-moderated chat app must include the logic that sets up each User ID with user App Context data (metadata) that includes at least the name field. email, and profileUrl are optional fields that can also be added by the admin to users' App Context metadata.

User ID / UUID

User ID is also referred to as UUID/uuid in some APIs and server responses but holds the value of the userId parameter you set during initialization.

Here's an example of a fully populated user object that can be interpreted by Moderation Dashboard:

custom: {
  "name": "John Smith",
  "email": "jsmith@acme.com",
  "profileUrl": "https//profiles.acme.com/johnsmith"
  }

App Context metadata is not enabled by default. Before making calls to the App Context API, you must enable App Context on your keyset on the Admin Portal as described in the User Metadata document. To notify your chat clients of changes to the users' status, you must also enable User Metadata Events and Channel Metadata Events options on the Admin Portal.

For simplicity, Moderation Dashboard sets user metadata to ban, mute, block, or flag users. You can also choose to use Access Manager, an alternative security-control method supported by PubNub SDKs, to implement channel muting or blocking. Read on to check how you can validate user's App Context metadata in a chat app to enforce user banning, muting, or blocking. If you want to use Access Manager, you will need to modify Moderation Dashboard to update your users' Access Manager tokens accordingly.

Moderation with PubNub SDKs

Check also how you can set profanity filters, flag messages, ban and mute users with our PubNub SDKs.

• Ban users

A banned user should not have any access to any channel in a chat application. Chat applications that enforce banned users through metadata should validate user’s metadata after they log into a chat app. If the metadata includes the ban: true field, the application should log the user out or prevent them from viewing or sending messages to any channel.

If your chat app uses Access Manager, you may want to update the code in BanUser.js, replacing (or adding) the call to setUserMetaData, with a call to the back-end service that manages the Access Manager tokens (https:/mypamservice.acme.com/blockUser?uuid=userID). This interface should implement a pubnub.grantToken() call that sets the user's read and write permissions to false for all channels.

• Mute users

A muted user should be allowed to view the messages in a channel, but should not be allowed to publish them. To enforce a muted user on a particular channel with user’s metadata, inspect the mutedChannels property of the user’s metadata. If the comma-separated list includes the current channel in the value, the application should provide some type of GUI that informs the user they are muted on the channel and should not allow them to publish to that channel.

If your chat app uses Access Manager, you may want to update the code in UserAction.js, replacing (or adding) the call to handleMuteClick, with a call to the back-end service that manages the Access Manager tokens (https:/mypamservice.acme.com/muteUser?uuid=userID&channel=CHANNELID). This interface should implement a pubnub.grantToken() call that sets the user's write permissions to false for the channel.

• Block users

A blocked user should not be allowed to view messages or create new messages in any channel they are blocked from. To enforce a blocked user on a particular channel using user’s metadata, inspect the blockedChannels property of the user’s metadata. If the comma-separated list includes the current channel in the value, the application should provide some type of GUI that informs the user they are blocked from the channel and should not allow them to subscribe or publish to that channel.

If your chat app uses Access Manager, you may want to update the code in UserAction.js, replacing (or adding) the call to handleMuteClick, with a call to the back-end service that manages Access Manager tokens (https:/mypamservice.acme.com/blockUser?uuid=userID&channel=CHANNELID). This interface should implement a pubnub.grantToken() call that sets the user's read and write permissions to false for the channel.

• Flag users

Moderated chat apps may want to implement the ability for one user to flag another user. Apps that implement this functionality should update the flagged user's metadata with the following key/value pairs:

flag: true,
flaggedAt: "2021-09-10T07:40:15.538Z", // ISO timestamp when flagging occurred
flaggedBy: "userID", // User ID of the flagging user
reason: "reason for flagged"  // Optional reason collected in the flagging UI

Channels

The Channels view in the moderation tool is populated through channel metadata. That's why any chat app should include the logic that sets up each channel with channel's App Context data (metadata) that includes the channel and name fields. description is an optional field that can also be added by the admin to channel's App Context metadata.

Here's an example of a fully populated channel object that can be interpreted by Moderation Dashboard:

custom: {
  "id": "space_bc03548bcb11eb8dcd0242c130",
  "name": "Besties",
  "description": "",
  "updated": "2021-08-05T07:05:30.480949Z"
}

Channel naming convention

We recommended you follow a unique and consistent channel ID naming pattern for your moderated channels, such as public.*.

Channel memberships

Moderation Dashboard's ability to show which users are online/offline in the Channels view is enabled by Presence. Presence is not a default keyset feature so you must enable it on the Admin Portal with the default settings.

Messages

Moderation Dashboard provides a view that allows admins to review messages sent over the last 24 hours and, optionally, to delete or modify them. This functionality requires Message Persistence to be enabled for the moderated chat app's keyset on the Admin Portal. Message Persistence is not enabled by default. After enabling it, set the Retention value to 1 Day (or more, if your application will use stored messages in a different way) and make sure the Enable Delete-From-History option is selected.

When an admin modifies a message, a message action is added to a message with the new updated value:

  action: {
      type: 'updated',
      value: 'Hello World! (fixed typo)',
  },

When an admin deletes a message, a message action is added to a message with the deleted action type:

  action: {
      type: 'deleted',
      value: '.',
  },

To design a chat app that responds to these admin actions, you need to ensure that the chat app listens for messageAction events, and updates the message history view properly. Similarly, when a chat app fetches messages from Message Persistence through the Message Persistence API, it should ensure that any returned messageAction data is properly processed.

Automatic text and image moderation

Moderation Dashboard deploys Functions to perform automatic text and image moderation. These functions are invoked when a Before Publish or Fire (for text moderation) or a Before Publish File (for image moderation) event occurs. The logic in these functions expects the publish payloads for both function types to be in the following format:

{
  "text": "Message with the text"
}

See the formats for messages sent through text and image moderation functions:

• Text message:

  {
    "message": {
      "text": "hello",
      "type": "text"
    },
    "timetoken": "16288547735385049",
    "message_type": null,
    "meta": "",
    "uuid": "userId"
  }

• Image and text message:

  {
    "message": {
      "message": {
        "text": "hi",
        "type": "text"
      },
      "file": {
        "url": "fileUrl",
        "name": "Screenshot.png",
        "id": "bdc547d5-1444-4763-b081-407e067f781e"
      }
    },
    "timetoken": "16288575775551984",
    "message_type": 4,
    "meta": "",

  show all 17 lines

Text moderation configuration allows for the moderation logic to completely block a message (in which case no subscribe event is sent to the clients) or to mask the message with a chosen masking character.

The following is an example of the message format that will be used when the text moderation logic transforms a masked message:

{
  "message": {
    "text": "***",
    "type": "text"
  },
  "timetoken": "16288559005032306",
  "message_type": null,
  "meta": "",
  "uuid": "user1"
}

Text and image moderation configuration allows for the moderation logic to route a copy of any masked or blocked message to a banned.* channel. For example, if a message is posted to a channel called public.water-cooler, the banned message will be sent to the respective channel called banned.public.water-cooler.

Chat clients should not display the contents of banned.* channels to end-users as they are for the use of moderation admins only.

The following are examples of moderated messages sent to a banned channel:

• Masked text message routed to a banned channel:

  {
    "message": {
      "moderatedMessage": "***",
      "type": "text",
      "originalMessage": "go to hell"
    },
    "timetoken": "16288559005165712",
    "message_type": null,
    "meta": "",
    "uuid": ""
  }

• Banned/blocked image and masked text message routed to a banned channel:

  {
    "message": {
      "message": {
        "moderatedMessage": "***",
        "type": "text",
        "originalMessage": "go to hell",
        "reason": "personal attack"
      },
      "type": "text",
      "file": {
        "url": "fileUrl",
        "reason": [
          {
            "text": "reason for blocking"
          }

  show all 26 lines

File Sharing

If you want to use the Moderation Dashboard's image moderation feature, you need a chat application that uses PubNub to send Files. File sending is not a default feature, so you must enable it for your keyset on the Admin Portal.