Skip to content

EchoThread Comment Widget Documentation

Use these EchoThread docs to install a privacy-first comment widget on any website in under a minute. Start with the copy-paste embed snippet, then configure thread identifiers, theming, import/export, moderation, and platform setup for Shopify, Wix, Framer, Squarespace, WordPress, Next.js, Hugo, Astro, Ghost, Jekyll, Eleventy, and Gatsby.

Last updated · See the changelog for recent widget updates, or the EchoThread blog for in-depth guides.

Popular setup paths

Quick start

Get EchoThread running on your site in under a minute. No build tools required.

1

Create an account & register your site

Sign up for free, then add your website domain in the dashboard. You'll receive an API key for your site.

2

Add the embed snippet

Paste this before your closing </body> tag, replacing YOUR_API_KEY with the key from your dashboard:

<div id="echothread"
     data-api-key="YOUR_API_KEY"></div>
<script src="https://cdn.echothread.io/widget.js" async></script>
3

You're live

Comments will appear on your page immediately. Manage them from the moderation dashboard.

Configuration

Customize the widget using data-* attributes on the container element.

AttributeDefaultDescription
data-api-key(required)Your site API key from the dashboard.
data-page-urlwindow.location.hrefCanonical URL of the page. Used to group comments into threads.
data-identifierpage URLStable unique ID for the comment thread. Use a slug or database ID so threads survive URL changes.
data-page-titledocument.titleTitle stored with the thread. Shown in the dashboard.
data-langauto (browser)Widget UI language: "en", "ko", "it", "zh" (Simplified Chinese), or "el" (Modern Greek). Omit to follow each visitor's browser language (falling back to English). Set it to pin one language for every visitor.
data-themeauto (your page)"light", "dark", or any hex color (e.g. "#FAF7F2") for a custom background. Omit and the widget matches the background of the page it sits on, falling back to the visitor's OS preference only when the page has none.
data-theme-source(none)CSS custom property to read from the host page as the widget background, e.g. "--color-bg". Useful for themes with user-selectable color schemes.
data-accent-color#4f46e5Custom accent color for the send button and footer link.
data-auth-button-stylelabelledSet to "icons" to render social sign-in buttons as icon-only 44px buttons with accessible provider labels.
data-fontsystemTypography preset: "system", "sans", "serif", "mono", or "rounded". data-font-family overrides this.
data-font-familysystem stackOverride the widget font. Any CSS font-family value, e.g. "'Inter', sans-serif". Use "inherit" to pick up your site's font.
data-font-size14pxOverride the base font size. Any CSS length, e.g. "15px" or "0.95rem".
data-radius8pxBorder radius for the widget container and cards. Any CSS length, e.g. "0" for sharp corners or "16px" for softer cards.
data-mobile-gap6pxRow gap between avatar and composer on mobile (≤480px). Tighten with "0" or "4px" for narrow sidebars, or widen for more breathing room.
data-mobile-avatar-size28pxAvatar size on mobile (≤480px). Defaults to 28px so the composer card uses more horizontal space; "24px" gives the editor even more room in very narrow columns.
data-mobile-min-widthautoMinimum widget width on mobile (≤480px). Set to "100%" to fill the host column edge-to-edge.
data-structured-datatrueSet to "false" to stop the widget from auto-injecting its schema.org DiscussionForumPosting JSON-LD — use this only if you already render the same document server-side (SSR) yourself, to avoid a duplicate block.

Full example

<div id="echothread"
     data-api-key="YOUR_API_KEY"
     data-page-url="https://example.com/blog/my-post"
     data-identifier="blog-my-post"
     data-page-title="My Blog Post"
     data-theme="dark"
     data-theme-source="--color-bg"
     data-accent-color="#e8353a"
     data-auth-button-style="icons"></div>
<script src="https://cdn.echothread.io/widget.js" async></script>

Theming

