Notion
Страницы и базы данных Notion как контекст для ответов: чтение, вопросы в комментариях, отчёт исследования страницей, область, вебхук и опрос.
Notion для команды — то же, что Confluence: письменный контекст, которого нет ни в задаче, ни в коде. Требования, решения, регламенты, ранбуки — и таблицы: базы данных Notion, в которых команда ведёт задачи, реестры и договорённости. Интеграция даёт модели читать всё это, когда нужно для ответа, принимает вопросы прямо в комментариях к странице и умеет оставлять результат страницей, а не только комментарием.
Инструменты
| Инструмент | Что делает |
|---|---|
search_pages | ищет страницы и базы данных по словам — в заголовках через поиск Notion и в тексте страниц области своими силами: Notion ищет только по заголовкам, а вопрос обычно о том, что на странице написано. Слова сравниваются по основе, падежи не мешают; страница читается один раз до следующей правки |
get_page | читает страницу целиком — как markdown с заголовками, списками, таблицами и кодом — вместе с обсуждением |
get_page_children | перечисляет вложенные страницы и базы данных раздела |
get_database | устройство базы данных: её источники данных и свойства с типами |
query_database | записи базы — каждая своими свойствами текстом; при желании с фильтром по одному свойству, в диалекте Notion для его типа |
get_comments | обсуждения страницы: ветки, кто и когда писал |
add_comment | комментарий на странице или ответ в ветке |
create_page | дочерняя страница из markdown — внутри области подключения |
Шесть первых только читают и доступны везде, где модели даются инструменты коннектора — в «Спросить» и в глубоком исследовании. Два пишущих модели не достаются ни на одной стадии: ими пользуется сам коннектор, когда по команде платформы возвращает ответ комментарием или отчёт исследования дочерней страницей — и только внутри области.
Страница приходит как markdown, а не как дерево блоков. С версии API 2026-03-11 Notion отдаёт и принимает страницу одним вызовом в своём markdown; интеграция ничем не дополняет его и ничего не обрезает — длинная страница остаётся длинной. Запись базы данных приходит плоской: каждое свойство — текстом, по своему типу (статус — именем, дата — датой, флажок — «да»/«нет»).
Обращения на странице
Всё, что описано в «Интеграциях с трекерами», работает и
здесь: @buff <вопрос>, @buff research …, @buff task … или /ask, /research,
/task в комментарии к странице — это вопрос, исследование или черновик задачи. Ответ
приходит в ту же ветку обсуждения; вопрос в новой ветке начинает новый разговор.
В Notion интеграцию нельзя упомянуть через @: она не человек и в подсказку не
попадает. К боту обращаются словом в тексте — псевдонимом из настроек (buff) или
именем интеграции. Оба пишутся как есть, регистр не важен.
У страницы нет ветки кода, поэтому ответ считается на уровне проекта разработки — или пространства — к которому привязано подключение.
Исследование — страницей
Ответ на /research в Notion не кладётся в комментарий: под страницей, где спросили,
появляется дочерняя страница с отчётом — сам текст, а не картинка текста, — и к ней
приложен PDF-документ. В ветку обсуждения приходит комментарий со ссылкой на отчёт и на
исследование в Buff. Страница создаётся только внутри области.
Область
В подключении перечисляются корни — ссылки или идентификаторы страниц и баз данных. Бот работает в них и во всём, что вложено: страница считается «своей», если среди её родителей есть корень (страница → страница → база данных → страница …). Так же ограничена запись: ответить, создать страницу или комментарий вне области нельзя.
Пустой список корней означает «всё, что открыто интеграции в Notion». Здесь границу уже провёл сам Notion: интеграция видит только страницы, к которым её подключили. Это отличается от трекеров, где пустой список означает «нигде», — семантика решается для каждого источника отдельно.
Права интеграции в Notion — внешняя граница, список корней — внутренняя; разумно иметь обе: подключите интеграцию к разделу, а не ко всему пространству.
События: вебхук и опрос
У Notion нет ленты комментариев по рабочему пространству, и новый комментарий не меняет страницу. Поэтому события устроены иначе, чем у Confluence и Figma:
- Вебхук разбирается. Событие
comment.createdназывает комментарий, интеграция читает его по API и отвечает через секунды. Приёмник принадлежит коннектору, ссылку выдаёт он — см. события трекеров. - Опрос — страховка. Интеграция обходит страницы области по кругу, несколько за
проход, и читает их комментарии. По умолчанию раз в 5 секунд: интервал — настройка
подключения, для Notion интеграция предлагает пять секунд. Холостой проход стоит один
запрос; при лимите Notion в 180 запросов в минуту на интеграцию (600 на планах
Business и Enterprise) это укладывается с запасом, а ответы
429интеграция выжидает так, как проситRetry-After.
Токен подписи — от Notion
Notion подписывает вызовы своим токеном подтверждения, а не секретом из ссылки:
при создании подписки он делает один неподписанный вызов с verification_token, и его
надо вставить в форму подтверждения в Notion. Коннектор делает это за вас:
- Включите приём вебхуков у подключения и скопируйте выданную ссылку.
- В настройках интеграции Notion (Webhooks) укажите эту ссылку. Notion пришлёт токен.
- Откройте подключение в коннекторе: токен уже там, с кнопкой «Скопировать». Вставьте его
в Notion и подтвердите подписку; подпишитесь на событие
comment.created.
С этого момента коннектор проверяет каждый вызов заголовком X-Notion-Signature этим
токеном. Если подписку пересоздать, Notion пришлёт новый токен — коннектор не
подменит им прежний молча: покажет новый на странице подключения и продолжит проверять
вызовы старым, пока вы не примете новый в поле «Секрет подписи».
Настройка
В Notion
- Создайте внутреннюю интеграцию в настройках рабочего пространства (раздел «Интеграции» → «Разработка»). Понадобятся возможности: читать содержимое, вставлять содержимое, читать и вставлять комментарии; чтение сведений о пользователях — по желанию, оно даёт имена авторов там, где Notion их не подставил.
- Скопируйте секрет интеграции — это токен для поля «api» в коннекторе.
- Подключите интеграцию к страницам: на корневой странице раздела (или базе данных) меню «…» → «Подключения» → выберите интеграцию. Всё вложенное откроется вместе с ней.
В коннекторе
| Поле | Значение |
|---|---|
| Адрес API | подставлен: https://api.notion.com — менять не нужно |
Учётные данные api | секрет внутренней интеграции |
| Страницы и базы данных | ссылки или идентификаторы корней, через запятую; пусто — всё, что открыто интеграции |
| Как ещё к боту обращаются | короткое имя, например buff |
| Интервал опроса | секунды; пусто — как предлагает интеграция, 5 |
Проверка связи говорит не «ок», а название рабочего пространства, имя интеграции, сколько корней в области и сколько из них ей реально доступно.
Из командной строки: connector install notion, затем
connector instance set --plugin notion --version 1.0.0 --set roots=<ссылка>,<ссылка> --poll 5.
Чего интеграция не делает
- Не редактирует существующие страницы и записи баз данных — только читает их, пишет комментарии и создаёт новые страницы внутри области.
- Не копирует и не индексирует содержимое Notion к нам: читается то, что понадобилось для конкретного ответа, и попадает в контекст этого ответа.
- Не индексирует заранее — поиск по тексту читает страницы области в момент вопроса (один раз до следующей правки страницы); в большой области первый поиск занимает время.
- Не ведёт задачи в Notion как трекер: база данных читается как знание, статусы по ней бот не двигает.
Источники знаний
Confluence, Figma, Notion и Google Диск как контекст для ответов: инструменты чтения, обращения на странице и макете, область, параметры вместо картинок.
Google Диск
Документы, таблицы и презентации Google как контекст: чтение, вопросы в комментариях, отчёт документом, область, сервисный аккаунт или своя учётная запись.