EchoThread Comment Widget Documentation

Features

Threaded replies

Conversations nest up to 5 levels deep. Each reply includes a "Replying to" indicator so readers can follow the conversation flow, even in busy threads.

Reactions

Readers can react to comments with Like, Love, Haha, and Angry by default (Sad and Fire are also available per site). Reactions are shown inline and don't require typing a reply, keeping threads focused.

Image attachments

Commenters can upload JPEG, PNG, GIF, or WebP images directly into their comments. Images are automatically resized, optimized, and served from a CDN.

Link previews

When a commenter pastes a URL, EchoThread automatically fetches Open Graph metadata and renders a rich preview card with title, description, and thumbnail.

Text formatting & spoiler tags

Comments support four formatting primitives via toolbar buttons, keyboard shortcuts, or inline markdown:

GIFs

The comment box has a GIF button next to the image button. It opens a picker that shows trending GIFs from KLIPY, with a Search KLIPY box for anything else. Pick a tile and it appears above the Post button as a removable preview.

• One GIF per comment. Choosing another replaces the first. A comment can be just a GIF, with no text.
• Top-level comments only. Like image uploads, the GIF button is not shown in nested reply boxes.
• Editing: authors can remove or swap the GIF when they edit their comment. Swapping in a different GIF sends a published comment back to your moderation queue, unless you or one of your moderators made the edit.
• Content filter: every search uses KLIPY's strictest filter setting.
• Moderation: GIF comments go through the same queue and the same approve, reject, and spam actions as any other comment. The spam filter reads comment text, so a GIF with no text follows your auto-approve setting, and a guest's GIF-only comment still waits for review.
• Keyboard: Escape closes the picker and returns focus to the GIF button.

On by default, on every plan. GIFs are included on every plan, Free included. To turn them off for a site, open My Sites → [your site], scroll to Site Settings → Moderation settings, switch off GIFs in comments, and save. With the setting off, the button disappears and the widget makes no requests to KLIPY. GIFs that were already posted keep showing.

Privacy: the search and the GIF itself are loaded by the reader's browser straight from KLIPY, so KLIPY receives that reader's IP address, browser details, and search words. EchoThread stores only a link to the chosen GIF, never the file. See the privacy policy.

Sorting

Readers can sort comments by newest, oldest, most liked, or most replied. The sort preference persists for the session.

Reader polls (Starter and above)

Each page can carry one poll, shown above the comment box. Write it under Polls in your site's menu: pick the page, enter a question and 2 to 6 answers, and save. You can also add one right on the page — while you are signed in to the widget as the site's owner, an Add a poll button appears where the poll will go.

• Voting: readers vote without signing in, one vote each. "See results" shows the bars without voting.
• Editing: the question and answers can be changed until the first vote; after that they are locked so nobody's vote changes meaning. You can close a poll at any time, and the final results stay visible.
• Privacy: to stop repeat votes we store a one-way, per-poll hash of the voter's network address and browser, never the address itself, and we delete it 30 days after the poll closes.

Star ratings (Starter and above)

Turn on Show star ratings on this site in the site's settings and choose what your pages are about (Recipe, Product, Book, Course and so on). Signed-in readers can then add 1 to 5 stars to a top-level comment, and the thread shows the page's average and star breakdown. Only approved comments count.

The widget also adds schema.org AggregateRating and up to 20 Review entries to the page. If your page already has JSON-LD for an item of the type you chose, the rating is added to that item; otherwise the widget adds a small item of its own named after the page. If the item already carries a rating from another plugin, the widget leaves it alone. Whether a search engine shows stars for a page is up to the search engine — check a page with Google's Rich Results Test.

To leave a page out (an About page, say), add data-ratings="false" to its embed snippet. data-structured-data="false" turns this markup off too.

Bluesky and Mastodon

Sign-in, on every plan. Readers can sign in with their Bluesky handle or their Mastodon server, alongside the other providers. Choose which providers your site offers under Sign-in methods in the site's settings.