EchoThread supports light and dark themes out of the box. By default it matches your page: the widget reads the background it is sitting on and picks the theme that belongs there, so a visitor whose device is in dark mode does not get a dark widget on your light page. If your page paints no background of its own, the visitor's operating system preference decides.

Force a theme

Set data-theme="light" or data-theme="dark" on the container to pin the theme instead. You can also pin it for a whole site — without editing the snippet — under Widget theme in that site's settings; a data-theme on the container wins over it.

Custom background color

Pass any hex color to data-theme to use it as the widget background. Text and surface colors adapt automatically based on the color's luminance.

<div id="echothread"
     data-theme="#FAF7F2"
     ...></div>

Follow a site theme variable

If your theme changes background colors with a CSS custom property, pass that property name to data-theme-source. EchoThread reads the current value as its background and updates when the host theme attribute changes.

<!-- Example: Ghost/Tuuli-style theme variables -->
<div id="echothread"
     data-theme-source="--color-bg"
     data-accent-color="#a31e13"
     ...></div>

Custom accent color

Use data-accent-color to match EchoThread to your brand. This applies to the submit button, active states, and footer link. Accepts any valid CSS color value.

Need examples before choosing? Paste your URL into the widget theme builder, or browse the widget theme gallery for light, dark, localized, background-color, accent, and icon-login combinations.

/* Example: override via CSS custom properties */
#echothread {
  --et-color-accent: #6366f1;
  --et-radius: 12px;
  --et-font: 'Inter', system-ui, sans-serif;
}

Match your site's typography

By default EchoThread uses a clean system font stack so it looks consistent across browsers. Pass data-font-family to use a specific font, or data-font-family="inherit" to pick up the font your site already uses. You can also tune the base size with data-font-size and the corner radius with data-radius.

<!-- Inherit your site's font, bump the base size, soften the corners -->
<div id="echothread"
     data-api-key="YOUR_API_KEY"
     data-font-family="inherit"
     data-font-size="15px"
     data-radius="12px"></div>

<!-- Or pin a specific font -->
<div id="echothread"
     data-api-key="YOUR_API_KEY"
     data-font-family="'Inter', system-ui, sans-serif"></div>

The widget defends its own typography against host-page CSS resets, so these attributes are the supported way to change fonts — host-side !important overrides on .et-widget descendants won't take effect.

CSS custom properties

VariableDefaultDescription
--et-color-accent#4f46e5Primary accent color (send button, links, active states).
--et-color-accent-hover#4338caAccent color used on hover.
--et-color-bg#ffffffWidget background. Derived automatically from data-theme when set.
--et-color-surface#f8fafcSurface color for comment bubbles, inputs, and chips.
--et-color-border#e2e8f0Border color for the container, inputs, and cards.
--et-color-text#1e293bPrimary text color.
--et-color-muted#64748bMuted text color (timestamps, secondary actions).
--et-radius8pxBorder radius for the container and cards.
--et-fontsystem stackFont family for all widget text.
--et-font-size14pxBase font size for the widget.

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:

Bold
**text**Ctrl + B
bold text
Italic
_text_Ctrl + I
italic text
Strikethrough
~~text~~Ctrl + Shift + S
struck text
Spoiler
||text||Ctrl + Shift + X
a clue
Spoilers are keyboard-accessible: focus, press Enter or Space to reveal, Escape to re-mask. aria-label announces the current state. WCAG 2.1 AA aligned — useful for movie, TV, gaming, and book threads.

Sorting

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

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>

Only set this if you're actually rendering the JSON-LD yourself. data-structured-data="false" doesn't reduce structured data on your page — with no SSR replacement, it removes all of it.

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. -->
<a href="/post/first/" data-et-count="post-1">Leave a comment</a>
<a href="/post/second/" 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.

Wording and language

The defaults are No comments, 1 Comment, and N Comments. Override any of them on the script tag — the count script has no locale of its own, because the words around it are yours:

<!-- Optional: your own wording, in your own language.
     {count} is replaced with the number. -->
