Use Notion as Your AI Knowledge Base: Complete Playbook

This guide connects your ABC Salesbot AI Agent to your company's Notion workspace, allowing team members to ask questions on WhatsApp and get answers straight from your SOPs, policies, and documentation.

1. Overview

Use Cases

• Company info: "What is our company mission?"
• HR policies: "How many days leave do I get?"
• SOPs: "How do I onboard a new client?"
• Guidelines: "What's the expense claim limit?"

Requirements

• ABC Salesbot account with AI Agent access
• Notion workspace with admin permissions
• Documentation already in Notion

Time Required

About 30 minutes to set up.

2. Architecture

How It Works

A team member asks a question, your AI Agent calls two custom tools against the Notion API, then replies with the answer plus a link to the source page:

1. Team member asks a question in chat
2. The AI Agent searches Notion for matching pages
3. The AI Agent fetches the content of the best-matching page
4. The AI Agent answers with the actual content and the Notion link

Two-Tool Workflow

The Notion API requires TWO separate calls:

• Step 1, query_notion_pages: searches Notion and returns page titles and IDs
• Step 2, get_notion_page_content: fetches the actual content from a specific page

Why two tools? Notion's search API only returns page metadata (titles, IDs), not the actual content inside pages. We need a second call to fetch the content.

3. Step 1: Create a Notion Integration

3.1 Go to Notion Integrations

• Open https://www.notion.so/my-integrations
• Click + New integration

3.2 Configure the Integration

• Name: ABC Salesbot (or your preferred name)
• Logo: Optional, upload your company logo
• Associated workspace: Select your company workspace

3.3 Set Capabilities

Under Content Capabilities, enable:

• Read content (required)

Under Comment Capabilities:

• Read comments (optional)

3.4 Save and Copy the Secret

1. Click Save
2. Click Show next to Internal Integration Secret
3. Copy the Internal Integration Secret
4. Save it somewhere safe, you'll need it for ABC Salesbot

3.5 Configure Access to Pages

Critical step! Your integration can ONLY access pages you explicitly grant access to.

1. In your integration settings, click the Access tab
2. You'll see options to select which pages or workspace the integration can access
3. Select the pages you want the AI to be able to read: you can grant access to specific pages, or grant access to your entire workspace
4. Click Save or Update to confirm

Tip: if you grant access to a parent page, all child pages underneath are also accessible.

Recommended structure: keep everything under one top-level page, for example a Company Knowledge Base page containing child pages such as:

• Mission, Vision & Values
• Company Goals
• HR Policies: Leave Policy, Expense Claims, Code of Conduct
• SOPs: Client Onboarding, Support Process, Sales Process
• Technical Docs: Product Setup, Troubleshooting

Grant access to the top-level "Company Knowledge Base" page, and all child pages inside become accessible.

4. Step 2: Create Custom Tools in ABC Salesbot

You need to create TWO custom tools.

Tool 1: query_notion_pages

This tool searches your Notion workspace.

Info tab:

• Name: query_notion_pages
• Description: Search the company Notion knowledge base for relevant pages. Returns page titles and IDs. After searching, you MUST use get_notion_page_content to fetch the actual content.
• Method: POST
• URL: https://api.notion.com/v1/search
• Enabled: On
• Crawl page: Off

Configurations tab:

• Username: leave empty
• Password: leave empty
• API Key: leave empty
• Bearer Token: paste your Notion Integration Secret

Custom Headers (click "Add Header" for each):

• Notion-Version: 2022-06-28
• Content-Type: application/json

Parameters tab (click "Add Params" and fill in):

• Name: query
• Description: The search keywords to find relevant Notion pages
• Type: string
• Default: leave empty
• Location: body
• Required: On

Click Save.

Tool 2: get_notion_page_content

This tool fetches the actual content from a page.

Info tab:

• Name: get_notion_page_content
• Description: Retrieve the full content of a Notion page using its page ID. ALWAYS use this after query_notion_pages to get the actual text content before answering the user.
• Method: GET
• URL: https://api.notion.com/v1/blocks/{page_id}/children
• Enabled: On
• Crawl page: Off

Configurations tab:

• Username: leave empty
• Password: leave empty
• API Key: leave empty
• Bearer Token: paste your Notion Integration Secret (same as Tool 1)

Custom Headers (click "Add Header"):

• Notion-Version: 2022-06-28

Parameters tab (click "Add Params" and fill in):

• Name: page_id
• Description: The Notion page ID from search results (the "id" field)
• Type: string
• Default: leave empty
• Location: path
• Required: On

Click Save.

Important: Double-Check After Saving

After saving both tools, go back and verify that the custom headers were saved correctly on both Tool 1 and Tool 2. There may be a bug where headers don't save properly the first time. Check:

• Tool 1: Notion-Version and Content-Type headers are still there
• Tool 2: Notion-Version header is still there

