# Comments

People who open a page can **pin a comment** to the words, chart or image it's about. Everyone who can open the page sees every comment and reply. It works on any page: there's nothing to add to your HTML.

For a comment box your own page draws and controls, use [entries](/docs/entries.md) instead.

## At a glance

| | |
| --- | --- |
| **On for pages that aren't public** | A new page that's shared with your team, with named people or behind a password starts with comments on. Public pages start with them off. Changing who can open a page later doesn't change it |
| **Turn on or off per page** | On the page itself: your team presses the DocPin badge, then **Turn on comments**. Or **Ask for comments** on the page's Overview tab in the app, `PATCH /v1/pages/{id}` with `{"comments": true}`, or the MCP tool `request_feedback`. **Settings → New pages** can turn them on for new public pages too |
| **Who can comment** | Anyone who can open the page. People who aren't signed in comment with just a name |
| **Who can read** | Anyone who can open the page |
| **Where they show** | Behind the DocPin badge at the bottom of the page. Press it to show pins and the comments panel, press it again to put them away |
| **New versions** | Comments carry over and stay pinned to the same words |
| **Email** | The person who published the page gets one email per page when new comments stop arriving for 10 minutes. So does anyone with a confirmed email who has written in the thread |
| **AI apps** | `get_artifact_comments`, `comment_on_artifact`, `reply_to_comment`, `resolve_comment`. See [MCP](/docs/mcp.md#comments) |

## What people see

- **Comments closed:** a clean page. The badge shows how many comments are open.
- **Comments open:** pins on the page (a red pushpin on a chart or image, a highlight with a small numbered chip on words), and a panel with two tabs. **Discussion** lists the threads. **Activity** lists every comment and reply, newest first, with a line where each new version was published.
- **To comment:** select some text and press **Pin a comment**, or press **Pin a comment** in the panel and click the spot you mean (a chart, an image, anything). The page keeps working while comments are open: only that one click is taken.
- **Reactions:** open a thread, point at a comment and press the smiley to react with 👍 ❤️ 😂 🎉 🤔 or 👀. Press a reaction again to take yours back. Hover over one to see who reacted. Reactions don't send email.
- **Resolving:** the person who started a thread, or anyone on your team, presses **Resolve** at the top of the thread. It moves to **Resolved** at the end of the list, and **Undo** shows for a few seconds.
- **Links:** each thread has **Copy link**. The link opens the page on that thread, and so do the links in emails.

## Who can do what

| | Guest (a name, not signed in) | Signed-in viewer | Workspace member |
| --- | --- | --- | --- |
| Read, comment, reply, react | Yes | Yes | Yes |
| Edit or delete their own | Yes, from the same browser | Yes | Yes |
| Resolve or reopen | Threads they started | Threads they started | Any |
| Delete any comment | No | No | Yes |

- Members' comments carry a tag with your workspace's name, so a guest can't pass as your team by typing its name.
- A guest's name isn't checked. On password and people-only pages, guests are limited to people you gave access to.
- Guests can press **Get replies by email** to confirm an email with Google or a 6-digit code. Their earlier comments on that page move to that email.
- Other viewers never see emails: signed-in people show as the part of their email before the @.

## When the page changes

A pin remembers the words it was put on and a few words either side. A pin on a chart or image remembers which element it was on (by its label and the heading above it) and how far across and down it sat.

| The new version | What the pin does |
| --- | --- |
| Has the same words | Stays |
| Changed the words a little | Moves to them, and the thread says the words changed |
| Removed the words | The thread stays in the list under **Pinned to an earlier version**, with the words it was pinned to |
| Redrew the chart | Stays at the same spot on it. The thread says which version it was made on |

Give charts and images a label (`aria-label`, `alt`, or a `<figcaption>`) and pins on them hold on better across versions.

Text inside a closed tab or accordion can't show a pin. If your page keeps that state in the URL (`?tab=pricing`, `#faq`), clicking the thread reopens it. See [How pages run](/docs/page-runtime.md).

## Privacy and safety

- Your page's own scripts never see comments, names or emails. They can only learn where pins sit.
- Comments are plain text. Links are clickable; HTML isn't run.
- Turning comments off hides them and keeps them. Deleting a page deletes its comments.
- Drafts, archived pages and version previews don't take comments.

## For your workspace

| | |
| --- | --- |
| **App** | The page's Overview tab turns comments on and off and shows how many are open. Read and answer them on the page itself |
| **REST API** | [`/v1/pages/{id}/comments`](/docs/api.md#comments) |
| **MCP** | [Comment tools](/docs/mcp.md#comments) |

## Limits

| Limit | Value |
| --- | --- |
| One comment | 4,000 characters |
| Threads on a page | 1,000 |
| Comments in a thread | 200 |
| Reactions on a comment | 200 |
| A signed-in person | 30 comments a minute per page |
| A guest | 10 a minute and 60 a day per page |

Reactions count toward the per-minute limits, not the guest's 60 a day.