<script src="https://cdn.echothread.io/count.js"
        data-api-key="YOUR_API_KEY"
        data-count-zero="Nessun commento"
        data-count-one="1 commento"
        data-count-many="{count} commenti" async></script>

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.

On WordPress, the EchoThread plugin does this for you: turn on Archive comment counts and your theme's existing counts are filled from EchoThread instead of WordPress's own table, which stops updating the moment EchoThread takes over.

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 or GitHub via OAuth. No passwords to manage, no separate accounts to create. The sign-in flow happens inside the widget without navigating away from your page.

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.

SettingDescription
Site nameDisplay name for your site (shown in the dashboard only).
DomainThe domain where the widget is embedded. Used for CORS validation.
DescriptionOptional description for your own reference.
Auto-approveWhen on, new comments are immediately visible. When off, they require manual approval.
Spam filterWhen on, likely spam is automatically flagged and sent to the spam queue.
Allow votingShow or hide emoji reactions (Like, Love, Haha, Angry) on comments.
Restricted wordsYour own blocklist for this site, checked against the comment body and the author's display name before the spam filter runs. Up to 2,000 entries of 128 characters each; * is a wildcard. Owner-only.
Restricted word actionWhat a restricted-word match does, for the whole list: hold for review (the default) or reject. A display-name match always holds.
Auto-close threadsStop new comments 30, 60, 90, 180, or 365 days after a thread is created. Off by default. Existing comments stay visible, and clearing the setting reopens the threads.

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.

Keep your API key private. While the key is included in your page's HTML (and therefore visible to visitors), it is scoped to your registered domain. Requests from other domains will be rejected.

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. See the full webhooks documentation for event payloads, the X-EchoThread-Signature verification scheme, and the retry schedule.

Public API

On the Starter plan and above, read your sites, threads and comments and moderate comments — approve, reject, delete — from your own server, 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.

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.

Platform guides

EchoThread works on any website that supports custom HTML — from static site generators to hosted no-code builders like Shopify, Wix, Framer, and Squarespace. Static site generators are especially popular with EchoThread since they have no built-in backend for comments, and no-code builders pair well with it because their native comment tools are limited. For a deeper comparison, see our guide to the best commenting system for static sites. Below are detailed setup guides for the most popular platforms.

Static HTML

Static HTML is the simplest integration. No build tools, frameworks, or dependencies — just copy and paste.

Step 1 — Add the embed snippet

Paste the following code in your HTML file where you want the comment section to appear. A good location is after your article content, before the closing </body> tag:

<!-- Add this where you want comments to appear -->
<div id="echothread"
     data-api-key="YOUR_API_KEY"
     data-page-url="https://example.com/blog/my-post.html"
     data-identifier="my-post"
     data-page-title="My Blog Post"></div>
<script src="https://cdn.echothread.io/widget.js" async></script>

Step 2 — Set your attributes

Replace the placeholder values with your own:

  • data-api-key — your site's API key from the EchoThread dashboard (My Sites → Settings).
  • data-page-url — the full canonical URL of the page. This should be the same URL visitors see in their browser.
  • data-identifier — a unique, stable string for this page (e.g. a slug like "my-post"). This ensures comments stay linked to the page even if you change the URL later.
  • data-page-title — the page title shown in your moderation dashboard and notifications.

Step 3 — Customize (optional)

Add optional attributes to control the look and feel:

<div id="echothread"
     data-api-key="YOUR_API_KEY"
     data-page-url="https://example.com/blog/my-post.html"
     data-identifier="my-post"
     data-page-title="My Blog Post"
     data-theme="dark"
     data-accent-color="#6366f1"></div>
<script src="https://cdn.echothread.io/widget.js" async></script>

Full page example

Here's a minimal complete HTML page with EchoThread:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My Blog Post</title>
</head>
<body>
  <article>
    <h1>My Blog Post</h1>
    <p>Your post content here...</p>
  </article>

  <!-- EchoThread comments -->
  <div id="echothread"
       data-api-key="YOUR_API_KEY"
       data-page-url="https://example.com/blog/my-post.html"
       data-identifier="my-post"
       data-page-title="My Blog Post"></div>
  <script src="https://cdn.echothread.io/widget.js" async></script>
