Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion apps/docs/content/api/models.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ hideTableOfContents: true
<Card title="Реакция на сообщение" href="#reaktsiya-na-soobschenie" methods="GET POST DELETE" />
<Card title="Напоминание" href="#napominanie" methods="GET POST PUT DELETE" />
<Card title="Представление" href="#predstavlenie" methods="POST" />
<Card title="Параметры бота" href="#parametry-bota" methods="POST, GET, PUT" />
<Card title="Параметры бота" href="#parametry-bota" methods="POST, GET, PUT, DELETE" />
<Card title="Событие исходящего вебхука" href="#sobytie-ishodyaschego-vebhuka" methods="GET DELETE" />
<Card title="Событие аудита" href="#sobytie-audita" methods="GET" />
</CardGroup>
Expand Down Expand Up @@ -154,8 +154,10 @@ hideTableOfContents: true
## Параметры бота

- [Новый бот](POST /bots)
- [Список ботов](GET /bots)
- [Информация о боте](GET /bots/{id})
- [Редактирование бота](PUT /bots/{id})
- [Удаление бота](DELETE /bots/{id})
- [Саморегистрация вебхука бота](PUT /bot/webhook)
- [Ротация токена бота](POST /bots/{id}/recreate_token)
- [Ротация собственного токена бота](POST /bot/recreate_token)
Expand Down
9 changes: 9 additions & 0 deletions apps/docs/content/guides/bots/setup.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,8 @@ related:
<Steps>
<Step title="Отправьте запрос на создание">
Передайте параметры бота в объекте `bot.webhook`: имя, никнейм, Webhook URL, список событий и команды. Никнейм должен заканчиваться на `_bot`.

Тип бота — в один или несколько чатов — задаётся полем `single_chat` и только при создании: изменить его потом нельзя, как и тип бота в интерфейсе. Ограничение «в один чат» распространяется только на беседы и каналы, треды и личные сообщения не в счёт.
</Step>
<Step title="Сохраните access_token">
В ответе вы получите `access_token` бота — сразу сохраните его. Повторно получить токен вы сможете только через интерфейс (вкладка **API** настроек бота), там же его можно перевыпустить. Вместе с токеном придёт `id` бота (его `user_id`).
Expand Down Expand Up @@ -92,6 +94,13 @@ related:
- **Все участники (кроме гостей)**
- **Публичный бот**

### Настройка через API

Эти доступы можно задать не только в интерфейсе, но и через API — методом [Редактирование бота](PUT /bots/{id}) или сразу при создании:

- **Кто может редактировать настройки бота** — поле `can_edit` (роли `admin` и `chat_owners`). Создатель имеет доступ всегда, поэтому в поле перечисляются только дополнительные роли, а пустой массив означает «только создатель»
- **Кто может добавлять бота в чаты** — поле `who_can_add` (`creator`, `creator_admin`, `creator_admin_user`, `anyone`)

## Настройка вебхуков и API

