---
title: "Reader comments"
description: "Turn comments on, choose how they are moderated, show and accept them on a headless site, moderate, reply and erase through the API, and import or export them."
canonical: "https://writavo.com/docs/comments"
---

# Reader comments

Let readers comment on your articles. Comments are off until you turn them on and are held for review by default. Hosted blogs show them by themselves; headless sites use the API.

## How comments work

- **Off by default,** per Site. Turning them off hides them all and keeps them stored.
- **Plain text** with line breaks. No HTML, Markdown or images.
- **One level of replies.** A reply to a reply joins the top-level thread.
- **Only `approved` comments are public.** The others are `pending` or `spam`.
- **Team replies** publish at once (`author_kind: staff`) and approve the comment they answer.
- **Free** on every plan, and included in the Site export and import.

## Turn comments on

Needs the Moderate comments permission. In the dashboard: Settings > Site > Reader comments. With the API, use a key with comments:write:

curl:

```bash
curl -s -X PATCH https://api.writavo.com/v1/comments/settings \
  -H "Authorization: Bearer $WRITAVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "moderation": "hold_links", "require_email": true, "close_after_days": 90 }'
```

200 response:

```json
{
  "ok": true,
  "data": {
    "enabled": true,
    "moderation": "hold_links",
    "require_email": true,
    "close_after_days": 90
  }
}
```

| Setting | Default | What it does |
|---|---|---|
| `enabled` | `false` | Comments on or off for the whole Site. |
| `moderation` | `hold_all` | Which comments wait for review (see below). |
| `require_email` | `false` | Refuse a comment without an email address. The address is never public. |
| `close_after_days` | `null` | Stop taking comments this many days after publishing, 1 to 3650. `null` never closes. Existing comments stay visible. |

Send only the settings you want to change. A bad value is 422 VALIDATION_FAILED, naming the field. GET /comments/settings reads them.

## Moderation modes

| Mode | A reader's comment is |
|---|---|
| `hold_all` (default) | always `pending` until a moderator approves it |
| `hold_links` | `pending` when its text or name contains a link (`http://`, `https://`, `www.`, `[url` or `<a `), otherwise `approved` at once |
| `approve_all` | `approved` at once; moderate after the fact |

A new mode applies to new comments only.

## On a hosted blog

Blogs Writavo serves (writavo.com address, custom domain or reverse proxy) show approved comments and a form under every article once comments are on. Nothing to build. The form asks for an email only when require_email is on.

## Behind a reverse proxy

Behind a proxy, every reader shares the proxy's address. The Cloudflare Worker and nginx snippets on the Delivery page send two headers so limits apply per reader:

the two headers the snippets add:

```
X-Writavo-Proxy-Key: wvp_...           # this connection's key, shown in the snippet
X-Writavo-Reader-IP: <the reader's address>
```

- The key is per connection and already in the snippet. Without it the address is ignored, as is a list or a non-public address.
- Without the headers (an older snippet, or Next.js rewrites), limits apply per Site: 300 comments an hour. Copy the new snippet from Delivery for per-reader limits.
- To change the key, remove the proxy connection and set it up again.

## Headless: show the comments

Needs articles:read. A publishable key works, in the browser or at build time.

curl:

```bash
curl -s https://api.writavo.com/v1/comments/posts/hello-world \
  -H "Authorization: Bearer $WRITAVO_PUBLISHABLE_KEY"
```

200 response:

```json
{
  "ok": true,
  "data": {
    "slug": "hello-world",
    "enabled": true,
    "open": true,
    "require_email": false,
    "count": 2,
    "comments": [
      {
        "id": "6a1d0c3e-0000-4000-8000-000000000001",
        "parent_id": null,
        "author_name": "Sam",
        "author_kind": "reader",
        "body": "Clear and useful, thank you.\nOne question: does this work offline?",
        "created_at": "2026-10-03T14:02:11Z"
      },
      {
        "id": "6a1d0c3e-0000-4000-8000-000000000002",
        "parent_id": "6a1d0c3e-0000-4000-8000-000000000001",
        "author_name": "The Example team",
        "author_kind": "staff",
        "body": "It does, once the page has loaded once.",
        "created_at": "2026-10-03T15:20:40Z"
      }
    ]
  }
}
```