</body>
</html>

Multi-page sites: Each page needs its own unique data-identifier. If all your pages share the same identifier, all comments will appear on every page. Use the page slug, filename, or any unique string.

WordPress

WordPress has a built-in comment system, but many site owners prefer EchoThread for its modern UI, threaded replies, reactions, and ML spam filtering. The easiest way is our official plugin — no code required. If you want more control, you can also add EchoThread by hand in three ways.

Recommended — Official WordPress plugin (no code)

Install Comments – EchoThread from the WordPress.org plugin directory — or search EchoThread under Plugins → Add New in your dashboard. Activate it, open Settings → EchoThread Comments, paste your site shortname and API key, and pick where comments appear: replace your theme's comments, append below the content, or drop them anywhere with the [echothread] shortcode. No theme edits, no database tables.

Turn on Archive comment counts while you're there. WordPress stops updating its own comment counts once EchoThread hosts the discussion, so category and home-page teasers keep showing whatever the number was on the day you switched — or zero. With the setting on, those counts come from EchoThread instead. See Comment counts.

Prefer to wire it up by hand? Three more ways:

Option A — Custom HTML block (per post)

This is the quickest way to try EchoThread on a single page. Open the post or page in the WordPress block editor, add a Custom HTML block where you want comments, and paste the snippet:

<div id="echothread"
     data-api-key="YOUR_API_KEY"
     data-page-url="<?php the_permalink(); ?>"
     data-identifier="wp-<?php the_ID(); ?>"
     data-page-title="<?php the_title(); ?>"></div>
<script src="https://cdn.echothread.io/widget.js" async></script>

Note: PHP tags (<?php ... ?>) only work inside theme template files, not in the block editor. If you're using the block editor, hardcode the page URL and a unique identifier instead, or use Option B for automatic values.

Option B — Theme template (site-wide, recommended)

To add EchoThread to every post automatically, edit your theme's single post template. This is the recommended approach for most WordPress sites.

Open single.php (or singular.php) in your active theme and add the snippet after the post content:

<!-- In your theme's single.php, after the_content() -->

<?php if ( comments_open() || get_comments_number() ) : ?>
  <div id="echothread"
       data-api-key="YOUR_API_KEY"
       data-page-url="<?php echo esc_url( get_permalink() ); ?>"
       data-identifier="wp-<?php the_ID(); ?>"
       data-page-title="<?php echo esc_attr( get_the_title() ); ?>"></div>
  <script src="https://cdn.echothread.io/widget.js" async></script>
<?php endif; ?>

Option C — Replace the default comment system

To completely replace WordPress's default comments with EchoThread, create a custom comment template. Add this to your theme's functions.php:

// functions.php — Load EchoThread instead of default comments
function echothread_comments_template( $template ) {
    return get_stylesheet_directory() . '/echothread-comments.php';
}
add_filter( 'comments_template', 'echothread_comments_template' );

Then create echothread-comments.php in your theme folder:

<!-- echothread-comments.php -->
<div id="echothread"
     data-api-key="YOUR_API_KEY"
     data-page-url="<?php echo esc_url( get_permalink() ); ?>"
     data-identifier="wp-<?php the_ID(); ?>"
     data-page-title="<?php echo esc_attr( get_the_title() ); ?>"></div>
<script src="https://cdn.echothread.io/widget.js" async></script>

Child themes: If you're using a child theme, place echothread-comments.php and functions.php edits in the child theme folder so your changes survive theme updates. This approach works with all major themes including Astra, GeneratePress, Kadence, and block themes (FSE).

Disable WordPress's default comments (optional)

If you're fully switching to EchoThread, you can disable the built-in comment system to avoid confusion:

