A RetroSearch Logo

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Search Query:

Showing content from https://developers.notion.com/docs/working-with-comments below:

Working with comments

Notion offers the ability for developers to add comments to pages and page content (i.e. blocks) within a workspace. Users may add comments:

📘

When using the public API, inline comments can be used to respond to existing discussions.

The Notion UI with a page and inline/block comment added.

This guide will review how to use the public REST API to add and retrieve comments on a page. It will also look at considerations specific to integrations when retrieving or adding comments.

Before discussing how to use the public REST API to interact with comments, let’s first review who can comment on a page. Notion relies on a tiered system for page permissions, which can vary between: 

When using the Notion UI, users must have Can comment access or higher (i.e. less restricted) to add comments to a page.

Integrations must also have comment permissions, which can be set in the Integrations dashboard.

📘

Integrations are apps developers build to use the public API within a Notion workspace. Integrations must be given explicit permissions to read/write content in a workspace, included content related to comments.

To give your integration permission to interact with comments via the public REST API, you need to configure the integration to have comment capabilities.

There are two relevant capabilities when it comes to comments — the ability to:

  1. Read comments.
  2. Write (or insert) comments.

You can edit your integration's capabilities in the Integrations dashboard. If these capabilities are not added to your integration, REST API requests related to comments will respond with an error.

Configuring capabilities on the integration settings page.

See our reference guide on Capabilities for more information.

In the Notion UI, users can:

✅ Using the public REST API, integrations can:

❌ When using the public REST API, integrations cannot:

👍

Keep an eye on our Changelog for new features and updates to the REST API.

The Retrieve comments endpoint can be used to list all open (or “un-resolved”) comments for a page or block. Whether you’re retrieving comments for a page or block, the block_id query parameter is used. This is because pages are technically blocks.

This endpoint returns a flatlist of comments associated with the ID provided; however, some block types may support multiple discussion threads. This means there may be multiple discussion threads included in the response. When this is the case, comments from all discussion threads will be returned in ascending chronological order. The threads can be distinguished by sorting them discussion_id field on each 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);
})();

By default, the response from this endpoint will return a maximum of 100 items. To retrieve additional items, you will need to use pagination.

You can add a top-level comment to a page by using the Add comment to page endpoint. Requests made to this endpoint require the ID for the parent page, as well as a rich text body (i.e. the comment content).

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);
})();

The response will contain the new comment object.

The exception to what will be returned occurs if your integration has “write comment” capabilities but not “read comment” capabilities. In this situation, the response will be a partial object consisting of only the id and object fields. This is because the integration can create new comments but can’t retrieve comments, even if the retrieval is just the response for the newly created one. (Reminder: You can update the read/write settings in the Integrations dashboard.)

In the Notion UI, this new comment will be displayed on the page using your integration's name and icon.

The Add comment to page endpoint can also be used to respond to a discussion thread on a block. (Reminder: Page blocks are the child elements that make up the page content, like a paragraph, header, to-do list, etc.)

If you’re using this endpoint to respond to a discussion, you will need to provide a discussion_id parameter instead of a parent.page_id.

📘

Inline comments cannot be directly added to blocks to start a new discussion using the public API. Currently, the API can only be used to respond to inline comments (discussions).

The are two possible ways to get the discussion_id for a discussion thread.

  1. You can use the Retrieve comments endpoint, which will return a list of open comments on the page or block.
  2. You can also get a discussion_id manually by navigating to the page with the discussion you’re responding to. Next, click the "Copy link to discussion" menu option next to the discussion.

"Copy link to discussion" menu option in Notion UI.

This will give you a URL like:

https://notion.so/Something-something-a8d5215b89ae464b821ae2e2916ab9ce?d=5e73b63447c2428fa899e906b1f1d20e#b3e87b2b5e114cbd99f96288c22bacce

The value of the d query parameter is the discussion_id.

Once you have the discussion_id, you can make a request to respond to the thread like so:

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": "8fa6e3ecbebf494b94bae5e9737842fb"
    "rich_text": [
      {
        "text": {
          "content": "Hello world"
        }
      }
    ]
	});
  
  console.log(response);
})();

In this guide, you learned about comment permissions and how to interact with page and block-level comments using Notion’s public REST API. There are many potential use-cases for this type of interaction, such as:

Updated almost 2 years ago

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4