Admin guide

KeyBlogging Comments — setup tutorial

For website admins: create your company & blog, install the embed on Astro/static sites, moderate comments, and optional GFAVIP Chat alerts.

Installing on Astro / many static sites? Use the dedicated guide: /docs/astro — site-wide login bridge, cache-bust v=, canonical host, agent checklist.

1. Requirements & plans

GFAVIP tier	What you can do here
`free`	Comment on blogs (as a reader). Cannot create companies/blogs.
`paid` (Premium)	1 company, up to 5 blogs.
`team`	Unlimited companies & blogs.

App host: https://my.keyblogging.com · Service: keyblogging

2. Create account (SSO)

Open https://my.keyblogging.com/login.
Continue with GFAVIP (same wallet account as the rest of the ecosystem).
You land on the dashboard. Your profile shows tier and limits.

3. Company & blog

In the dashboard, Create company (Premium/Team required).
Open the company → Add blog:
- Name — display name
- Slug — used in the embed URL, e.g. my-blog (lowercase, hyphens)
- Domain — your public site host only, e.g. www.example.com or localhost:4321 (no https:// path). Used for CORS so the embed can call our API.
- Auto-approve — see below
- Webhook URL — optional; see webhooks section
Optional: open the blog → Add thread for a post slug, or let the first comment create the thread automatically.

4. Install embed code

On each article (Astro, static HTML, etc.), add:

<div id="keyblogging-comments"></div>
<script
  src="https://my.keyblogging.com/static/embed.js?blog=YOUR-BLOG-SLUG&post=YOUR-POST-SLUG"
  async></script>

Replace

YOUR-BLOG-SLUG — the slug from the dashboard (e.g. my-blog)
YOUR-POST-SLUG — stable post id (often the page path slug, e.g. hello-world)

Astro example: use blog={blogSlug}&post={post.slug} from frontmatter.

What visitors see

Anyone — approved comments (no login)
Login with GFAVIP — popup on https://my.keyblogging.com, then they can post/reply
Pending comments stay hidden until you approve them

Crawlable / SEO fallback

Public HTML (optional link or prerender):

https://my.keyblogging.com/embed/YOUR-BLOG-SLUG/YOUR-POST-SLUG

Optional CSS variables

#keyblogging-comments {
  --kb-fg: #111;
  --kb-muted: #6b7280;
  --kb-border: #e5e7eb;
  --kb-bg: #fff;
  --kb-accent: #111;
  --kb-radius: 8px;
  --kb-font: system-ui, sans-serif;
}

5. Moderation settings

auto_approve	Behavior
`all`	Every new comment is public immediately
`no_links`	Approve if no URLs; otherwise pending (default)
`after_first_approval`	First comment pending; later ones auto-approve for that author on the blog

Moderate at /dashboard/moderation — bulk approve, reject, or delete. Per-thread view: open the blog → thread → Comments.

6. GFAVIP Chat webhooks (alerts)

When someone posts a comment, we can notify a Matrix room in GFAVIP Chat.

Do not use the room browser link as the webhook URL.

This is only for opening the room in your browser — it is not an API endpoint:

https://webchat.gfavip.com/workspace/…#/room/!YUPvwpZLwbCqciojzX%3Agfavip.com

Room ID (e.g. !YUPvwpZLwbCqciojzX:gfavip.com) is used only when creating the integration inside GFAVIP Chat. Do not paste the room ID into KeyBlogging.

Use the generated HTTPS webhook URL from Workspace → Integrations (Generic JSON). It looks like a full https://… URL that GFAVIP gives you after you click Generate — not the webchat UI link.

Also invalid: app://./api/webhooks/…

That is a Matrix/Element client deep link. Our server cannot POST to app://. You need the copyable https:// webhook URL from Integrations (often labeled “Webhook URL” after Generate).

How to create the webhook in GFAVIP Chat

Open the room where alerts should appear.
Room Settings (gear) → Advanced → copy Internal Room ID (!…:gfavip.com).
Go to Workspace Settings → Integrations.
Name it (e.g. “KeyBlogging comments”), paste the Room ID, choose type Generic JSON, click Generate.
Copy the unique Webhook URL GFAVIP shows you.
Paste that full URL into:
- Blog settings → Webhook URL (recommended, per site), or
- Server env GFAVIP_WEBHOOK_URL (global fallback for all blogs).

Item	Example shape	Put in KeyBlogging?
Webchat room link	`https://webchat.gfavip.com/workspace/…#/room/!…`	❌ No
Room ID	`!YUPvwpZLwbCqciojzX:gfavip.com`	❌ No (only in Chat Integrations UI)
Webhook URL	`https://…` (from Integrations → Generate)	✅ Yes

We POST Slack-style blocks JSON. If the webhook is down, comments still save — we only log the failure.

7. Invite moderators

Company page → Invite moderator (email + role: moderator or admin).
Share the accept link: https://my.keyblogging.com/invites/accept/<token>
They must log in with GFAVIP using the same email as the invite.

8. Troubleshooting

Symptom	Fix
Cannot create company	Need GFAVIP `paid` or `team` (or super-admin).
Embed loads but API blocked / CORS	Blog domain must match the site host (e.g. `www.example.com`).
Login works but post fails 401	Complete login popup until it closes; try again. Token is stored for that tab.
Comments not public	Check auto-approve; approve in `/dashboard/moderation`.
No Chat alert	Confirm you used the generated webhook URL, not the webchat room link or room ID.
Wrong post thread	Keep `post=` slug stable when you rename URLs; use dashboard “Edit permalink” to move the thread without losing comments.

Quick checklist

☐ GFAVIP login works on https://my.keyblogging.com
☐ Company + blog created; domain set
☐ Embed on a real post with correct blog + post
☐ Test comment as free user
☐ Moderation queue works
☐ (Optional) Real Integrations webhook URL, not webchat UI link