Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.thinnest.ai/llms.txt

Use this file to discover all available pages before exploring further.

Notion Integration

Give your agents the ability to read from and write to Notion — append call notes to a shared database, create pages in a project wiki, query a product-knowledge workspace before answering customers, or turn every voice conversation into a structured record. Perfect for persistent memory: the agent can look up a customer’s prior interactions in Notion and write today’s call summary back into the same row.

Connecting Notion

Connection goes through Notion’s verified OAuth flow — you do not need to create an internal integration, copy an API key, or manage page-by-page sharing. thinnestAI brokers the OAuth through Composio.

Step 1: Connect via OAuth

  1. Navigate to Agents and select your agent.
  2. Open the Tools section and click Add Tool.
  3. Select Notion.
  4. Click Connect Notion.
  5. A Notion sign-in popup opens. Authenticate with the workspace you want the agent to access.
  6. Select which pages and databases to grant access to (page picker), then click Allow access.
The popup closes automatically when the connection is complete. The modal shows a green Connected badge with your workspace name.
Scoped by page selection. Notion grants access only to the pages / databases you explicitly pick during OAuth. The agent cannot read or write anything else in the workspace. To grant access to additional pages later, disconnect and re-connect with a broader selection.

Step 2: Choose Allowed Actions

Four capability toggles control which action groups the agent can invoke:
ToggleDefaultWhat it unlocks
Read Pages✅ OnGet page content, block children, traverse the tree
Read Databases✅ OnQuery rows, filter, sort, look up by property
Write Pages✅ OnCreate pages, append blocks, update content
Write Databases✅ OnInsert rows, update row properties
Manage Database SchemaOffCreate new databases, add properties, change types
Archive & DeleteOffSoft-delete pages, archive database rows
Leave Manage Database Schema and Archive & Delete off unless the agent specifically needs to reshape the workspace. Most call-logging flows only need Read + Write.

Available Actions

Pages (5)

ActionDescription
Get PageRead a page’s properties and metadata
Get Page ContentRead the full block tree under a page
Create PageCreate a new page in a parent page or database
Update PageUpdate page properties or cover / icon
Append BlocksAdd blocks (paragraphs, lists, todos) to a page

Databases (5)

ActionDescription
Query DatabaseFilter and sort rows by property values
Get DatabaseRead a database’s schema (property definitions)
Create Database RowInsert a new row with properties filled
Update Database RowUpdate properties on an existing row
SearchFull-text search across pages and databases

Blocks (3)

ActionDescription
Get BlockRead a single block’s content
Update BlockModify a block’s content or type
Delete BlockRemove a block (soft-delete)

Schema (3) — opt-in

ActionDescription
Create DatabaseCreate a new database with a property schema
Update Database SchemaAdd / rename / retype properties
Archive PageSoft-delete a page (reversible from Notion UI)

Voice-AI Use Cases

Notion pairs naturally with voice agents for structured long-term memory. Unlike Slack (ephemeral) or Google Sheets (2D only), Notion holds rich page content — transcripts, recordings, action items, linked records — all queryable by the agent on the next call.

Call-Log Database

Agent instructions:
"After every call, insert a new row into the 'Call Log' Notion
database with these properties:
- Caller name (Title)
- Phone number (Phone)
- Call date (Date)
- Duration (Number)
- Outcome (Select: Won | Lost | Follow-up)
- Summary (Rich text, 2-3 sentences)
- Recording URL (URL)
- Next action (Checkbox)"

Customer 360 Lookup

Agent instructions:
"Before answering a caller, search Notion for their phone number:
1. Query the 'Customer' database where Phone = caller_phone
2. If found, read prior call summaries and open todos
3. Greet the caller by name and reference last interaction
4. After this call, append today's summary to their page."

Project Handoff

Agent instructions:
"When a caller reports a bug or feature request:
1. Create a new page under 'Product Backlog' database
2. Fill: Title, Reporter (caller), Priority (infer from call),
   Description (full transcript of the issue portion)
