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-search
• аудит, журнал событий, безопасность → 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 с превью-данными

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} — удали событие, чтобы не обработать повторно

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

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

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

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

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

PUT /bots/{id}

скоуп: bots:write

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

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

POST /messages/{id}/link_previews

скоуп: link_previews:write

{
  "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