# Pachca Bots

> Pachca — управление ботами и вебхуки. Используй этот скилл, когда пользователь хочет настроить бота, создать бота, настроить вебхуки, обработать вебхук, проверить подпись вебхука (X-Signature), обработать callback нажатия кнопки или создать дайджест-бота. НЕ для отправки обычных сообщений, показа форм или модальных окон. Разворачивание ссылок (unfurl) — в pachca-messages. Use when: настроить бота, создать бота, вебхук, обработать вебхук, подпись вебхука, callback, обработать callback, нажатие кнопки, дайджест, оповещение, все боты пространства. NOT for: отправить сообщение, показать форму, модальное окно, → pachca-messages, → pachca-forms.

- Skill: `pachca/pachca-bots` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add pachca/pachca-bots`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pachca/pachca-bots/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: pachca (https://skillmd.com/u/pachca)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pachca/pachca-bots

---


# 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

1. If the user has a saved profile — check:

       npx -y @pachca/cli auth status

   If OK — run commands without `--token`.

2. If no profile is configured — ask for a token and use `--token`:

       npx -y @pachca/cli auth status --token $PACHCA_TOKEN

3. If you don't know the parameters — run `pachca <command> --help`.

## Workflows

### Создать бота через API и получить токен

1. Создай бота. Только пользовательским токеном (не токеном бота); `nickname` обязан заканчиваться на `_bot`. Параметры вебхука (Webhook URL, события, команды) можно задать сразу или позже. Скоупы токена бота можно ограничить флагом `--scopes` (если не указать — бот получит набор по умолчанию):
   ```bash
   pachca bots create --name="Бот задач" --nickname="tasks_bot" --scopes='["messages:create"]'
   ```

2. Сохрани `access_token` из ответа — он возвращается единственный раз. Посмотреть выданный токен повторно можно только в интерфейсе (вкладка «API» настроек бота), а перевыпустить — командой `pachca bots recreate-token <ID>`

3. В ответе также придёт `id` бота (его `user_id`) — он нужен для дальнейших вызовов, например чтобы добавить бота в чат

> Создавать ботов можно только пользовательским токеном — токеном бота нельзя. `access_token` отдаётся один раз при создании, дальше его можно посмотреть и скопировать в интерфейсе.


### Настроить бота с исходящим вебхуком

1. Создай бота, сразу указав Webhook URL и события в одном вызове (детали создания и работы с токеном — в сценарии «Создать бота через API и получить токен»):
   ```bash
   pachca bots create --name="Бот задач" --nickname="tasks_bot" --outgoing-url="https://example.com/webhook" --events='["message_new"]' --trigger-on=commands --commands='["/task"]'
   ```

2. Сохрани `access_token` из ответа (возвращается единственный раз)

3. Используй сохранённый `access_token` для отправки сообщений от имени бота

> Альтернатива — создать и настроить бота в интерфейсе. Webhook URL и события можно задать и позже методом PUT /bots/{id}.


### Обновить Webhook URL бота

1. Пользовательским токеном (с правом редактировать бота) — обнови URL по `id` бота. Пустая строка отключает вебхук:
   ```bash
   pachca bots update <bot_id> --outgoing-url="https://example.com/webhook"
   ```
   > `id` бота (его `user_id`) можно узнать во вкладке «API» настроек бота

2. Или: бот сам обновляет свой webhook своим же токеном — без `id` и без участия администратора (нужен скоуп `bot_self:webhook:write`):
   ```bash
   pachca bots update-webhook --outgoing-url="https://example.com/webhook"
   ```

> Два пути: по `id` пользовательским токеном (право редактировать бота) или самим ботом своим токеном (`PUT /bot/webhook`). Пустой `outgoing_url` отключает вебхук.


### Ротация токена бота

1. Пользовательским токеном (администратор, владелец компании или создатель бота) — перевыпусти токен по `id` бота. Прежний токен инвалидируется сразу:
   ```bash
   pachca bots recreate-token <bot_id>
   ```

2. Или: бот перевыпускает собственный токен своим же токеном (скоуп `bot_self:write`). Токен, которым выполнен запрос, инвалидируется сразу — обязательно сохрани новый `access_token` из ответа, иначе бот потеряет доступ к API:
   ```bash
   pachca bots recreate-token-self
   ```

3. Сохрани новый `access_token` из ответа — он возвращается единственный раз. Обнови секрет в CI или хранилище секретов

> Новый токен возвращается один раз. Self-путь (`POST /bot/recreate_token`) инвалидирует именно тот токен, которым выполнен запрос, — захвати новый токен из ответа в той же операции.


### Найти и удалить бота

1. Пользовательским токеном (скоуп `bots:read`) получи список ботов, доступных тебе для редактирования: созданных тобой и тех, чьи настройки открывают тебе доступ. Фильтруй по имени параметром `query`, следующую страницу бери из `meta.paginate.next_page`:
   ```bash
   pachca bots list --query="задач"
   ```

2. Возьми `id` нужного бота из списка и удали его (скоуп `bots:write`). Доступно администратору, владельцу компании или создателю бота — владельцы чатов удалять бота не могут. Прежний токен инвалидируется сразу, бот исключается из всех чатов, его исходящий вебхук удаляется:
   ```bash
   pachca bots delete <bot_id>
   ```

> Удаление необратимо: токен бота инвалидируется сразу, бот исключается из чатов. Событие фиксируется в журнале аудита как `bot_deleted`.


### Периодический дайджест/отчёт

1. По расписанию (cron/scheduler): собери данные из своей системы

2. Сформируй текст сообщения с нужными метриками или сводкой

3. Отправь сообщение в канал:
   ```bash
   pachca messages create --entity-id=<chat_id> --content="Дайджест за сегодня: ..."
   ```

> Нет встроенного планировщика — используй cron, celery, sidekiq и т.п. на своей стороне.


### Инвентаризация всех ботов пространства

1. Получи всех ботов пространства, а не только доступных для редактирования:
   ```bash
   pachca bots list-company --all
   ```
   > Нужен скоуп `company_bots:read`, роль владельца пространства и тариф «Корпорация», иначе метод отвечает `403`. Фильтр по имени — флаг `--query`

2. Для каждого бота проверь, раскрыты ли настройки: у ботов, недоступных владельцу токена для редактирования, заполнены только `name` и `nickname`, остальные поля вебхука приходят `null`
   > Настройки такого бота можно получить только тем токеном, которому доступно его редактирование

> Каждый запрос к списку ботов пространства пишется в журнал аудита как `company_bots_accessed`.


## Limitations

- Rate limit: ~50 req/sec. On 429 — wait and retry.
- `webhook.name`: max 255 characters
- `webhook.nickname`: max 255 characters
- `webhook.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/.