Replies in your thread (Starter and above). In the site's settings, connect the site's Bluesky or Mastodon account, then give a page its post: paste the link to the post you shared it in, or share the page from the dashboard in one click. Replies to that post appear in the page's thread with a Bluesky or Mastodon badge and a link back, and go through your moderation queue like any other comment. A reader who signed in with Bluesky or Mastodon can tick "Also reply on Bluesky" (or Mastodon), and once their comment is approved it is posted from their own account as a reply to your post.

• Which Mastodon posts work: the post you link must be Public. Replies set to Public or Quiet public appear in your thread; followers-only replies and private mentions don't. Mastodon explains the settings in Posting to your profile.
• What connecting allows: you approve the connection on Bluesky's or Mastodon's own page, through their standard sign-in (Bluesky's OAuth, Mastodon's OAuth). EchoThread never sees your password. Your account only posts when you click Share; readers' replies go out from their own accounts. Disconnect any time from the same settings card.

Languages & localization

The widget interface — buttons, labels, prompts, relative timestamps, and dates — is fully localized in English, Korean (한국어), Italian (italiano), Simplified Chinese (简体中文), and Modern Greek (Ελληνικά). By default each visitor sees the widget in their own browser language when it's supported, falling back to English otherwise, so a Greek reader and an English reader on the same page each get their own language with zero configuration.

To pin the widget to a single language for every visitor, set data-lang="el" (or "en" / "ko" / "it" / "zh") on the container. Dates and "5 minutes ago"–style timestamps are formatted with the browser's native Intl APIs, so they read naturally in each language. Comment content is never translated — only the widget's own interface.

Accessibility

The widget is built with WCAG 2.1 Level AA success criteria in mind: visible focus rings on buttons, inputs, and the compose editor; aria-labels on the compose toolbar, image-remove, and lightbox-close controls; a focus-trapped image lightbox with Escape-to-close; and broad prefers-reduced-motion coverage across animated affordances. No configuration required.

Structured data (schema.org)

On every render, the widget automatically injects a schema.org DiscussionForumPosting JSON-LD block into your page's <head>, with each comment nested as a Comment. This helps search engines and AI answer engines understand — and cite — the conversation on your page. No configuration required. Because it's injected by JavaScript, it's read by crawlers that execute JavaScript, including Googlebot's rendering pass.

Every document also carries a publisher node crediting EchoThread as the discussion platform — a permanent, machine-readable citation trail so AI answer engines and search crawlers can trace a cited conversation back to its source.

Avoiding duplicate structured data

To reach crawlers that don't run JavaScript — most AI answer bots, and the initial-HTML SEO pass — fetch the same document server-side (SSR) and render it into the page's raw HTML instead. First resolve the thread, then fetch its JSON-LD:

// Server-side — resolve the thread once (creates it on first visit,
// same as the widget itself does), then fetch and cache its JSON-LD.
const thread = await fetch(
  'https://api.echothread.io/api/v1/embed/thread?api_key=' + API_KEY +
    '&identifier=' + encodeURIComponent(PAGE_IDENTIFIER) +
    '&page_url=' + encodeURIComponent(PAGE_URL)
).then(r => r.json())

const res = await fetch(
  'https://api.echothread.io/api/v1/embed/threads/' + thread.id +
    '/discussion.jsonld?api_key=' + API_KEY
)
const jsonld = await res.text() // already HTML-escaped, safe inside a <script> tag

// <script type="application/ld+json">...jsonld...</script>

The endpoint returns a single DiscussionForumPosting document (or {} for a thread with no approved comments yet — emit nothing in that case), only ever includes approved comments, and is cacheable for 60 seconds.

If you SSR your own copy, set data-structured-data="false" on the widget container so it doesn't also inject a second, duplicate block — both documents share the same @id, and two conflicting copies on one page is worse for SEO than one:

<!-- Opt the widget out of its own JSON-LD since you're rendering the
     fetch() result above yourself -->
<div id="echothread"
     data-api-key="YOUR_API_KEY"
     data-identifier="blog-my-post"
     data-structured-data="false"></div>
<script src="https://cdn.echothread.io/widget.js" async></script>

Validate the output with Google's Rich Results Test.

Comment counts on listing pages

