Documentation

Getting started

To add comments to your website you need to add the following code snippet to your website which you find on your account page as well:


  <div
    class="just-comments"
    data-apikey="YOUR_API_KEY">
  </div>
  <script async src="https://just-comments.com/w2.js"></script>

Replace YOUR_API_KEY with an actual API key of your account. To obtain the API key go to your account page.

The snippet above consists of two tags. Place the div to the location on your website where you want comments to be shown. The script has be included after the div tag and the best place would right before the closing </body> tag.

Note about security

JustComments is a public comment system which means that the comments are publicly available via API to everyone who knows the page id the comments are associated with. This documentation offers multiple options to control the appearance of the widget which may look like security features, but they are, in fact, not! You can find the actual security settings in your account page and they apply on the backend.

How JustComments decides what page comments are attached to?

To determine the page ID, JustComments is using the page URL. JustComments converts the page URL to an ID which identifies the page. For example, https://mysite.com?mypage=id#1234 becomes mysite.com?mypageid=id. This way it does not matter if the page is opened via http or https or any other protocol: JustComments will be able to detect that it is the same page. Since v2, JustComments does not assume that the part after ? (query) uniquely identifies the page. If you want to use the query part as the page ID, you can set data-usequery="true" on your widget. Also, JustComments automatically removes typical parameters which normally don't identify the page, such as ref, utm_source, utm_medium, utm_campaign, utm_term,utm_content.

Configuration

You can control the behavior of the comments widget using data- attributes. The most common attribute is data-apikey="YOUR_API_KEY" which is the key that the widget is using to access the backend of JustComments.

Additional options available will be shown in the next sections describing more complex integrations.

Widget Language

The default language of the widget is English. You can change it by specifying data-locale attribute:


  <div
    class="just-comments"
    data-locale="en_US"
    data-apikey="YOUR_API_KEY">
  </div>
  <script async src="https://just-comments.com/w2.js"></script>

The following languages are available at the moment:
  • de (German)
  • en (English)
  • es_MX (Mexican Spanish)
  • fa (Farsi)
  • fi (Finnish)
  • fr (French)
  • hu (Hungarian)
  • ja (Japanese)
  • ko (Korean)
  • pl (Polish)
  • pt (Portuguese)
  • pt_BR (Brazilian Portuguese)
  • ru (Russian)
  • sv (Swedish)
  • uk (Ukrainian)
  • vi (Vietnamese)
  • zh_CN (Chinese - China)
  • zh_HK (Chinese - Hong Kong)
  • zh_TW (Chinese - Taiwan)
You can specify either a locale, for example, ru_RU or just a language ru. We are extending the list of supported languages constantly. Contact us if you need an additional language.

Integration with Recaptcha

To protect your comments from bots, you can opt-in for Recaptcha. For this you need to define the corresponding data attribute on the integration code and turn on the corresponding backend configuration on your account page.


  <div
    class="just-comments"
    data-recaptcha="true"
    data-apikey="YOUR_API_KEY">
  </div>
  <script async src="https://just-comments.com/w2.js"></script>

With Recaptcha integration enabled the widget will ask users to solve a challenge if Recaptcha suspects that the user is a robot.

Integration with own user database

If you have your own user database and your own authentication mechanism, you can integrate it with JustComments seamlessly. To make it work your need to create a JWT token for every user that wants to comment. For example, on your NodeJS backend you can do it like this:


  const jwt = require('jsonwebtoken');
  const user = {
    apiKey: 'YOUR_API_KEY',         // required
    username: 'Alex Rudenko',       // required
    userEmail: 'test@email.com',    // required
    userId: 'alex',                 // optional
    userPic: '/widget/no-pic.png',  // optional
    userUrl: '/profile/alex'        // optional
  };
  var token = jwt.sign(user, 'YOUR_API_KEY_SECRET', {
    algorithm: 'HS256',
    expiresIn: '1h',                // always set expiration
  });

the token generated on the backend needs to be provided to JustComments via a data attribute on the client side:

  <div
    class="just-comments"
    data-jwt="TOKEN_HERE"
    data-apikey="YOUR_API_KEY">
  </div>
  <script async src="https://just-comments.com/w2.js"></script>

If you provide your own JWT as shown above, you can choose to hide login methods that JustComments provides out of the box: social and anonymous form

Lazy-loading JustComments widget

You may want to load w2.js lazily on a page, for example, when a user clicks on the Show comments button. In this case, in order for the social login feature to work for your users you need to include an additional file on the page. This file has to be always included but don't worry it's only 564 bytes gzipped and cached quite efficiently.


  <script src='https://just-comments.com/auth2.js' async defer></script>

What this script does is it passes the authentication data via the local storage to the main page of your web site where your user initiated a social login flow. For example, if your user wants to authenticate via Twitter before leaving a comment.

Disable social login

You may want to disable the login via social networks such as Twitter. For this, modify the container tag as following:


  <div
    class="just-comments"
    data-disablesociallogin="true"
    data-apikey="YOUR_API_KEY">
  </div>
  <script async src="https://just-comments.com/w2.js"></script>

Disable anonymous login