3. Add a todo block: '[ ] Triage within 24h'
4. Send Slack notification with the Notion URL."

Example: Customer-Aware Support Agent

Build a voice agent that reads the caller’s Notion history before answering, and writes the call summary back on hangup.

Agent Setup

FieldValue
NameContext-Aware Support
ModelGPT-4o
ToolsNotion, Google Sheets

Agent Instructions

You are a support agent for an existing customer base. Use
Notion as your memory — every customer has a page with their
full interaction history.

WORKFLOW:
1. On call start, query the 'Customers' database by phone number.
   - If no match: politely collect name + email, create new page.
   - If match: read prior summaries, open todos, plan and tier.
2. Greet by name: "Hi {name}, I see you called {N} days ago
   about {topic} — is this a follow-up or a new issue?"
3. During call, address both (a) the open todos and (b) today's
   concern.
4. On hangup:
   - Append today's summary block to their page
   - Update the 'Last contact' date property
   - If new action items, add todo blocks
   - If the issue is resolved, check off the prior open todo

RULES:
- Never invent details not said during the call — read from
  Notion, write from the transcript.
- If the customer's page doesn't exist, create it BEFORE the
  conversation continues so every later message has somewhere
  to land.
- Keep summaries tight (3-5 sentences). Full transcript lives
  elsewhere; Notion is the skimmable index.

Structured Writes vs Free-Form

Notion has two write patterns, each suited to different flows: Structured — database rows: Use for CRM-style records where every call has the same fields (caller, outcome, summary, next_action). Query is easy; reporting is easy. Best for call logs, lead tracking, ticket backlogs. Free-form — page content blocks: Use for narrative memory where each customer’s page grows organically. Best for customer-history pages where today’s call appends to yesterday’s summary. Most real agents use both — a row in a “Calls” database links to a dedicated customer page with the full history.

Combining with Other Tools

CombinationUse Case
Notion + VoicePersistent customer memory across calls
Notion + Google SheetsNotion for narrative, Sheets for metrics / reports
Notion + SlackNotify a channel when a new page is created (#new-tickets)
Notion + GmailEmail the customer a link to their Notion page
Notion + Google CalendarAuto-create Notion meeting-prep pages for upcoming calls

Security & Privacy

  • OAuth tokens are encrypted at rest. thinnestAI never sees your Notion password.
  • Per-user scoping — Each user’s workspace connection is isolated. An agent owned by User A cannot read User B’s Notion.
  • Page-level scoping — At OAuth time, you pick which pages / databases the agent can touch. Unselected pages remain invisible even to the integration.
  • Revoke access — Disconnect from the config modal, or revoke directly from Notion → Settings & Members → Connections.
  • Audit trail — every agent-written change appears in Notion’s page history with the connected user as the editor.

Troubleshooting

IssueSolution
”object_not_found” errorsThe page / database wasn’t shared with the integration during OAuth. Reconnect and select the missing page in the picker.
”validation_error: … is not a valid UUID”You passed a plain page name instead of the Notion page ID (32-char UUID). Use Search first to resolve name → ID.
Properties don’t writeProperty type mismatch. A Number column rejects text, a Select column rejects values not in its options list. Read the schema via Get Database first.
Write fails with “archived”Pages in the trash can’t be modified. Restore the page in Notion UI or pick a different parent.
Pagination missing resultsDefault Query Database returns 100 rows. Pass start_cursor from a prior response to continue.
Rate-limitedNotion API caps at ~3 requests/sec per integration. Agents making bursts of 10+ writes may get 429s. Add small delays for batch flows.

Next Steps

  • Voice — Use Notion as persistent memory across voice conversations.
  • Google Sheets — Simpler tabular logging when you don’t need rich page content.
  • Slack — Notify your team when agents create new Notion pages.