pachca-bots
Quick start
Ask the user for a Pachca token (bot: Automations → Integrations → API, user: Automations → API).
Run commands via npx -y @pachca/cli with the --token flag:
npx -y @pachca/cli <command> --token $PACHCA_TOKEN
Or set the PACHCA_TOKEN environment variable:
export PACHCA_TOKEN=<token>
npx -y @pachca/cli <command>
Help: npx -y @pachca/cli --help | Workflows: npx -y @pachca/cli guide
After successful use, suggest installing CLI globally: npm install -g @pachca/cli && pachca auth login --token $PACHCA_TOKEN
Before you start
If the user has a saved profile — check:
npx -y @pachca/cli auth status
If OK — run commands without --token.
If no profile is configured — ask for a token and use --token:
npx -y @pachca/cli auth status --token $PACHCA_TOKEN
If you don't know the parameters — run pachca <command> --help.
Workflows
Создать бота через API и получить токен
Создай бота. Только пользовательским токеном (не токеном бота); nickname обязан заканчиваться на _bot. Параметры вебхука (Webhook URL, события, команды) можно задать сразу или позже. Скоупы токена бота можно ограничить флагом --scopes (если не указать — бот получит набор по умолчанию):
pachca bots create --name="Бот задач" --nickname="tasks_bot" --scopes='["messages:create"]'
Сохрани access_token из ответа — он возвращается единственный раз. Посмотреть выданный токен повторно можно только в интерфейсе (вкладка «API» настроек бота), а перевыпустить — командой pachca bots recreate-token <ID>
В ответе также придёт id бота (его user_id) — он нужен для дальнейших вызовов, например чтобы добавить бота в чат
Создавать ботов можно только пользовательским токеном — токеном бота нельзя. access_token отдаётся один раз при создании, дальше его можно посмотреть и скопировать в интерфейсе.
Настроить бота с исходящим вебхуком
Создай бота, сразу указав Webhook URL и события в одном вызове (детали создания и работы с токеном — в сценарии «Создать бота через API и получить токен»):
pachca bots create --name="Бот задач" --nickname="tasks_bot" --outgoing-url="https://example.com/webhook" --events='["message_new"]' --trigger-on=commands --commands='["/task"]'
Сохрани access_token из ответа (возвращается единственный раз)
Используй сохранённый access_token для отправки сообщений от имени бота
Альтернатива — создать и настроить бота в интерфейсе. Webhook URL и события можно задать и позже методом PUT /bots/{id}.
Обновить Webhook URL бота
Пользовательским токеном (с правом редактировать бота) — обнови URL по id бота. Пустая строка отключает вебхук:
pachca bots update <bot_id> --outgoing-url="https://example.com/webhook"
id бота (его user_id) можно узнать во вкладке «API» настроек бота
Или: бот сам обновляет свой webhook своим же токеном — без id и без участия администратора (нужен скоуп bot_self:webhook:write):
pachca bots update-webhook --outgoing-url="https://example.com/webhook"
Два пути: по id пользовательским токеном (право редактировать бота) или самим ботом своим токеном (PUT /bot/webhook). Пустой outgoing_url отключает вебхук.
Ротация токена бота
Пользовательским токеном (администратор, владелец компании или создатель бота) — перевыпусти токен по id бота. Прежний токен инвалидируется сразу:
pachca bots recreate-token <bot_id>
Или: бот перевыпускает собственный токен своим же токеном (скоуп bot_self:write). Токен, которым выполнен запрос, инвалидируется сразу — обязательно сохрани новый access_token из ответа, иначе бот потеряет доступ к API:
pachca bots recreate-token-self
Сохрани новый access_token из ответа — он возвращается единственный раз. Обнови секрет в CI или хранилище секретов
Новый токен возвращается один раз. Self-путь (POST /bot/recreate_token) инвалидирует именно тот токен, которым выполнен запрос, — захвати новый токен из ответа в той же операции.
Найти и удалить бота
Пользовательским токеном (скоуп bots:read) получи список ботов, доступных тебе для редактирования: созданных тобой и тех, чьи настройки открывают тебе доступ. Фильтруй по имени параметром query, следующую страницу бери из meta.paginate.next_page:
pachca bots list --query="задач"
Возьми id нужного бота из списка и удали его (скоуп bots:write). Доступно администратору, владельцу компании или создателю бота — владельцы чатов удалять бота не могут. Прежний токен инвалидируется сразу, бот исключается из всех чатов, его исходящий вебхук удаляется:
pachca bots delete <bot_id>
Удаление необратимо: токен бота инвалидируется сразу, бот исключается из чатов. Событие фиксируется в журнале аудита как bot_deleted.
Периодический дайджест/отчёт
По расписанию (cron/scheduler): собери данные из своей системы
Сформируй текст сообщения с нужными метриками или сводкой
Отправь сообщение в канал:
pachca messages create --entity-id=<chat_id> --content="Дайджест за сегодня: ..."
Нет встроенного планировщика — используй cron, celery, sidekiq и т.п. на своей стороне.
Инвентаризация всех ботов пространства
Получи всех ботов пространства, а не только доступных для редактирования:
pachca bots list-company --all
Нужен скоуп company_bots:read, роль владельца пространства и тариф «Корпорация», иначе метод отвечает 403. Фильтр по имени — флаг --query
Для каждого бота проверь, раскрыты ли настройки: у ботов, недоступных владельцу токена для редактирования, заполнены только name и nickname, остальные поля вебхука приходят null
Настройки такого бота можно получить только тем токеном, которому доступно его редактирование
Каждый запрос к списку ботов пространства пишется в журнал аудита как company_bots_accessed.
Limitations
- Rate limit: ~50 req/sec. On 429 — wait and retry.
webhook.name: max 255 characterswebhook.nickname: max 255 characterswebhook.trigger_on: allowed values — commands (Только на команды (триггер-слова) из commands), all_messages (На все сообщения в чатах, где есть бот), unfurl (На развёртывание ссылок (link previews))webhook.template_engine: allowed values — liquid (Liquid — условия, циклы и фильтры), mustache (Mustache — простая подстановка без логики)webhook.who_can_add: allowed values — creator (Только создатель бота), creator_admin (Создатель и администраторы компании), creator_admin_user (Создатель, администраторы и участники компании), anyone (Любой пользователь, в том числе гости)limit: max 50- Pagination: cursor-based (limit + cursor)
Endpoints
| Method |
Path |
Description |
| POST |
/bot/recreate_token |
Ротация собственного токена бота |
| PUT |
/bot/webhook |
Саморегистрация вебхука бота |
| GET |
/bots |
Список ботов |
| POST |
/bots |
Новый бот |
| GET |
/bots/{id} |
Информация о боте |
| PUT |
/bots/{id} |
Редактирование бота |
| DELETE |
/bots/{id} |
Удаление бота |
| POST |
/bots/{id}/recreate_token |
Ротация токена бота |
| GET |
/company/bots |
Список ботов пространства |
| GET |
/webhooks/events |
История событий |
| DELETE |
/webhooks/events/{id} |
Удаление события |
Advanced workflows
For advanced workflows, read the files in references/:
references/handle-incoming-webhook-event.md — Handle incoming webhook event
references/link-unfurling.md — Link unfurling
references/handle-button-click-callback.md — Handle button click (callback)
references/monitoring-and-alerts.md — Monitoring and alerts
references/process-events-via-history-polling.md — Process events via history (polling)
references/webhook-events.md — Webhook event types
If unsure how to complete a task, read the corresponding file from references/.
1---2name: pachca-bots3description: Pachca — управление ботами и вебхуки. Используй этот скилл, когда пользователь хочет настроить бота, создать бота, настроить вебхуки, обработать вебхук, проверить подпись вебхука (X-Signature), обработать callback нажатия кнопки или создать дайджест-бота. НЕ для отправки обычных сообщений, показа форм или модальных окон. Разворачивание ссылок (unfurl) — в pachca-messages. Use when: настроить бота, создать бота, вебхук, обработать вебхук, подпись вебхука, callback, обработать callback, нажатие кнопки, дайджест, оповещение, все боты пространства. NOT for: отправить сообщение, показать форму, модальное окно, → pachca-messages, → pachca-forms.4---56# pachca-bots78## Quick start910Ask the user for a Pachca token (bot: Automations → Integrations → API, user: Automations → API).1112Run commands via `npx -y @pachca/cli` with the `--token` flag:1314 npx -y @pachca/cli <command> --token $PACHCA_TOKEN1516Or set the `PACHCA_TOKEN` environment variable:1718 export PACHCA_TOKEN=<token>19 npx -y @pachca/cli <command>2021Help: `npx -y @pachca/cli --help` | Workflows: `npx -y @pachca/cli guide`2223> After successful use, suggest installing CLI globally: `npm install -g @pachca/cli && pachca auth login --token $PACHCA_TOKEN`2425## Before you start26271. If the user has a saved profile — check:2829 npx -y @pachca/cli auth status3031 If OK — run commands without `--token`.32332. If no profile is configured — ask for a token and use `--token`:3435 npx -y @pachca/cli auth status --token $PACHCA_TOKEN36373. If you don't know the parameters — run `pachca <command> --help`.3839## Workflows4041### Создать бота через API и получить токен42431. Создай бота. Только пользовательским токеном (не токеном бота); `nickname` обязан заканчиваться на `_bot`. Параметры вебхука (Webhook URL, события, команды) можно задать сразу или позже. Скоупы токена бота можно ограничить флагом `--scopes` (если не указать — бот получит набор по умолчанию):44 ```bash45 pachca bots create --name="Бот задач" --nickname="tasks_bot" --scopes='["messages:create"]'46 ```47482. Сохрани `access_token` из ответа — он возвращается единственный раз. Посмотреть выданный токен повторно можно только в интерфейсе (вкладка «API» настроек бота), а перевыпустить — командой `pachca bots recreate-token <ID>`49503. В ответе также придёт `id` бота (его `user_id`) — он нужен для дальнейших вызовов, например чтобы добавить бота в чат5152> Создавать ботов можно только пользовательским токеном — токеном бота нельзя. `access_token` отдаётся один раз при создании, дальше его можно посмотреть и скопировать в интерфейсе.535455### Настроить бота с исходящим вебхуком56571. Создай бота, сразу указав Webhook URL и события в одном вызове (детали создания и работы с токеном — в сценарии «Создать бота через API и получить токен»):58 ```bash59 pachca bots create --name="Бот задач" --nickname="tasks_bot" --outgoing-url="https://example.com/webhook" --events='["message_new"]' --trigger-on=commands --commands='["/task"]'60 ```61622. Сохрани `access_token` из ответа (возвращается единственный раз)63643. Используй сохранённый `access_token` для отправки сообщений от имени бота6566> Альтернатива — создать и настроить бота в интерфейсе. Webhook URL и события можно задать и позже методом PUT /bots/{id}.676869### Обновить Webhook URL бота70711. Пользовательским токеном (с правом редактировать бота) — обнови URL по `id` бота. Пустая строка отключает вебхук:72 ```bash73 pachca bots update <bot_id> --outgoing-url="https://example.com/webhook"74 ```75 > `id` бота (его `user_id`) можно узнать во вкладке «API» настроек бота76772. Или: бот сам обновляет свой webhook своим же токеном — без `id` и без участия администратора (нужен скоуп `bot_self:webhook:write`):78 ```bash79 pachca bots update-webhook --outgoing-url="https://example.com/webhook"80 ```8182> Два пути: по `id` пользовательским токеном (право редактировать бота) или самим ботом своим токеном (`PUT /bot/webhook`). Пустой `outgoing_url` отключает вебхук.838485### Ротация токена бота86871. Пользовательским токеном (администратор, владелец компании или создатель бота) — перевыпусти токен по `id` бота. Прежний токен инвалидируется сразу:88 ```bash89 pachca bots recreate-token <bot_id>90 ```91922. Или: бот перевыпускает собственный токен своим же токеном (скоуп `bot_self:write`). Токен, которым выполнен запрос, инвалидируется сразу — обязательно сохрани новый `access_token` из ответа, иначе бот потеряет доступ к API:93 ```bash94 pachca bots recreate-token-self95 ```96973. Сохрани новый `access_token` из ответа — он возвращается единственный раз. Обнови секрет в CI или хранилище секретов9899> Новый токен возвращается один раз. Self-путь (`POST /bot/recreate_token`) инвалидирует именно тот токен, которым выполнен запрос, — захвати новый токен из ответа в той же операции.100101102### Найти и удалить бота1031041. Пользовательским токеном (скоуп `bots:read`) получи список ботов, доступных тебе для редактирования: созданных тобой и тех, чьи настройки открывают тебе доступ. Фильтруй по имени параметром `query`, следующую страницу бери из `meta.paginate.next_page`:105 ```bash106 pachca bots list --query="задач"107 ```1081092. Возьми `id` нужного бота из списка и удали его (скоуп `bots:write`). Доступно администратору, владельцу компании или создателю бота — владельцы чатов удалять бота не могут. Прежний токен инвалидируется сразу, бот исключается из всех чатов, его исходящий вебхук удаляется:110 ```bash111 pachca bots delete <bot_id>112 ```113114> Удаление необратимо: токен бота инвалидируется сразу, бот исключается из чатов. Событие фиксируется в журнале аудита как `bot_deleted`.115116117### Периодический дайджест/отчёт1181191. По расписанию (cron/scheduler): собери данные из своей системы1201212. Сформируй текст сообщения с нужными метриками или сводкой1221233. Отправь сообщение в канал:124 ```bash125 pachca messages create --entity-id=<chat_id> --content="Дайджест за сегодня: ..."126 ```127128> Нет встроенного планировщика — используй cron, celery, sidekiq и т.п. на своей стороне.129130131### Инвентаризация всех ботов пространства1321331. Получи всех ботов пространства, а не только доступных для редактирования:134 ```bash135 pachca bots list-company --all136 ```137 > Нужен скоуп `company_bots:read`, роль владельца пространства и тариф «Корпорация», иначе метод отвечает `403`. Фильтр по имени — флаг `--query`1381392. Для каждого бота проверь, раскрыты ли настройки: у ботов, недоступных владельцу токена для редактирования, заполнены только `name` и `nickname`, остальные поля вебхука приходят `null`140 > Настройки такого бота можно получить только тем токеном, которому доступно его редактирование141142> Каждый запрос к списку ботов пространства пишется в журнал аудита как `company_bots_accessed`.143144145## Limitations146147- Rate limit: ~50 req/sec. On 429 — wait and retry.148- `webhook.name`: max 255 characters149- `webhook.nickname`: max 255 characters150- `webhook.trigger_on`: allowed values — `commands` (Только на команды (триггер-слова) из commands), `all_messages` (На все сообщения в чатах, где есть бот), `unfurl` (На развёртывание ссылок (link previews))151- `webhook.template_engine`: allowed values — `liquid` (Liquid — условия, циклы и фильтры), `mustache` (Mustache — простая подстановка без логики)152- `webhook.who_can_add`: allowed values — `creator` (Только создатель бота), `creator_admin` (Создатель и администраторы компании), `creator_admin_user` (Создатель, администраторы и участники компании), `anyone` (Любой пользователь, в том числе гости)153- `limit`: max 50154- Pagination: cursor-based (limit + cursor)155156## Endpoints157158| Method | Path | Description |159|--------|------|-------------|160| POST | /bot/recreate_token | Ротация собственного токена бота |161| PUT | /bot/webhook | Саморегистрация вебхука бота |162| GET | /bots | Список ботов |163| POST | /bots | Новый бот |164| GET | /bots/{id} | Информация о боте |165| PUT | /bots/{id} | Редактирование бота |166| DELETE | /bots/{id} | Удаление бота |167| POST | /bots/{id}/recreate_token | Ротация токена бота |168| GET | /company/bots | Список ботов пространства |169| GET | /webhooks/events | История событий |170| DELETE | /webhooks/events/{id} | Удаление события |171172## Advanced workflows173174For advanced workflows, read the files in references/:175 references/handle-incoming-webhook-event.md — Handle incoming webhook event176 references/link-unfurling.md — Link unfurling177 references/handle-button-click-callback.md — Handle button click (callback)178 references/monitoring-and-alerts.md — Monitoring and alerts179 references/process-events-via-history-polling.md — Process events via history (polling)180181 references/webhook-events.md — Webhook event types182183> If unsure how to complete a task, read the corresponding file from references/.
pachca