How to install and use Civil Comments

Congratulations! You’re about to begin hosting on-page communities without the hassles and headaches traditionally associated with internet comments. Civil Comments is the first platform built from the ground up for quality and civility, automatically moderating comments with a clever built-in peer review system.

This documentation will help you install, configure, and manage Civil Comments. If the answer to your question isn’t listed here, please email us using the link below.

Note: You will need an active subscription to Civil Comments, and the Site ID associated with your subscription.


While people possess a community, they usually understand that they can’t afford to lose it; but after it is lost, gradually even the memory of what was lost is lost.

– Jane Jacobs

Why did we build this?

We created Civil Comments because we know it’s important for people to be able to discuss, debate, and argue with people they disagree with online, and the existing options were woefully inadequate. Until now, social platforms, and particularly public-facing platforms, were designed around concepts that enable and promote the ugliest sides of humanity. The result: spaces so toxic and abusive that site owners have chosen to shut them off entirely.

At Civil, we understand that social software must be designed to bring out the best in all of us. No one is perfect, we all have bad days, but most of us are willing to put in a little effort to control our baser instincts if it means getting to be a part of something we care about. When platforms are designed from the start with this basic understanding, there’s no need for site owners to do away with their communities. Rather, a site’s community becomes one of its strongest features.

How it works

Civil Comments has all the features users expect in a modern commenting platform — it’s fast, lightweight, easy to use, and great for discussing and debating ideas on the same page as your articles, posts, and videos.

What sets Civil Comments apart from all the other platforms is its patent-pending peer review engine. Comments usually go off the rails as volumes increase, making it nearly impossible to manage high-volume communities. With Civil Comments, the more comments your site gets, the more help you have with moderation. It’s win-win for you and your audience.

When a user submits a comment with Civil Comments, they’re given three comments to rate for quality and civility before their own comment is, in turn, rated by others. Backend algorithms process the ratings and make the final publication decisions, meaning your comments are effectively pre-moderated by the community. It’s the best of both worlds: your commenters are able to have fast-paced, authentic, but reasonably civil conversations, and you aren’t overwhelmed trying to keep up with it all.

Is this artificial intelligence?

Civil reverses the approach all other platforms use to process user-generated content. Where everyone else uses machines to attempt to understand the content, with armies of humans cleaning up after the (constant) mistakes, Civil has humans rate the content, and uses machines to process the ratings and keep things fair. This is not a simple word filter or other blunt instrument, this is a complex and highly effective set of behavior-based algorithms.

Will people actually use it?

Yes! Despite requiring commenters to spend an additional 30 seconds submitting comment, our customers are seeing increasing comment volumes — in some cases more than doubling the number of comments posted per month on previous platforms.

Does it work?

Yes! On sites using Civil Comments, staff moderation time is down over 90% due to a dramatic reduction in user flags and complaints, and increased self-regulation. Commenters modifying their own language and tone in anticipation of the peer review process means 85% fewer comments are removed overall, compared to previous platforms.

Will it create echo chambers?

No. Discussions and debates continue to show the same mix of positive/negative comments as before. Civil doesn’t change opinions; only the tone in which those opinions are expressed.

Installing Civil Comments

Installing Civil Comments is as easy as installing any standard commenting platform plugin. All you need is access to modify your site’s pages, ability to change a few Javascript variables, and (optionally) knowledge of your site’s user authentication process for Single Sign-On integration.

Universal code

Note: You will need an active subscription to Civil Comments, and the Site ID associated with your subscription.

Copy and paste the following code into the desired location in your site’s html. Be sure to include your subscription’s custom Site ID, as well as the ID and language of the page’s content.

Hide the comments until clicked

You can have the comments hidden until the user clicks the comments button. By adding Civil({ hideComments: true }), Civil will hide the comments and add a button with the comment count.

Comment counts

To display a count of page comments elsewhere on your site (like an index view), simply include the following as needed in your page templates:

To manually request a refresh of the comment count after page load:

Most commented

To get a list of pages (called ‘topics’ internally) with the most comments, you can query our API directly:


Days_since defaults to 30.


Open Graph data

