Product Updates

PubNub's Chat Moderator Quick Start Guide

6 min read Chandler Mayo on Oct 6, 2022

This quick start will cover how to run the PubNub Chat Moderation Dashboard locally to moderate chat messages and enforce community guidelines. After reading this quick start you’ll be able to try the Moderation Dashboard, armed with a high-level overview of the chat moderation functionality you can expect. You will be able to configure the moderation tools described here on users and chat messages to enforce community guidelines, filter profanity, ban users, and more in real time.

Chat Moderation Tools

Moderating user messages and images is an essential feature for chat apps and chat rooms. However, it’s not an easy task to build moderation tools, and there are a lot of objectives and features to consider. Building a dashboard takes away from the time you could be building other things you care about. So we did it for you. The Open Source PubNub Moderation Dashboard is a project that you can use to moderate chat messages and images in real time for any of your PubNub API keys. It’s totally free for you to take and use.

Let’s review what the Moderation Dashboard can do for you.

How to enable a chat moderator using PubNub's Moderation Dashboard

The PubNub Moderation Dashboard provides you with moderation tools to configure moderation settings for chat moderation on PubNub API keys. The open source Moderation Dashboard is loaded with features, such as profanity filtering and channel moderation, that any chat developer needs to moderate user activity and enforce community guidelines. Administrators can also view a live stream of chat messages, manually moderate them, as well as revoke user permissions in a channel.

The Moderation Dashboard is designed to provide a starting point or a template for developers who are building chat solutions that require moderation. It encapsulates best practice functionality for many common chat message moderation tasks. You can deploy the Moderation Dashboard as-is and configure the moderation tools to meet your own needs.

First, we’ll take a look at the moderator functionality included in the Moderation Dashboard.

PubNub’s Chat moderator features

In this quick start, we’ll break down the available functionality into three moderation tool categories: Automatic Message Moderation Features, Administrator Message Moderation Features, and Administrator User Management Features.

Automatic message moderation features

These features will work with almost any chat application and do not require any special application design. However, there is some consideration in channel naming conventions if the application developer only wants certain channels to be moderated. 

  • Automatic Word List moderation

  • Automatic Advanced text moderation using

  • Automatic Image moderation using SightEngine

Administrator message moderation features

These features allow an Administrator to monitor and moderate message activities in a channel and to perform manual chat moderation to those messages. The chat application being moderated must implement certain configuration and design patterns to support these features. For example: History must be enabled in the chat application being moderated. After-the-fact Administrator moderation leverages message reactions, and the moderated chat app must be instrumented to handle message action events and update or hide messages accordingly.

  • Administrator can view history and real-time activity on a channel.

  • (If configured) Administrator can view text and images that have been blocked or obfuscated by automatic moderation.

  • Administrator can make after-the-fact deletes or edits of messages.

Administrator user management features

Administrators can perform manual moderation actions on users as well, such as enforcing community guidelines by banning users. These features also require certain application configuration and design patterns in the moderated application. A user’s moderation status, such as flagged, blocked, muted on a channel, or banned on a channel, is stored in the user’s object metadata. The application needs to be configured to use metadata and the moderated chat app must be instrumented to handle user metadata change events and respond accordingly.

  • Administrators can flag/un-flag users.

  • Administrators can block/mute users from a particular channel.

  • Administrators can ban users from the app completely.

Next, we’ll take a look at what you need to consider to create a chat app that works with the Moderation Dashboard. 

Building a chat moderator application

There are requirements and design patterns to consider if you plan to use all of the features available in the Moderation Dashboard. The moderated chat application requirements and design patterns are described as part of the Moderation Dashboard documentation. We have also created a sample moderated chat app as part of the React Chat Components repo. 

Developers starting a new project that will include moderation should use the moderated chat sample as a starting point. Once you’ve completed this quickstart and have the Moderation Dashboard running locally, you should follow our Moderate Chat Messages with a Moderation Chat Dashboard tutorial to run the moderated chat sample, as well as try all of the features and test your moderation settings. 

Let’s run the Moderation Dashboard locally, so we can take a closer look and understand in-depth how the application will help you moderate your chat apps. 

Running the chat moderation dashboard locally

We’re going to download and run the Moderation Dashboard application, but before you do that you’ll need to configure some tools.

Chat Environment set up

You’ll need a free PubNub account to run the Moderation Dashboard. You’ll also need a chat app to test against if you want to demo all the features. We have a Moderated Chat App Sample as part of the React Chat Components repo that works well with the Moderation Dashboard. The Moderated Chat App Sample conveniently configures all of the meta data you need for chat moderation the first time you run it. 

Our in-depth Moderate Chat Messages with a Moderation Chat Dashboard tutorial covers how to run the moderated chat app to demo the Moderation Dashboard features. If you’re building or using your own chat app, the moderated chat application requirements and design patterns are described as part of the Moderation Dashboard documentation

How to set up your Node.js development environment for your chat moderation app

To start using our Moderation Dashboard, you first need to install Node.js.

If you’ve already installed Node.js, go to the next section.

If you don’t have Node.js installed, visit the Node.js Downloads page and select the installer for your platform.

Open your terminal and run the following commands to check the installation:

You should see a version number after you run these commands. 

How to set up your Git to clone the Moderation Dashboard

To clone the Moderation Dashboard from GitHub, you need Git installed.

If you’ve already installed Git, go to the next section.

To install Git, follow the Getting Started - Installing Git guide.

Open your terminal and run the following command to check Git installation:

You should see a version number after you run the command.

Now you’re ready to start the Moderation Dashboard.

Starting the Moderation Dashboard

  1. Clone the GitHub repository.

  1. Install the project.

  1. Start the project.

No really - that’s all there is to it. A web browser should automatically open http://localhost:3000, and you can start to explore the Moderation Dashboard. Next, let’s login to the Moderation Dashboard.

Logging into the Chat Moderator Dashboard

Once the project is up and running you will see a login page.  

Login with your credentials. Use the same credentials you use to access your PubNub admin dashboard

Important for SSO and Google Login: This app uses the PubNub provisioning API which does not work for accounts that use SSO or Google login. If you use SSO or Google to login to the PubNub admin dashboard there is a way to add a password to your account so you can login to the Moderation Dashboard. Go to the PubNub admin dashboard login page and click the “Forgot Password” link. Follow the steps to configure your account to use a password. A password will work in addition to SSO or Google login for the same email account. Use the password you set to login to the Moderation Dashboard. 

After you login to the Moderation Dashboard you will see a list of all the API keysets associated with your account. You can select which API keyset you want to perform chat moderation for and start exploring moderation configuration.

For all of the Moderation Dashboard Features to work it’s necessary that the app is designed with certain patterns that the Dashboard expects. See the Building a Moderated Chat Application section above in this post or read our in-depth tutorial, Moderate Chat Messages with a Moderation Chat Dashboard, that covers how to run a moderated chat app to demo the Moderation Dashboard features.

Chat Moderation Dashboard next steps

In this Quick Start we covered what the PubNub Moderated Dashboard is, the moderation features available, and how to run the Moderation Dashboard locally. In our in-depth tutorial, we cover how to run a moderated chat application you can use with the Moderation Dashboard and demonstrate how to use the features in depth. 

Want to learn more about the Moderation Dashboard and talk to someone about how you can take full advantage of our platform? Get in touch with our sales team and let's discuss the possibilities.