Документация ботов под раздел «Интеграции» и публичный API ботов

apps/docs/components/api/scope-roles-table.tsx

@@ -7,13 +7,14 @@ import type { Schema } from '@/lib/openapi/types';
 import { CopyableCode } from './schema-tree';
 import { InlineCodeText } from './inline-code-text';
 
-const ROLES = ['owner', 'admin', 'user', 'bot'] as const;
+const ROLES = ['owner', 'admin', 'user', 'multi_guest', 'bot'] as const;
 type Role = (typeof ROLES)[number];
 
 const ROLE_LABELS: Record<Role, string> = {
   owner: 'Владелец',
   admin: 'Администратор',
   user: 'Сотрудник',
+  multi_guest: 'Мульти-гость',
   bot: 'Бот',
 };
 

apps/docs/components/mdx/cards.tsx

@@ -141,6 +141,7 @@ const GUIDE_ICONS: Record<string, string> = {
   '/guides/workflows': 'Route',
   '/guides/webhook': 'Webhook',
   '/guides/webhook/overview': 'Webhook',
+  '/guides/oauth/overview': 'KeyRound',
   '/guides/export': 'Download',
   '/guides/forms/overview': 'LayoutList',
   '/guides/dlp': 'ShieldCheck',

apps/docs/components/mdx/mdx-components.tsx

@@ -122,7 +122,7 @@ export async function ErrorSchema() {
       {apiError && (
         <WebhookSchemaSection
           schema={apiError}
-          title="ApiError (400, 402, 403, 404, 409, 410, 422)"
+          title="ApiError (400, 402, 403, 404, 409, 410, 422, 429, 503, 504)"
         />
       )}
       {oauthError && <WebhookSchemaSection schema={oauthError} title="OAuthError (401, 403)" />}

apps/docs/content/api/errors.mdx

@@ -1,6 +1,6 @@
 ---
 title: Ошибки
-description: "Коды ошибок HTTP в API Пачки и структуры тела ответа: ApiError (400/402/403/404/409/410/422) и OAuthError (401/403) с описанием полей и кодов"
+description: "Коды ошибок HTTP в API Пачки и структуры тела ответа: ApiError (400/402/403/404/409/410/422/429/503/504) и OAuthError (401/403) с описанием полей и кодов"
 related:
   - /api/limits
   - /api/requests-responses
@@ -21,7 +21,7 @@ related:
 
 В зависимости от типа ошибки вы получите в теле ответа одну из следующих структур:
 
-- **ApiError** — для кодов `400`, `402`, `403`, `404`, `409`, `410`, `422`. Содержит массив `errors` с детальной информацией об ошибках.
+- **ApiError** — для кодов `400`, `402`, `403`, `404`, `409`, `410`, `422`, а также `429` при суточном пределе сообщений, `503` и `504`. Содержит массив `errors` с детальной информацией об ошибках.
 - **OAuthError** — для кодов `401` и `403`. Содержит поля `error` и `error_description` с информацией об ошибке авторизации.
 
 > Код `403` может вернуть обе структуры:
@@ -33,4 +33,6 @@ related:
 
 <Info>Код `409` возвращается, когда объект с такими данными уже есть: сотрудник с этим адресом почты, тег с этим названием, закрепление у этого сообщения, черновик в этом чате. В `errors[].code` приходит `already_exists`, а в `errors[].key` — конфликтующее поле: например, `email` при повторном адресе почты сотрудника. Если определить поле не удалось, `key` в ошибке не будет. У черновика вдобавок приходит `errors[].payload.draft_id` — номер того, который уже лежит в чате, чтобы дописать его методом [Редактирование черновика](PUT /drafts/{id}).</Info>
 
+<Info>Код `504` с `errors[].code` равным `timeout` возвращают методы поиска и [Список сотрудников](GET /users) с параметром `query`, когда запрос не уложился по времени. Такой запрос стоит сузить: повтор того же запроса, скорее всего, снова не уложится.</Info>
+
 <Info>Ответ `429 Too Many Requests` приходит в двух видах. Превышение суточного предела сообщений в чат — обычный `ApiError` с кодом `rate_limit`. Превышение лимита на частоту запросов обрабатывается до того, как запрос доходит до метода: тело не `JSON`, а короткий текст с `Content-Type: text/plain`. Разбирайте тело `429` только после проверки `Content-Type`, иначе разбор упадёт. Заголовок `Retry-After` есть в обоих случаях. Подробнее — на странице [Лимиты](/api/limits).</Info>

apps/docs/content/api/models.mdx

@@ -25,6 +25,9 @@ hideTableOfContents: true
   <Card title="Черновик" href="#chernovik" methods="GET POST PUT DELETE" />
   <Card title="Представление" href="#predstavlenie" methods="POST" />
   <Card title="Параметры бота" href="#parametry-bota" methods="POST, GET, PUT, DELETE" />
+  <Card title="Бот в методах самого бота" href="#bot-v-metodah-samogo-bota" methods="PUT POST" />
+  <Card title="Токен бота" href="#token-bota" methods="GET POST PUT DELETE" />
+  <Card title="Каталог прав бота" href="#katalog-prav-bota" methods="GET" />
   <Card title="Параметры бота пространства" href="#parametry-bota-prostranstva" methods="GET" />
   <Card title="Событие исходящего вебхука" href="#sobytie-ishodyaschego-vebhuka" methods="GET DELETE" />
   <Card title="Событие аудита" href="#sobytie-audita" methods="GET" />
@@ -101,6 +104,7 @@ hideTableOfContents: true
 - [Редактирование чата](PUT /chats/{id})
 - [Архивация чата](PUT /chats/{id}/archive)
 - [Разархивация чата](PUT /chats/{id}/unarchive)
+- [Отметка чата непрочитанным](PUT /chats/{id}/unread)
 - [Редактирование роли](PUT /chats/{id}/members/{user_id})
 - [Выход из чата](DELETE /chats/{id}/leave)
 - [Исключение пользователя](DELETE /chats/{id}/members/{user_id})
@@ -173,12 +177,34 @@ hideTableOfContents: true
 - [Информация о боте](GET /bots/{id})
 - [Редактирование бота](PUT /bots/{id})
 - [Удаление бота](DELETE /bots/{id})
-- [Саморегистрация вебхука бота](PUT /bot/webhook)
 - [Ротация токена бота](POST /bots/{id}/recreate_token)
-- [Ротация собственного токена бота](POST /bot/recreate_token)
+- [Ротация секрета клиента](POST /bots/{id}/rotate_client_secret)
 
 <ModelSchema name="BotResponse" />
 
+## Бот в методах самого бота
+
+- [Саморегистрация вебхука бота](PUT /bot/webhook)
+- [Ротация собственного токена бота](POST /bot/recreate_token)
+
+<ModelSchema name="BotSelfResponse" />
+
+## Токен бота
+
+- [Список токенов бота](GET /bots/{id}/tokens)
+- [Новый токен бота](POST /bots/{id}/tokens)
+- [Изменение токена бота](PUT /bots/{id}/tokens/{token_id})
+- [Перевыпуск токена бота](POST /bots/{id}/tokens/{token_id}/reissue)
+- [Удаление токена бота](DELETE /bots/{id}/tokens/{token_id})
+
+<ModelSchema name="BotAccessToken" />
+
+## Каталог прав бота
+
+- [Каталог прав бота](GET /bots/{id}/scopes)
+
+<ModelSchema name="BotScopeCatalog" />
+
 ## Параметры бота пространства
 
 - [Список ботов пространства](GET /company/bots)

apps/docs/content/guides/bots/access.mdx

@@ -17,26 +17,22 @@ related:
 Чтобы бот получил доступ к закрытому каналу или беседе, его нужно добавить туда как участника. После добавления бот автоматически получает доступ ко всем тредам этого чата.
 
 Добавить бота в чат можно двумя способами:
-- Через интерфейс — в диалоге **Добавление участников** на вкладке **Интеграции**. Список доступных ботов зависит от настройки [Кто может добавлять бота в чаты](/guides/bots/setup#kto-mozhet-dobavlyat-bota-v-chaty).
-- Через API — метод [Добавление пользователей](POST /chats/{id}/members), передав `user_id` бота в `member_ids`.
+- Через интерфейс — в диалоге **Добавление участников** (в канале — **Добавление подписчиков**) на вкладке **Интеграции**. Список доступных ботов зависит от настройки [Кто может добавлять бота в чаты](/guides/bots/settings#kto-mozhet-dobavlyat-bota-v-chaty).
+- Через API — метод [Добавление пользователей](POST /chats/{id}/members), передав `id` бота в `member_ids`. Настройка действует и здесь: если вам добавлять бота нельзя, метод ответит `403` с кодом `bot_add_denied` и не добавит никого из запроса.
 
 ## Треды
 
 Бота можно добавить напрямую в тред — без добавления в родительский чат. Это возможно благодаря [сквозным тредам](/guides/threads#skvoznye-tredy) Пачки: участник треда видит только сам тред и родительское сообщение, но не историю чата.
 
 Добавить бота в тред можно двумя способами:
 - Через API — метод [Добавление пользователей](POST /chats/{id}/members), передав `chat_id` треда.
-- Через упоминание `@никнейм_бота` в сообщении — доступно, когда бот настроен как **публичный**.
+- Через упоминание `@никнейм_бота` в сообщении — доступно, когда бот настроен как **публичный**, всем, кроме гостей и мульти-гостей.
 
 ## Личные сообщения
 
-Пользователь может писать боту личные сообщения и взаимодействовать с ним 1 на 1 в трёх случаях:
+Написать боту в личные сообщения сотрудник может, если бот публичный, у них есть общая беседа или канал или бот написал ему первым. Подробнее об этих случаях и о том, что происходит при первом сообщении, — в разделе [Первый диалог с ботом](/guides/bots/first-contact#kak-sotrudnik-popadaet-k-botu).
 
-- Бот настроен как **публичный** — любой участник пространства может начать диалог.
-- Бот сам ранее отправил пользователю [Новое сообщение](POST /messages) через API (с `entity_type: "user"`) — после этого пользователь может отвечать, даже если бот не публичный.
-- Бот и пользователь состоят в одной беседе или канале, и этот чат не в архиве — общего чата достаточно, чтобы открыть с ботом личную переписку.
-
-При этом бота нельзя добавить в существующие личные сообщения между двумя участниками пространства.
+Бота нельзя добавить в существующие личные сообщения между двумя участниками пространства.
 
 ## Поиск бота
 
@@ -46,7 +42,7 @@ related:
 
 Одинаково для всех ролей, включая гостей и мульти-гостей:
 
-- **Публичные боты** — везде в пространстве, даже если у пользователя нет с ними общих чатов.
+- **Публичные боты** — везде в пространстве, даже если у сотрудника нет с ними общих чатов.
 - **Непубличные боты-участники текущего чата** — дополнительно, когда `@` набирается внутри этого чата.
 
 Непубличные боты, не состоящие в текущем чате, в подсказках упоминаний не появляются.
@@ -55,18 +51,22 @@ related:
 
 Поиск из общей строки поиска и при создании личных сообщений ведёт себя по-разному в зависимости от роли:
 
-- **Сотрудники и администраторы** — видят и обычных пользователей, и публичных ботов в пространстве.
-- **Гости и мульти-гости** — видят **только тех, с кем уже есть личные сообщения**. Бот появится в выдаче только если с ним уже была переписка — например, потому что бот сам ранее отправил пользователю [Новое сообщение](POST /messages).
+- **Сотрудники и администраторы** — видят и сотрудников, и публичных ботов в пространстве.
+- **Гости и мульти-гости** — видят только тех, с кем у них уже есть личные сообщения, а по запросу от трёх символов — ещё и участников общих чатов.
+
+Непубличных ботов глобальный поиск не показывает никому, даже если бот уже писал сотруднику: такому боту отвечают в уже открытой переписке.
 
 ### Список добавления участников в чат
 
-Зависит от настройки [Кто может добавлять бота в чаты](/guides/bots/setup#kto-mozhet-dobavlyat-bota-v-chaty) каждого бота и роли пользователя:
+Зависит от настройки [Кто может добавлять бота в чаты](/guides/bots/settings#kto-mozhet-dobavlyat-bota-v-chaty) каждого бота и роли того, кто добавляет:
 
 - **Создатель бота** — всегда видит ботов, которых он создал.
-- **Администраторы** — видят ботов с настройками «Все участники», «Публичный бот», «Создатель и Администраторы».
-- **Сотрудники** — видят ботов с настройками «Все участники» и «Публичный бот».
+- **Администраторы** — видят публичных ботов и ботов с настройками «Все участники (кроме гостей)» и «Создатель и Администраторы».
+- **Сотрудники** — видят публичных ботов и ботов с настройкой «Все участники (кроме гостей)».
 - **Гости и мульти-гости** — в выдаче пусто.
 
+Бот с настройкой [Ограничить одним чатом](/guides/bots/settings#ogranichit-odnim-chatom), который уже состоит в беседе или канале, в списке не показывается никому, в том числе создателю.
+
 <Info>
-  Бот получает [исходящие вебхуки](/guides/webhook/overview) только из тех чатов и тредов, в которых он состоит. Глобальные события (например, изменение участников пространства) приходят без добавления в чат.
+  Бот получает [исходящие вебхуки](/guides/webhook/overview) из чатов, где он состоит, из тредов этих чатов и из тредов, куда его добавили. Без добавления в чат приходят изменения участников пространства, ссылки на домены бота и отправка форм, которые открыл бот.
 </Info>

apps/docs/content/guides/bots/examples.mdx

@@ -13,7 +13,7 @@ related:
 
 Автоматическое приветствие новых сотрудников в личных сообщениях. Три шаблона сообщений: `short`, `default`, `extended`. Развёртывание на Vercel или собственном сервере.
 
-<Info>Подробнее — в статье [Welcome Bot](https://www.pachca.com/blog-posts/welcome-bot) и на [GitHub](https://github.com/pachca/public-integrations/tree/main/welcome-bot)</Info>
+<Info>Подробнее — в статье [Welcome Bot](https://pachca.com/blog/welcome-bot) и на [GitHub](https://github.com/pachca/public-integrations/tree/main/welcome-bot)</Info>
 
 ## Review Bot
 
@@ -23,6 +23,6 @@ related:
 
 ## Unfurl-бот
 
-Бот для создания превью ссылок из рабочих сервисов (Trello, Kaiten, Пачка) прямо в чате. Когда пользователь отправляет ссылку, вместо простого URL все видят информативное превью с заголовком, описанием и изображением.
+Бот для создания превью ссылок из рабочих сервисов (Trello, Kaiten, Пачка) прямо в чате. Когда сотрудник отправляет ссылку, вместо простого URL все видят информативное превью с заголовком, описанием и изображением.
 
 <Info>Подробнее — в статье [Unfurl-бот](https://pachca.com/blog/unfurl-bot) и на [GitHub](https://github.com/pachca/public-integrations/tree/main/Unfurling-bot)</Info>