// functions.php — Disable default WordPress comments entirely
add_action( 'admin_init', function() {
    // Remove comments from admin menu
    remove_menu_page( 'edit-comments.php' );
    // Disable comments on all post types
    foreach ( get_post_types() as $post_type ) {
        remove_post_type_support( $post_type, 'comments' );
        remove_post_type_support( $post_type, 'trackbacks' );
    }
});

For React frameworks and static site generators, follow the dedicated guide for your platform. Each guide walks through the reusable component or template include, identifier choices, conditional rendering, and any framework-specific gotchas.

Hosted website builders don't expose theme files the way a static site generator does, but each one has a place for custom HTML — so the same embed snippet works with no build step. The guides below cover the platform-specific placement; for the full walkthrough, follow the linked companion guide for each platform.

Framer

Framer's Embed element accepts raw HTML, so EchoThread drops in without code. To add comments to every blog post at once, edit the CMS Collection page rather than an individual page.

  1. Open the CMS Collection page (or a static page) and drag an Embed element below your content.
  2. Set the embed type to HTML and paste the Quick start snippet.
  3. For blog posts, use the code editor's + menu to bind the post slug to data-identifier so each post gets its own thread.
  4. Set the element width to Fill and height to Auto so the thread can grow, then publish.
Read the full Framer guide

Wix

Use Wix's Custom Code feature, not the Embed HTML element. Wix's own documentation states that its HTML element is an iframe, so code inside it runs on a Wix address rather than your domain — which means commenter sign-in cannot complete. Custom Code injects into the page itself.

  1. Publish the site and connect your domain. Wix requires both before Custom Code runs, and EchoThread needs the domain registered in your dashboard before sign-in will complete.
  2. In your Wix dashboard open Settings → Custom Code and add a snippet placed in Body – end.
  3. Paste a short script that creates the <div id="echothread"> container and then loads the widget — the full snippet is in the Wix guide below.
  4. Scope it to your blog post pages rather than all pages, and set it to load on each new page so it follows client-side navigation.
Read the full Wix guide

Shopify

Shopify blog posts are rendered by your theme's article template. Add EchoThread by editing that template in the theme code editor — no app required.

  1. From the Shopify admin, go to Online Store → Themes, then … → Edit code. Duplicate the theme first so you can test safely.
  2. Open sections/main-article.liquid (or templates/article.liquid on older themes).
  3. Paste the Quick start snippet just after {{ article.content }}, using data-identifier="{{ article.id }}" so each post keeps its own thread.
  4. Replace the native {% if blog.comments_enabled? %} block rather than adding beside it, then save and preview.
  5. Disable Shopify's own comments under Content → Blog posts → Manage blogs, or it keeps accepting them behind the scenes.
Read the full Shopify guide

Squarespace

Squarespace supports EchoThread through a Code Block — a no-code installation that takes a few minutes.

  1. Edit a blog post (or the blog post template) and add a Code Block below the content.
  2. Paste the Quick start snippet and confirm the block is set to render HTML, not display it as text.
  3. On the Core, Plus and Advanced plans (code injection is not on the entry-level plan) you can instead paste the whole snippet once into the blog page's Advanced → Post Blog Item Code Injection field, which applies it to every post in that blog — including ones you write later.
  4. Turn off Squarespace's own comments in the blog's Comments Settings, or you will have two comment boxes on the same post.
Read the full Squarespace guide

Ghost