The widget renders one discussion, on one page. To show how many comments a post has from somewhere the widget isn't — a category archive, your home page, a related-posts rail — use the count script instead. It's under 4 KB gzipped and resolves every count on the page in a single request.

Mark each spot with data-et-count, set to the same identifier the widget uses for that page, then load the script once:

<!-- Anywhere you list posts: archives, the home page, a related-posts rail.
     The element keeps whatever text you put in it until the count arrives.
     End the link at #echothread so the click lands on the thread itself. -->
<a href="/post/first/#echothread" data-et-count="post-1">Leave a comment</a>
<a href="/post/second/#echothread" data-et-count="post-2">Leave a comment</a>

<!-- Once per page, at the end. Fills every placeholder in one request. -->
<script src="https://cdn.echothread.io/count.js"
        data-api-key="YOUR_API_KEY" async></script>

Each element's text is replaced only once its number arrives, so whatever you put inside is what a reader sees if the request fails or the script is blocked. The resolved number is also written to data-et-count-value, so you can style on it — hiding a "0 comments" badge, for example.

If you didn't set data-identifier on the widget, your threads are keyed on the page URL: leave data-et-count empty on a link and the script uses that link's href — a trailing #echothread doesn't affect the match.

Counts on links take the reader to the discussion: end the link at #echothread, the widget's anchor on the post page, and the click lands with the thread in view rather than at the top of the post. A link your theme wrote for its own comments area (WordPress's #comments, say) is repointed to the widget once the count arrives; a link that already aims somewhere specific is never redirected.

Wording and language

Counts read in the same language as the widget. Set data-lang to pin one (en, ko, it, zh or el), or leave it off and each visitor sees the count in their browser's language — the same choice the widget's container makes. Any single form can still be overridden with your own wording, and an override always wins:

<!-- Optional: pin a language for every visitor, and/or your own
     wording. data-count-* overrides win over the locale; {count} is the number. -->
<script src="https://cdn.echothread.io/count.js"
        data-api-key="YOUR_API_KEY"
        data-lang="it"
        data-count-zero="Nessun commento"
        data-count-one="1 commento"
        data-count-many="{count} commenti" async></script>

Counts also fit themselves to your page. If the colour a count would inherit is unreadable against the background behind it — black text in a dark theme's meta row, the usual case — the script repaints it with a readable one. A readable colour, and any colour you set inline on the element, is never touched.

Fetching counts yourself

The script is a thin wrapper around one public endpoint, so a static-site generator or a server-rendered template can bake the numbers straight into the HTML:

// Or ask for the numbers yourself — up to 50 identifiers per request.
const res = await fetch(
  'https://api.echothread.io/api/v1/embed/counts?api_key=' + API_KEY +
    '&identifiers=' + encodeURIComponent(['post-1', 'post-2'].join(','))
)
const { counts } = await res.json()
// { "post-1": 12, "post-2": 0 }

Every identifier you ask about comes back, including ones with no thread yet — those are 0. The response is cacheable for 60 seconds. Counts include replies, and match the number shown in the widget's own header.

Authentication

How readers post is configurable per site. You can require an account or open commenting to guests — either way, the Siftfy ML spam filter screens new comments and gives moderators a clean queue.

Guest commenting

Turn on Allow guest comments in a site's moderation settings and readers can post with just a display name — no account required. Every guest comment is always scored by Siftfy before it can appear, even when auto-approve is on, so you get frictionless commenting without the spam. Guest commenting is off by default; enabling it is a one-click, per-site choice.

Commenter sign-in

Visitors can also sign in with Google, GitHub, X, Facebook, Discord, Bluesky or Mastodon. No passwords to manage, no separate accounts to create. The sign-in flow happens inside the widget without navigating away from your page. Choose which of these your site offers under Sign-in methods in the site's settings.

Sign in with EchoThread

On Starter and above you can also offer Sign in with EchoThread. Readers comment with their own EchoThread name and photo, which they edit once and which follow them to every site that offers it. If a reader has turned on a public profile, their name links to it. Readers sign up free, with a magic link or a passkey.

