Команды в РФ часто собирают контур из CRM или портала, мессенджера MAX и внутренней базы знаний. Adminica закрывает RAG-слой: ответ по документам через API, события на ваш webhook и бот в MAX для сотрудников — без трёх разных продуктов.
Три канала — одна библиотека
| Канал | Кому | Типичный сценарий |
|---|---|---|
POST /api/v1/query | CRM, портал, скрипты | Кнопка «Справка по тикету» → ответ с источниками |
Webhooks (POST /api/v1/webhooks) | Ваш backend | Уведомление о готовом ответе, низком балансе, digest архива |
| MAX-бот из ЛК | Сотрудники в мессенджере | Быстрый вопрос по runbook без открытия CRM |
POST /chat/async + callback_url | Долгие диалоги | Ответ приходит POST на URL CRM, не блокируя UI |
Подробнее про MAX — в статье про бота MAX; про digest — scheduled queries.
Сценарий CRM: вопрос из тикета
- Пользователь нажимает «Подсказка из базы знаний» в карточке обращения.
- Ваш сервер вызывает
POST /api/v1/queryс API-ключомak_…(ключ — Профиль → Безопасность). - В теле запроса — текст тикета и при необходимости
filtersпо разделу библиотеки. - Ответ Adminica содержит текст и
entries[]с источниками — показываете в CRM или сохраняете в комментарий.
POST /api/v1/query
Authorization: Bearer ak_YOUR_KEY
Content-Type: application/json
{
"query": "Ошибка 502 на ingress nginx — что проверить по runbook?",
"filters": { "section": "DevOps" }
}
Webhooks: события в вашу систему
Создайте подписку в ЛК или через API. Adminica доставляет POST на ваш HTTPS URL с подписью X-Adminica-Signature: sha256=<hmac>.
query.completed— после успешного/api/v1/query(удобно для аудита и метрик CRM).chat.completed/chat.error— после async-чата.tokens.low— остаток < 500 токенов (напоминание пополнить баланс).digest.ready— «новое в архиве» по расписанию.
POST /api/v1/webhooks
{
"url": "https://crm.example.com/hooks/adminica",
"events": ["query.completed", "tokens.low"],
"description": "Bitrix24 / внутренний портал"
}
Секрет из ответа 201 сохраните один раз — им проверяете HMAC от сырого тела запроса. Retry с backoff; доставки видны в админке (карточка webhook observability).
Async-чат с callback_url
Если ответ RAG занимает десятки секунд, не держите HTTP-соединение CRM: POST /chat/async с callback_url и опционально callback_secret. Adminica вернёт task_id, а по готовности отправит тот же JSON, что и webhook chat.completed.
Ограничения безопасности: только HTTPS в production, private IP и localhost заблокированы (SSRF).
MAX для полевых и дежурных
CRM хорош для учёта обращений, но дежурный чаще в чате. Подключите бота MAX — ответы по той же библиотеке, токены с баланса владельца интеграции. Для узкого контекста (один клиент, один проект) включите bot_enabled на персональной ссылке.
Практики интеграции
- Разные API-ключи для staging и production; отзыв ключа в ЛК без смены пароля.
- Логируйте
X-Adminica-Delivery— id попытки доставки для разбора сбоев. - Для проактивного «что нового в архиве» — webhook на
digest.ready+run_scheduled_queries.pyпо cron. - Не дублируйте RAG в CRM: один запрос к Adminica, в тикет — ссылка на источник из
entries[].
Итог: CRM получает ответы через /api/v1/query и события через webhooks; MAX закрывает мессенджер; async-чат — длинные диалоги без таймаута. Всё на одной библиотеке знаний Adminica.