Civil Comments will check your page for Open Graph data, and pull, the title, description, and image for each page. This is used to provide context during peer reviews, as well as data for the “Most Commented” endpoint.


Single Sign-On

Integrating with your identity management

Civil offers single sign-on (SSO) to allow your users to log in directly to your site and seamlessly use Civil Comments with the same account.

Including SSO on your page

Once you have subscribed to the Civil SSO integration, you can use this embed code.


provider string

The authentication provider ID. Currently, Civil supports custom authentication using JSON Web Tokens.

jwt Custom authentication with JSON Web Tokens

getUser function

A function that returns the current authenticated user. getUser can return the user directly or call a callback for asynchronous methods.

Synchronous Example


Asynchronous Example


Note: callback expects error as the first parameter and success as the second.

After login complete callback

If you want a callback after the login is complete with it’s success or failed status, you can pass in a parameter called onCompete with a function. That function will be called after login with any errors as the first parameter and the user’s profile as the second.



JWT Example


login function

The function used on your site to open the log in modal and log in or sign up the user. login is passed a callback as the first parameter. callback expects error as the first parameter and success as the second.

JWT example


logout function

The function used on your site to log the user out. logout is passed a callback as the first parameter. callback expects error as the first parameter if the logout failed.


JSON Web Tokens

The JSON Web Token needs the following fields:





Signing the token

In the Civil Comments Admin Dashboard you can find the secret key needed to sign your token on the “Installation” page of your publication. We automatically generate one but you can change it to a different key.

Debugging JWT errors

To diagnose errors with your token, you can make a request to:


You’ll see detailed output about what might be wrong with your token, or a message saying your token is valid. Here’s an example of the message you’d see for an invalid token:


Full Embed Demo View (JWT)

Refreshing user data

To refresh the user data without reloading the page, call the refreshUser function:

After this call, we clear the user data and ask for the JWT again. The token is then sent to the backend to load the new user data.

Profile comments API

You can use Civil’s profile comments API to populate your own profile comment history pages (SSO only).


This returns several objects: an ordered, paginated collection of comment_ids, and matching collections of comment, profile, and article data, each keyed by id.

Third-party analytics

Civil includes hooks to get events into your analytics tool of choice.

This embed code will allow you to pass in a callback for events.


id string

Your unique page/article id.

site string

Your unique site id.

language string

The language of the page. For example: en.

logEvent function

A function that will be called with each event. logEvent gets passed eventName and eventDatawhen called.


Events published


Single Page Applications

If you’re using Civil Comments in a Single Page App or would like to change the article without reloading the page, you can trigger Civil Comments to reload and use a new article ID.

Configuring Civil Comments

Custom CSS

Fonts, colors, and other basic styles can be customized using the Custom CSS field in the Civil Comments admin, under “Installation/Live Example”.

Changes will take 5 minutes to take effect.






Site Settings

You can adjust site-wide preferences under the “Site settings” menu. For lower-volume sites, automatically flagging all newcomer comments for staff review may be an appealing option, while higher-volume sites may choose to remove pre-approvals for newcomers, requiring explicit community approval. The option to “censor profanity” will automatically replace common profanities with asterisks (****).

Adding Managers

Managers can be added to your team through the “Manage team” menu. Click the “Add Manager” button and enter the email address of the user you’d like to add. If they’ve already created an account on Civil using this email address, they’ll be automatically added to your team, with full access to the admin tools. If they don’t have an existing Civil account with this email, they’ll receive an email with an invite code valid for 24 hours. You can resend as many invitations as you need to using the “Add Manager” button.


What commenters see

Reading comments

The Civil Comments reading experience will be familiar to anyone who’s read comments below an article or video online.

How reply comments are displayed

Civil offers an infinite level of comment replies; all comments can be replied to using the “Reply” button at the bottom right corner of each comment. Replies are shown in one level of nesting, indented below the first comment in each thread, and all replies are ordered chronologically from oldest to newest. To maintain context and readability, reply comments that are not ordered immediately below their parent comments will include a short “In reply to…” excerpt quote from the original comment.

Show/hide replies to comments

