Sync Notion

Notion is a popular place for product docs, runbooks, and knowledge bases. Hilal Chatbot connects via Notion’s official OAuth, lets you pick the specific pages and databases to ingest, and keeps them in sync.

In this guide:

• Connect a Notion workspace
• Pick pages and databases
• How sync works
• Disconnect

How the integration works

The frontend is a thin client over Hilal’s backend Notion endpoints — your Notion access token is stored on the backend, never on your browser. Authorization runs through Notion’s standard OAuth consent screen, not a personal API key.

Step 1: Connect

Open Knowledge base → Add knowledge source → Notion.

Click Connect to Notion. You’re redirected to Notion’s consent screen, where you’ll be asked to:

• Choose which workspace to connect.
• Pick which top-level pages or databases Hilal Chatbot can read. Notion’s permission model lets you grant access to specific pages — the bot only sees what you select.

Screenshot: Notion’s OAuth consent screen with workspace selection.

After approval, you return to Hilal Chatbot.

Step 2: Pick pages and databases

You’ll see a searchable list of every page and database Notion exposed to the integration. Filter by typing in the search box.

Screenshot: The Notion page picker with multi-select and search.

Use the multi-select checkboxes to pick what to import. The list paginates — click Load more to see further results.

Click Import. Each selected page or database becomes one source row in the knowledge base.

How sync works

• One-shot import on add. Selected pages are pulled into the index when you import.
• Manual re-sync. Click Retrain on any Notion source to re-pull from Notion.
• Auto-retrain (New). Combine with Auto-retraining to schedule periodic re-syncs (daily / weekly / monthly).

Today there’s no live webhook from Notion → bot. If a teammate edits a page, the change shows up on the next sync.

Step 3: Disconnect

Open the Notion picker again and click Disconnect. The integration is removed; your Notion access token is deleted from Hilal Chatbot’s backend. Existing imported source rows remain — they just won’t re-sync.

To remove imported sources, delete them from the knowledge-base list.

What’s extracted

• Page content (text, headings, lists, tables, code blocks, callouts).
• Database rows treated as individual entries — title and properties become searchable text.
• Internal links between Notion pages are preserved (but only resolve within the imported set).

Limitations

• Embedded blocks (tweets, Figma boards, Loom videos) extract as their captions only.
• Comments and discussions are not synced.
• Permissions on Notion still apply at sync time — if Notion later removes a page from the integration, that source becomes empty on next re-sync.

Troubleshooting

• “Connect to Notion” loops back without success. Pop-up was blocked or your browser ate the redirect cookie. Allow pop-ups for both notion.so and app.hilalsoftware.tools and retry.
• A page I expected to see is missing. During Notion’s consent step, the page wasn’t selected. Re-run Connect and select it.
• Some pages are empty after import. They likely contain only embedded blocks (Figma, Loom) which don’t have meaningful text to extract.

What’s next