If they're missing, add them again and save.

5. Step 3: Configure the System Prompt

Copy the full system prompt from the Appendix at the end of this guide and paste it into your AI Agent's System Prompt field.

Key Sections in the System Prompt

• Identity & Purpose: tells the AI who it is and what it does
• Two-Tool Workflow: critical instructions to use BOTH tools
• Terminology Translation: maps casual language to business terms
• Search Strategy: how to search effectively
• Escalation Guidelines: when to direct to manager, HR, and so on
• Response Format: how to structure answers
• Sample Interactions: examples of good responses

Customization Checklist

Before using, update these sections:

• Terminology Translation: add your company-specific terms
• Escalation contacts: update department names and contacts
• Sample interactions: add examples relevant to your docs

6. Step 4: Testing

Run these tests to verify everything works.

Test 1: Basic Search

Ask: "What is our company mission?"

Expected behavior:

• AI calls query_notion_pages with "mission vision"
• AI extracts the page_id from the results
• AI calls get_notion_page_content with that page_id
• AI responds with the actual mission statement plus the Notion link

Test 2: Policy Question

Ask: "How many days annual leave do I get?"

Expected behavior:

• AI searches for leave-related pages
• AI fetches the content
• AI gives a specific answer with a link

Test 3: Terminology Translation

Ask: "What's my commission?" (when your docs say "fees")

Expected behavior:

• AI translates "commission" to "fees"
• AI finds and returns the relevant content

Test 4: Not Found

Ask: "What's the pet policy?" (assuming this doesn't exist)

Expected behavior:

• AI searches, finds nothing
• AI honestly says it was not found
• AI suggests alternatives (ask manager, HR)

Success Criteria

• AI calls both tools
• AI gives actual content, not just page titles
• AI includes the Notion link in the response
• AI handles "not found" gracefully

7. Troubleshooting

Error: "missing_version"

Message: Notion-Version header failed validation, Notion-Version header should be defined.

Fix: Add the custom header Notion-Version with value 2022-06-28 in the Configurations tab.

Error: "unauthorized" or "invalid_token"

Message: API token is invalid.

Fix:

• Regenerate the token in Notion integrations
• Copy the new token to the Bearer Token field
• Make sure there are no extra spaces before or after the token

Error: "object_not_found"

Message: Could not find page with ID: xxxxx.

Fix: The page isn't shared with your integration. Go to Notion, open the page, and add your integration via Connections.

Error: "invalid_request_url"

Message: Invalid request URL.

Fix: Turn OFF the "Crawl page" toggle in the tool settings.

AI Only Returns Page Titles, Not Content

Cause: The AI is not calling the second tool.

Fix:

• Check the system prompt has the two-tool instructions
• Make the get_notion_page_content description more explicit
• Test with a stronger instruction: "After searching, you MUST call get_notion_page_content"

Search Returns No Results

Possible causes:

• Pages not shared with the integration
• Search terms don't match page content
• Notion-Version header missing

Fix:

• Verify pages are shared (check Connections in Notion)
• Try broader search terms
• Check the headers in the Configurations tab

AI Doesn't Translate Terms

Cause: Terminology is not in the system prompt, or the AI is ignoring instructions.

Fix:

• Add the missing terms to the Terminology Translation section
• Make the terminology section more prominent in the system prompt
• Consider using a stronger model (GPT-4o instead of GPT-4.1 mini)

Model Recommendations

• GPT-4.1 mini: ~70-80% reliability, cheapest, best for a simple knowledge base on a budget
• GPT-4o mini: ~85% reliability, low cost, balanced performance
• GPT-4o: ~95% reliability, medium cost, best for a complex knowledge base where high accuracy is needed
• GPT-4.1: ~95% reliability, medium cost, best for complex multi-step tasks

8. Appendix: Full System Prompt

Copy everything inside the toggle below into your AI Agent's System Prompt, then customize the terminology and escalation contacts for your company.

Quick Reference Card

Setup Checklist

1. Create a Notion integration at notion.so/my-integrations
2. Copy the Integration Secret (Bearer Token)
3. Share your Notion pages with the integration
4. Create Tool 1: query_notion_pages (POST to /v1/search)
5. Create Tool 2: get_notion_page_content (GET to /v1/blocks/{page_id}/children)
6. Add the header Notion-Version: 2022-06-28 to both tools
7. Paste the system prompt
8. Test with "What is our company mission?"

Tool Quick Reference

• query_notion_pages: POST to https://api.notion.com/v1/search, key parameter query (body)
• get_notion_page_content: GET to https://api.notion.com/v1/blocks/{page_id}/children, key parameter page_id (path)

Headers Required (Both Tools)

• Notion-Version: 2022-06-28
• Content-Type: application/json (Tool 1 only)