> ## Documentation Index
> Fetch the complete documentation index at: https://botpress.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Notion

> Add a bot to Notion using the official integration.

{/* vale on */}

[Open in Hub](https://studio.botpress.cloud/home?exploreHub=1\&hubItemId=intver_01KN89RW8Z2ZK98F8JM8X66RXS)
*v3.0.5*

The Notion Integration with Botpress enables seamless integration to boost productivity, allowing interactions such as commenting on discussions or pages and database manipulations right from your Botpress bot.

## Setup

> [tab] Basic configuration
>
> > [!NOTE]
> >
> > You will need:
> >
> > * A [published bot](https://botpress.com/docs/get-started/quick-start.md)
> > * A [Notion account](https://www.notion.so/signup) and [workspace](https://www.notion.so/onboarding)
>
> **Step 1**
>
> In Botpress Studio, select **Explore Hub** in the upper-right corner.
>
> **Step 2**
>
> Search for the **Notion** integration, then select **Install Integration**.
>
> **Step 3**
>
> In the **Configuration** menu, select **Authorize Notion**.
>
> **Step 4**
>
> Follow the instructions to connect Botpress to your Notion account.

> [tab] Manual configuration
>
> For advanced use cases, you can configure the integration manually using a Notion integration token.
>
> > [!NOTE]
> >
> > You will need:
> >
> > * A [published bot](https://botpress.com/docs/get-started/quick-start.md)
> > * A [Notion account](https://www.notion.so/signup) and [workspace](https://www.notion.so/onboarding)
>
> ### Step 1: Install the integration in Botpress
>
> **Step 1**
>
> In Botpress Studio, select **Explore Hub** in the upper-right corner.
>
> **Step 2**
>
> Search for the **Notion** integration, then select **Install Integration**.
>
> **Step 3**
>
> In the **Configuration** menu, select the drop-down and choose **Configure the integration using a Notion integration token**.
>
> **Step 4**
>
> You should see two fields:
>
> * **Internal Integration Secret**
> * **Webhook Verification Secret**
>
> Leave these empty for now—you'll come back to them after setting up the integration in Notion.
>
> ### Step 2: Create an integration in Notion
>
> Next, create a corresponding integration in Notion:
>
> **Step 1**
>
> Go to your [integrations page](https://www.notion.so/profile/integrations) in Notion.
>
> **Step 2**
>
> Select **New integration**.
>
> **Step 3**
>
> Enter an **Integration Name** and **Associated workspace** for the integration. Then, select **Save**.
>
> **Step 4**
>
> Select **Configure integration settings**.
>
> **Step 5**
>
> Under **Internal Integration Secret**, select **Show**, then **Copy**.
>
> **Step 6**
>
> Go back to the integration's configuration menu in Botpress. Then, paste the secret into the **Internal Integration Secret**.
>
> **Step 7**
>
> Select **Save Configuration**.
>
> ### Step 3: Give access to pages and databases
>
> For your bot to interact with your Notion workspace, you need to manually specify which pages and databases it has access to:
>
> **Step 1**
>
> In your Notion integration's settings, go to the **Access** tab.
>
> **Step 2**
>
> Select **Edit access**.
>
> **Step 3**
>
> Select the pages you want your bot to have access to. Then, select **Save**.
>
> ### Step 4: Configure webhook events (optional)
>
> If you want to use the integration's [Triggers](#triggers) and have your bot respond to events in your Notion workspace, follow the steps below:
>
> **Step 1**
>
> In the integration's configuration menu in Botpress, copy the webhook URL (starting with `https://webhook.botpress.cloud/`).
>
> **Step 2**
>
> In your Notion integration's settings, go to the **Webhooks** tab. Then, select **+ Create a subscription**.
>
> **Step 3**
>
> Paste the webhook URL you copied in the **Webhook URL** field.
>
> **Step 4**
>
> Under **Select the events to listen to**, select the following events:
>
> * **Page created**
> * **Page deleted**
> * **Comment created**
>
> **Step 5**
>
> Scroll down to the bottom of the page and select **Verify**.
>
> **Step 6**
>
> In Botpress, go to your bot's most recent [logs](https://botpress.com/docs/get-started/manage-your-agent/inspect.md#logs). Copy the verification token sent from Notion.
>
> **Step 7**
>
> Go back to your Notion integration and paste the token in the **Verification token** field.
>
> **Step 8**
>
> Select **Verify subscription**.
>
> **Step 9**
>
> Finally, go back to the integration's **Configuration** menu in Botpress. Paste the verification token into the **Webhook Verification Secret** field.

> [!TIP]
>
> Your Notion integration is ready to use. You can use the integration's [Cards](#cards) or [Triggers](#triggers) to interact with your Notion workspace.

***

## Cards

> [!NOTE]
>
> To use certain Cards, you might need to identify elements by their IDs. You can get page and database IDs:
>
> * From their URL while viewing them in your browser
> * By choosing **Copy Link** from their options menu

{/* vale off */}

Here's a reference for all [Cards](https://botpress.com/docs/studio/concepts/cards/introduction.md) available with the integration:

### Add Comment

Add a comment to a page, block, or discussion in Notion

**input** `object`

**parentType** `enum\<string\>` *required*

The type of the parent

Available options: `page`, `block`, `discussion`

**parentId** `string` *required*

The ID of the parent to add the comment to. Can be found in the URL of the parent

**commentBody** `string` *required*

Must be plain text

**output** `object`

**commentId** `string` *required*

The ID of the comment that was created

**discussionId** `string`

The ID of the discussion that was created

### Append Blocks to Page

Append a markdown text to a page in Notion. The markdown text will be converted to notion blocks.

**input** `object`

**pageId** `string` *required*

The ID of the page to append the blocks to. Can be found in the URL of the page

**markdownText** `string` *required*

The markdown text to append to the page

**output** `object`

**pageId** `string` *required*

The ID of the page where blocks were appended

**blockIds** `array` *required*

The IDs of the blocks that were created

### Create Page

Create a new page in Notion

**input** `object`

**parentType** `enum\<string\>` *required*

The type of the parent

Available options: `data source`, `page`

**parentId** `string` *required*

The ID of the parent to add the page to. Can be found in the URL of the parent

**title** `string` *required*

The title of the page

**dataSourceTitleName** `string` (default: Name)

The name of the title property in the data source. If not provided, the default is "Name".

**output** `object`

**pageId** `string` *required*

The ID of the page that was created

### Delete Block

Delete a block in Notion

**input** `object`

**blockId** `string` *required*

The ID of the block to delete. Can be found in the URL of the block

**output** `object`

**blockId** `string` *required*

The ID of the block that was deleted

### Get Data Source

Get a data source from Notion

**input** `object`

**dataSourceId** `string` *required*

The ID of the data source to fetch. Can be found in the URL of the data source

**output** `object`

**object** `string` *required*

A stringified representation of the data source

**properties** `object` *required*

Schema of properties for the data source as they appear in Notion

**pages** `array` *required*

List of pages in the data source

**array item properties**

**id** `string` *required*

The ID of the page

**title** `string` *required*

The title of the page

**pageProperties** `object` *required*

Schema of properties for the page as they appear in Notion

### Get Database

Get a database from Notion

**input** `object`

**databaseId** `string` *required*

The ID of the database to fetch. Can be found in the URL of the database

**output** `object`

**object** `string`

The type of object returned

**dataSources** `array` *required*

List of data sources in the database

**array item properties**

**id** `string` *required*

The ID of the data source

**name** `string` *required*

The name of the data source

### Get Page

Get a page from Notion

**input** `object`

**pageId** `string` *required*

The ID of the page to fetch. Can be found in the URL of the page

**output** `object`

**object** `string`

The type of object returned

**id** `string`

The ID of the object returned

**created\_time** `string`

The time the object was created

**parent** `object`

The parent of the object

**created\_by** `object`

The user who created the object

**object** `string`

The type of object returned

**id** `string`

The ID of the object returned

**archived** `boolean`

Whether the object is archived

**properties** `object`

Schema of properties for the page as they appear in Notion

### Get Page Content

Get the content blocks of a page or block in Notion

**input** `object`

**pageId** `string` *required*

The ID of the page or block to fetch content from. Can be found in the URL

**output** `object`

**blocks** `array` *required*

Array of content blocks from the page

**array item properties**

**blockId** `string` *required*

The unique ID of the block

**parentId** `string`

The ID of the parent page or block

**type** `string` *required*

The type of the block (paragraph, heading\_1, etc.)

**hasChildren** `boolean` *required*

Whether the block has nested child blocks

**richText** `array` *required*

The rich text content of the block with formatting information

### Search by Title

Search for pages and databases in Notion. Optionally filter by title. Only returns items that have been shared with the integration.

**input** `object`

**title** `string`

Optional search query to match against page and database titles. If not provided, returns all accessible pages and databases.

**output** `object`

**results** `array` *required*

Array of pages and databases matching the search query

**array item properties**

**id** `string` *required*

The ID of the page or database

**title** `string` *required*

The title of the page or database

**type** `string` *required*

The type of the result (page or database)

**url** `string` *required*

The URL to the page or database

### Update Page Properties

Update one or more properties on a Notion page using raw Notion properties JSON

**input** `object`

**pageId** `string` *required*

The ID of the page to update. Can be found in the page URL

**propertiesJson** `string` *required*

Stringified JSON object for the Notion properties payload (same format as Notion pages.update API endpoint but without the "properties" key). Check the Notion API documentation for the correct format. [https://developers.notion.com/reference/patch-page](https://developers.notion.com/reference/patch-page)

**output** `object`

**pageId** `string` *required*

The updated page ID

***

## Triggers

{/* vale off */}

Here's a reference for all [Triggers](https://botpress.com/docs/studio/concepts/triggers.md) available with the integration:

> [!TIP]
>
> You can access data returned from any of these Triggers by reading `event.payload` after the Trigger fires.

### Aggregate File Changes

**payload** `object`

**modifiedItems** `object` *required*

The modified items

**created** `array` *required*

The files created

**array item properties**

**id** `string` *required*

The file's ID. This could be a unique identifier from the external service, or a relative or absolute path, so long as it's unique.

**type** `string` *required*

**name** `string` *required*

The file's name. This will be displayed in the Botpress UI and be used as the file's name on Files API."

**parentId** `string`

The parent folder ID. Leave empty if the file is in the root folder.

**absolutePath** `string` *required*

The full path of the file

**sizeInBytes** `number`

The file size in bytes, if available

**lastModifiedDate** `string (date-time)`

The last modified date of the file, if available

**contentHash** `string`

The hash of the file content, or version/revision number, if available

**updated** `array` *required*

The files updated

**array item properties**

**id** `string` *required*

The file's ID. This could be a unique identifier from the external service, or a relative or absolute path, so long as it's unique.

**type** `string` *required*

**name** `string` *required*

The file's name. This will be displayed in the Botpress UI and be used as the file's name on Files API."

**parentId** `string`

The parent folder ID. Leave empty if the file is in the root folder.

**absolutePath** `string` *required*

The full path of the file

**sizeInBytes** `number`

The file size in bytes, if available

**lastModifiedDate** `string (date-time)`

The last modified date of the file, if available

**contentHash** `string`

The hash of the file content, or version/revision number, if available

**deleted** `array` *required*

The files and folders deleted

> [tab] file
>
> **id** `string` *required*
>
> The file's ID. This could be a unique identifier from the external service, or a relative or absolute path, so long as it's unique.
>
> **type** `string` *required*
>
> **name** `string` *required*
>
> The file's name. This will be displayed in the Botpress UI and be used as the file's name on Files API."
>
> **parentId** `string`
>
> The parent folder ID. Leave empty if the file is in the root folder.
>
> **absolutePath** `string` *required*
>
> The full path of the file
>
> **sizeInBytes** `number`
>
> The file size in bytes, if available
>
> **lastModifiedDate** `string (date-time)`
>
> The last modified date of the file, if available
>
> **contentHash** `string`
>
> The hash of the file content, or version/revision number, if available

> [tab] folder
>
> **id** `string` *required*
>
> The folder's ID. This could be a unique identifier from the external service, or a relative or absolute path, so long as it's unique.
>
> **type** `string` *required*
>
> **name** `string` *required*
>
> The folder's name. This will be displayed in the Botpress UI and be used as the folder's name on Files API."
>
> **parentId** `string`
>
> The parent folder ID. Leave empty if the folder is in the root folder.
>
> **absolutePath** `string` *required*
>
> The full path of the folder

### Comment Created

A comment was created in Notion

**payload** `object`

**workspace\_id** `string` *required*

The ID of the Notion workspace

**type** `string` *required*

The type of event

**entity** `object` *required*

The entity that the event is related to

**type** `string` *required*

The type of entity (comment)

**id** `string` *required*

The ID of the entity

**data** `object` *required*

Additional data about the event

**page\_id** `string` *required*

The ID of the page the comment was created on

**workspace\_name** `string` *required*

The name of the Notion workspace

### File Created

**payload** `object`

**file** `object` *required*

The created file

**id** `string` *required*

The file's ID. This could be a unique identifier from the external service, or a relative or absolute path, so long as it's unique.

**type** `string` *required*

**name** `string` *required*

The file's name. This will be displayed in the Botpress UI and be used as the file's name on Files API."

**parentId** `string`

The parent folder ID. Leave empty if the file is in the root folder.

**absolutePath** `string` *required*

The full path of the file

**sizeInBytes** `number`

The file size in bytes, if available

**lastModifiedDate** `string (date-time)`

The last modified date of the file, if available

**contentHash** `string`

The hash of the file content, or version/revision number, if available

### File Deleted

**payload** `object`

**file** `object` *required*

The deleted file

**id** `string` *required*

The file's ID. This could be a unique identifier from the external service, or a relative or absolute path, so long as it's unique.

**type** `string` *required*

**name** `string` *required*

The file's name. This will be displayed in the Botpress UI and be used as the file's name on Files API."

**parentId** `string`

The parent folder ID. Leave empty if the file is in the root folder.

**absolutePath** `string` *required*

The full path of the file

**sizeInBytes** `number`

The file size in bytes, if available

**lastModifiedDate** `string (date-time)`

The last modified date of the file, if available

**contentHash** `string`

The hash of the file content, or version/revision number, if available

### File Updated

**payload** `object`

**file** `object` *required*

The updated file

**id** `string` *required*

The file's ID. This could be a unique identifier from the external service, or a relative or absolute path, so long as it's unique.

**type** `string` *required*

**name** `string` *required*

The file's name. This will be displayed in the Botpress UI and be used as the file's name on Files API."

**parentId** `string`

The parent folder ID. Leave empty if the file is in the root folder.

**absolutePath** `string` *required*

The full path of the file

**sizeInBytes** `number`

The file size in bytes, if available

**lastModifiedDate** `string (date-time)`

The last modified date of the file, if available

**contentHash** `string`

The hash of the file content, or version/revision number, if available

### Folder Deleted Recursive

**payload** `object`

**folder** `object` *required*

The deleted folder

**id** `string` *required*

The folder's ID. This could be a unique identifier from the external service, or a relative or absolute path, so long as it's unique.

**type** `string` *required*

**name** `string` *required*

The folder's name. This will be displayed in the Botpress UI and be used as the folder's name on Files API."

**parentId** `string`

The parent folder ID. Leave empty if the folder is in the root folder.

**absolutePath** `string` *required*

The full path of the folder


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.