Comments

Managing comments

All comments can be managed in the Dashboard, where you can approve, delete, or reply to them.

Each page has its own comments section, where you can manage comments specific to that page.

Additionally, each Author page has its own comments section, where you can manage comments specific to that author.

Pinned comments

Comments can be pinned by toggling the “star” icon on the Comment view. This will toggle the comment’s ‘pinned’ property, which can be sorted by via the API.

Displaying comments

To display comments on your site, send a GET request to the /comments endpoint with the following headers:

x-site-id: The site ID from the Dashboard.
x-slug: The page URL where the comments are being displayed, e.g., /blog/my-post.

The response will contain an array of approved comments, which you can render on your site.

Authors

An author is a user who has commented on your site. Each author has a unique ID, name, and email address, which can be used to identify them.

If an author does not exist, a new author will be created when they comment on your site. You can view all authors in the Dashboard.

External ID

You can assign an external ID to an author to link them to an existing user in your system. This can be useful for syncing comments with your user database.

Notifications

You can enable email notifications for new comments in the Site’s Settings

Via the API

List all comments

Get all comments related to a page. Ensure you have the x-site-id header set to the site ID.

By default, the API will return approved comments only. To get all comments, including those pending moderation, set the approved query parameter to all.

Request

GET /comments

Available query parameters

page_id - The id of the page to filter comments by (required)
page - The page number to return, defaults to 1
email - Filter comments by author email
approved - Filter comments by approval status

Response

{
  "data": [
    {
      "id": "01j544f16bqp0mz5jmsmd1enav",
      "created_at": "2024-08-12T20:28:52.000000Z",
      "updated_at": "2024-08-13T19:09:57.000000Z",
      "content": "Wow, this is great!",
      "approved": true,
      "author_name": "Tim Apple",
      "author_email": "[email protected]",
      "site_id": "01j509cg4wwxtdtef3xws5kgf2",
      "page_id": "01j5414d4evrdg48brxz3jbhjq",
      "parent_id": null,
      "team_id": "01j4sjct8ps0dntdjthexpqwxh",
      "order": 0,
      "children": []
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 1
  }
}

Get a comment

Get a single comment by ID, ensure you have the x-site-id header set to the site ID.

Request

GET /comments/:id

Response

{
  "id": "01j544f16bqp0mz5jmsmd1enav",
  "created_at": "2024-08-12T20:28:52.000000Z",
  "updated_at": "2024-08-13T19:09:57.000000Z",
  "content": "Wow, this is great!",
  "approved": true,
  "author_name": "Tim Apple",
  "author_email": "[email protected]",
  "site_id": "01j509cg4wwxtdtef3xws5kgf2",
  "page_id": "01j5414d4evrdg48brxz3jbhjq",
  "parent_id": null,
  "team_id": "01j4sjct8ps0dntdjthexpqwxh",
  "order": 0,
  "children": []
}

Update a comment

Update a comment’s approved status, ensure you have the x-site-id header set to the site ID.

Request

PUT /comments/:id

{
  "approved": true
}

Response

{
  "id": "01j544f16bqp0mz5jmsmd1enav",
  "created_at": "2024-08-12T20:28:52.000000Z",
  "updated_at": "2024-08-13T19:09:57.000000Z",
  "content": "Wow, this is great!",
  "approved": true,
  "author_name": "Tim Apple",
  "author_email": "[email protected]",
  "site_id": "01j509cg4wwxtdtef3xws5kgf2",
  "page_id": "01j5414d4evrdg48brxz3jbhjq",
  "parent_id": null,
  "team_id": "01j4sjct8ps0dntdjthexpqwxh",
  "order": 0,
  "children": []
}

Delete a comment

Delete a comment by ID, ensure you have the x-site-id header set to the site ID.

Request

DELETE /comments/:id

Response

{
  "id": "01j544f16bqp0mz5jmsmd1enav",
  "message": "Comment deleted successfully"
}

Create a comment

Create a new comment, ensure you have the x-site-id, x-title and x-slug headers.

x-site-id: The site ID from the Dashboard.
x-title: The title of the page where the comments are being displayed, e.g., “My Blog Post”.
x-slug: The page URL where the comments are being displayed, e.g., /blog/my-post.

If a page with the specified title and slug does not exist, a new page will be created automatically.

Request

POST /comments

{
  "content": "Wow, this is great!",
  "author_name": "Tim Apple",
  "author_email": "[email protected]"
}

Optional fields:

{
  "parent_id": "123", // The ID of the parent comment if this is a reply
  "external_id": "456", // An external ID to link this comment to a user in your system
  "external_source": "my-app" // The source of the external ID
}

Including a parent_id will create a reply to an existing comment. If the existing comment has a parent itself, the reply will be automatically nested to the parent’s level, keeping the thread to one level deep.