Integration

Notion, where the page is a tree rather than a document

A Notion integration lets a Telegram bot read pages and databases from a workspace — usually as the corpus for an AI assistant. Notion content is a tree of typed blocks rather than a document, which is genuinely useful for chunking and means extraction is a traversal rather than a fetch.

Notion integration: auth, limits and availability

Auth model: API key
Rate limit: ~3 requests/second average
GCC availability: No regional restriction
Data flow: 5 hops, worker-mediated

As of 2025-10-01, Telegram Bot API 13.4

Why this integration exists

Notion is where a growing number of companies keep the knowledge an assistant should answer from: handbooks, product specifications, process documentation. It is also unusually well suited to being a corpus, because its content is already structured. A heading is a heading rather than bold text that looks like one, and a toggle genuinely contains its children.

That structure solves the hardest problem in retrieval, which is chunking. A passage split mid-argument retrieves as nonsense regardless of the embedding model, and inferring boundaries from a flat document is guesswork. Notion's block tree gives real boundaries — this section, this toggle, this database row — so chunks can follow the author's own structure rather than a token count.

The practical constraints are sharing and rate. An integration sees only pages explicitly shared with it, which is a sensible default and a common source of a corpus that is quietly missing a third of what people assumed. And the API is rate-limited at around three requests per second, which matters because reading a page means traversing its blocks — a large workspace is a lot of requests, and it belongs in a scheduled job rather than in a request path.

How the data actually moves

Chunk boundaries follow the block tree rather than a token count, so a retrieved passage is a section the author actually wrote as one.

An internal integration token held as a Worker secret, with access granted per page or database from within Notion. The permission model is additive and explicit: the integration sees nothing until somebody shares something with it, which means an incomplete corpus is a sharing gap rather than a bug.

Auth model: API key

Their limits, and what they mean for you

The API is rate-limited to roughly three requests per second on average.

Reading a page means traversing its blocks, so a full workspace sync is thousands of requests. Ingestion runs as a scheduled job with pacing, never in a request path.

An integration can access only pages and databases explicitly shared with it.

A corpus missing a third of the handbook is usually a sharing gap. The ingestion job reports what it can see so the gap is visible rather than assumed away.

Page content is a tree of typed blocks, retrieved by paginated child queries.

Extraction is a recursive traversal rather than a single fetch. It is more work and it produces far better chunk boundaries than flat text.

Database properties are typed, and formula and rollup values are computed by Notion.

Computed values are read rather than recalculated. Reimplementing a Notion formula in the bot guarantees the two disagree eventually.

How it fails, and what happens when it does

The assistant confidently does not know something that is written down.

Almost always an unshared page. The ingestion report lists what was seen, which turns an unanswerable complaint into a specific sharing action.

A full sync trips the rate limit and takes hours.

Incremental sync uses last-edited timestamps so only changed pages are re-read. A full re-ingest is an occasional deliberate operation rather than the daily default.

A page is edited and the index still holds the old passage.

Staleness is the commonest way these assistants degrade. Re-ingestion runs on a schedule and the index records when each chunk was last refreshed.

Deeply nested content is missed by a shallow traversal.

Traversal is fully recursive with pagination at every level. A depth limit produces an assistant that knows the beginning of every document and the end of none.

Availability in the UAE and the wider GCC

Global

No regional restriction. Plan tier affects features rather than API availability.

Documentation-heavy teams

The intended case, and where the block structure genuinely pays off in retrieval quality.

Data residency

Content is held in Notion's infrastructure. Reading it into an assistant means embedding it elsewhere too, which is worth being explicit about.

Very large workspaces

Rate limits make full syncs slow. Incremental ingestion is not an optimisation here; it is what makes the integration practical.

When not to use this integration

Your documentation is out of date. The assistant will retrieve the wrong answer faster and with more authority than a person would.
The content lives in Google Docs or Confluence. Integrate with where it actually is rather than migrating to suit a bot.
You cannot share pages with an integration for policy reasons. The permission model is explicit and there is no way around it.
You need write access to keep Notion in sync from the bot. Possible, and a different and larger piece of work.

What it runs on

Component	Version	Why
Cloudflare Workers	current	Paced traversal, incremental sync and chunking.
Cloudflare Vectorize	current	Vector index holding chunks with their Notion source.
Cloudflare D1	current	Page cursors, last-edited timestamps and ingestion reports.
Zod	4.4	Validation of block payloads, which vary by block type.

Questions that come up during scoping

Why is Notion a good corpus for an AI assistant?

Because the content is already structured. Chunk boundaries can follow the author's own block tree rather than a token count, and a passage split mid-argument retrieves as nonsense regardless of how good the embedding model is.

The assistant does not know something that is definitely written down. Why?

Almost always because that page was never shared with the integration. Notion's permission model is explicit and additive, so the ingestion job reports what it could see — which turns a vague complaint into a specific sharing action.

How long does a full sync take?

Longer than expected, because reading a page means traversing its blocks and the API allows roughly three requests per second. Incremental sync on last-edited timestamps is what makes this practical rather than an optimisation on top.

How do we stop the index going stale?

Scheduled re-ingestion, with each chunk recording when it was last refreshed. Staleness is the most common way these assistants quietly degrade, and it is invisible unless the index tracks its own freshness.

Should the bot recompute Notion formulas?

No. Computed values are read from the API rather than reimplemented, because a reimplementation will diverge from the original eventually and nobody will notice which is right.

Can the bot write back into Notion?

Yes, and it is a different and larger piece of work with its own conflict questions. Read-only ingestion for an assistant is the common case and is considerably simpler to reason about.