Replies to top-level comments can be collapsed or expanded using the “Show/Hide replies” toggle button at the top of the comment listing, or on each comment using the down-carat menu in the upper-left-hand corner of each top-level comment.

Changing the order comments are listed in

Comments are listed in order based on the selected sort option, which include:

• Highest rated – Threads ordered by a combination of factors, including peer review ratings, number of replies, and reaction counts.

• Most reactions – Threads ordered by the total number of reactions on all comments in the thread, with threads having the most reactions listed first

• Oldest first – Chronological order based on the creation date of the first comment in the thread

• Newest first – Reverse-chronological order based on the creation date of the first comment in the thread

The default setting is “Highest rated”, but it can be changed using the “Sort by” menu at the top of the comment listing. Sort preferences are stored in browser cookies so users don’t need to keep re-setting them.


Reacting to comments

Users can react to comments by selecting emojis from a set of available reactions. Visitors who are not logged in will be prompted to do so before their reaction is recorded. The selections are:

Image of the 'Like' emoji, a yellow star icon Like

Image of the 'Funny' emoji, a yellow laughing face with closed eyes Funny

Image of the 'Wow' emoji, a yellow face with open eyes and mouth Wow

Image of the 'Sad' emoji, a yellow frowning face Sad

Image of the 'Disagree' emoji, a yellow face with eyes looking sideways and a slanted frown Disagree

Commenters may place one reaction per comment. The top three reactions, by count, are shown in the bottom-left-hand corner of each comment, and viewers can see the full range of reactions and who submitted each by clicking on the reactions.

The default set of reactions and their order are not currently editable.


Posting comments

The first time a user submits a comment using Civil Comments, they see a welcome screen with a short message introducing them to the peer review system:

After they click “Okay, got it!”, they’re assigned their first comment to review. This is a real comment, assigned from the queue of comments needing review. They’re asked two questions: “Do you think this is a good comment?”, and “Is this comment civil?”. If they need more context, the headline and excerpt from the article are available at the top of the window, as well as the replied-to comment if the comment they’re reviewing is a reply.

The commenter rates two comments from other people, then sees their own comment with the single question “Is this comment civil?”. Unlike the comments from other people, this self-review has an editable comment field. Commenters can (and frequently do) revise their own comments in this self-review field, prior to clicking “Yes”, it’s civil.

Once the commenter has rated all three comments, the review window closes, and they see a message at the top of the comment listings thanking them for submitting a comment. If they sort the comments by “Newest first” they will likely see their own comment at the top of the list, though it will likely still be pending final approval from their peers. They can track the status of their comment in the Activity View.

Editing comments

After users submit a new comment, they have 7 minutes to make any changes they might want (fixing typos, fixing a link, etc). Once the 7 minute window is up, the comment is no longer editable. This prevents users from changing comments after the community has approved them.

Reporting comments

Users who come across a comment they feel doesn’t belong on the site can use the down-carat menu in the upper-right-hand corner of the comment to place the comment in the Reported Comments queue for moderator review. Users are asked to select a reason; options include Abuse or Harassment, Spam, Threat to Self or Others, or Inappropriate Username or Avatar. Reports submitted by users with a history of abusing the report function will be discounted by the system.

Show/hide replies

Commenters can toggle visibility on comment thread replies, on both individual threads or on all threads.

Muting other users

By popular demand, users can now choose to “mute” other commenters, so their comments don’t show up in threads. Clicking or tapping on a username or avatar will show a mute/unmute toggle button. Choosing to mute another user will automatically hide their comments, reactions, and any direct replies to their comments, and will prevent you from receiving reply/reaction notifications.

To read muted comments, or to unmute a user, click the “Show Muted” button at the top of the comment section. Note: muting a user does not prevent them from posting replies or reactions, and because we use server-side rendering to quickly load the app, muted comments will be visible for a second or two after loading the page.

Managing Civil Comments

What moderators do with Civil Comments

With Civil Comments, moderators act as community managers, since the commenters themselves handle front-line comment moderation. Since all individual comments are automatically screened coming in, moderators are primarily responsible for handling flagged comments and working with individuals to assign trusted user status, badges, and account restrictions/deactivations.