- `comments`: approved only, oldest first, up to 1,000. Group replies by `parent_id`; replies to unapproved comments are left out.
- `enabled: false`: comments are off, show nothing. `open: false`: off or past `close_after_days`, so show comments but hide the form.
- `require_email`: whether your form must ask for an email.
- `count` matches `comments` in the article's [engagement](/docs/headless#engagement). An unknown or unpublished slug is `404 NOT_FOUND`.

## Headless: accept a comment

Your form posts to your own server, which calls Writavo with a secret key (engagement:write). Never call it from the browser.

curl:

```bash
curl -s -X POST https://api.writavo.com/v1/comments \
  -H "Authorization: Bearer $WRITAVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "hello-world",
    "body": "Clear and useful, thank you.",
    "author_name": "Sam",
    "author_email": "sam@example.com",
    "reader_ip": "203.0.113.7"
  }'
```

201 response:

```json
{
  "ok": true,
  "data": {
    "id": "6a1d0c3e-0000-4000-8000-000000000003",
    "parent_id": null,
    "author_name": "Sam",
    "author_kind": "reader",
    "body": "Clear and useful, thank you.",
    "created_at": "2026-10-04T10:15:00Z",
    "status": "pending",
    "duplicate": false
  }
}
```

| Field | Required | Rules |
|---|---|---|
| `slug` | yes | A published article's slug. |
| `body` | yes | Plain text, 1 to 5,000 characters. |
| `author_name` | yes | 1 to 80 characters. Public. |
| `author_email` | when `require_email` is on | Valid, at most 254 characters. Never public. |
| `parent_id` | no | An approved comment on the same article. |
| `reader_ip` | no | The reader's IPv4 or IPv6 address. Anything else is a 422. |

- `status` is `pending` or `approved`, depending on the moderation mode.
- `duplicate: true`: the same reader sent this exact comment here in the last day. You get the first one back.