It is off by default and separate from "Allow all providers": turn it on under Sign-in methods in your site's settings. On Hobby the option is shown but locked.

Commenter profiles

Anyone with an EchoThread account can edit their name, photo, bio and website under Profile in the account menu. Signing in again with Google, GitHub, X, Facebook or a magic link never overwrites them. A public profile page at echothread.io/u/your-handle is optional and off until the reader turns it on. It shows only their name, photo, bio and website link, never their email or comments.

Use data-auth-button-style="icons" when a narrow theme column makes full "Continue with ..." buttons feel cramped. The buttons render as icon-only 44px targets with accessible labels, so screen readers still announce the provider names.

Site owner sign-in

Site owners use magic link authentication. Enter your email, click the link we send, and you're in. No password to remember or reset.

Moderation

EchoThread gives you full control over what appears on your site.

Moderation dashboard

The dashboard lets you approve, reject, or delete comments with a single click. Filter by status (pending, approved, rejected, spam) to work through your queue efficiently.

Auto-approve mode

Toggle auto-approve per site. When enabled, new comments go live immediately without manual review. When disabled, all comments start as "pending" until you approve them.

Spam filter

EchoThread scores every incoming comment with a machine-learning spam classifier. High-confidence spam is kept out of the public thread automatically; borderline comments land in your spam queue, tagged with the signals that flagged them — link density, ALL-CAPS, repeated characters, promo keywords, and drive-by links — so you can review at a glance. Behind the scenes, each comment's spam probability is scored by the Siftfy classification API: very high scores auto-block, borderline scores go to your review queue, and the rest pass through.

Restricted words

Keep a blocklist of your own on each site. Every new comment is checked against it — both the comment body and the author's display name — before the spam classifier runs, so your own rule decides first and a comment your list catches never goes to the classifier at all.

Pick what a match does for the whole list, not word by word: hold sends the comment to your moderation queue (the default), or reject files it as rejected — the same status as a comment you reject by hand, so it stays in the queue under Rejected and can be approved later. A match on the author's display name always holds and never rejects: a name is not a message.

Matching is case-insensitive. * is a wildcard that matches a run of non-space characters, and a space in an entry matches any run of whitespace, so a phrase pasted with odd spacing still matches. Entries that begin or end with an ASCII letter, digit, or underscore are matched on word boundaries — ass doesn't fire on class — while entries in scripts those boundaries don't apply to, such as Chinese, Arabic, or Hebrew, are matched as substrings rather than left unmatchable.

A list holds up to 2,000 entries of up to 128 characters each, enforced on the server. In the queue, a comment your list caught is labelled as your own rule rather than as spam and shows the text that matched — both details are visible to you and your moderators only, like the spam score, and never to the commenter. The list travels with your data: it's included in the site's JSON export under a moderation object. Only the site owner can edit the list; moderators can't change it.

Banning and trusting commenters

Each site keeps its own standing on the people who comment there. Ban stops someone posting to that site. Trust auto-approves their comments on it. Both are per site and per person — never platform-wide, so your decision never follows a reader to anyone else's site.

A trusted commenter skips pre-moderation and a restricted-word hold, but never a restricted-word reject — that's a rule about content, not about a person.

A ban can optionally reject that person's still-visible comments from the last 30 days. It's opt-in and never the default, and those comments are rejected rather than deleted, so the decision is reversible. On a very busy site the sweep examines a bounded window of recent comments and tells you when it stopped early, so you can check the Rejected tab for any it didn't reach.

Owners and moderators can both ban and trust — it's queue work. People who hold a seat on the site can't be banned or trusted.

This isn't the same thing as a reader blocking someone. A reader's block hides that person from that one reader and tells nobody; a ban removes them from your site.

Auto-closing old threads

Set auto-close to 30, 60, 90, 180, or 365 days and a thread stops taking new comments that many days after it was created. Leave it off — the default — and threads stay open indefinitely.

Existing comments stay visible and readable; closing a thread only stops new ones. The window is worked out when the page is requested rather than written onto your threads, so lengthening the setting or turning it off reopens the threads it had closed. A thread you re-open by hand is exempt from the schedule from then on.