Handling flagged comments

Comments that get flagged by other commenters are listed in an easy-to-use queue, under the “Flag” icon in the top navigation bar. Moderators can approve or reject flagged comments from the queue; users who frequently have their flags overturned by moderators will have future flags discounted by the system.

Optional article- and site-level settings can also result in comments being added to the flag queue. The origin of the flag (user, AI, pre-moderation, or newcomer gating) is listed in the comment status history on the right side of the display, below the Approve and Reject buttons.

To clear the queue, simply click Approve or Reject on each comment until there are zero flagged comments remaining.

Training comments

To ensure commenters are voting within community guidelines, site owners can manually select a few dozen training comments. Users with a pattern of suspicious voting behavior will be served a training comment, and incorrect “is it civil?” votes will trigger a series of increasingly urgent warnings, beginning with an “are you sure?” message. Users will receive a 24-hour rate limit restriction after 5 failed training comments/warnings.

Article moderation settings

Moderation settings can be changed on a per-article basis, both in the admin app and on the articles themselves. Anyone with moderator or admin privileges can choose from five settings:

• No Moderation

• Community Moderation (Standard)

• Gated Moderation (Sensitive)

• Staff Screened

• Comments Off

Browsing comments

Although it isn’t necessary to keep up with the incoming comments, as the Pending queue is worked by the commenters themselves, moderators can still browse, search, and manually approve/reject individual comments. Comments can be filtered by state (All, Published, Pending, Rejected, Abandoned) or by user type (All, Newcomers, Ghosts, Trusted). An icon in the upper-right corner of each comment shows the current state of the comment.

If the current state is “algorithm_hold” or “algorithm_approved”, the comment is pending community moderation. If the state is “approved” or “rejected”, the community has finished rating the comment and a verdict has been reached. If it’s “moderator_approved” or “moderator_rejected”, the comment was manually approved or rejected by a site moderator or admin.

The full history of a comment and its ratings/state changes is visible to the right of the comment, under the manual Approve/Reject buttons.

Browsing articles

Moderators can browse, search, and view comments by article in the Civil Comments admin tools, under the “Articles” menu. Clicking on the “X comments” link below the Details header will open the list of comments for this article, as well as a switch to turn comments off or on for this specific article. Articles do not appear in this list until they have at least one comment submitted.

Browsing the community

Moderators can browse, search, and view individual user profiles in Civil Comments. Users are ordered by total number of comments, with the count of comments, the percent deleted, and their overall community quality/civility rating averages displayed. Clicking any of the profiles will open the individual profile’s admin page, where the moderator can browse the user’s comments, assign or remove status, and contact the user directly via email.

Working with individuals

Managing profiles

From an individual profile admin page, moderators can browse the user’s comments, assign or remove status, and contact the user directly via email.

Trusted users

Community managers can assign individual users the ability to skip the peer review process. Trusted users will have their comments posted immediately, without review, and will not be asked to review comments from others when submitting a comment. Trusted users will occasionally be asked if they’d like to opt-in to reviewing a handful of comments, but they can choose not to.


Moderators can assign badges, visible in the public comment listings, next to a profile’s user name. Currently the only option is “Staff”.

Restricting accounts

Moderators have three options for restricting problematic accounts without actually deactivating the account.

Always hold for peer review

The first, and mildest, is to remove an account’s pre-approval privileges. This means that none of this user’s comments will be visible to others until the community has explicity approved the comment.

Temporarily limit the number of comments user can post

The next are time-based rate limits, restricting the commenter to a limited number of comments in a time range (2 comments a day for 3 days, for instance). Moderators should feel free to use these as warranted; the user will see a clear message explaining the restriction.

Require staff approval

Finally, if absolutely necessary, moderators can choose to require explicit moderator approval on an individual commenter by selecting the “Ghost” checkbox, which will prevent the users comments from being reviewed by the community, instead placing them in the “Pending/Ghosted” comments queue.

Deactivating accounts

If necessary, moderators can deactivate an entire user account. Clicking the Deactivate button will remove all of a user’s comments and prevent the user from posting future comments.