Внешние интеграции

HCAPP может обмениваться данными с другими системами: сайтом, бухгалтерией, мессенджером, скриптом или AI-агентом. Для операций с данными используйте Bot API, для событий — вебхуки, для чтения и анализа данных в AI-ассистенте — MCP.

Направление	Инструмент	Для чего
Снаружи в HCAPP	Бот + Bot API	Внешний сервис создаёт, читает и обновляет задачи
Чтение данных HCAPP в AI-ассистенте	MCP (пилот)	Формы, списки задач с фильтрами и комментарии с учётом прав бота
Из HCAPP наружу	Вебхук формы	HCAPP сообщает внешнему сервису, что задача создана, изменена или завершена
Из HCAPP наружу	Вебхук бота	HCAPP отправляет боту каждое событие, адресованное ему: сообщение клиента из канала, комментарий, назначение. Так AI-агент слушает задачи

Большинство интеграций их сочетают: вебхук сообщает «в задаче 123 что-то произошло», а сервис затем читает задачу через Bot API и действует.

Боты: вход для внешних сервисов

Бот — это отдельный пользователь с ролью BOT. Это не человек, а учётная запись, под которой работает внешний сервис. Всё, что сервис делает в HCAPP, делается от имени этого бота, поэтому всегда видно, кто создал или изменил задачу.

Как это устроено:

Администратор создаёт бота в Profile → Users.
Боту выдаётся токен со сроком действия в неделях. Сервис передаёт этот токен в каждом запросе. Когда срок истекает, запросы перестают работать, пока не выдан новый токен.
Выдача нового токена отменяет предыдущий.
По умолчанию бот ничего не видит. Он работает только в тех формах, к которым ему выдан доступ, и с теми правами, которые в этом доступе указаны.

Через Bot API бот может создавать задачи, читать их и получать списком, обновлять поля, завершать задачи, возвращать их на этап, писать комментарии и загружать файлы. Подробнее: Bot API HCAPP.

Доступ для бота

Доступ выдаётся по каждой форме во вкладке Access формы, так же, как человеку. Помимо обычных прав, для ботов полезны два ограниченных:

Только чтение: бот читает задачи и комментарии и ничего не меняет. Подходит для отчётов и выгрузки данных.
Только создание: бот создаёт задачи и комментарии и загружает файлы, но не может читать существующие данные. Подходит для формы на сайте или канала приёма заявок.

По умолчанию один бот может иметь доступ максимум к 2 формам. Если интеграции нужно больше форм, создайте ещё одного бота.

Как подключить бота

Откройте Profile → Users и создайте пользователя с ролью BOT.
Сгенерируйте токен и выберите срок его действия.
Откройте форму → Access и выдайте боту доступ с нужными правами.
Укажите токен во внешнем сервисе. Он передаётся как Authorization: Bearer <token>.
Проверьте подключение запросом GET /bot/auth/verify.

Подробнее: Пользователи, Аутентификация, Правила и ограничения.

Вебхуки: HCAPP уведомляет внешний сервис

Вебхук — это запрос, который HCAPP отправляет на ваш адрес, когда происходит событие. Вашему сервису не нужно постоянно спрашивать HCAPP «есть ли что-то новое?».

Вебхук формы

Включается во вкладке Extensions формы. Вы указываете адрес и выбираете события:

задача создана
задача обновлена
задача завершена

HCAPP отправляет на адрес запрос с названием события (create, update или finish). Дополнительно можно включить передачу ID задачи и ID формы, а также задать токен, который HCAPP передаст в заголовке Authorization, чтобы ваш сервис мог убедиться, что запрос действительно пришёл из HCAPP.

Вебхук — это сигнал, данных задачи в нём нет. Чтобы получить данные, прочитайте задачу по её ID через Bot API.

Кнопка с вебхуком

Поле Button может вызывать адрес, когда пользователь нажимает кнопку. Используйте его, когда действие должен запускать человек: «отправить в бухгалтерию», «сформировать документ», «запустить проверку».

Уведомления бота

У бота может быть свой адрес вебхука, он задаётся в карточке бота в Profile → Users (блок Webhook, переключатель Deliver events). Каждое уведомление, адресованное боту, уходит туда POST-запросом с JSON вместо письма или сообщения в Telegram, которые получил бы человек. Так бот или AI-агент реагирует на то, что происходит в задачах.

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

Бот получает событие, когда:

он ответственный или участник задачи и кто-то пишет комментарий, отправляет сообщение или переводит задачу;
канал сообщений (Telegram, WhatsApp, Facebook), работающий от имени этого бота, получает сообщение от клиента;
его упомянули в комментарии.

О собственных действиях бот событий не получает, поэтому агент никогда не отвечает сам себе.

Тело запроса:

json

{
  "event_id": "task-notification:...",
  "event_type": "RESPONSIBLE",
  "notification_id": 1234,
  "recipient_user_id": 38,
  "company_id": 3,
  "form_id": 13,
  "task_id": 69941,
  "target_id": 7727,
  "form_name": "Расходы",
  "step_name": "Открыта",
  "content": "текст сообщения или комментария",
  "author_name": "Анна",
  "subject": null
}

target_id — ID сообщения или комментария, author_name — кто его написал (для сообщения из канала это клиент). Вебхук только сигнал: чтобы получить задачу целиком, прочитайте её по task_id через Bot API.

Доставка: ваш адрес должен ответить 2xx в течение 10 секунд. Иначе HCAPP повторит запрос через 30 секунд, 2 минуты, 10 минут и 24 часа. После пяти неудачных попыток вебхук выключается в карточке бота, его нужно включить снова.

Что выбрать

Нужно анализировать задачи в AI-ассистенте → MCP и AI-ассистенты. Пилотная версия работает только на чтение и требует настройки администратором.
Сайт или другая система должны создавать задачи в HCAPP → бот с правами «только создание».
Нужно выгружать данные в отчёт или другую систему → бот с правами «только чтение».
Внешняя система должна реагировать на изменения в HCAPP → вебхук формы и бот для чтения задачи.
Сотрудник должен запускать внешнее действие из задачи → кнопка с вебхуком.
AI-агент работает с задачами и отвечает в комментариях → бот с доступом к форме и вебхук бота.

Как пользоваться

Профиль

Формы

Типы полей

Расширения