---
name: pachca-bots
description: >
  Управление ботами, входящие/исходящие вебхуки, разворачивание ссылок
  (unfurling). Используй когда нужно: настроить бота, обработать вебхук,
  обработать нажатие кнопки, периодический дайджест, алерты, polling событий,
  развернуть ссылку. НЕ используй для: отправки сообщений от бота (→
  pachca-messages), интерактивных форм (→ pachca-forms).
---

# pachca-bots

Base URL: `https://api.pachca.com/api/shared/v1`
Авторизация: `Authorization: Bearer <ACCESS_TOKEN>`
Токен: бот (Автоматизации → Интеграции → API) или пользователь (Автоматизации → API).
Если токен неизвестен — спроси у пользователя перед выполнением запросов.

## Когда использовать

- настроить бота
- вебхук
- webhook
- обработать событие
- подпись вебхука
- нажатие кнопки
- callback
- дайджест
- алерт
- polling
- unfurl
- развернуть ссылку
- link preview

## Когда НЕ использовать

- получить профиль, мой профиль, установить статус → **pachca-profile**
- найти сотрудника, создать пользователя, список сотрудников → **pachca-users**
- создать канал, создать беседу, создать чат → **pachca-chats**
- отправить сообщение, ответить в тред, прикрепить файл → **pachca-messages**
- показать форму, интерактивная форма, модальное окно → **pachca-forms**
- создать задачу, список задач, напоминание → **pachca-tasks**
- аудит, журнал событий, безопасность → **pachca-security**

## Пошаговые сценарии

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

1. Создай бота в интерфейсе Пачки: Автоматизации → Интеграции → Webhook
2. Получи `access_token` бота во вкладке «API» настроек бота
3. Укажи Webhook URL для получения событий
4. Выбери типы событий: новые сообщения, реакции, кнопки, участники

> Бот создаётся через UI, не через API. Единственный эндпоинт для ботов — PUT /bots/{id} (обновление webhook URL). API используется для отправки сообщений от имени бота.

### Обработать входящий вебхук-событие

1. Получи POST-запрос на свой Webhook URL
2. Проверь подпись (Signing secret) для безопасности
3. Проверь `webhook_timestamp` — должен быть в пределах 1 минуты
4. Разбери JSON: тип события, данные
5. Для полной информации сделай запрос к API: GET /messages/{id} — особенно важно для получения вложений (`files[]`), которых нет в вебхуке

> Вебхук содержит минимум данных — файлы (`files`) в нём отсутствуют. Если сообщение может содержать вложения, всегда запрашивай GET /messages/{id}.

### Разворачивание ссылок (unfurling)

1. Создай специального Unfurl-бота и укажи отслеживаемые домены в его настройках
2. При появлении ссылки бот получает вебхук `"event": "link_shared"` с массивом `links` (`url` + `domain`) и `message_id`
3. Извлеки данные из своей системы по URL из `links`
4. Отправь POST /messages/{id}/link_previews с превью-данными

```bash
curl "https://api.pachca.com/api/shared/v1/messages/56431/link_previews" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"link_previews":{"https://example.com/article":{"title":"Заголовок статьи","description":"Краткое описание","image_url":"https://example.com/img.png"}}}'
```

> Эндпоинт привязан к конкретному сообщению. Необходим специальный Unfurl-бот с указанными доменами.

### Обработать нажатие кнопки (callback)

1. Получи вебхук с `"event": "message_button_clicked"` — в payload: `data` (из кнопки), `user_id`, `message_id`
2. Выполни нужное действие (запись в БД, запрос к API и т.д.)
3. Ответь пользователю: POST /messages с `"entity_type": "user"`, `"entity_id": user_id` из вебхука
4. Опционально: обнови исходное сообщение через PUT /messages/{id} — чтобы убрать кнопки передай `"buttons": []`, чтобы изменить текст — передай `"content"`

> Кнопка с `data` отправляет событие на вебхук. Кнопка с `url` — открывает ссылку (вебхука не будет).

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

1. По расписанию (cron/scheduler): собери данные из своей системы
2. Сформируй текст сообщения с нужными метриками или сводкой
3. POST /messages с `"entity_id": chat_id` нужного канала

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

### Мониторинг и алерты

1. Внешняя система (CI, мониторинг, сервис) обнаруживает событие (ошибка, деплой, порог метрики)
2. Делает POST запрос к твоему боту или напрямую вызывает Pachca API
3. POST /messages в канал алертов с описанием события и кнопками «Взять в работу» / «Игнорировать»
4. При нажатии кнопки — обработай callback и обнови статус алерта

### Обработка событий через историю (polling)

1. В настройках бота включи «Сохранять историю событий» (вкладка «Исходящий webhook»). Webhook URL указывать не обязательно.
2. По расписанию или по запросу: GET /webhooks/events — получи накопленные события с пагинацией (`limit`, `cursor`)
3. Обработай каждое событие (тот же формат payload, что и в real-time вебхуке)
4. После обработки: DELETE /webhooks/events/{id} — удали событие, чтобы не обработать повторно

```bash
curl "https://api.pachca.com/api/shared/v1/webhooks/events?limit=50" \
  -H "Authorization: Bearer $TOKEN"
```

> Polling — альтернатива real-time вебхуку, если у бота нет публичного URL или нужна отложенная обработка. Подходит для batch-сценариев, скриптов, serverless-функций по расписанию.

## Обработка ошибок

| Код | Причина | Что делать |
|-----|---------|------------|
| 422 | Неверные параметры | Проверь обязательные поля, типы данных, допустимые значения enum |
| 429 | Rate limit | Подожди и повтори. Лимит: ~50 req/sec, сообщения ~4 req/sec |
| 403 | Нет доступа | Недостаточно скоупов (`insufficient_scope`), бот не в чате, или endpoint только для админов/владельцев |
| 404 | Не найдено | Неверный id. Проверь что сущность существует |
| 401 | Не авторизован | Проверь токен в заголовке Authorization |

## Доступные операции

### Редактирование бота

`PUT /bots/{id}`

> скоуп: `bots:write`

```json
{
  "bot": {
    "webhook": {
      "outgoing_url": "https://www.website.com/tasks/new"
    }
  }
}
```

### Unfurl (разворачивание ссылок)

`POST /messages/{id}/link_previews`

> скоуп: `link_previews:write`

```json
{
  "link_previews": {}
}
```

### История событий

`GET /webhooks/events`

> скоуп: `webhooks:events:read`

### Удаление события

`DELETE /webhooks/events/{id}`

> скоуп: `webhooks:events:delete`

## Ограничения и gotchas

- `limit`: максимум 50
- Пагинация: cursor-based (limit + cursor), НЕ page-based

## Подробнее

см. [references/endpoints.md](references/endpoints.md)