Comments

Hyvor Talk's main feature is the comments embed. It is a fully-featured real-time commenting system that can be embedded on blogs, news sites, and other websites.

Comments Component (for developers)
Commenting (for users)

Comments Component

The comments embed is loaded via the <hyvor-talk-comments> Web Component. Go get started, add the following script right before the </body> tag. It registers the <hyvor-talk-comments> Web Component on your webpage.

<script async src="https://talk.hyvor.com/embed/embed.js" type="module"></script>

Then, add the <hyvor-talk-comments> element to the place where you want the comments section to load. It is possible to add multiple comments sections to a single page if needed.

<hyvor-talk-comments
    website-id="YOUR_WEBSITE_ID"
    page-id=""
></hyvor-talk-comments>

For platform-specific instructions, see the Install page.

Attributes

The following attributes are supported in the <hyvor-talk-comments> element

Attribute

Value

website-id

Your Hyvor Talk Website ID

page-id

A unique identifier for the current page. See page-id.

page-url

Page URL (optional).

page-title

Page title (optional). The page title is shown in notifications, emails, and in the Console. document.title is used by default.

page-language

Override the website's language for this page. See languages.

page-author

Email (or base64 encoded email) of the author

sso-user and sso-hash

See Stateless Single Sign-on

colors

light, dark, or os. See Styles & Colors

loading

Accepts default, lazy, and manual. See loading

settings

JSON encoded settings. See settings

t-*

Set custom texts. See translations

page-id

The page-id attribute is used to identify the current page, and it is perhaps the most important attribute.

If it is not set or empty, the canonical URL of the current page will be used as the page-id.
If it is set, the value will be used as the page-id.

Each page-id will load a different thread. It is highly recommended to use an ID that does not change over time (e.g. a database ID). If an ID change, you will need to migrate data to the new page manually. See our moving data between pages.

Creating the Component with JavaScript

Instead of adding the <hyvor-talk-comments> element directly to the HTML, you can create it with JavaScript. This is useful when you need to use properties.

const comments = document.createElement("hyvor-talk-comments");
comments.setAttribute("website-id", "YOUR_WEBSITE_ID");
comments.setAttribute('page-id', page.id);

document.body.appendChild(comments);

Settings Attribute

All website-level settings can be overridden at the page level using the settings attribute. It accepts a JSON-encoded string. Here is an example:

<hyvor-talk-comments
	website-id="x"
	settings='{
		"custom_css":"#app { font-size: 18px }",
		"profiles": {
			"pictures": false
		}
	}'
></hyvor-talk-comments>

Click the button below to see all available settings.

Translations (t- Attributes)

You can set custom translations using the t- attributes.

<hyvor-talk-comments
	t-as-guest="Comment without account"
	t-newest="Latest"
/>

You can find the keys on the translation page (login required). For example, if the key is as-guest, the attribute should be t-as-guest. See language documentation for more information.

Properties (Deprecated)

Properties are deprecated. Use settings attribute and t- attributes instead.

1. Settings (Deprecated)

The settings property does the same thing as the settings attribute. This is only supported for backward compatibility.

Note that in order to make settings property work, you should wait until the Web Component is defined. The easiest method is to use customElements.whenDefined.

customElements.whenDefined('hyvor-talk-comments').then(() => {
    // create the element
	const comments = document.createElement("hyvor-talk-comments");
	// set the settings
	comments.settings = {}
	// then append
    document.getElementById("wrap").appendChild(comments);
});

2. Translations (Deprecated)

This property is only supported for backward compatibility. We recommend using t- attributes for translations for new users.

const comments = document.createElement("hyvor-talk-comments");

comments.translations = {
    sort: "Order by",
    reactions_text: "What do you think about this post?",
}

Loading

By default, the comments section is loaded as soon as the commponent is added to the DOM. You can customize this behavior using the loading attribute. It accepts the following values:

default - start loading immediately
lazy - start loading when the element is in the viewport (using IntersectionObserver)
manual - start loading when .load() is called on the <hyvor-talk-comments> element.

Manual Loading

The loading attribute can be set to manual to delay the rendering of the comments embed until the .load() method is called. Here is an example with a button to load the comments:

<hyvor-talk-comments
	website-id="YOUR_WEBSITE_ID"
	page-id=""
	loading="manual"
></hyvor-talk-comments>

<button onclick="document.querySelector('hyvor-talk-comments').load()">Load Comments</button>

API

The <hyvor-talk-comments> element exposes a mini-API with the following methods:

api.reload() - reload the comments section. Same as .load()
api.page() - get current page data. See Page Object.
api.auth.user() - get the current user's public data. See User Object. null if not logged in.
api.auth.logout() - logout the current user. Removes the login storage from the localStorage.

Here is an example of how to get the current user's data:

const comments = document.querySelector("hyvor-talk-comments");
comments.api.auth.user();

API Objects

Page Object

interface Page {
    id: number,
    created_at: number,
    identifier: string,
    url: string,
    title: string,
    is_closed: boolean,
    is_premoderation_on: boolean,
    comments_count: number,
    reactions: Record<'superb' | 'love' | 'wow' | 'sad' |  'laugh' | 'angry', number>,
    ratings: {
        average: number,
        count: number
    },
    online_count: number
}

User Object

interface User {
    id: number,
    type: 'hyvor' | 'sso'
    name: string,
    username: string,
    picture_url: string | null,
    bio: string | null,
    location: string | null,
    website_url: string | null,
	badges: number[]
}

Events