You may want to hide the anonymous comment form so that only social networks or your own authentication mechanism could be used. For this, modify the container tag as following:


  <div
    class="just-comments"
    data-disableanonymouslogin="true"
    data-apikey="YOUR_API_KEY">
  </div>
  <script async src="https://just-comments.com/w2.js"></script>

Custom styling / Themes

You may want to modify default styles to better match your website's styling. These can be achieved via themes. JustComments widget comes with only one built-in theme but it's easy to create your own using CSS variables. For example, below you find a theme for dark websites. You are free to re-define all or only some variables. Try changing them to find the best match to your own website:


  <style>
    .just-comments.myTheme {
      --border-color: #2c2c57;

      --primary-bg-color: #3f3356;
      --secondary-bg-color: #ecebed;
      --secondary-bg-color-lighter: #ecebed33;

      --primary-color: #ffffff;
      --primary-color-lighter: #e61d0f1a;
      --primary-color-light: #e61d0f0d;

      --primary-text-color: #ffffff;
      --secondary-text-color: #d0cddc;

      --outline-style: 3px var(--primary-color) dashed;
      --outline-offset: 3px;

      --button-border-radius: 6px;
      --input-border-radius: 6px;
      --bubble-border-radius: 10px;
      --user-pic-border-radius: 50%;

      --font-heading1-size: 22px;
      --font-heading1-line-height: 28px;
      --font-heading2-size: 15px;
      --font-heading2-line-height: 20px;

      --font-button1-size: 17px;
      --font-button1-line-height: 22px;
      --font-button2-size: 15px;
      --font-button2-line-height: 20px;
      --font-button3-size: 13px;
      --font-button3-line-height: 18px;

      --font-text1-size: 18px;
      --font-text1-line-height: 24px;
      --font-text2-size: 15px;
      --font-text2-line-height: 24px;
      --font-text3-size: 13px;
      --font-text3-line-height: 18px;

      --primary-button-color: var(--primary-bg-color);
      --primary-button-bg-color: var(--primary-color);
      --primary-button-hover-color: var(--primary-color);
      --primary-button-hover-bg-color: var(--primary-bg-color);
      --primary-button-border: 2px solid var(--primary-button-bg-color);
    }
  </style>

  <div
    class="just-comments myTheme"
    data-apikey="YOUR_API_KEY">
  </div>
  <script async src="https://just-comments.com/w2.js"></script>

In this snippet, a theme is defined via the variables in a CSS class myTheme. Note that the same class myTheme needs to be used for the div tag and the CSS selector.

Overriding page ID

You may want to display same comments on different pages which have different URLs. By default, comments attach to the current page URL but there is a way to override this.


  <div
    class="just-comments"
    data-pageid="UNIQ_PAGE_ID"
    data-apikey="YOUR_API_KEY">
  </div>
  <script async src="https://just-comments.com/w2.js"></script>

You can define the attribute data-pageid. All comments with the same pageid will be grouped and shown together. The actual page URL won't matter in this case.

Search Engine Optimization

By default, comments are available for search engine crawlers and bots. It means that as soon as a search engine (for example, Google) indexes the comments, other users will be able to find your website using the comment content. This also means that crawlers will fetch comments just like normal users and, thus, they will consume additional credits. If you don't want the comments to be indexed and want to reduce costs, you can disable the access for bots by adding data-disableseo attribute.


  <div
    class="just-comments"
    data-disableseo="true"
    data-apikey="YOUR_API_KEY">
  </div>
  <script async src="https://just-comments.com/w2.js"></script>

Advanced Widget Options

There are a few additional options which you can configure:

  • data-sort (values: asc or desc) Determines the order of comments.
  • data-pagesize (values: 1 to 100) Determines how many comments are shown at once.
  • data-disableloadmore (values: true) Disables the Load More button.
  • data-enablewebsite (values: true) Enables an additional attribute "Website" in the comment form.
  • data-disableprofilepictures (values: true) Hides all profile pictures for all users.
  • data-disablesharebutton (values: true) Hides the button to share a comment.
  • data-hideattribution (values: true) Hides the "powered by" link. We are happy if you keep the link to support JustComments though.
  • data-hidecommentheader (values: true) Hides the header which says "Comments" and the actual count of comments. It's useful if you fetch the number of comments via theAPI
  • data-hidenocommentstext (values: true) Hides the default message when there are no comments on the page. It's useful if you fetch the number of comments via theAPI and have your own text.
  • data-defaultuserpicurl (values: URL) You can provide an URL to an image to be used as the default user avatar when none is provided by the user. Recommended size is a square picture between 56x56 px and 100x100 px.
  • data-disablepushnotifications (values: true) Removes the button to turn on push notifications in the comment form.
  • data-disablereactions (values: true) Removes the possibility to react to comments.
  • data-disablereply (values: true) Hides the Reply button preventing nesting of comments.

  <div
    class="just-comments"
    data-sort="desc"
    data-pagesize="5"
    data-disableloadmore="true"
    data-enablewebsite="true"
    data-disableprofilepictures="true"
    data-disablesharebutton="true"
    data-hideattribution="true"
    data-hidecommentheader="true"
    data-hidenocommentstext="true"
    data-disablepushnotifications="true"
    data-disablereactions="true"
    data-disablereply="true"
    data-apikey="YOUR_API_KEY">
  </div>
  <script async src="https://just-comments.com/w2.js"></script>