Ghost has had its own comments since 5.0, but they are members-only — a reader has to sign up to your publication before posting. Both default themes, Source and Casper, render them from a {{#if comments}} block in post.hbs, so replacing that block swaps members-only comments for open ones.

  1. Register your Ghost site's domain in your EchoThread dashboard so sign-in can complete.
  2. Download the active theme from Settings → Design & branding → Theme. You do not need a local Ghost install.
  3. In post.hbs, replace the {{#if comments}} block with the EchoThread container and script, using data-identifier="{{id}}" and data-page-url="{{url absolute="true"}}".
  4. Re-upload the theme. Use {{id}} rather than {{slug}} — editing a post title rewrites the slug, which would strand the discussion.
Read the full Ghost guide

Running a traditional CMS? Each of these has a dedicated guide covering the exact file to edit, which identifier survives a URL change, and how to switch off the platform's own comments so you don't end up with two.

Import and export reference

Load the detailed Disqus, WordPress, JSON, and CSV field reference when you are ready to move comment data.

Migrating from Disqus? Start with the safe Disqus export guide.

Troubleshooting

Widget doesn't appear

  • Check that the data-api-key matches the key in your dashboard.
  • Make sure the widget script URL is correct: https://cdn.echothread.io/widget.js
  • Verify your domain is registered in your site settings. The API key is scoped to your domain.
  • Open your browser's developer console and look for error messages.

Comments not showing up

  • If auto-approve is off, new comments stay in "pending" until you approve them in the dashboard.
  • Check the moderation queue for pending or spam-flagged comments.

CORS errors

  • The domain in your site settings must match the domain where the widget is embedded.
  • Include the protocol: example.com, not http://example.com.
  • If testing locally, register localhost as your domain.

Wrong thread / duplicate threads

  • Use data-identifier to tie a thread to a stable ID (e.g., a post slug). Without it, threads default to the page URL, which can cause duplicates if URLs change.
  • Use data-page-url to set the canonical URL if your pages are accessible via multiple URLs.

FAQ

Is EchoThread free?

Yes. The Hobby tier is free for your first site, with no credit card required. It is a permanent free plan; paid plans start at $9/month if you outgrow it.

Does EchoThread use cookies?

No. EchoThread does not set any cookies. When a commenter signs in, their session tokens are kept in your browser's local storage — not in cookies, and never shared with third parties.

Does EchoThread track my visitors?

No. There are no analytics, no ads, and no third-party tracking scripts. We collect only the data needed to display and moderate comments.

How big is the widget?

Under 60 KB gzipped. Zero dependencies. It loads asynchronously and won't block your page rendering.

Can I export my data?

Yes. You can export all comments from any site as JSON or CSV from your site settings page. The JSON export uses the same format as the import, so you can easily migrate between sites. See the Exporting comments section above.

Will the free tier ever go away?

No. The Hobby tier is a permanent free plan. Paid plans exist for high-volume sites, but a generous free tier will always be available.

Is there a WordPress plugin?

Yes. Install "Comments – EchoThread" from the WordPress.org plugin directory (or search EchoThread under Plugins → Add New), then paste your site shortname and API key — no code or theme edits. You can replace your theme's comments, append them below the content, or place them with the [echothread] shortcode. Prefer to do it by hand? The WordPress section above covers the embed snippet and theme-template methods too.

Can guests comment without signing in?

Yes, if the site owner enables it. 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 screened by the Siftfy ML spam filter first. Owners can also require Google, GitHub, X, or Facebook sign-in instead. Guest commenting is off by default.

Does the widget support other languages?

Yes. The widget interface is localized in English, Korean, Italian, Simplified Chinese, and Modern Greek. By default each visitor sees it in their own browser language, falling back to English — no setup required. You can pin a single language for all visitors with data-lang="el" (or "en" / "ko" / "it" / "zh") on the container. Timestamps and dates are formatted natively per language. Comment content itself is never translated, only the widget's own interface.

How do I add schema markup to my comments automatically?

It's already on — no setup needed. The widget injects a schema.org DiscussionForumPosting/Comment JSON-LD block into your page on every render, which covers Googlebot and other JavaScript-rendering crawlers, and every document credits EchoThread as the publisher so AI answer engines can trace a cited conversation back to its source. To also reach crawlers that don't run JavaScript (most AI answer bots), fetch the same document server-side (SSR) from the discussion.jsonld endpoint and render it into your page's raw HTML — set data-structured-data="false" on the widget container so it stops injecting its own copy once you've done that, avoiding a duplicate block. See the Structured data section above for the endpoint and a code example.

Support

Need help? Sign in to your dashboard and use the Feedback form to reach us directly.