The <hyvor-talk-comments> element emits a few events that you can listen to. For example, if a comment is published, you can use events to record it in your analytics service.

The following events are emitted:

loaded - dispatched when the embed is fully loaded
comment:published
comment:edited
comment:deleted
comment:voted
comment:flagged
reaction
rating
auth:login:clicked* - when the login button/link as clicked
profile:clicked* - when the user's profile (name or profile picture) is clicked

You may call preventDefault() on the event to prevent the default action in events marked with *.

Listening to Events

Use addEventListener on the <hyvor-talk-comments> element.

const comments = document.querySelector("hyvor-talk-comments");
comments.addEventListener('comment:published', function (e) {
    console.log("Comment ID: " + e.detail.id);
})

Event Data

Here's a typescript definition of the all emitted events (event_name: data):

interface CommentsEvents {
    'loaded': null,
    'comment:published': RealComment,
    'comment:edited': Comment,
    'comment:deleted': Comment,
    'comment:voted': {
        comment: Comment,
        vote: 'up' | 'down' | null
    },
    'comment:flagged': {
        comment: Comment
    },
    'reaction': {
        type: 'superb' | 'love' | 'wow' | 'sad' |  'laugh' | 'angry'
    },
    'rating': {
        rating: number,
        count: number,
        average: number
    },
    'auth:login:clicked': null,

    // when clicking on user's name or profile picture
    'profile:clicked': User,
}

Comment Object

The Comment object can be a HiddenComment (ex: a deleted comment that has replies) or a RealComment.

interface BaseComment {
    id: number,
    page_id: number,
    url: string,
    parent_id: number | null,
    depth: number,
    created_at: number,
}
interface HiddenComment extends BaseComment {
    is_hidden: true,
}
interface RealComment extends BaseComment {
    is_hidden: false,
    content: string
    content_html: string,
    is_featured: boolean,
    is_loved: boolean,
    is_edited: boolean,
    upvotes: number,
    downvotes: number,
    user: User,
    status: 'published' | 'spam' | 'deleted' | 'pending'
}
type Comment = HiddenComment | RealComment;

Commenting

This documentation explains everything about commenting on a website that uses Hyvor Talk. If you are a website owner, you may share this document with your users.

Guest Commenting

Guest commenting is enabled by default. But, websites can disable it.
You can publish comments with a name (required) and email (optional).
If you provide an email address, it will be used to show a Gravatar and send you reply notifications. Website owners will be able to see your email address.
You cannot edit or delete guest comments once they are published - only moderators can.

Authentication

Each website uses one of the following authentication methods:

HYVOR: Log in with a HYVOR account.
SSO (Single Sign-on): You need an account on the website you are commenting on.

While the login methods are different, both Hyvor and SSO users have access to the same features.

Writing Comments

Hyvor Talk provides a Rich Text Editor for writing comments. This means that while most comments are text-based, commenters are able to add rich content like images, GIFs, and embeds to comments.

Note that the Editor is highly configurable. Therefore, some websites may disable some or all of the following features.

1. Text Styling

The following text styles are supported. Most styles support Markdown-style shortcuts.

Bold - Ctrl/⌘ + B or **Text**
Italic - Ctrl/⌘ + I or *Text*
Strikethrough - ~~Text~~
Code - `Text`
Spoiler - !!Text!!

2. Links

You can add links to your comment by using one of the following methods:

Select the text you want to link, click the link icon in the toolbar, paste the URL, and click "Add Link"
Type the URL, select the text, and click the link icon in the toolbar
Use Markdown syntax: [Text](URL)

3. Images

You can upload images and add them to your comment. The maximum image upload size is 2MB for Premium websites and 5MB for Business websites. PNG, JPEG/JPG, GIF, and WEBP formats are supported. Use one of the following methods to upload an image:

Upload from your computer. The image will be uploaded to Hyvor Talk’s CDN.
Link to an external image. The image will be linked to the original location (URL). The image will be displayed as long as the external server allows.

4. GIFs

While you can upload GIFs from your computer as images, you can also search for GIFs easily and add them to your comments. Click the GIF icon below the comments box and search for the GIFs and add them. This feature is powered by Tenor.

5. Embeds and Link Previews

Hyvor Talk supports embedding rich content from 1000+ platforms including Youtube, Twitter, Facebook, Linkedin, etc. To embed, click the Link button in the comments box, paste the URL, and choose “Embed”. If the link is not embeddable as rich content, it will be shown as a link preview (bookmark). This feature is powered by Iframely.

The URL you are embedding should be publicly accessible. Contents behind logins are not embeddable.

6. Code Blocks

Type ``` in a new line to add a code block. Code blocks will be highlighted autmatically using highlight.js.

7. Mentions

You can mention other commenters. In the comments box, type @ to see suggestions. You can only mention commenters who have published at least one comment on that website. The mentioned user will receive an email notification with a link to your comment.

8. Math (KaTeX)

You can add math equations to your comments usingKaTeX. Type $$ to start a math block. The math block will be rendered automatically.

Other Commenting Features

1. Blocking Users

You can block other users to hide their comments automatically in the future. They will also no longer see your comments. To block a user, first, open their user profile by clicking on their name or profile picture near their comment. Then, click the “Block User” button.

2. Online Users

On each page, you can see the total number of online users on that page, which is updated as users join or leave the page. This online count is the total of logged-in and guest users. If the website has enabled it, you can also see who is online at a specific time on a page.

3. Badges

Moderators of the website can assign you up to 3 badges. These badges will be displayed alongside your name in your comments and the website profile.