Working with comments

Overview

Comments exist on pages and blocks within Notion. Users may add comments to pages or add comments inline to text or other blocks. This guide will teach you how to interact with comments using the public API.

772772

A comment from an integration on a page.

Currently, integrations may interact with comments in the following ways:

  • Add a comment to a page.
  • Add a comment to an existing discussion thread.
  • Read comments on a block or page.

🚧

Limitations of the comments API

  • The API does not currently support the ability to create new comments/discussion threads on blocks.
  • You cannot update comments using the API.
  • You cannot retrieve resolved comments using the API.

Capabilities

To interact with comments in the public API, your integration must have configured the relevant comment capabilities. Additionally, the page to be commented on must have been shared with your integration.

There are currently two relevant capabilities: one for reading comments, and one for inserting comments. You can edit your integration's capabilities at https://notion.so/my-integrations. See our reference guide on Capabilities for more information.

928928

Configuring capabilities on the integration settings page.

Adding a comment to a page

You may add a top-level comment to a page by using the add comment to page endpoint and specifying a page parent and a rich text body.

curl -X POST https://api.notion.com/v1/comments \
  -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2022-06-28" \
  --data '
  {
    "parent": {
      "page_id": "59e3eb41-33b2-4151-b05b-31115a15e1c2"
    },
    "rich_text": [
      {
        "text": {
          "content": "Hello from my integration."
        }
      }
    ]
  }
  '
const { Client } = require('@notionhq/client');

const notion = new Client({ auth: process.env.NOTION_API_KEY });

(async () => {
  const response = await notion.comments.create({
    parent: {
      page_id: "59e3eb41-33b2-4151-b05b-31115a15e1c2"
    },
    rich_text: [
      {
        text: {
          content: "Hello from my integration.",
        },
      },
    ],
  });
  console.log(response);
})();

You'll receive the created comment object as the response. If your integration has write comment capabilities but not read comment capabilities, the response will be a partial object consisting of only the id and object fields.

The comment will be displayed on the page using your integration's name and icon.

Listing comments for a page or block

You may use the retrieve comments endpoint to list all un-resolved comments for a page or block. In both cases, you will use the block_id query parameter (since pages are blocks).

A flat list will always be returned, but some block types may support multiple discussion threads (i.e. commenting on different sections of a text block). In that case, comments from all discussion threads will be returned interleaved in ascending chronological order. You may distinguish between different threads by looking at the discussion_id field on the comment object.

curl 'https://api.notion.com/v1/comments?block_id=5c6a28216bb14a7eb6e1c50111515c3d'\
  -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
  -H "Notion-Version: 2022-06-28"
const { Client } = require('@notionhq/client');

const notion = new Client({ auth: process.env.NOTION_API_KEY });

(async () => {
  const blockId = 'd40e767c-d7af-4b18-a86d-55c61f1e39a4';
  const response = await notion.comments.list({ block_id: blockId });
  console.log(response);
})();

The response from this endpoint will by default return a maximum of 100 items. To retrieve further items, you will need to use pagination.

Responding to a discussion thread

You can also use the add comment to page endpoint to respond to a discussion thread on a block. In this form, you provide a discussion_id parameter instead of a parent parameter.

You can get a discussion ID from the response to the retrieve comments endpoint. If you want to get a discussion ID manually, click "Copy link to discussion" on any comment thread. This gives you a URL like https://notion.so/Something-something-a8d5215b89ae464b821ae2e2916ab9ce?d=5e73b63447c2428fa899e906b1f1d20e#b3e87b2b5e114cbd99f96288c22bacce. The value of the d query parameter is the discussion ID.

curl -X POST https://api.notion.com/v1/comments \
  -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2022-06-28" \
  --data '
  {
    "discussion_id": "59e3eb41-33b2-4151-b05b-31115a15e1c2",
    "rich_text": [
      {
        "text": {
          "content": "Hello from my integration."
        }
      }
    ]
  }
  '
const { Client } = require('@notionhq/client');

const notion = new Client({ auth: process.env.NOTION_API_KEY });

(async () => {
  const response = await notion.comments.create({
    discussion_id: "59e3eb41-33b2-4151-b05b-31115a15e1c2",
    rich_text: [
      {
        text: {
          content: "Hello from my integration.",
        },
      },
    ],
  });
  console.log(response);
})();

Conclusion

In this guide you learned how to interact with page and block-level comments using the Notion API. There are many potential use-cases for this type of interaction: you can comment on a task when a related pull request is merged, or periodically paste reminders to pages meeting certain criteria (after using the Query a database endpoint). We're excited to see what you come up with.

Next steps


Did this page help you?