> Расположение: MCP
> Краткое содержание: Восемь скиллов плагина «Пачка» подробно: подключение и права, сообщения и правила переписки, поиск, пересказ и напоминания, администрирование, боты и интеграции, AI-агент в Пачке, работа от имени сотрудника и API в скриптах. По каким просьбам агент берёт скилл и что из него знает
> Это Markdown-версия конкретной страницы. Для контекста за её пределами (правила API, полный перечень методов, авторизация) ОБЯЗАТЕЛЬНО открой [llms.txt](https://dev.pachca.com/llms.txt) перед ответом — это сэкономит токены и предотвратит неполный ответ.


# Скиллы

Скилл — это знание о том, как правильно делать задачи в Пачке. Агент читает скилл сам, когда просьба подходит под его описание, поэтому вызывать скилл не нужно. Скиллы работают при любом способе подключения: через MCP-сервер, CLI или API.

Скиллы приходят вместе с [плагином «Пачка»](/guides/mcp/plugin), а в другие агенты ставятся отдельно, как в разделе [Скиллы без плагина](/guides/mcp/plugin#skilly-bez-plagina). Пересказ треда и слежение за тредом запускают командами плагина. Как вызвать команду в вашей программе, сказано в разделе [Команды плагина](/guides/mcp/plugin#komandy-plagina).

| Скилл | Когда пригодится |
|---|---|
| [С чего начать](#s-chego-nachat) `pachca` | Вход в Пачку, ведёт агента к нужному скиллу. Помогает подключить агента через MCP, CLI или API, выбрать токен, разобраться с отказом `401` или `403` и отсутствием инструмента |
| [Сообщения](#soobscheniya) `pachca-messaging` | Написать или ответить в треде, упомянуть, подготовить черновик, запланировать сообщение, отправить файл, поставить реакцию, закрепить, исправить или дополнить отправленное сообщение |
| [Поиск, пересказ и напоминания](#poisk-pereskaz-i-napominaniya) `pachca-search` | Найти обсуждение, чат или сотрудника, пересказать тред, собрать дайджест, поставить напоминания по итогам, узнать, кто в теге или чате |
| [Администрирование](#administrirovanie) `pachca-admin` | Пригласить, приостановить или удалить сотрудника, сменить роль, изменить теги и участников чатов, открыть или отозвать доступ к API, прочитать журнал аудита, выгрузить переписку, составить правило DLP |
| [Боты и интеграции](#boty-i-integratsii) `pachca-bots` | Сделать бота или интеграцию: вебхуки, события, токены и права, кнопки, формы, разворачивание ссылок, витрина |
| [AI-агент в Пачке](#ai-agent-v-pachke) `pachca-ai-agent` | Сделать AI-агента в виде бота, которого зовут упоминанием в чате или треде либо пишут ему в личный чат |
| [Работа от имени сотрудника](#rabota-ot-imeni-sotrudnika) `pachca-oauth` | Сделать бота, который работает от имени каждого сотрудника с его согласия |
| [API в скриптах и сервисах](#api-v-skriptah-i-servisah) `pachca-api` | Написать скрипт, сервис или задание CI: выбор токена, пагинация, ошибки и повторы, файлы, SDK и CLI |

## С чего начать

Скилл `pachca` — вход в Пачку для агента. С него агент начинает, когда подключается или не знает, какой скилл взять, и переходит к нужному: переписке, поиску, администрированию, ботам или API. Сам скилл отвечает за подключение: агент выбирает способ входа и токен, говорит, от чьего имени работает, и объясняет, почему не хватает прав или инструмента.

Агент берёт скилл по таким просьбам:

| Просьба | Что сделает агент |
|---|---|
| *«Подключи Пачку»*, *«Настрой MCP Пачки»* | Подскажет способ входа для вашей программы и проверит подключение |
| *«Войди в Пачку через CLI»* | Попросит выполнить вход в вашем терминале и проверит его |
| *«Каким токеном подключить агента?»* | Подберёт токен под задачу: персональный (вход через браузер, в CLI или готовый токен), токен бота или авторизацию бота от имени сотрудника |
| *«Что это за экран входа MCP?»* | Объяснит экран согласия и какое пространство получит доступ |
| *«Агент получил 403 `insufficient_scope`»* | Разберёт отказ и скажет, что поможет |
| *«Почему нет инструмента экспорта?»* | Назовёт роль, тариф или тип токена, которых не хватает |
| *«Что умеет Пачка?»* | Расскажет о возможностях и перейдёт к нужному скиллу |

Что агент знает из скилла:

| Тема | Что знает агент |
|---|---|
| Какой путь доступа выбрать | Сотруднику в программе с агентом подходит MCP-сервер. Для своей интеграции подходит API, а для агента, который живёт в Пачке, бот. Агенту с терминалом подойдёт и CLI: команды он узнаёт из `--help` и тратит меньше контекста. |
| Вход в программах с плагином | В Claude Code агент предложит войти через `/mcp` и не станет добавлять второй сервер вручную: сервер с тем же адресом скрыл бы сервер плагина. В Cursor вход не нужен: плагин берёт персональный токен из переменной `PACHCA_TOKEN`, и агент напомнит сохранить токен там и перезапустить Cursor. |
| Какой токен под задачу | Агенту на сервере, который отвечает многим сотрудникам, нужен токен бота: с персональным токеном все писали бы от вашего имени. Агенту только для чтения нужен отдельный персональный токен с правами на чтение и поиск. Боту, которому нужны данные самого сотрудника, например его напоминания, нужна авторизация от имени сотрудника, её ведёт скилл `pachca-oauth`. |
| Вход через браузер | Права входа агент не сужает: экран согласия их только показывает, а суженное подключение получает отказы `insufficient_scope`. Доступ получает пространство, открытое в браузере, поэтому для другого пространства агент предложит отозвать подключение, переключиться в Пачке и войти снова. |
| Вход в CLI | Команду `pachca auth login` вы выполняете в своём терминале: в командах, которые запускает агент, обычно нет диалога, и CLI сразу отказывает. Готовый токен агент советует передать через stdin, а не аргументом, который остаётся в истории команд, и никогда не просит прислать токен в чат. |
| От чьего имени работает агент | Через MCP имя, роль и тип токена агент берёт из инструкций сервера и не спрашивает, Владелец ли вы. Если программа не передала инструкции, агент читает ваш профиль, а через CLI спросит, Владелец ли вы: в профиле Владелец выглядит как администратор. Сообщения после входа через браузер или CLI помечены «Отправлено через …» с названием программы, а с персональным токеном выглядят как набранные вручную. |
| Почему нет инструмента | Сервер показывает только инструменты, которые подходят роли, тарифу и типу токена. Если инструмента нет, агент называет, чего не хватает, и не ищет обход через другие инструменты: экспорт и журнал аудита, например, есть только у Владельца на тарифе «Корпорация». |
| Отказ `401` | Токена нет, он истёк или отозван: после входа через браузер или CLI поможет новый вход, а готовый токен могли удалить, и нужен новый. После перевода сотрудника в гости токен отозван навсегда. |
| Отказ `403` | При `insufficient_scope` готовому токену добавляют право в его настройках, а после входа через браузер или CLI нужен новый вход: простое переподключение оставит прежние права. Отказ `role_forbidden` снимет только смена роли, а `403` без кода обычно значит, что вы не участник чата или ваша роль в нём ниже нужной. |
| Кто может подключиться | Гости не подключаются никак, а персональные токены, вход в CLI и вход в MCP через браузер по умолчанию есть только у администраторов. Если на экране согласия видно «Доступ к API ограничен администраторами пространства», агент объяснит, что Администратору нужно выбрать **Все сотрудники** в настройке **Кто может создавать персональные токены**, и не станет искать другой способ входа. |
| Смена роли и тарифа | После понижения роли токен работает в пределах новой роли. Инструмент, который стал доступен после смены роли или тарифа, появится только после переподключения сервера. |
| Отзыв доступа | Подключения через браузер отзываются в списке **Авторизации**, входы в CLI в списке **Токены CLI** на странице **Интеграции** > **API**. Для готового токена `pachca auth logout` только удаляет профиль с компьютера, а сам токен работает, пока его не удалят. |
| Подключение без плагина | Агент подскажет команду подключения для вашей программы и установку скиллов командой `npx skills add`. В программу с плагином агент скиллы отдельно не ставит: каждый загрузился бы дважды. |
| Куда передать задачу | Писать агент будет по скиллу `pachca-messaging`, искать по `pachca-search`, администрировать по `pachca-admin`. Бота, AI-агента в Пачке, приложение с OAuth и скрипты ведут скиллы `pachca-bots`, `pachca-ai-agent`, `pachca-oauth` и `pachca-api`. |

Когда агент сам спрашивает подтверждение в чате и как обращается с чужим текстом и секретами, описано в разделах [Подтверждение действий](/guides/mcp/overview#podtverzhdenie-deystviy) и [Безопасность](/guides/mcp/overview#bezopasnost). Подробнее — на страницах [Подключение к MCP](/guides/mcp/connect) и [Агенты и MCP в пространстве](/guides/agents-access).

## Сообщения

Скилл `pachca-messaging` агент читает всякий раз, когда что-то пишет в Пачку: сообщение, комментарий в треде, личное сообщение, черновик, отложенное сообщение, файл, реакцию, закрепление, отметку «Важное», правку или удаление. Аргументы описаны в самих инструментах, а скилл добавляет то, чего там нет: куда писать, когда сначала спросить и что ломает сообщение.

> В переписке с коллегами скилл `pachca-messaging` даёт агенту подходы по умолчанию, у каждого есть причина. Если вам нужно иначе, например чтобы агент писал коллегам в личные сообщения или ставил реакции по-другому, скажите об этом в просьбе или запишите своё правило в файл инструкций, который читает ваша программа, например `AGENTS.md` или `CLAUDE.md`: здесь ваши указания важнее подходов скилла. Как устроена Пачка и когда агент спрашивает перед необратимым действием, от указаний не зависит.


Агент берёт скилл по таким просьбам:

| Просьба | Что сделает агент |
|---|---|
| *«Напиши в чат «Релизы», что сборка готова»* | Найдёт чат по названию и отправит сообщение |
| *«Ответь Анне в треде, что макет готов»* | Ответит в тред, а не в общий чат |
| *«Напиши Максиму в личку, что встреча переносится на 15:00»* | Отправит личное сообщение, личный чат появится сам |
| *«Напиши в тред, что релиз готов, и упомяни Анну»* | Упомянет Анну, а если её нет в треде, сначала спросит: упоминание пригласит её в тред |
| *«Создай тред с Анной и Максимом про загрузку файлов»* | Покажет участников и текст первого сообщения, а после вашего «да» создаст самостоятельный тред |
| *«Подготовь черновик, я отправлю сам»* | Оставит черновик в поле ввода чата и скажет, в каком он чате |
| *«Напоминай в канал «Команда» каждый понедельник»* | Покажет текст, время и повтор, а после вашего «да» создаст отложенное сообщение |
| *«Отправь отчёт файлом .md»*, *«Приложи файл»* | Приложит файл к сообщению |
| *«Перешли сообщение в чат «Дизайн»»* | Отправит ссылку на сообщение или перепостит его от вашего имени |
| *«Поставь реакцию»*, *«Закрепи сообщение»* | Поставит реакцию или закрепит сообщение в шапке чата |
| *«Отметь как важное»* | Добавит сообщение в ваш раздел «Важное» |
| *«Исправь сообщение»*, *«Допиши к сообщению»* | Поправит сообщение, а если его уже прочитали, напишет дополнение ответом |
| *«Ты написал не то»* | Сразу исправит своё сообщение по тем же правилам и скажет, что поменял, не спрашивая заново |

Что агент знает из скилла:

| Тема | Что знает агент |
|---|---|
| Уведомления | Каждое сообщение приходит уведомлением, поэтому несколько коротких сообщений уведомят несколько раз. Упоминания, правку и разметку агент учитывает, как сказано в строках ниже. |
| Подходы к переписке | Для каждого случая агент знает варианты и когда какой подходит: где спросить коллегу (тред под сообщением, самостоятельный тред или личные сообщения), как начать, чем подтвердить, кого упомянуть, когда вмешаться, как ждать ответа и подвести итог. Без ваших указаний агент выбирает тред, пишет суть в первом сообщении и ставит реакцию только на то, по чему что-то сделает: реакцию часто читают как ответ «увидел, занимаюсь». |
| Что пишете вы сами | Извинения, благодарность за работу и отзыв о работе коллеги несут ваш голос, поэтому агент предлагает черновик. |
| Куда писать | Чтобы обсудить одно сообщение, агент пишет в тред под ним, а ответ, который должен остаться в ленте чата, отправляет с цитатой. Если разговор идёт в треде, агент отвечает в этот тред, а не в общий чат. |
| Новый тред и новый чат | Тред агент открывает, только если вы о нём просили или продолжаете его: удалить тред нельзя. Обсуждение в новом треде агент сразу начинает первым сообщением, а тред, который команда `watch-thread` открыла, чтобы следить за сообщением, может остаться пустым. Новый чат агент создаёт только по прямой просьбе. |
| Где писать нельзя | Подписчик канала пишет только в треды под сообщениями канала, поэтому вместо отказа `403` агент предложит тред. В открытом чате, где вы не участник, агент ответит в тред, который уже есть под сообщением, а чтобы написать в сам чат, нужно вступить в него. В архивный чат писать нельзя, и разархивировать его агент сам не станет. |
| Разметка Пачки | Списки, таблицы и цитаты в сообщении остаются простым текстом, поэтому агент пишет короткими абзацами с жирными вводными словами. Теги HTML и заготовки вроде `<name>` пропадают, иногда вместе со строками ниже, линии `---` тоже исчезают, а у ссылки без схемы, например `https://`, остаётся только подпись. |
| Длинный ответ | Таблицу, чек-лист, схему или длинный отчёт агент прикладывает файлом `.md`: если это единственный документ в сообщении и он не слишком большой, Пачка показывает его карточкой. Текст длиннее 40 000 байт, это около 20 000 кириллических символов, тоже уходит файлом. |
| Упоминания | Агент упоминает по `id` сотрудника или по нику из ответа инструмента: ник, придуманный из имени, никого не упомянет. В черновике агент пишет `@nickname`, потому что форма с `id` при отправке из поля ввода остаётся текстом. В беседе или канале упоминание доходит только до участников чата. |
| Упоминание в треде | Упоминание в треде приглашает: упомянутый сотрудник увидит тред и родительское сообщение. При включённых [сквозных тредах](/guides/threads#skvoznye-tredy) это касается и сотрудников вне чата, а упоминание тега добавит всех сотрудников тега. При выключенных добавятся только участники чата, а в самостоятельный тред никто. Упоминания `@all` и `@here` никого не добавляют. Назвать сотрудника для контекста агент может и без приглашения, тогда сотрудник вне треда не получит и уведомления. |
| Участники треда | Позвать сотрудника в тред можно и без упоминания, добавив его в участники через `pachca_add_members`. Это работает при любой настройке сквозных тредов, но никого не уведомляет, поэтому в самостоятельный тред агент добавляет участников и упоминает каждого в первом сообщении. Мульти-гость зовёт в тред только упоминанием. |
| Черновик | На «подготовь», «я проверю», «отправлю сам» агент оставляет черновик в поле ввода чата и говорит, где он: Пачка о черновике не уведомляет. В чате бывает только один черновик: если он уже есть, агент сначала читает его и обновляет, а не создаёт второй, и объединит свой текст с вашим, если вы попросите. С токеном бота черновиков нет. |
| Отправка черновика | Отдельного метода нет: агент отправляет обычное сообщение с содержимым черновика, и черновик удаляется после отправки. Всё, чего нет в сообщении, пропадает вместе с черновиком, поэтому агент переносит текст, цитату и файлы. |
| Отложенные сообщения | Повторяющееся сообщение агент записывает во времени UTC: сообщение на `10:00+03:00` каждый понедельник ушло бы в 13:00 по Москве. После создания агент сверяет время первой отправки с вашей просьбой. Просьба «напомни мне завтра в 9:00» — это напоминание, его агент ставит по скиллу `pachca-search`. |
| Файлы | Небольшой текст, который агент написал сам, он передаёт содержимым в вызове MCP, а документ или картинку с диска загружает и прикладывает по ключу. В чате приложения Claude файл с диска не загрузить: агент скажет об этом и предложит приложить файл в Пачке вручную или сделать черновик с текстом. |
| Пересылка | Метода пересылки в API нет: агент отправит ссылку на сообщение или перепостит его от вашего имени без пометки о пересылке. Настоящую пересылку вы делаете кнопкой **Переслать** в приложении. |
| Реакции, закрепление и «Важное» | Реакция на сообщение с тредом подписывает вас на этот тред. Закреплённое сообщение видят все участники чата, а в тредах закрепления нет. «Важное» — личная отметка, которую видите только вы. |
| Правка или дополнение | Правка никого не уведомляет. Чтобы поправить или дополнить отправленное, агент сначала готовит текст, а прямо перед отправкой проверяет, кто прочитал сообщение (`pachca_list_message_readers`): его могут прочитать, пока агент работает. Если адресаты его ещё не прочитали, агент правит его, и они прочитают исправленный текст. Если прочитали, правку не заметят, поэтому агент пишет дополнение ответом на исходное сообщение. Если исходный текст должен остаться верным, например в длинном сообщении, к которому будут возвращаться, агент правит его и коротко отвечает, что изменил. Если вы указали на ошибку в сообщении, которое агент отправил за вас, он исправляет его сразу и не спрашивает разрешения. |
| Файлы при правке | Файлы при правке заменяются целиком: агент передаёт снова те, что нужно оставить, иначе они удалятся из хранилища. Любая правка убирает превью ссылок. |
| Удаление | Удалённое сообщение исчезает у всех вместе с файлами и реакциями, и восстановить его нельзя, а тред под ним остаётся. Чужие сообщения могут удалять админы и редакторы чата. |
| Лимиты и превью | На `429` агент ждёт не меньше, чем просит Пачка, а если пауза длиннее минуты, останавливается и сообщает вам. Через MCP превью ссылки не строится, а в CLI и API агент включает его, только если вы попросили превью своей ссылки. |

Если в просьбе есть текст и адресат, агент отправляет сразу, а разрешение спрашивает программа. Отправленное не вернуть: уведомление уже ушло, а удаление оставляет пометку «Сообщение удалено». Поэтому агент покажет адресат и итоговый текст и дождётся вашего «да», если:

- текст или адресат не заданы точно, или агент открыл бы тред, о котором вы не просили
- сообщение уходит многим сразу или большему числу адресатов, чем вы назвали, в том числе с `@all` или `@here`, которых вы не просили
- упоминание в треде пригласит сотрудника, которого там нет, даже если вы его назвали
- текст, время или повтор отложенного сообщения агент заполнил сам
- нужно исправить или удалить сообщение, на которое вы не дали ссылку
- сообщение из закрытого чата или личной переписки переносится в чат с другими читателями
- чтобы написать в открытый чат, агенту нужно в него вступить

Кнопки, формы и нажатия агент делает по скиллу `pachca-bots`, напоминания и чтение «Важного» по `pachca-search`, загрузку файлов из кода по `pachca-api`. Подробнее — на страницах [Черновик вместо отправки](/guides/ai-agents/drafts), [Оформление ответов](/guides/ai-agents/markdown) и [Треды](/guides/threads).

## Поиск, пересказ и напоминания

Скилл `pachca-search` агент читает, чтобы найти обсуждение, чат или сотрудника, пересказать тред, собрать дайджест и поставить напоминания себе или коллегам. В Пачке несколько поисков и лент, и каждый охватывает свою часть пространства. Чаще всего ответ выходит неверным из-за неподходящего поиска, чтения только первой страницы или неверного `id` треда, и скилл учит агента этого избегать.

Агент берёт скилл по таким просьбам:

| Просьба | Что сделает агент |
|---|---|
| *«Найди, где обсуждали переезд на новый сервер»* | Поищет по сообщениям и даст ссылку на каждое найденное |
| *«Кто писал про релиз?»* | Найдёт сообщения по теме и назовёт авторов |
| *«Где меня упоминали?»* | Поищет упоминания по вашему имени, нику и тегам |
| *«Найди чат «Продажи»»*, *«Найди Максима из отдела продаж»* | Найдёт чат по названию или сотрудника по имени, должности и отделу |
| *«Перескажи тред»* | Прочитает тред целиком и перескажет решения, открытые вопросы и задачи |
| *«Что было в канале за неделю?»*, *«Дайджест»* | Соберёт дайджест за период со ссылками на сообщения |
| *«Какие решения приняли?»*, *«Поставь задачи по итогам»* | Выделит решения и поручения, а напоминания коллегам поставит после вашего «да» |
| *«Напомни мне завтра в 9:00»* | Поставит напоминание, и Пачка уведомит вас в срок |
| *«Мои напоминания»* | Покажет напоминания, где исполнитель вы |
| *«Что у меня в «Важном»?»* | Покажет сообщения, которые вы отметили |
| *«Кто в теге «Дизайн»?»*, *«Кто в чате?»* | Покажет сотрудников тега или участников чата |

Что агент знает из скилла:

| Тема | Что знает агент |
|---|---|
| Что видит агент | Поиск и ленты отвечают от имени владельца токена, поэтому агент видит ваши чаты. Мульти-гость не видит открытые чаты, куда его не добавили, даже их ленту. |
| Какой поиск что охватывает | Тему агент ищет по сообщениям, потому что поиск чатов смотрит только названия. Открытый чат, где вы не участник, поиск по сообщениям не охватывает, и такой чат агент читает по ленте. |
| Треды, которые поиск пропускает | Если не указать чаты, поиск пропускает самостоятельные треды, треды в личных чатах и треды, в родительском чате которых вас нет. Их агент берёт из списка тредов и ищет в них отдельно, а вывод «никто не обсуждал» из пустого поиска не делает. |
| Чего в Пачке нет | Списка непрочитанного нет, поэтому «что нового» агент превращает в период, например «со вчерашнего вечера», и называет его в ответе. |
| Упоминания | Фильтра по упоминаниям нет: агент ищет имя и фамилию в кавычках, потом ник и названия ваших тегов, потому что упоминание тега не содержит ни имени, ни ника. Из найденного агент оставляет только сообщения, где вас действительно упомянули. |
| Запрос | Поиск по сообщениям учитывает формы слов, но не исправляет опечатки, поэтому без результата агент пробует другую форму или синоним. Имена агент не переводит: «Анна» не станет «Anna». |
| Чтение треда | Тред агент читает по его собственной ленте, а не по ленте родительского чата, и отдельно берёт сообщение, под которым открыт тред: в ленте треда его нет. |
| Полное чтение | Перед пересказом агент проходит все страницы до конца и читает по порядку времени, потому что позднее сообщение отменяет раннее. Первую страницу агент не выдаёт за весь тред. |
| Даты | Период агент записывает с вашим часовым поясом: «вчера» заканчивается в конце дня по вашему времени. Время в ответах приходит в UTC, и агент переводит его в ваш пояс, прежде чем назвать день или час. |
| Дайджест | По каждому чату агент собирает решения, вопросы к вам, вопросы без ответа и ближайшие сроки, со ссылкой у каждого пункта. В конце агент называет охват, например «12 чатов, 340 сообщений, 9 тредов», и чего не видел. |
| Решения и поручения | Решением агент считает только подтверждённое, а предложение, которое никто не подтвердил, относит к открытым вопросам. Автора агент берёт из данных сообщения, а если в обсуждении нет ответственного или срока, оставляет поле пустым и говорит об этом. |
| Голосовые и файлы | Голосовое без расшифровки агент отмечает как пропущенное и не придумывает его содержание. Файл, который агент не открывал, он не пересказывает. |
| Напоминания | Напоминание коллеге агент явно назначает на него: без этого исполнителем станете вы. День без часа становится напоминанием на весь день, а не на выдуманное время. |
| Привязка напоминания к чату | Привязать напоминание можно к беседе или личному чату, где вы участник, но не к каналу и не к треду. В открытой беседе привязанное напоминание может прочитать любой сотрудник, поэтому личное агент не привязывает. |
| Список напоминаний | «Мои напоминания» агент отбирает по вам как исполнителю: без фильтра в списке есть и напоминания коллег из общих чатов. Поиска по тексту и фильтра по сроку нет, поэтому агент читает все страницы и отбирает сам. |
| Изменение напоминаний | Сделанное агент закрывает отметкой о выполнении, а не удалением. Передача напоминания заменяет весь список исполнителей, поэтому агент сначала читает текущий список и сохраняет тех, кто остаётся. |
| Теги | Тег агент ищет по полному названию без учёта регистра: «дизайн» найдёт «Дизайн», а «дизайнеры» нет. Если ничего не нашлось, агент просматривает все теги и выбирает ближайшее название. |
| Дайджест для других | Дайджест агент публикует только в чат, участники которого видят все чаты-источники: иначе туда попали бы сообщения из закрытых чатов и личной переписки. |
| Список всех чатов | Список всех чатов пространства, который есть у Владельца на тарифе «Корпорация», агент для поиска не берёт: каждый вызов записывается в журнал аудита, и этот инструмент относится к скиллу `pachca-admin`. |

Одно напоминание, которое вы продиктовали, агент ставит сразу. Сначала он спросит, если:

- из обсуждения получилось несколько напоминаний для коллег: агент покажет список (что, кто, к какому сроку) и поставит их после вашего «да»
- ответственный не назван или под имя подходят два сотрудника: молча назначать такое напоминание вам агент не станет
- под название подходят два тега
- напоминание нужно удалить: агент назовёт его и предложит отметить выполненным, потому что удаление окончательное
- напоминание нужно перенести в другой чат: для этого его приходится удалить и создать заново

Публикует результат агент по скиллу `pachca-messaging`, теги и участников меняет по `pachca-admin`, а файл, чтобы прочитать его, скачивает по `pachca-api`. Подробнее — на страницах [Треды](/guides/threads) и [Теги](/guides/tags).

## Администрирование

Скилл `pachca-admin` нужен Владельцу и Администраторам: сотрудники, теги, участники чатов, роли, доступ к API, журнал аудита, экспорт и защита данных. Каждое такое действие меняет, что видят и могут другие сотрудники, поэтому скилл прежде всего учит агента, кто что может и когда сначала спросить.

Агент берёт скилл по таким просьбам:

| Просьба | Что сделает агент |
|---|---|
| *«Пригласи anna@example.com»* | Пригласит сотрудника с ролью, которую вы назовёте |
| *«Удали Максима из Пачки»*, *«Уволь сотрудника»* | Найдёт сотрудника и спросит, удалить насовсем или приостановить |
| *«Сделай Анну администратором»* | Сменит роль и напомнит, что роли в чатах не изменятся |
| *«Добавь Максима в тег «Дизайн»»* | Добавит тег и сохранит остальные теги сотрудника |
| *«Добавь Анну в чат «Продажи»»*, *«Удали участника чата»* | Добавит или удалит участника |
| *«Кто в закрытом канале, где я не состою?»* | Покажет участников, если вы Владелец |
| *«Доступ к API ограничен»* | Назовёт настройку пространства, которую нужно переключить |
| *«Отзови доступ сотрудника к API»* | Подскажет, где отозвать доступ на вкладке **Все токены** |
| *«Покажи журнал аудита за неделю»* | Подберёт типы событий и запросит их |
| *«Выгрузи переписку канала за сентябрь»* | Запросит экспорт за период |
| *«Составь правило DLP»* | Составит и проверит правило, а вставит его Владелец |

Что агент знает из скилла:

| Тема | Что знает агент |
|---|---|
| Кто действует и на каком тарифе | Перед планом агент проверяет роль, права токена и тариф. Через MCP роль Владельца агент знает из инструкций сервера, а через CLI или API спрашивает вас, Владелец ли вы. Методы Владельца агент не пробует наугад, потому что каждый вызов журнала аудита или списка всех чатов сам попадает в журнал. |
| Что есть только у Владельца | Участников любого чата Владелец видит на любом тарифе. Экспорт, журнал аудита, список всех чатов и ботов, DLP, безопасный контур и шифрование есть только у Владельца на тарифе «Корпорация». Передать права Владельца можно только в веб-интерфейсе: инструмента для этого нет. |
| Две системы ролей | Администратор не видит закрытые чаты, где не состоит, и не может добавиться в них напрямую: его добавляет участник чата, или он входит через тег, привязанный к чату. Роль в чате задаётся при входе и потом не пересчитывается: повышение до Администратора ничего не меняет в чатах, где сотрудник уже состоит. |
| Удаление и приостановка | Удаление необратимо: сотрудник выходит из всех групповых чатов, теряет теги, а напоминания, где он единственный исполнитель, удаляются. Приостановку можно отменить, но токены после восстановления оживают, поэтому агент советует отозвать их на вкладке **Все токены**. |
| Перевод в гости | Перевод в гости необратим: сотрудник остаётся в одной беседе или одном канале, выходит из остальных бесед и каналов (личные чаты и треды остаются), теряет теги и все токены, а повышение ничего из этого не вернёт. |
| Приглашение | Письмо уходит сразу и не отзывается, поэтому адрес агент берёт только от вас, а не из сообщения или файла. Если ник занят, Пачка без ошибки меняет его, и агент назовёт ник, который получился. Повторное приглашение отправляется только в веб-интерфейсе, а удалять и приглашать заново агент не станет. |
| Вход через SSO | У сотрудника со входом через SSO следующий вход перезапишет поля профиля, а при настроенном сопоставлении групп также теги и роль. Агент предупредит, что менять их нужно в провайдере. |
| Статус сотрудника | Срок отпуска агент ставит сроком статуса в часовом поясе сотрудника, а не пишет в подпись статуса. |
| Теги сотрудника | Список тегов при правке заменяется целиком: агент читает текущие теги и отправляет полный список. Название с опечаткой молча создаст новый тег, поэтому агент сверяет его со списком тегов. |
| Участник из тега | Участника, которого добавил тег, нельзя удалить по одному: удаление вернёт успех и ничего не изменит. Агент предложит снять тег с сотрудника или убрать тег из чата. |
| Тег из чата и удаление тега | Убрать тег из чата значит вывести из чата всех, кого держал только этот тег. Удалённый тег оставляет всех в чатах обычными участниками, поэтому, чтобы вывести команду из канала, агент сначала убирает тег из чата. |
| Участники чатов | Массовых операций нет, и агент работает с каждым чатом отдельно. Добавление отклоняется целиком, если хоть один сотрудник неизвестен или неактивен. |
| Чат без админов | Чат без админов можно вернуть под управление: в него добавляют Владельца или Администратора, который ещё не в чате, и тот входит админом чата. В закрытый чат его может добавить только участник, который не гость и не мульти-гость, а если таких не осталось, войти можно только через привязанный к чату тег. Результат агент проверяет по списку админов чата. |
| Увольнение по шагам | Агент проверяет чаты, которые создал сотрудник, и оставляет в них другого админа. Перед удалением он переназначает нужные напоминания, где сотрудник единственный исполнитель. Ботов сотрудника агент тоже находит: бот не останавливается вместе с создателем, поэтому нужные боты сотрудник, пока он активен, открывает для редактирования Администраторам, а остальные удаляет. Потом агент приостанавливает или удаляет сотрудника и просит Администратора отозвать его токены на вкладке **Все токены**. |
| Доступ к API | Если сотрудники не могут подключить агента, обычно настройка **Кто может создавать персональные токены** стоит на **Только администраторы**. Вторая настройка, **Кто может создавать интеграции**, решает, кто создаёт ботов и их токены. Обе закрывают только новый доступ, а выданный отзывается на вкладке **Все токены**. Настройки есть только в веб-интерфейсе, и агент скажет, где их переключить. |
| Журнал аудита | Агент сначала сопоставляет вопрос с типами событий. При смене роли и изменении участников чата действующим лицом записан сам сотрудник, а кто это сделал, агент берёт из деталей события. |
| Экспорт | Период агент берёт у вас: до 45 дней, а для выбранных чатов до 366. Архив содержит закрытые чаты независимо от участия, и агент предупреждает, что данные чувствительные. Скачать архив может только тот, кто его запросил, в течение 7 дней. |
| Правила DLP | Правило агент составляет в JSON и проверяет на примерах, а вставляет его Владелец в веб-интерфейсе. Агент предупредит, что действие `BLOCK` не оставляет в журнале записи о срабатывании, и предложит `BLOCK_AND_AUDIT_LOG`, если блокировки должны быть видны. |
| Безопасный контур и шифрование | Этих настроек нет в API, и агент предупреждает о последствиях. Очистка списка адресов остановит скачивание защищённых файлов, а смена ключа или отключение шифрования сделает старые сообщения нечитаемыми. |

Ясную просьбу, например «сделай Анну администратором», агент выполняет сразу, а разрешение спрашивает программа. В чате агент сначала назовёт, кого и что затронет изменение, и дождётся вашего «да», если:

- сотрудника или объект агент выбрал сам, например из нескольких найденных
- шаг нельзя отменить, хотя подошёл бы обратимый, как удаление вместо приостановки
- изменение затрагивает многих сразу: нескольких сотрудников, тег, который убирают из чата или удаляют, или участников нескольких чатов
- сотрудника переводят в гости: он сразу теряет теги, все токены и все беседы и каналы, кроме одного

Одно «да» относится к одному действию, а не к пакету, которого вы не видели. О последствиях остальных действий агент пишет в отчёте: например, что приглашение уже ушло на почту или что при архивации чата из него удалены гости.

> **Внимание:** Просьба «удали сотрудника» для агента не подтверждение. Агент найдёт сотрудника, назовёт имя, ник и `id`, скажет, что удаление нельзя отменить и что оно уберёт, предложит приостановку и спросит «Удалить насовсем или приостановить?». Удалит он только после вашего ответа «удалить» в следующем сообщении. Окно подтверждения в программе этот вопрос не заменяет: его можно выключить, и в нём виден вызов инструмента с `id`, а не то, кто что потеряет.


Отсутствующий инструмент и общие отказы `401` и `403` агент разбирает по скиллу `pachca`, состав тега или чата смотрит по `pachca-search`, а собственные токены бота меняет по `pachca-bots`. Подробнее:

- [Права и роли](/guides/permissions)
- [Теги](/guides/tags)
- [Агенты и MCP в пространстве](/guides/agents-access)
- [Журнал аудита событий](/guides/audit-events)
- [Экспорт сообщений](/guides/export)
- [DLP-система](/guides/dlp)
- [Шифрование и безопасный контур](/guides/data-protection)

## Боты и интеграции

Скилл `pachca-bots` помогает выбрать, на чём построить интеграцию, и настроить бота так, чтобы он получал события и отвечал. Бот в Пачке — служебный участник пространства: он состоит в чатах, пишет и получает события от своего имени, и на нём построена любая интеграция. Подробнее — на странице [Боты](/guides/bots/overview).

Агент берёт скилл по таким просьбам:

| Просьба | Что сделает агент |
|---|---|
| *«Сделай, чтобы уведомления из CI приходили в чат»* | Предложит входящий вебхук и предупредит, что он пишет во все беседы и каналы бота, а для одного чата понадобится токен бота |
| *«Бот не получает сообщения»* | Проверит по порядку адрес вебхука, событие **Новые сообщения**, режим сообщений и участие бота в чате, а по истории событий поймёт, дело в настройках или в обработчике |
| *«Как проверить подпись вебхука?»* | Посчитает подпись по исходному телу запроса до разбора JSON и добавит проверку свежести `webhook_timestamp` |
| *«Добавь в сообщение бота кнопки и форму»* | Напомнит, что кнопки отправляются токеном бота, нужно событие **Нажатие кнопок**, а форма открывается в первые 3 секунды после нажатия, поэтому нужен обработчик: агент в разговоре с вами в это окно не успевает |
| *«Сделай превью для ссылок на наш сервис»* | Скажет, что событие разворачивания ссылок и его домены включает только Администратор или Владелец |
| *«Какие права дать токену бота?»* | Предложит отдельный токен на каждый сервис с минимальным набором прав |
| *«Токен бота утёк»* | Перевыпустит токен и предупредит, что старое значение перестаёт работать сразу и каждому сервису с этим токеном нужен новый |
| *«Опубликуй бота в витрине»* | Подскажет, что для витрины нужны включённая авторизация и сохранённое описание, а публикация не даёт писать боту, поэтому опубликованного бота делают ещё и публичным |

Что агент знает из скилла:

| Тема | Что знает агент |
|---|---|
| Какую интеграцию выбрать | Уведомлениям из сервиса хватит входящего вебхука. Чтобы отвечать сотрудникам, нужны исходящий вебхук и токен бота, а для работы с данными сотрудника нужна авторизация от его имени. |
| Что видит бот | Бот видит открытые беседы и каналы с их тредами, а закрытые чаты и треды только после добавления. Чужие личные чаты он не видит никогда. |
| Первые шаги | Токен бота, созданного через API, показывается один раз, а потерянный токен только перевыпускают. Новый бот не состоит ни в одном чате и слушает команды с пустым списком, поэтому ничего не слышит. |
| Токены и права | Права открывают методы, но не расширяют видимость данных. Токен бота бессрочный и действует, пока его не перевыпустят, не удалят или не удалят самого бота. |
| Доступ к тредам и личным чатам | Упоминание в треде добавляет только публичного бота, а новый бот непубличный, поэтому его добавляют участником треда. Открытие личного чата с ботом события не присылает: бот узнаёт о сотруднике из первого сообщения или пишет первым. |
| Ответы в беседах | Режима, в котором приходят только упоминания, нет, поэтому бот в режиме **Любые сообщения** получает все сообщения и решает сам. Отвечает он в треде и пропускает сообщения других ботов, чтобы два бота не отвечали друг другу бесконечно. |
| Приём событий | Обработчик сразу отвечает `200`, а работу ставит в очередь: Пачка ждёт ответа 5 секунд и повторяет событие, только если не смогла подключиться. По перенаправлениям Пачка не идёт, поэтому адрес вебхука должен быть конечным. |
| Защита от дублей | Событие изредка приходит дважды, поэтому ключ защиты от дублей для каждого типа событий свой. Изменение сообщения приходит и без правки, например когда сообщение добавили в «Важное». |
| История событий | Бот без публичного адреса читает историю событий опросом или потоком в реальном времени. Обработанные записи он удаляет сам, иначе они приходят снова. |
| Кнопки и формы | Форма открывается только нажатием Data-кнопки в сообщении бота, а `trigger_id` для неё живёт 3 секунды. На отправку формы бот отвечает за 3 секунды, а бот без адреса вебхука за 5. |
| Разворачивание ссылок | Доменов не больше 5, а ссылки на них бот получает из всех чатов, даже из тех, где не состоит. Одна неверная ссылка в запросе отменяет все превью. |
| Входящий вебхук | Ответ `200` не значит, что сообщение опубликовано. Если шаблон дал пустой текст, текст длиннее лимита или бот не состоит ни в одной беседе и ни в одном канале, в чат ничего не придёт. |
| Публичный бот | Публичного бота находят в поиске и на вкладке **Обзор**, написать ему может любой, а добавить в чат любой сотрудник, кроме гостей. |

Когда агент спрашивает, о чём предупреждает и чего не делает:

| Действие | Что делает агент |
|---|---|
| Удаление бота | Если вы Владелец или Администратор, спрашивает и предлагает вместо удаления приостановить бота: приостановку можно отменить, а после удаления токены отзываются, вебхуки и авторизации перестают работать. |
| Ограничение **Кто может добавлять бота в чаты** или включение **Ограничить одним чатом** | Спрашивает: бот сразу выйдет из тегов и чатов, куда попал через теги. |
| Отключение OAuth (**Удаление OAuth-клиента**) | Спрашивает: все выданные авторизации сразу отзываются. |
| Новый бот или токен | Показывает токен только вам в ответе, не пишет его в чат и не сохраняет в репозиторий. |
| Новый адрес входящего вебхука или **Signing secret** после утечки | Предупреждает, что интеграция не работает, пока сервис или обработчик не получит новое значение. Настройки вебхука агент записывает до удаления и восстанавливает после. |

Соседние задачи агент ведёт по другим скиллам: AI-агента, который отвечает в тредах, по `pachca-ai-agent`, работу от имени сотрудника по `pachca-oauth`, скрипты, пагинацию и ошибку `429` по `pachca-api`.

Подробнее — на страницах [Доступы к чатам и сообщениям](/guides/bots/access), [Токены бота](/guides/bots/tokens), [Настройка и типы событий](/guides/webhook/events), [Безопасность и обработчик](/guides/webhook/handler), [Обработка форм](/guides/forms/handling) и [Витрина](/guides/bots/showcase).

## AI-агент в Пачке

Скилл `pachca-ai-agent` помогает сделать AI-агента, который живёт в Пачке в виде бота. Его зовут упоминанием в чате или треде либо пишут ему в личный чат, а он собирает контекст, показывает, что работает, и отвечает там же. В этом разделе такой агент называется агентом-ботом, чтобы не путать его с агентом, который читает скилл.

Агенту, который работает в Пачке от вашего имени из программы на вашем компьютере, нужны скиллы `pachca`, `pachca-messaging` и `pachca-search`. Как устроен агент-бот — на странице [Взаимодействие с агентом](/guides/ai-agents/interaction).

Агент берёт скилл по таким просьбам:

| Просьба | Что сделает агент |
|---|---|
| *«Сделай AI-агента, который отвечает, когда его упоминают в треде»* | Предложит настройку бота: исходящий вебхук, событие **Новые сообщения** в режиме **Любые сообщения**, права токена и проверку, к агенту-боту ли обращаются |
| *«Агент не слышит упоминание»* | Проверит, публичный ли бот: упоминание в треде не добавляет непубличного бота, а новый бот непубличный |
| *«Как агенту собрать контекст треда?»* | Покажет, что читать: историю треда по `chat_id` из события, родительское сообщение, сообщение, на которое ответили, и вложения |
| *«Как показать, что агент работает?»* | Предложит реакцию `agent-thinking`: вместо счётчика Пачка покажет таймер |
| *«Пусть длинный ответ приходит карточкой .md»* | Объяснит, как загрузить файл `.md` и что он должен быть единственным документом сообщения |
| *«Бот или MCP?»* | Сравнит, от чьего имени пишет агент и что он видит, и выберет бота, если агента зовут в Пачке |
| *«Пусть агент отвечает в личных сообщениях»* | Скажет, что написать боту сотрудник может, если бот публичный, у них есть общий чат не в архиве или бот написал первым |

Что агент знает из скилла:

| Тема | Что знает агент |
|---|---|
| Бот или MCP | Агент-бот пишет от имени бота и видит то, что видит бот. Агент через MCP пишет от имени сотрудника, чьим токеном подключён, а агент-бот может вызывать MCP-сервер и с токеном бота. |
| Настройка бота для агента | Для каждого агента заводят отдельного бота с событием **Новые сообщения** в режиме **Любые сообщения** и включённым **Игнорировать свои сообщения**, иначе агент-бот ответит сам себе. Если в ответах будут кнопки или формы, нужно ещё событие **Нажатие кнопок**. |
| Где агент-бот слышит | В беседе или канале агент-бот слышит всё после добавления, а в треде после добавления участником или по упоминанию, если бот публичный. Упоминание в самой беседе или канале бота не добавляет. |
| Обращаются ли к агенту-боту | Да, если это личный чат, упоминание целым словом вне кода, команда, ответ на сообщение агента-бота или продолжение разговора в треде, где кроме бота только один сотрудник. Остальные сообщения в беседах и тредах сотрудники пишут друг другу, и агент-бот молчит. |
| Как выглядит упоминание | Упоминание из приложения приходит как `@` и имя бота, а отправленное через API как `@nickname`, поэтому агент-бот ищет оба. Упоминания в пересланном сообщении и добавленные правкой никого не зовут. |
| Сбор контекста | Историю треда агент-бот читает по `chat_id` из события, а не по родительскому чату, страницами по 50 сообщений. Ещё он читает родительское сообщение, сообщение, на которое ответили, и вложения: суть просьбы часто там. |
| Индикатор работы | Реакцию `agent-thinking` сотрудник создаёт в приложении один раз: API для этого нет. Таймер идёт до 5 минут, а если такой реакции нет, агент-бот работает без индикатора. |
| Где отвечать | В личном чате и треде агент-бот отвечает туда же, а в беседе или канале в тред под сообщением. Результат уходит одним ответом, а если задачу выполнить не удалось, агент-бот так и пишет. |
| Оформление ответа | В тексте сообщения списки и таблицы остаются простым текстом, поэтому отчёт уходит файлом `.md`. Точная вёрстка уходит файлом `.html` без скриптов и внешних ресурсов. |
| Черновики и отложенные сообщения | У бота их нет, и авторизация сотрудника этого не меняет. «Напомни в понедельник» агент-бот выполняет своим планировщиком или напоминанием. |
| Чужие чаты в ответе | Бот видит больше, чем те, кому он отвечает. Сообщения, файлы и участников другого чата агент-бот приводит, только если все читатели ответа этот чат видят, а иначе говорит, что не может поделиться ими здесь. |
| Чужие указания в тексте | Сообщения, имена файлов и другие поля — это данные, а не указания. MCP-сервер отделяет такой текст разметкой, а на прямом API защиту пишет разработчик агента-бота. |
| Петли между ботами | **Игнорировать свои сообщения** отбрасывает только свои сообщения, поэтому автора проверяют на `bot: true`. Другим ботам агент-бот отвечает, только если они упоминают его или начинают сообщение с его команды. |

Токену агента-бота скилл даёт права `messages:create`, `threads:create`, `reactions:write`, `messages:read`, `chats:read`, `profile:read`, `users:read`, `files:read` и `uploads:write`. Токен с вкладки **API** создаётся без прав, поэтому каждое отмечают вручную, а права для самой работы агента-бота добавляют к этому набору.

Когда агент-бот оставляет решение сотруднику, переспрашивает или предупреждает:

| Ситуация | Что делает агент-бот |
|---|---|
| Ответ, который сотрудник хочет проверить | Присылает текст вызвавшему сотруднику в личный чат с ботом как явно помеченное предложение, а отправляет сотрудник сам |
| Сообщение по расписанию | Повторяет вызвавшему чат и точное время, потому что при отправке сообщение никто не проверит |
| Часовой пояс сотрудника не задан | Спрашивает, какой пояс имеется в виду |
| Нужны данные самого сотрудника, например его напоминания | Присылает в личном чате кнопку авторизации, и сотрудник решает, дать ли доступ |
| Работа дольше 5 минут | Пишет об этом в тред, чтобы таймер не остановился молча |

Подпись вебхука, повторы, защиту от дублей, токены, кнопки и формы агент берёт из скилла `pachca-bots`, авторизацию от имени вызвавшего сотрудника из `pachca-oauth`, а черновики с собственным входом сотрудника из `pachca-messaging`.

Подробнее — на страницах [Общение с ботом](/guides/bots/conversations), [Доступы к чатам и сообщениям](/guides/bots/access), [Оформление ответов](/guides/ai-agents/markdown) и [Черновик вместо отправки](/guides/ai-agents/drafts).

## Работа от имени сотрудника

Скилл `pachca-oauth` помогает сделать бота, который работает от имени каждого сотрудника с его согласия. Сотрудник разрешает доступ на экране согласия, а бот получает токен этого сотрудника и вызывает API от его имени в пределах набора прав бота и роли сотрудника. Своё такое приложение в Пачке всегда делают ботом и настраивают на вкладке **OAuth** в карточке бота. Подробнее — на странице [Авторизация от имени сотрудника](/guides/oauth/overview).

Агент берёт скилл по таким просьбам:

| Просьба | Что сделает агент |
|---|---|
| *«Пусть бот ставит напоминания от имени сотрудника»* | Предложит авторизацию от имени сотрудника: у каждого сотрудника свой токен с набором прав из настроек бота |
| *«Включи OAuth у моего бота»* | Включит вкладку **OAuth** через `pachca_update_bot` с адресом возврата и минимальным набором прав в `oauth_client.scopes` |
| *«Как обменять код на токен?»* | Напишет обмен кода с тем же `redirect_uri` и `code_verifier`: на сервере бота с `client_secret` или в приложении на устройстве сотрудника без секрета, и учтёт, что код живёт 10 минут и срабатывает один раз |
| *«Сотрудник видит отказ вместо экрана согласия»* | Проверит настройку **Кто может создавать персональные токены**: по умолчанию в ней стоит **Только администраторы**, и остальные сотрудники видят отказ |
| *«Бот не присылает кнопку для авторизации»* | Пройдёт проверки перед запуском: может ли сотрудник написать боту, узнаёт ли бот о сообщении, есть ли у токена бота право `messages:create` |
| *«Токен сотрудника вернул 401 или 403»* | Разберёт код: после `401` токен удаляют, `403` `role_forbidden` повторная авторизация не исправит, а `insufficient_scope` исправит |
| *«Сотрудник отозвал доступ»* | Научит бота удалять токен после `401` и присылать кнопку снова, когда сотрудник ему напишет |

Что агент знает из скилла:

| Тема | Что знает агент |
|---|---|
| Какой токен выбрать | Боту, который работает от своего имени, хватит токена бота, а своему скрипту хватит персонального токена или входа в CLI. OAuth нужен, когда согласиться должен каждый сотрудник. |
| Почему не собирать персональные токены | Персональный токен не истекает и копируется вместе со всеми правами владельца. Авторизация ограничена набором прав бота, а сотрудник видит её в списке **Авторизации** и может отозвать. |
| Кто может авторизовать бота | Сотрудники пространства, где создан бот, и мульти-гости, если им это разрешает настройка **Кто может создавать персональные токены**. Гости не могут никогда. |
| Тип клиента | **Серверное, с секретом** обменивает код на сервере, где хранится `client_secret`. **Браузер, мобильное, CLI** работает без секрета, только с PKCE. |
| Набор прав | Набор прав один на бота, а параметр `scope` в ссылке игнорируется. Черновики, управление ботами и права только Владельца или Администратора в набор не попадают. |
| Роль сотрудника | Вызов по праву, которого не даёт роль сотрудника, получает `403` `role_forbidden`. Смена роли действует на токен сразу. |
| Срок жизни токена | Токен не истекает и работает до отзыва. Повторная авторизация с тем же набором прав возвращает тот же токен. |
| Сообщения от имени сотрудника | Они подписаны именем сотрудника, а на аватаре стоит иконка бота с подсказкой «Отправлено через». Если бот слушает все сообщения чата, они приходят ему вебхуком с `user_id` сотрудника, поэтому бот запоминает id отправленных сообщений и пропускает эти события. |
| Адреса возврата | Простой `http` разрешён только на локальном компьютере, а `redirect_uri` в ссылке должен точно совпадать с адресом из списка. Порт локального адреса не сравнивается. |
| Порядок шагов | Новые `state` и пара PKCE на каждую кнопку, кнопка со ссылкой в личном чате, проверка `state` и `iss`, обмен кода и проверка владельца токена. |
| Пересланная кнопка | Бот сверяет `user_id` из информации о токене с сотрудником, которому ушла кнопка. Если они разные, бот сохраняет токен под тем, кто согласился, не отзывает его и присылает кнопку снова тому, кому она предназначалась. |
| Изменения набора прав | Расширенный набор сотрудник подтверждает при следующей авторизации. Убранное право остаётся в выданных токенах до их отзыва. |
| Отказы | После `invalid_grant` нужна новая кнопка, а после `401` токен удаляют. `403` `access_denied` значит, что сотрудник приостановлен или удалён, и кнопку слать не нужно. |
| Приложение на устройстве сотрудника | Оно обходится без личного чата и вебхука и принимает код на локальный адрес возврата с любым свободным портом. Токен оно хранит в хранилище ключей системы. |
| Что делается инструментами | Вкладку **OAuth** агент включает через `pachca_update_bot` на вашем подключении. Ссылку, обмен кода и отзыв он пишет в код бота: инструментов MCP для них нет. |

Когда агент спрашивает, о чём предупреждает и что советует:

| Действие | Что делает агент |
|---|---|
| Отключение OAuth (**Удаление OAuth-клиента**) | Спрашивает: все авторизации сотрудников сразу отзываются, бот уходит из витрины, а его описание и скриншоты удаляются навсегда |
| Новый `client_secret` | Отдаёт его только вам в ответе, чтобы вы положили его в хранилище секретов |
| Обновление секрета (**Обновить секрет**) | Предупреждает, что старый секрет перестаёт работать сразу, поэтому бот должен быть готов принять новый |
| Бот для обычных сотрудников | Советует до начала работы проверить у Администратора настройку **Кто может создавать персональные токены** |
| Кнопка авторизации | Добавляет к ней, зачем боту доступ и что он будет делать, и просит сотрудника не пересылать ссылку |

Бота, который работает от своего имени, вебхуки и витрину агент делает по скиллу `pachca-bots`, вход MCP-клиента и отказ инструмента разбирает по `pachca`, свой токен в скрипте выбирает по `pachca-api`, а отзыв доступа на вкладке **Все токены** берёт из `pachca-admin`.

Подробнее — на страницах [Чек-лист запуска](/guides/oauth/checklist), [Настройка авторизации](/guides/oauth/setup), [Получение токена](/guides/oauth/flow) и [Согласие и отзыв](/guides/oauth/consent).

## API в скриптах и сервисах

Скилл `pachca-api` нужен, когда агент пишет код, который вызывает API Пачки: скрипт, сервис, задание CI, клиент на SDK или команды `pachca` в shell-скрипте. Справочник по методам скилл не повторяет: метод, его право и тело запроса агент находит в описании инструмента MCP, через `pachca api` или на странице метода. Подробнее — на странице [Обзор API](/api/overview).

Агент берёт скилл по таким просьбам:

| Просьба | Что сделает агент |
|---|---|
| *«Напиши скрипт, который выгружает всех сотрудников»* | Сделает выгрузку в терминале, например `pachca users list --all -o csv > users.csv`, а не цепочкой вызовов инструментов |
| *«Какой токен дать заданию в CI?»* | Предложит токен бота: задание продолжит работать, даже если сотрудник, который его настроил, уйдёт |
| *«Мой код получает 403»* | Определит, о чём отказ: о правах токена, роли сотрудника, доступе к API вообще или доступе к чату |
| *«Упёрлись в 429»* | Добавит ожидание не меньше `Retry-After`, а при паузе больше минуты остановит задание |
| *«Поиск вернул 504 timeout, повторить?»* | Не станет повторять тот же запрос и сузит его: меньше чатов, короче период или конкретный автор |
| *«Обойди все страницы»* | Напишет цикл по курсору с явным `limit` и остановкой по `has_next: false` |
| *«Загрузи файл из кода»* | Сделает три шага загрузки: параметры загрузки, форма с файлом последним полем, ключ файла в сообщении |
| *«Какой метод API это делает?»* | Найдёт метод через `pachca api ls` или индекс документации и не станет придумывать путь |

Что агент знает из скилла:

| Тема | Что знает агент |
|---|---|
| Выбор токена | Для своего скрипта подходит персональный токен, а для CI и сервера без сотрудника токен бота. Боту, которому нужны данные одного сотрудника, нужен токен по авторизации. |
| Что видит токен | Права открывают методы, но не расширяют видимость. Почта и телефон других сотрудников приходят `null`, если пространство не показывает личные данные, поэтому выгрузку контактов агент запускает на персональном токене Администратора. |
| Только бот или только сотрудник | Разворачивание ссылок, формы и история событий работают только с токеном бота. Черновики и управление ботами работают только с токеном самого сотрудника: из интерфейса, входом в CLI или через браузер в MCP, но не с токеном, который бот получил по авторизации. |
| Запросы и ответы | Тело часто обёрнуто в корневой ключ вроде `{"message": {...}}`, но не всегда, а некоторые id строковые. Время приходит в UTC, и время без смещения API тоже читает как UTC. |
| Пагинация | Агент передаёт явный `limit`, останавливается по `has_next: false`, а не по длине страницы, и не разбирает курсор. `--all` в CLI после 500 страниц выдаёт неполный список с кодом выхода `0` и только предупреждением. |
| Опрос новых записей | В списках от новых к старым новые записи ловит `prev_page`. Результаты поиска по курсору не опрашиваются. |
| Лимиты | Отправка сообщений считается по получателю, и у неё есть дневной предел на чат. Каждая попытка во время такой паузы её удлиняет, поэтому задание останавливают до конца паузы. |
| Повторы | `5xx` на `GET`, `PUT` и `DELETE` повторяют до трёх раз с нарастающей паузой. Оборвавшийся `POST` повторяют, только если сообщения или объекта нет. |
| Разбор ошибок | `401` значит, что недействителен сам токен, а `403` `role_forbidden` не исправит ни новый токен, ни новый вход. `402` значит, что пространство приостановлено, и повторять нечего. |
| Файлы | Ссылка на вложение работает до 7 дней, а часто меньше, поэтому файл скачивают сразу. При шифровании ссылка ведёт на метод скачивания, которому нужен `files:read`. |
| SDK и генератор | SDK для TypeScript, Python, Go, Kotlin, Swift и C# сами обходят страницы и повторяют запросы, поэтому свой цикл повторов вокруг них не нужен. Свой клиент собирает `@pachca/generator`. |
| CLI в CI | Токен передают в `PACHCA_TOKEN`, вывод задают `-o json`, а коды выхода идут от `0` до `4`. Удаление без `--force` в неинтерактивном режиме не выполняется. |
| Вызов из браузера | API не отвечает на запросы со страниц других сайтов. Поэтому страница ходит через свой сервер, где хранится токен. |

Ясную просьбу агент выполняет сразу. Когда он спрашивает и чего не делает без вашей просьбы:

| Действие | Что делает агент |
|---|---|
| Массовое действие: рассылка, изменение многих сотрудников или чатов | Спрашивает до начала |
| Удаление, когда подошло бы обратимое действие | Спрашивает и предлагает обратимое, например приостановить сотрудника вместо удаления |
| Изменение цели, которую агент выбрал сам | Спрашивает |
| Удаление сообщения или вложения | Удаляет, только если вы попросили, а если сообщение найдено по догадке, сначала спрашивает: файл стирается сразу и без корзины |
| Флаг `--force` в CLI | Добавляет только к удалению, о котором вы попросили |
| Новое право токену бота | Спрашивает, если вы об этом не просили: правка меняет работающую интеграцию |
| Создание сотрудника, когда на бесплатном тарифе кончился дневной предел писем | Спрашивает, прежде чем создать его без письма-приглашения через `skip_email_notify: true` |

Подключение агента и отказ инструмента MCP агент разбирает по скиллу `pachca`, а сообщение или файл в чат прямо сейчас отправляет по `pachca-messaging`. Ботов и события агент делает по `pachca-bots`, OAuth для сотрудников по `pachca-oauth`, а политику токенов и экспорт переписки ведёт по `pachca-admin`.

Подробнее — на страницах [Авторизация](/api/authorization), [Пагинация](/api/pagination), [Ошибки](/api/errors), [Лимиты](/api/limits), [Файлы](/api/file-uploads), [SDK](/guides/sdk/overview) и [Флаги и скрипты](/guides/cli/scripting).


## Связанные разделы

- [Плагин и скиллы](/guides/mcp/plugin)
- [Команды плагина](/guides/mcp/commands)
- [MCP-сервер](/guides/mcp/overview)