The widget renders a closed thread read-only with a plain explanation, and signed-out readers see that notice too. Thread responses carry a closed_reason of "closed", "locked", or "auto_close", so a scheduled close is distinguishable from one somebody made by hand.

Notifications

Get dashboard notifications when new comments arrive or spam is detected. The notification bell polls for unread counts so you never miss activity.

Site settings

Each site you register has its own configuration. Navigate to My Sites → [your site] in the dashboard to manage these.

API key

Each site has a unique API key that authenticates the embed widget. You can find it on your site's settings page in the dashboard.

Regenerating your key

If your API key is compromised, click Regenerate on your site settings page. The old key stops working immediately. Update the embed snippet on your site with the new key.

Webhooks

On the Starter plan and above, subscribe an HTTPS endpoint to comment and thread events — new comments, approvals, rejections, deletions, new threads — and get a signed request the moment they happen instead of polling the API. The same screen, Alerts and webhooks on each site, also sends new comments to a Slack or Discord channel: paste the channel's incoming-webhook URL, choose whether to hear about comments awaiting review, published comments, or both, and press Send test. Comments that ask a question are marked, and an alert never includes a commenter's email or IP address. See the full webhooks documentation for event payloads, the X-EchoThread-Signature verification scheme, and the retry schedule.

Public API

Read your sites, threads and comments from your own server on every plan — the free Hobby plan can create up to 2 read-only tokens — and, on the Starter plan and above, moderate comments — approve, reject, mark spam, reply, delete — authenticated with a personal API token from Account → API Tokens. Creating comments through the API isn't supported — comments are only ever posted by a real visitor through the embed widget. See the full public API documentation for every route, cursor pagination, and error shapes.

MCP server

Manage your comments from Claude, ChatGPT desktop, Cursor or any other assistant that speaks the Model Context Protocol. The EchoThread MCP server, @echothread/mcp, runs on your own computer and calls the public API with a personal API token, so it can do exactly what that token's scopes and your plan allow: read on every plan, and moderate, reply and delete on Starter and above. It is open source (MIT) and listed in the official MCP Registry as io.echothread/mcp.

1. Create a token on Account → API Tokens. Tick only the scopes the assistant needs.
2. Add the server to your assistant's MCP configuration, with the token in ECHOTHREAD_API_TOKEN:

{
  "mcpServers": {
    "echothread": {
      "command": "npx",
      "args": ["-y", "@echothread/mcp"],
      "env": { "ECHOTHREAD_API_TOKEN": "et_..." }
    }
  }
}

It offers 11 tools: list your sites, the moderation queue, new comments since a time, get a thread with its comments, get a comment, per-site comment stats, approve, reject, mark spam, reply, and delete. Delete is permanent, so give the token the delete scope only if you want the assistant to have it. A tool the token has no scope for returns a clear message naming the missing scope, and nothing changes. The server cannot post new comments: comments come only from real visitors through the widget.

n8n

On the Starter plan and above, the EchoThread community node for n8n starts a workflow for each new comment and lets the workflow act on it. Install @echothread/n8n-nodes-echothread from Settings → Community Nodes in n8n, then add an EchoThread credential with a personal API token.

• EchoThread Trigger — New Comment: polls every site your account owns and runs once per new comment, optionally only for the statuses you pick (pending, approved, spam or rejected). On first activation it starts from that moment, so old comments don't flood the workflow.
• EchoThread: approve, reject, mark spam, reply to, or get a comment by id.

A token without the scope an action needs fails that item with the API's scope_required message; a Hobby token gets "The n8n node needs Starter". The node is open source (MIT); see its source on GitHub.

Single sign-on (SSO)

On the Pro plan and above, sign your readers into EchoThread automatically using the identity they already have on your site: your backend HMAC-signs a small {id, email, name, avatar} payload with your site's SSO secret and passes it to the widget, so a visitor already signed in on your side lands signed in here too, with no second login step. See the full SSO documentation for the payload shape, worked Node and PHP signing examples, the 5-minute timestamp window, and secret rotation.

Troubleshooting

FAQ