<ImageCard src="/images/bots/bot_webhook_api_settings.webp" alt="Вкладки настройки вебхуков и API бота" caption="Вкладки настройки вебхуков и API бота" maxWidth={533} />
Expand Down
2 changes: 1 addition & 1 deletion apps/docs/content/guides/cli/installation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ pachca doctor
# ✔ Конфиг ~/.config/pachca/config.toml (права: 600)
# ✔ Профиль personal (user: Иван Иванов)
# ✔ Токен действителен (11 скоупов)
# ✔ CLI v2026.6.3 (актуальная версия)
# ✔ CLI v2026.7.0 (актуальная версия)
```

## Обновление
Expand Down
6 changes: 4 additions & 2 deletions apps/docs/content/guides/n8n/resources.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ related:
| 8 | [Profile](#profile) | 6 | Мой профиль: информация, аватар, статус | |
| 9 | [OAuth](#oauth) | 1 | Информация о токене | да |
| 10 | [Task](#task) | 5 | Задачи: полный CRUD | |
| 11 | [Bot](#bot) | 8 | Боты: создание, получение, редактирование, вебхук, ротация токена, события | |
| 11 | [Bot](#bot) | 10 | Боты: создание, получение, список, редактирование, удаление, вебхук, ротация токена, события | |
| 12 | [File](#file) | 1 | Загрузка файлов через S3 | |
| 13 | [Form](#form) | 1 | Модальные формы | |
| 14 | [Custom Property](#custom-property) | 1 | Дополнительные поля | да |
Expand Down Expand Up @@ -208,13 +208,15 @@ related:

## Bot

Боты: создание, получение, редактирование, саморегистрация вебхука, ротация токена, история и удаление событий.
Боты: создание, получение, список, редактирование, удаление, саморегистрация вебхука, ротация токена, история и удаление событий.

| Операция | API |
|----------|-----|
| Create | [Новый бот](POST /bots) |
| Get | [Информация о боте](GET /bots/{id}) |
| Get Many | [Список ботов](GET /bots) |
| Update | [Редактирование бота](PUT /bots/{id}) |
| Delete | [Удаление бота](DELETE /bots/{id}) |
| Update Webhook | [Саморегистрация вебхука бота](PUT /bot/webhook) |
| Recreate Token | [Ротация токена бота](POST /bots/{id}/recreate_token) |
| Recreate Token Self | [Ротация собственного токена бота](POST /bot/recreate_token) |
Expand Down
8 changes: 8 additions & 0 deletions apps/docs/content/guides/webhook/events.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -94,3 +94,11 @@ related:
<SchemaBlock name="LinkSharedWebhookPayload" />

<Info>Payload содержит обнаруженные ссылки. Полное сообщение получите методом [Информация о сообщении](GET /messages/{id}) по `message_id`.</Info>

## Видеозвонки

Вебхук отправляется для видеозвонков в чатах, где состоит бот, и в тредах этих чатов. Поле `event` в payload различает три события: `started` (звонок начался), `finished` (звонок завершился) и `recording_ready` (запись готова). Набор полей payload зависит от события.

<SchemaBlock name="VideoCallWebhookPayload" />

<Info>Для события `finished` payload содержит список участников с временем подключения и выхода, для `recording_ready` — ссылку на файл записи, её размер и длительность. Полные данные участников получите методом [Информация о сотруднике](GET /users/{id}) по каждому `user_id`, а чат — методом [Информация о чате](GET /chats/{id}) по `chat_id`.</Info>
24 changes: 24 additions & 0 deletions apps/docs/content/updates/2026-07-07.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
---
date: "2026-07-07"
title: "Список и удаление ботов, права доступа бота, вебхуки видеозвонков"
---

Появились методы для управления ботами. Метод [Список ботов](GET /bots) возвращает ботов, которые вы можете редактировать, с поиском по имени. Метод [Удаление бота](DELETE /bots/{id}) удаляет бота: прежний токен сразу инвалидируется, бот исключается из чатов, его исходящий вебхук удаляется. Оба метода требуют скоуп `bots:read` и `bots:write` соответственно.

- [Список ботов](GET /bots)
- [Удаление бота](DELETE /bots/{id})

При создании и редактировании бота добавились настройки прав доступа: `who_can_add` — кто может добавлять бота в чаты (`creator`, `creator_admin`, `creator_admin_user`, `anyone`), и `can_edit` — роли, которым, помимо создателя, разрешено редактировать настройки бота (`admin`, `chat_owners`). При создании также можно передать `single_chat` — ограничить бота одной беседой или каналом (личные чаты и треды в ограничение не входят). Все три поля возвращаются в объекте бота.

- [Новый бот](POST /bots)
- [Редактирование бота](PUT /bots/{id})

Появился новый тип исходящего вебхука — события видеозвонков: `video_call_started`, `video_call_finished` и `video_call_recording_ready`. Вебхук приходит для видеозвонков в чатах, где состоит бот. Подробнее о payload — в гайде [Настройка и типы событий](/guides/webhook/events#videozvonki).

В журнале аудита появился тип события `bot_deleted` — удаление бота. Его можно фильтровать параметром `event_key`.

- [Журнал аудита событий](GET /audit_events)

В поиске сотрудников у параметра `sort` появилось значение `creation` — сортировка по дате создания (в дополнение к `by_score` и `alphabetical`).

- [Поиск сотрудников](GET /search/users)
88 changes: 88 additions & 0 deletions apps/docs/data/releases.json
Original file line number Diff line number Diff line change
@@ -1,4 +1,92 @@
[
{
"product": "sdk",
"version": "1.0.26",
"date": "2026-07-07",
"changes": [
{
"type": "+",
"description": "Метод `Список ботов` (`GET /bots`) — список ботов с поиском по имени"
},
{
"type": "+",
"description": "Метод `Удаление бота` (`DELETE /bots/{id}`)"
},
{
"type": "+",
"description": "У бота поля прав доступа: `who_can_add`, `can_edit`, `single_chat`"
},
{
"type": "+",
"description": "Новый payload исходящего вебхука `VideoCallWebhookPayload` и события `video_call_started`, `video_call_finished`, `video_call_recording_ready`"
},
{
"type": "+",
"description": "Журнал аудита: новый тип события `bot_deleted`"
},
{
"type": "+",
"description": "Поиск сотрудников (`GET /search/users`): значение сортировки `creation` (по дате создания)"
}
]
},
{
"product": "cli",
"version": "2026.7.0",
"date": "2026-07-07",
"changes": [
{
"type": "+",
"description": "`pachca bots list` — список ботов с поиском по имени (`--query`)"
},
{
"type": "+",
"description": "`pachca bots delete` — удаление бота по его `id`"
},
{
"type": "+",
"description": "`pachca bots create` и `bots update` — права доступа бота: `--who-can-add`, `--can-edit`, `--single-chat`"
},
{
"type": "+",
"description": "`pachca search users` — значение сортировки `--sort creation` (по дате создания)"
}
]
},
{
"product": "n8n",
"version": "2.0.14",
"date": "2026-07-07",
"changes": [
{
"type": "+",
"description": "Bot: новые операции `Get Many` (список ботов) и `Delete`"
},
{
"type": "+",
"description": "Bot: поля прав доступа `who_can_add`, `can_edit`, `single_chat` в операциях `Create` и `Update`"
},
{
"type": "+",
"description": "Trigger: события видеозвонков `video_call_started`, `video_call_finished`, `video_call_recording_ready`"
},
{
"type": "+",
"description": "User: поиск — опция сортировки `Creation` (по дате создания)"
}
]
},
{
"product": "generator",
"version": "1.1.9",
"date": "2026-07-07",
"changes": [
{
"type": "-",
"description": "Kotlin SDK: сериализатор union исходящих вебхуков теперь строится по членам union, а не по захардкоженному списку — новый тип payload подхватывается автоматически (чинит компиляцию при добавлении `VideoCallWebhookPayload`)"
}
]
},
{
"product": "generator",
"version": "1.1.8",
Expand Down
2 changes: 1 addition & 1 deletion apps/docs/public/.well-known/agent-skills/index.json
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@
"type": "skill-md",
"description": "Pachca — управление ботами и вебхуки. Используй этот скилл, когда пользователь хочет настроить бота, создать бота, настроить вебхуки, обработать вебхук, проверить подпись вебхука (X-Signature), обработать callback нажатия кнопки или создать дайджест-бота. НЕ для отправки обычных сообщений, показа форм или модальных окон. Разворачивание ссылок (unfurl) — в pachca-messages.",
"url": "/.well-known/skills/pachca-bots/SKILL.md",
"digest": "sha256:c87e4bce24d102b399a60c3c2c49aa6980ea4931ef0f5be446a13c4e1c970b0d"
"digest": "sha256:c019fa2d37fb1703eae7ceb380c4c7e2da209116c77fe191b3340cfc1f6826ad"
},
{
"name": "pachca-forms",
Expand Down
2 changes: 1 addition & 1 deletion apps/docs/public/.well-known/skills/index.json
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@
"type": "skill-md",
"description": "Pachca — управление ботами и вебхуки. Используй этот скилл, когда пользователь хочет настроить бота, создать бота, настроить вебхуки, обработать вебхук, проверить подпись вебхука (X-Signature), обработать callback нажатия кнопки или создать дайджест-бота. НЕ для отправки обычных сообщений, показа форм или модальных окон. Разворачивание ссылок (unfurl) — в pachca-messages.",
"url": "/.well-known/skills/pachca-bots/SKILL.md",
"digest": "sha256:c87e4bce24d102b399a60c3c2c49aa6980ea4931ef0f5be446a13c4e1c970b0d"
"digest": "sha256:c019fa2d37fb1703eae7ceb380c4c7e2da209116c77fe191b3340cfc1f6826ad"
},
{
"name": "pachca-forms",
Expand Down
18 changes: 18 additions & 0 deletions apps/docs/public/.well-known/skills/pachca-bots/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,21 @@ Help: `npx -y @pachca/cli --help` | Workflows: `npx -y @pachca/cli guide`
> Новый токен возвращается один раз. 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): собери данные из своей системы
Expand All @@ -127,6 +142,7 @@ Help: `npx -y @pachca/cli --help` | Workflows: `npx -y @pachca/cli guide`
- Rate limit: ~50 req/sec. On 429 — wait and retry.
- `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)

Expand All @@ -136,9 +152,11 @@ Help: `npx -y @pachca/cli --help` | Workflows: `npx -y @pachca/cli guide`
|--------|------|-------------|
| 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 | /webhooks/events | История событий |
| DELETE | /webhooks/events/{id} | Удаление события |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,12 @@ Sent when members are added/removed in chats where the bot is a member.

Global event (does not require the bot to be in a chat). Events: invite, confirm, update, suspend, activate, delete.

## Video calls

Sent for video calls in chats where the bot is a member.
Field `event` distinguishes: `started`, `finished` (includes participants and duration), `recording_ready` (includes recording file `url`, `size`, `duration`).
Field `type` is always `video_call`. Common fields: `video_room_id`, `chat_id`, `owner_id`, `thread`.

## Security

1. Verify signature: `HMAC-SHA256(Signing secret, raw body)` === `Pachca-Signature`
Expand Down
Loading
Loading