| Error | Meaning |
|---|---|
| `404 COMMENTS_DISABLED` | Comments are off for the Site. Hide the form. |
| `404 NOT_FOUND` | Not a published article on this Site. |
| `404 PARENT_NOT_FOUND` | `parent_id` is not an approved comment on that article. |
| `422 COMMENTS_CLOSED` | Past `close_after_days`. Comments are closed. |
| `422 VALIDATION_FAILED` | `error.fields` names the bad field. |
| `429 RATE_LIMIT_EXCEEDED` | `error.limit` is `reader`, `site` or `queue` (see [Limits](#limits)). Try later. |

Branch on error.code, not the status: there are three different 404s.

> reader_ip is never stored, only hashed under a daily salt for the per-reader limit and repeat check. Without it, all your comments share the Site-wide limit.

app/api/comments/route.ts (Next.js), the server side of your form:

```
export async function POST(req: Request) {
  const form = await req.json();
  const res = await fetch("https://api.writavo.com/v1/comments", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.WRITAVO_SECRET_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      slug: form.slug,
      body: form.body,
      author_name: form.author_name,
      author_email: form.author_email || undefined,
      parent_id: form.parent_id || undefined,

      reader_ip: req.headers.get("x-forwarded-for")?.split(",")[0]?.trim() || undefined,
    }),
  });
  const body = await res.json();

  return Response.json(body, { status: res.status });
}
```

## Rendering comments safely

- Render `body` and `author_name` as escaped plain text: in React `{comment.body}`, never `dangerouslySetInnerHTML`. Keep line breaks with `white-space: pre-line`.
- Give any links you create `rel="nofollow ugc"`.
- Show replies under their parent, and mark staff replies (`author_kind: staff`).

## The moderation API

Needs the Moderate comments permission (owners, admins and editors by default) and a secret key: comments:read to read, comments:write to change. Publishable keys cannot moderate, because the queue holds email addresses.

| Request | Scope | What it does |
|---|---|---|
| `GET /comments` | `comments:read` | The queue, newest first, with counts per status |
| `GET /comments/{id}` | `comments:read` | One comment, with its email and article |
| `PATCH /comments/{id}` | `comments:write` | Set `status`: `approved`, `spam` or `pending` |
| `DELETE /comments/{id}` | `comments:write` | Delete a comment and its replies |
| `POST /comments/{id}/replies` | `comments:write` | Reply as the Site's team |
| `GET /comments/settings` | `comments:read` | Read the settings |
| `PATCH /comments/settings` | `comments:write` | Change the settings |
| `POST /comments/erase` | `comments:write` | Delete everything one commenter wrote, by email |
| `POST /comments/import` | `comments:write` | Import comments (see below) |

the queue: comments waiting for review:

```bash
curl -s "https://api.writavo.com/v1/comments?status=pending&limit=50" \
  -H "Authorization: Bearer $WRITAVO_SECRET_KEY"
```

200 response:

```json
{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "6a1d0c3e-0000-4000-8000-000000000003",
        "parent_id": null,
        "author_name": "Sam",
        "author_kind": "reader",
        "body": "Clear and useful, thank you.",
        "created_at": "2026-10-04T10:15:00Z",
        "status": "pending",
        "author_email": "sam@example.com",
        "source": "api",
        "external_id": null,
        "article_id": "3f1b0c7a-0000-4000-8000-000000000001",
        "article_slug": "hello-world",
        "updated_at": "2026-10-04T10:15:00Z",
        "approved_at": null
      }
    ],
    "next_cursor": null,
    "counts": { "pending": 1, "approved": 41, "spam": 3 }
  }
}
```

Filters: status, slug, limit (1 to 100, default 50) and cursor. counts covers the whole Site. source is hosted, api, dashboard or import.

approve, mark as spam, reply, delete:

```
# approve (or "spam", or back to "pending")
curl -s -X PATCH https://api.writavo.com/v1/comments/6a1d0c3e-0000-4000-8000-000000000003 \
  -H "Authorization: Bearer $WRITAVO_SECRET_KEY" -H "Content-Type: application/json" \
  -d '{ "status": "approved" }'

# reply as the team (approves the comment too, if it was held)
curl -s -X POST https://api.writavo.com/v1/comments/6a1d0c3e-0000-4000-8000-000000000003/replies \
  -H "Authorization: Bearer $WRITAVO_SECRET_KEY" -H "Content-Type: application/json" \
  -d '{ "body": "Thanks, Sam. It does, once the page has loaded once.", "author_name": "The Example team" }'

# delete it, with any replies
curl -s -X DELETE https://api.writavo.com/v1/comments/6a1d0c3e-0000-4000-8000-000000000003 \
  -H "Authorization: Bearer $WRITAVO_SECRET_KEY"
```

- `PATCH` returns `200`, a reply `201`, `DELETE` `204`. An id from another Site is `404 NOT_FOUND`.
- A reply's `body` is 1 to 5,000 characters. `author_name` defaults to the key owner's name, else the Site's.
- Retrying a reply is safe: the same reply within 10 minutes returns the first one.
- Deleting is permanent. To hide a comment, set it back to `pending`.

## Import and export comments

The Site export (GET /export) includes comments in the import's row shape (skip them with?comments=false), so an export imports back as is. To import, call POST /comments/import from your server with a comments:write secret key and an Idempotency-Key header.

curl: a dry run of a comment and its reply:

```bash
curl -s -X POST https://api.writavo.com/v1/comments/import \
  -H "Authorization: Bearer $WRITAVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "comments": [
      {
        "external_id": "wp-comment:41",
        "post_external_id": "wp:12",
        "author_name": "Sam",
        "author_email": "sam@example.com",
        "body": "Thanks, the comparison table saved me a week.",
        "created_at": "2024-03-02T09:15:00Z"
      },
      {
        "external_id": "wp-comment:42",
        "post_external_id": "wp:12",
        "parent_external_id": "wp-comment:41",
        "author_name": "The Example team",
        "author_kind": "staff",
        "body": "Glad it helped.",
        "created_at": "2024-03-02T11:40:00Z"
      },
      {
        "external_id": "wp-comment:77",
        "post_slug": "an-article-that-was-never-imported",
        "status": "pending",
        "author_name": "Alex",
        "body": "Does this cover self-hosted options?",
        "created_at": "2025-11-20T18:02:11Z"
      }
    ]
  }'
```

200 response:

```json
{
  "ok": true,
  "data": {
    "dry_run": true,
    "written": { "created": 2, "updated": 0 },
    "problems": [
      {
        "index": 2,
        "external_id": "wp-comment:77",
        "problem": "no article on this Site with that post_slug"
      }
    ]
  }
}
```

Every import is a dry run until you send "dry_run": false (with a new Idempotency-Key). Fix the rows in problems first.

| Field | Required | Rules |
|---|---|---|
| `external_id` | yes | Its id in the old system: 1 to 255 printable ASCII characters, no spaces, unique on the Site. |
| `post_external_id` or `post_slug` | exactly one | The article, in any status. |
| `parent_external_id` | no | For a reply, the parent's `external_id`, imported earlier. |
| `status` | no | `approved` (default), `pending` or `spam`. |
| `author_name` | yes | 1 to 80 characters. |
| `author_email` | no | Never public; used for erasure. |
| `author_kind` | no | `reader` (default) or `staff`. |
| `body` | yes | Plain text, up to 20,000 characters. |
| `created_at` | yes | ISO 8601, 1990 to now. |

- Matched on `external_id`, so re-running updates and never duplicates.
- Parents must come before replies (an earlier call, or earlier in the same one) and be on the same article.
- At most 2,000 rows a call. Bad rows are listed in `problems` by `index`; the rest are written.
- Stored even while comments are off. No `comment.created` webhook fires.
- The WordPress import brings comments with the articles: approved, pending and spam from an export file, or approved only (no emails) from a live site. See [Move a blog to Writavo](/docs/migrate).

## Erasing a commenter (GDPR)

Deletes every comment on this Site with that email address (case-insensitive), and the replies under them.

curl:

```bash
curl -s -X POST https://api.writavo.com/v1/comments/erase \
  -H "Authorization: Bearer $WRITAVO_SECRET_KEY" -H "Content-Type: application/json" \
  -d '{ "author_email": "sam@example.com" }'
```

200 response:

```json
{ "ok": true, "data": { "deleted": 3 } }
```

deleted is 0 when nothing matched. The audit log keeps the count, never the address. Comments without an email must be deleted one by one.

## The comment.created webhook

Fires for every reader comment, approved or pending, but not for team replies or imports. Set-up is on the [Webhooks](/docs/webhooks) page.

- `data.id` is the comment id. Fetch it with `GET /comments/{id}` (`comments:read`) for its status, text and email.

## Limits

| Limit | Value |
|---|---|
| Comment and reply length | 5,000 characters (20,000 imported) |
| Rows in one import call | 2,000 |
| Name length | 80 characters |
| Comments from one reader | 5 per 10 minutes (needs `reader_ip` on the API, or a [reverse proxy](#reverse-proxy) that sends the reader's address; automatic on a hosted blog) |
| Comments on one Site | 300 per hour |
| Waiting for review | 2,000 per Site; new comments are refused until the queue is worked down |
| Marked as spam | deleted 30 days later |
| Shown per article | the first 1,000 approved |

A Site whose organisation is not active takes no comments. The usual API [rate limits](/docs/rate-limits) also apply.

## Privacy

- **Email addresses are never public.** Only moderators and `comments:read` keys see them.
- **IP addresses are never stored,** only a hash under a daily salt that is deleted the next day.
- **No cookies.** Erasure is one request by email; deletion is permanent.

## From an AI assistant (MCP)

Find comment actions with search_writavo_actions (for example "pending comments"); read with read_writavo_action, change with run_writavo_action. The connection needs the Reader comments row (Read, or Read and moderate to change), which is off unless the person chooses it, plus their own Moderate comments permission. They can add the row to an existing connection without signing in again.

At Read and moderate, import_content also brings comments when it moves a blog. Without it, comments are skipped; re-running later adds them without duplicating articles.

1. **Ask before turning comments on.** It changes the live blog. Send only what the person asked for.
2. **Moderate on instruction only.** Show the pending comments and act only on what the person says. Deleting is permanent.
3. **Never reveal an email address** beyond the person you are working for, and never in a public reply.
