Интеграция
Notion, где страница — это дерево, а не документ
Интеграция с Notion позволяет Telegram-боту читать страницы и базы из рабочего пространства — чаще всего как корпус для ИИ-ассистента. Содержимое Notion представляет собой дерево типизированных блоков, а не документ, и это по-настоящему удобно для нарезки: извлечение превращается в обход дерева, а не в одну загрузку.
Notion — интеграция: доступ, лимиты и доступность
- Модель авторизации
- Ключ API
- Лимит частоты
- ~3 запроса/секунду в среднем
- Доступность в Заливе
- Региональных ограничений нет
- Поток данных
- 5 узлов, всё через воркер
As of 2025-10-01, Telegram Bot API 13.4
Зачем нужна эта интеграция
В Notion всё больше компаний держат те знания, из которых ассистент и должен отвечать: внутренние регламенты, описания продукта, документацию процессов. Он ещё и необычно хорошо подходит на роль корпуса, потому что содержимое там уже структурировано. Заголовок — это заголовок, а не жирный текст, похожий на заголовок, и свёрнутый блок действительно содержит вложенное в него.
Эта структура решает самую трудную задачу в поиске по документам — нарезку. Фрагмент, разрезанный посреди рассуждения, извлекается как бессмыслица независимо от качества модели эмбеддингов, а угадывать границы в плоском документе — это именно угадывание. Дерево блоков Notion даёт настоящие границы: вот раздел, вот свёрнутый блок, вот строка базы, — поэтому фрагменты идут по авторской структуре, а не по счётчику токенов.
Практических ограничений два: выдача доступа и частота. Интеграция видит только те страницы, которыми с ней явно поделились, — это разумное поведение по умолчанию и частая причина корпуса, из которого незаметно выпала треть того, что все считали учтённым. А API ограничен примерно тремя запросами в секунду, и это важно, потому что прочитать страницу — значит обойти её блоки: большое рабочее пространство означает очень много запросов, и такому обходу место в задаче по расписанию, а не в обработке запроса пользователя.
Как на самом деле движутся данные
Токен внутренней интеграции в секретах воркера, а доступ выдаётся постранично или по базе из самого Notion. Модель прав здесь накопительная и явная: интеграция не видит ничего, пока с ней чем-то не поделились, — а значит неполный корпус это пробел в выдаче доступа, а не дефект кода.
Модель доступа: API-ключ
Их лимиты и что они означают для вас
API ограничен в среднем примерно тремя запросами в секунду.
Чтение страницы — это обход её блоков, поэтому полная синхронизация пространства складывается в тысячи запросов. Загрузка идёт задачей по расписанию с выдержкой пауз и никогда не выполняется в обработке запроса.
Интеграция получает доступ только к тем страницам и базам, которыми с ней поделились явно.
Корпус, в котором не хватает трети регламента, — обычно пробел в выдаче доступа. Задача загрузки отчитывается о том, что ей видно, чтобы этот пробел был заметен, а не молча списан.
Содержимое страницы — дерево типизированных блоков, которое достаётся постраничными запросами дочерних элементов.
Извлечение оказывается рекурсивным обходом, а не одной загрузкой. Работы больше, а границы фрагментов получаются несравнимо лучше, чем у плоского текста.
Свойства баз типизированы, а значения формул и сводных полей вычисляет сам Notion.
Вычисленные значения читаются, а не пересчитываются. Повторив формулу Notion внутри бота, вы гарантированно получите расхождение между ними.
Как это ломается и что происходит потом
Ассистент уверенно не знает того, что записано в документации.
Почти всегда это страница, которой не поделились. Отчёт о загрузке перечисляет увиденное, и неотвечаемая жалоба превращается в конкретное действие с выдачей доступа.
Полная синхронизация упирается в лимит частоты и тянется часами.
Инкрементальная синхронизация опирается на отметки времени последнего изменения, поэтому перечитываются только изменившиеся страницы. Полная перезагрузка корпуса — редкая осознанная операция, а не ежедневная норма.
Страницу поправили, а в индексе всё ещё лежит старый отрывок.
Устаревание — самый частый способ, которым такие ассистенты деградируют. Перезагрузка идёт по расписанию, а индекс хранит, когда каждый фрагмент обновлялся в последний раз.
Глубоко вложенное содержимое пропускается при неглубоком обходе.
Обход делается полностью рекурсивным с пагинацией на каждом уровне. Ограничение глубины даёт ассистента, который знает начало каждого документа и ни одного конца.
Доступность в ОАЭ и остальных странах Залива
Весь мир
Региональных ограничений нет. Тариф влияет на возможности, а не на доступность API.
Команды с большим объёмом документации
Тот самый случай, и именно здесь блочная структура по-настоящему окупается качеством поиска.
Место хранения данных
Содержимое лежит в инфраструктуре Notion. Чтение его в ассистента означает, что эмбеддинги окажутся ещё и в третьем месте, и об этом стоит сказать прямо.
Очень большие рабочие пространства
Из-за лимитов частоты полная синхронизация идёт медленно. Инкрементальная загрузка здесь не оптимизация, а то, без чего интеграция неработоспособна.
Когда эту интеграцию делать не нужно
- Ваша документация устарела. Ассистент выдаст неверный ответ быстрее и увереннее, чем это сделал бы человек.
- Содержимое лежит в Google Docs или Confluence. Интегрируйтесь туда, где оно действительно есть, а не переезжайте под удобство бота.
- Вы не можете делиться страницами с интеграцией по внутренним правилам. Модель прав здесь явная, и обойти её нечем.
- Нужна запись, чтобы бот поддерживал Notion в актуальном состоянии. Это возможно и это другая, заметно большая работа.
На чём это работает
| Компонент | Версия | Зачем |
|---|---|---|
| Cloudflare Workers | current | Обход с выдержкой пауз, инкрементальная синхронизация и нарезка. |
| Cloudflare Vectorize | current | Векторный индекс с фрагментами и ссылкой на источник в Notion. |
| Cloudflare D1 | current | Курсоры страниц, отметки последнего изменения и отчёты о загрузке. |
| Zod | 4.4 | Валидация тел блоков, которые различаются от типа к типу. |
Вопросы, которые возникают при оценке
Почему Notion — удачный корпус для ИИ-ассистента?
Потому что содержимое там уже структурировано. Границы фрагментов можно вести по авторскому дереву блоков, а не по счётчику токенов, а отрывок, разрезанный посреди рассуждения, извлекается как бессмыслица, насколько бы хороша ни была модель эмбеддингов.
Ассистент не знает того, что точно записано в Notion. Почему?
Почти всегда потому, что этой страницей с интеграцией никто не поделился. Модель прав в Notion явная и накопительная, поэтому задача загрузки отчитывается о том, что ей было видно, — и расплывчатая жалоба превращается в конкретное действие с доступом.
Сколько занимает полная синхронизация пространства Notion?
Дольше, чем ожидается: прочитать страницу — значит обойти её блоки, а API допускает примерно три запроса в секунду. Инкрементальная синхронизация по отметкам последнего изменения — это то, что делает подход практичным, а не надстройка сверху.
Как не дать индексу устареть?
Перезагрузкой по расписанию, где каждый фрагмент фиксирует, когда он обновлялся в последний раз. Устаревание — самый частый способ тихой деградации таких ассистентов, и его не видно, пока индекс не следит за собственной свежестью.
Должен ли бот пересчитывать формулы Notion?
Нет. Вычисленные значения читаются через API, а не реализуются заново, потому что своя реализация рано или поздно разойдётся с оригиналом и никто не заметит, какая из них права.
Может ли бот писать обратно в Notion?
Да, и это другая, заметно большая работа со своими вопросами про конфликты правок. Загрузка только на чтение для ассистента — распространённый случай, и рассуждать о ней несравнимо проще.
Что почитать дальше
Для команд на Atlassian, а не на Notion, равнозначный корпус — это интеграция с Confluence.
Продукт, который этот корпус питает, — это ИИ-ассистент с поиском по документам.
Когда документация — это папка с файлами, а не вики, смотрите интеграцию с Google Drive.
Если ответов фиксированный набор и поиск по документам не нужен, дешевле обойдётся многоязычный бот поддержки.