Docs / Features / Guest Commenting

Guest Commenting

Lower friction for first-time commenters — with moderation, rate limits, and a conversion path that turns guests into community members.

How it works

1. Reader chooses Comment as guest in the widget
2. Enters name + email (no password)
3. Comment is held for moderation by default
4. After 3 approved comments, future guest comments auto-approve (configurable)
5. Guest receives email to claim comments and create an account

Limits

• 3 guest comments per email per hour
• After 3 total guest comments, prompt to create an account
• Publishers can disable guest commenting per site

API

POST /v1/comments/guest
{
  "thread_url": "...",
  "site_id": "...",
  "content": "...",
  "guest_name": "Jane",
  "guest_email": "jane@example.com"
}

POST /api/auth/guest-claim  { "token": "...", "password": "..." }

Claim walkthrough

1. Guest posts via POST /v1/comments/guest and receives a claim_token (valid 7 days).
2. Claim email and the widget GuestClaimBanner link to /claim-comments?token=....
3. GET /api/auth/guest-claim?token=... returns claim preview: email, display_name, comment_count, site_name, has_account.
4. POST /api/auth/guest-claim with token, optional password and display_name migrates comments and sets a session.
5. Unclaimed guests are purged after 24 hours.

Example guest create response (includes claim token):

POST /v1/comments/guest
{
  "id": "cmt_abc123",
  "status": "pending",
  "claim_token": "gct_7d_xxxxxxxx",
  "guest_email": "jane@example.com"
}

Example GET claim preview:

GET /api/auth/guest-claim?token=gct_7d_xxxxxxxx
{
  "email": "jane@example.com",
  "display_name": "Jane",
  "comment_count": 2,
  "site_name": "Acme Blog",
  "has_account": false
}

Example POST claim (creates account / migrates comments / sets session):

POST /api/auth/guest-claim
{
  "token": "gct_7d_xxxxxxxx",
  "password": "optional-if-new-account",
  "display_name": "Jane Doe"
}

# Response
{
  "ok": true,
  "migrated": 2,
  "user": { "id": "usr_...", "email": "jane@example.com", "display_name": "Jane Doe" }
}