# Notion
> Страницы и базы данных Notion как контекст для ответов: чтение, вопросы в комментариях, отчёт исследования страницей, область, вебхук и опрос.
Notion для команды — то же, что Confluence: **письменный контекст**, которого нет ни в
задаче, ни в коде. Требования, решения, регламенты, ранбуки — и таблицы: базы данных
Notion, в которых команда ведёт задачи, реестры и договорённости. Интеграция даёт модели
читать всё это, когда нужно для ответа, принимает вопросы прямо в комментариях к странице
и умеет оставлять результат **страницей**, а не только комментарием.
_Иллюстрация: Вопрос, ответ на который записан только в 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; интеграция ничем не
дополняет его и ничего не обрезает — длинная страница остаётся длинной. Запись базы
данных приходит плоской: каждое свойство — текстом, по своему типу (статус — именем,
дата — датой, флажок — «да»/«нет»).
## Обращения на странице
Всё, что описано в [«Интеграциях с трекерами»](/docs/connector/trackers), работает и
здесь: `@buff <вопрос>`, `@buff research …`, `@buff task …` или `/ask`, `/research`,
`/task` в комментарии к странице — это вопрос, исследование или черновик задачи. Ответ
приходит **в ту же ветку обсуждения**; вопрос в новой ветке начинает новый разговор.
В Notion интеграцию **нельзя упомянуть через @**: она не человек и в подсказку не
попадает. К боту обращаются словом в тексте — псевдонимом из настроек (`buff`) или
именем интеграции. Оба пишутся как есть, регистр не важен.
У страницы нет ветки кода, поэтому ответ считается на уровне проекта разработки — или
[пространства](/docs/quickstart/space) — к
которому привязано подключение.
### Исследование — страницей
Ответ на `/research` в Notion не кладётся в комментарий: под страницей, где спросили,
появляется **дочерняя страница** с отчётом — сам текст, а не картинка текста, — и к ней
приложен PDF-документ. В ветку обсуждения приходит комментарий со ссылкой на отчёт и на
исследование в Buff. Страница создаётся только внутри области.
## Область
В подключении перечисляются **корни** — ссылки или идентификаторы страниц и баз данных.
Бот работает в них и во всём, что вложено: страница считается «своей», если среди её
родителей есть корень (страница → страница → база данных → страница …). Так же
ограничена запись: ответить, создать страницу или комментарий вне области нельзя.
**Пустой список корней означает «всё, что открыто интеграции в Notion».** Здесь границу
уже провёл сам Notion: интеграция видит только страницы, к которым её подключили. Это
отличается от трекеров, где пустой список означает «нигде», — семантика решается для
каждого источника отдельно.
Права интеграции в Notion — внешняя граница, список корней — внутренняя; разумно иметь
обе: подключите интеграцию к разделу, а не ко всему пространству.
## События: вебхук и опрос
У Notion **нет ленты комментариев** по рабочему пространству, и новый комментарий не
меняет страницу. Поэтому события устроены иначе, чем у Confluence и Figma:
- **Вебхук разбирается.** Событие `comment.created` называет комментарий, интеграция
читает его по API и отвечает через секунды. Приёмник принадлежит коннектору, ссылку
выдаёт он — см. [события трекеров](/docs/connector/trackers#события-опрос-и-вебхуки).
- **Опрос — страховка.** Интеграция обходит страницы области по кругу, несколько за
проход, и читает их комментарии. По умолчанию **раз в 5 секунд**: интервал — настройка
подключения, для Notion интеграция предлагает пять секунд. Холостой проход стоит один
запрос; при лимите Notion в 180 запросов в минуту на интеграцию (600 на планах
Business и Enterprise) это укладывается с запасом, а ответы `429` интеграция выжидает
так, как просит `Retry-After`.
### Токен подписи — от Notion
Notion подписывает вызовы **своим** токеном подтверждения, а не секретом из ссылки:
при создании подписки он делает один неподписанный вызов с `verification_token`, и его
надо вставить в форму подтверждения в Notion. Коннектор делает это за вас:
1. Включите приём вебхуков у подключения и скопируйте выданную ссылку.
2. В настройках интеграции Notion (**Webhooks**) укажите эту ссылку. Notion пришлёт токен.
3. Откройте подключение в коннекторе: токен уже там, с кнопкой «Скопировать». Вставьте его
в Notion и подтвердите подписку; подпишитесь на событие `comment.created`.
С этого момента коннектор проверяет каждый вызов заголовком `X-Notion-Signature` этим
токеном. Если подписку пересоздать, Notion пришлёт **новый** токен — коннектор не
подменит им прежний молча: покажет новый на странице подключения и продолжит проверять
вызовы старым, пока вы не примете новый в поле «Секрет подписи».
_Иллюстрация: Форма настройки: адрес API уже подставлен, остаётся назвать корни, интервал опроса и токен интеграции._
## Настройка
### В Notion
1. Создайте **внутреннюю интеграцию** в настройках рабочего пространства (раздел
«Интеграции» → «Разработка»). Понадобятся возможности: читать содержимое, вставлять
содержимое, читать и вставлять комментарии; чтение сведений о пользователях — по
желанию, оно даёт имена авторов там, где Notion их не подставил.
2. Скопируйте секрет интеграции — это токен для поля «api» в коннекторе.
3. **Подключите интеграцию к страницам**: на корневой странице раздела (или базе данных)
меню «…» → «Подключения» → выберите интеграцию. Всё вложенное откроется вместе с ней.
### В коннекторе
| Поле | Значение |
|---|---|
| Адрес 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** как трекер: база данных читается как знание, статусы по
ней бот не двигает.