crewAI/docs/edge/en/enterprise/integrations/notion.mdx

---
title: Notion Integration
description: "User management and commenting with Notion integration for CrewAI."
icon: "book"
mode: "wide"
---

## Overview

Enable your agents to manage users and create comments through Notion. Access workspace user information and create comments on pages and discussions, streamlining your collaboration workflows with AI-powered automation.

## Prerequisites

Before using the Notion integration, ensure you have:

- A [CrewAI AMP](https://app.crewai.com) account with an active subscription
- A Notion account with appropriate workspace permissions
- Connected your Notion account through the [Integrations page](https://app.crewai.com/crewai_plus/connectors)

## Setting Up Notion Integration

### 1. Connect Your Notion Account

1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)
2. Find **Notion** in the Authentication Integrations section
3. Click **Connect** and complete the OAuth flow
4. Grant the necessary permissions for user access and comment creation
5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations)

### 2. Install Required Package

```bash
uv add crewai-tools
```

### 3. Environment Variable Setup

<Note>
  To use integrations with `Agent(apps=[])`, you must set the
  `CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise
  Token.
</Note>

```bash
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
```

Or add it to your `.env` file:

```
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
```

## Available Actions

<AccordionGroup>
  <Accordion title="notion/list_users">
    **Description:** List all users in the workspace.

    **Parameters:**
    - `page_size` (integer, optional): Number of items returned in the response. Minimum: 1, Maximum: 100, Default: 100
    - `start_cursor` (string, optional): Cursor for pagination. Return results after this cursor.

  </Accordion>

  <Accordion title="notion/get_user">
    **Description:** Retrieve a specific user by ID.

    **Parameters:**
    - `user_id` (string, required): The ID of the user to retrieve.

  </Accordion>

  <Accordion title="notion/create_comment">
    **Description:** Create a comment on a page or discussion.

    **Parameters:**
    - `parent` (object, required): The parent page or discussion to comment on.
      ```json
      {
        "type": "page_id",
        "page_id": "PAGE_ID_HERE"
      }
      ```
      or
      ```json
      {
        "type": "discussion_id",
        "discussion_id": "DISCUSSION_ID_HERE"
      }
      ```
    - `rich_text` (array, required): The rich text content of the comment.
      ```json
      [
        {
          "type": "text",
          "text": {
            "content": "This is my comment text"
          }
        }
      ]
      ```

  </Accordion>
</AccordionGroup>

## Usage Examples

### Basic Notion Agent Setup

```python
from crewai import Agent, Task, Crew

# Create an agent with Notion capabilities
notion_agent = Agent(
    role="Workspace Manager",
    goal="Manage workspace users and facilitate collaboration through comments",
    backstory="An AI assistant specialized in user management and team collaboration.",
    apps=['notion']  # All Notion actions will be available
)

# Task to list workspace users
user_management_task = Task(
    description="List all users in the workspace and provide a summary of team members",
    agent=notion_agent,
    expected_output="Complete list of workspace users with their details"
)

# Run the task
crew = Crew(
    agents=[notion_agent],
    tasks=[user_management_task]
)

crew.kickoff()
```

### Filtering Specific Notion Tools

```python
comment_manager = Agent(
    role="Comment Manager",
    goal="Create and manage comments on Notion pages",
    backstory="An AI assistant that focuses on facilitating discussions through comments.",
    apps=['notion/create_comment']
)

# Task to create comments on pages
comment_task = Task(
    description="Create a summary comment on the project status page with key updates",
    agent=comment_manager,
    expected_output="Comment created successfully with project status updates"
)

crew = Crew(
    agents=[comment_manager],
    tasks=[comment_task]
)

crew.kickoff()
```

### User Information and Team Management

```python
from crewai import Agent, Task, Crew

team_coordinator = Agent(
    role="Team Coordinator",
    goal="Coordinate team activities and manage user information",
    backstory="An AI assistant that helps coordinate team activities and manages user information.",
    apps=['notion']
)

# Task to coordinate team activities
coordination_task = Task(
    description="""
    1. List all users in the workspace
    2. Get detailed information for specific team members
    3. Create comments on relevant pages to notify team members about updates
    """,
    agent=team_coordinator,
    expected_output="Team coordination completed with user information gathered and notifications sent"
)

crew = Crew(
    agents=[team_coordinator],
    tasks=[coordination_task]
)

crew.kickoff()
```

### Collaboration and Communication

```python
from crewai import Agent, Task, Crew

collaboration_facilitator = Agent(
    role="Collaboration Facilitator",
    goal="Facilitate team collaboration through comments and user management",
    backstory="An AI assistant that specializes in team collaboration and communication.",
    apps=['notion']
)

# Task to facilitate collaboration
collaboration_task = Task(
    description="""
    1. Identify active users in the workspace
    2. Create contextual comments on project pages to facilitate discussions
    3. Provide status updates and feedback through comments
    """,
    agent=collaboration_facilitator,
    expected_output="Collaboration facilitated with comments created and team members notified"
)

crew = Crew(
    agents=[collaboration_facilitator],
    tasks=[collaboration_task]
)

crew.kickoff()
```

### Automated Team Communication

```python
from crewai import Agent, Task, Crew

communication_automator = Agent(
    role="Communication Automator",
    goal="Automate team communication and user management workflows",
    backstory="An AI assistant that automates communication workflows and manages user interactions.",
    apps=['notion']
)

# Complex communication automation task
automation_task = Task(
    description="""
    1. List all workspace users and identify team roles
    2. Get specific user information for project stakeholders
    3. Create automated status update comments on key project pages
    4. Facilitate team communication through targeted comments
    """,
    agent=communication_automator,
    expected_output="Automated communication workflow completed with user management and comments"
)

crew = Crew(
    agents=[communication_automator],
    tasks=[automation_task]
)

crew.kickoff()
```

## Troubleshooting

### Common Issues

**Permission Errors**

- Ensure your Notion account has appropriate permissions to read user information
- Verify that the OAuth connection includes required scopes for user access and comment creation
- Check that you have permissions to comment on the target pages or discussions

**User Access Issues**

- Ensure you have workspace admin permissions to list all users
- Verify that user IDs are correct and users exist in the workspace
- Check that the workspace allows API access to user information

**Comment Creation Issues**

- Verify that page IDs or discussion IDs are correct and accessible
- Ensure that rich text content follows Notion's API format specifications
- Check that you have comment permissions on the target pages or discussions

**API Rate Limits**

- Be mindful of Notion's API rate limits when making multiple requests
- Implement appropriate delays between requests if needed
- Consider pagination for large user lists

**Parent Object Specification**

- Ensure parent object type is correctly specified (page_id or discussion_id)
- Verify that the parent page or discussion exists and is accessible
- Check that the parent object ID format is correct

### Getting Help

<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
  Contact our support team for assistance with Notion integration setup or
  troubleshooting.
</Card>