pachca-bots

https://api.pachca.com/api/shared/v1

Authorization: Bearer <ACCESS_TOKEN>

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

• настроить бота
• вебхук
• 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 с превью-данными

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-функций по расписанию.

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

insufficient_scope

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

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

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

Подробнее