Comment moderation

When someone leaves a new comment on your website, JustComments sends an email to your account's email address. The email contains a link which allows hiding the comment if the content is not appropriate. Moderation does not require access to your account and, therefore, you can forward the moderation emails to someone else to do the comment moderation for you. Alternatively, you can configure a different email address for these emails in your account.

Markdown

JustComments supports Markdown with tiny difference: whenever someone embeds an image or other content, it gets converted to a link.

Email Notifications

By default, JustComments notifies the users about new replies to their comments using push notifications. While push notifications are great, they have a couple of drawbacks:

  1. Not all web browsers support push notifications at the moment.
  2. Push notifications are real-time and if you forget or don't have time to react to them they may disappear, unlike email messages.

To increase the user retention and facilitate discussions, JustComments offers the possibility to enable email notifications. You can do it by adding an attribute data-enableemailnotifications="true" to your integration code.

How does it work? Users can opt-in to receive email notifications for replies to the comments they create. For the first time, the users will be asked to validate their email address. After that, when someone replies to a comment, an email will be sent by JustComments to the author of the comment.

Note that email notifications feature consumes additional credits. Every email sent costs 15 credits.

Browser Support

JustComments aims at supporting modern browsers. Therefore, by default, IE11 is not supported. To make JustComments work in older browsers include the following polyfills on a page with comments (startWith, ES6 Promise, Fetch API):

<script type="text/javascript">
  if (!String.prototype.startsWith) {
    String.prototype.startsWith = function(searchString, position) {
      position = position || 0;
      return this.substr(position, searchString.length) === searchString;
    };
  }
</script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/es6-promise/4.1.1/es6-promise.auto.min.js" integrity="sha256-OI3N9zCKabDov2rZFzl8lJUXCcP7EmsGcGoP6DMXQCo=" crossorigin="anonymous"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/fetch/2.0.4/fetch.min.js" integrity="sha256-eOUokb/RjDw7kS+vDwbatNrLN8BIvvEhlLM5yogcDIo=" crossorigin="anonymous"></script>

Code Highlighting

JustComments supports code highlighting using highlight.js. If you want to highlight code in the comments, simply add the CSS file with a highlightjs theme that you want to use to your website. For example, adding this line inside the head tag will highlight code in the comments using the Monokai Sublime theme:

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.14.2/styles/monokai-sublime.min.css" />

There is a lot of different themes available for highlight.js. You can choose any and host the CSS file yourself or import the styles from the public CDN.

API

JustComments offers you an API to build custom integrations.

Webhook

In your account settings, you can enter a URL that will be invoked whenever someone posts a comment. JustComments will send a POST request with a timeout of 2 seconds. The request's content type will be application/json and the body will be a JSON object with the following required attributes pageId, commentId, type and an optional commentUrl. Additionally, the request will contain an Authorization token signed with your account's secret which you should use to verify that the request originates from JustComments.

Example request:

POST /your-path HTTP/1.1
User-Agent: JustComments Webhook
Host: your-host
Content-Type: application/json
Authorization: Bearer jwt

{"commentId": "id here", "pageId": "pageId", "commentUrl": "commentUrl", "type": "comment.created"}

Currently, only the type "comment.created" is supported but you should check the type if you perform certain actions on webhook.

Note that webhooks consume additional credits. Every invocation consumes 1 credits.

Text and translation customization

For some use cases you may want to completely customize the text strings that JustComments uses. Such use cases may be something like changing the word "comments" to something else or providing a translation for the language that is not supported yet.

To customize the texts, copy the object with translations from GitHub to a global variable:

<script>
  window.customLocale = {
    // translations in the form of key: value go here
  }
</script>

Then, add the global variable name to the integration code like this data-customlocale="customLocale". Now JustComments will be using translations from your custom variable if they are available. You can adjust the translations to your needs.

An important note: using data-customlocale applies to the currently specified language. So your custom strings need to match the ones from the current language if you customize only certain strings. Also, when new strings are added to JustComments you might need to update your custom locale.

Importing comments from other services

It's possible to migrate existing data from other systems. Currently, the process has been tested for Disqus only. Contact us if you want to migrate from any other commenting system.

Migrating from Disqus

It's possible to import data from Disqus. In your Disqus account navigate to Admin -> select your site -> Community -> Export. Disqus will send you an XML file with your data. Send this data file to us and we will import it to your JustComments account.

Migrating from Wordpress

Export the tables wp_comments and wp_posts to CSV files. Send these data files to us and we will import them to your JustComments account. Please exclude the post content column because it's usually quite big and not needed for the import process.

Migrating from Commento

Send the JSON export file containing your Commento comments and we will import them to your JustComments account.

Are you ready to get started?
  • Learn about our pricing.
  • Every new account gets 100 000 free credits for a trial period. No credit card required.
  • Creation of comments and storage of comments is for free.