AI-ассистент (copilot-чат)

AI-ассистент — встроенный в админку чат, который знает возможности Notifly и помогает их настроить. Вы пишете задачу человеческим языком («хочу узнавать, если ночной бэкап не отработал», «проверяй, что сайт жив»), а ассистент отвечает пошаговой инструкцией с примерами и — главное — предлагает готовые кнопки-действия, которые открывают уже предзаполненный диалог создания нужной сущности.

Чат открывается плавающей кнопкой «Открыть ИИ-помощника», которая после входа видна на любой странице админки, и выезжает боковой панелью справа.

Это не тот же AI, что AI-помощники в формах (подбор правил webhook-роутера и почтового ящика, CSS-селекторов монитора контента и т. п.): у ассистента отдельная дневная квота (assistantRequestsPerDay), он не расходует лимит событий и не упирается в лимит AI-помощников (aiRequestsPerDay).

Заметка

Ответы ассистента приходят целиком, без стриминга (модель request → response): запрос к LLM возвращает готовый текст и список действий одним JSON-ответом. На один ход уходит до нескольких секунд.

Что он умеет

• Отвечать на вопросы о платформе: что такое heartbeat, чем отличаются типы мониторов, какие лимиты у Free, как настроить email-доставку.
• Предлагать действия. Когда вы просите «создай / добавь / настрой» что-то, к ответу прикрепляется блок-действие — кнопка, открывающая диалог создания (heartbeat, монитор, HTTP-монитор, монитор контента, монитор портов, workflow-монитор, источник метрик, почтовый ящик, webhook-роутер, веб-скрипт или новый канал) с уже заполненными полями. Вам остаётся выбрать канал и подтвердить.
• Диагностировать. Ассистент видит краткую сводку по вашему аккаунту: что сейчас в статусе down/degraded/alerting, сколько активных и онлайн устройств, расход квот, недавние уведомления. На вопросы «что у меня не работает» или «почему не приходят уведомления» он отвечает по фактическому состоянию (например, подскажет, что все устройства suspended из-за лимита тарифа — и уведомления физически некому показать).

Беседы (threads)

Чат — многоходовый: ассистент помнит предыдущие реплики внутри одной беседы (в контекст модели передаётся до последних 20 сообщений). Каждая беседа — отдельный thread со своим заголовком (он берётся из первого сообщения).

• Первое сообщение без threadId создаёт новую беседу — её threadId возвращается в ответе, передавайте его в последующих запросах, чтобы продолжать тот же диалог.
• Список бесед — GET /assistant/threads, их история — GET /assistant/threads/:id/messages.
• Беседу можно удалить целиком — DELETE /assistant/threads/:id.

Действия (notifly-action)

Когда ассистент предлагает что-то настроить, в ответе появляется массив actions. Каждый элемент — это предзаполнение диалога создания, а не автоматическое изменение: ничего не создаётся, пока вы сами не подтвердите в открывшемся окне.

{
  "kind": "heartbeat",
  "label": "Настроить контроль бэкапа",
  "params": {
    "name": "Ночной бэкап",
    "intervalSec": 86400,
    "graceSec": 3600,
    "alertTitle": "Бэкап не выполнился",
    "alertMessage": "Пинг от задачи бэкапа не пришёл вовремя"
  }
}

• kind — тип сущности: heartbeat, monitor, http_monitor, content_monitor, port_monitor, workflow_monitor, metric_source, email_inbox, webhook_router, web_script, application.
• label — подпись кнопки на языке пользователя.
• params — поля для предзаполнения (все опциональны, любое можно поправить в диалоге). Канал (appid) в действие не входит — его вы выбираете при подтверждении.

Один ответ может содержать несколько действий (например, сразу создать канал и heartbeat к нему). Для сущностей без диалога-создания — интерактивные вопросы (ask) и браузерный workflow-монитор — готового действия нет: ассистент объяснит и направит на нужную страницу.

Квота

Каждый ход диалога (один POST /assistant/chat) списывает одно обращение из отдельной дневной квоты ассистента. Лимит зависит от тарифа и не входит в общий лимит событий и в лимит AI-помощников:

Тариф	assistantRequestsPerDay
Free	100
Pro	5000
Business	100000

Квота списывается до обращения к модели; при исчерпании запрос возвращает 429. Сброс — в 00:00 MSK, как и остальные дневные лимиты. Подробнее — Квоты и тарифы.

Осторожно

Эндпоинты ассистента принимают токен устройства (C…) или API-токен (M…) — с любым уровнем доступа, в том числе read. Токены канала (A…) и share-токены (S…) получают 403. Ассистент видит сводку по всему аккаунту: скоуп API-токена по каналам её не сужает.

Пример: отправка сообщения

Минимальный запрос — только text (новая беседа создаётся автоматически). NOTIFLY_URL для облачного Notifly — https://api.notifly.ru:

curl -X POST "$NOTIFLY_URL/assistant/chat" \
     -H "X-Notifly-Key: $NOTIFLY_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"text":"Хочу узнавать, если ночной бэкап не отработал"}'

Ответ:

{
  "threadId": 184,
  "messageId": 921,
  "text": "Для контроля бэкапа подойдёт heartbeat: задача после успешного завершения «пингует» уникальный URL, а если пинг не пришёл вовремя — Notifly шлёт алерт. Нажмите кнопку ниже, чтобы создать монитор.",
  "actions": [
    {
      "kind": "heartbeat",
      "label": "Настроить контроль бэкапа",
      "params": {
        "name": "Ночной бэкап",
        "intervalSec": 86400,
        "graceSec": 3600
      }
    }
  ]
}

Продолжение того же диалога — добавьте threadId из ответа:

curl -X POST "$NOTIFLY_URL/assistant/chat" \
     -H "X-Notifly-Key: $NOTIFLY_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"threadId":184,"text":"А если бэкап раз в неделю, а не каждый день?"}'

В ответе actions может быть пустым (массив отсутствует) — для чисто справочных вопросов кнопок не будет.

REST API

Метод и путь	Авторизация	Назначение
GET /assistant/threads	токен устройства или API-токен	список бесед пользователя
GET /assistant/threads/:id/messages	токен устройства или API-токен	история сообщений беседы
DELETE /assistant/threads/:id	токен устройства или API-токен	удалить беседу целиком
POST /assistant/chat	токен устройства или API-токен	отправить сообщение, получить ответ + действия
GET /assistant/insights	токен устройства или API-токен	проактивные рекомендации по аккаунту

Тело POST /assistant/chat: text (обязательно), threadId (опционально — продолжить беседу; без него создаётся новая).

Ответ POST /assistant/chat: threadId, messageId, text, actions[] (kind, label, params).

Ошибки POST /assistant/chat:

Код	Когда
400	пустой text (или тело — не JSON)
403	запрос с токеном канала (A…) или share-токеном (S…)
404	threadId не существует или принадлежит другому пользователю
429	дневная квота ассистента исчерпана
502	ошибка обращения к LLM; ход квоты к этому моменту уже списан
503	LLM на сервере не настроена — ассистент недоступен (квота не списывается)

GET /assistant/threads/:id/messages и DELETE /assistant/threads/:id на чужую или несуществующую беседу тоже отвечают 404.

Проактивные рекомендации (insights)

Помимо диалога, ассистент умеет сам смотреть на аккаунт и подсказывать, что настроено не до конца. В админке эти подсказки — карточка «Рекомендации» на главной странице «Все сообщения»: её можно обновить, свернуть, а отдельную рекомендацию — скрыть кнопкой «Скрыть» (скрываются все рекомендации с этим code, запоминается в браузере). Если замечаний нет, карточка не показывается. Те же данные доступны через GET /assistant/insights:

curl "$NOTIFLY_URL/assistant/insights" -H "X-Notifly-Key: $NOTIFLY_API_TOKEN"

{
  "insights": [
    {
      "code": "channel_no_recipient",
      "severity": "warn",
      "title": "Алерты некому получать",
      "detail": "Каналы Prod, Staging получают события, но в аккаунте нет активных устройств, а доставка у них не включена."
    },
    {
      "code": "no_ssl_monitor",
      "severity": "info",
      "title": "Нет контроля SSL-сертификата для example.com",
      "detail": "Хост проверяется по HTTPS, но срок действия сертификата не контролируется.",
      "action": {
        "kind": "monitor",
        "label": "Создать SSL-монитор",
        "params": {"kind": "ssl", "target": "example.com", "name": "SSL example.com"}
      }
    }
  ],
  "generatedAt": "2026-06-23T10:00:00Z"
}

Рекомендации строятся детерминированными эвристиками по срезу аккаунта (каналы и их доставка, heartbeat-ы, мониторы, устройства, API-токены) — модель фактов не придумывает. Каждая эвристика даёт не больше 5 рекомендаций. Коды стабильны и годятся для собственной логики:

code	О чём предупреждает
channel_no_recipient	канал получает события, но в аккаунте нет активных устройств, а доставка у канала не настроена — алерты никто не увидит
delivery_enabled_empty	способ доставки включён, но адрес не заполнен: email, SMS, звонок, Slack, Telegram, webhook, Discord, Teams, Mattermost, PagerDuty или Opsgenie
monitor_flapping	монитор (обычный или HTTP) нестабилен: неудачных проверок подряд как минимум вдвое больше порога алерта
no_ssl_monitor	хост проверяется по HTTPS, но нет SSL-монитора на истечение TLS-сертификата
heartbeat_never_pinged	heartbeat создан больше суток назад и не получил ни одного ping
api_token_no_scope	API-токен с доступом write выдан без ограничения скоупа

Query-параметры:

Параметр	Значение
polish=1	переформулировать тексты через LLM (списывает один ход квоты ассистента; при любой ошибке вернутся исходные формулировки)
refresh=1	пересобрать снапшот, не дожидаясь истечения кэша
lang	язык полировки (ru по умолчанию)

Ответ кэшируется на 10 минут на пользователя — состояние аккаунта меняется медленно, а сборка снапшота стоит около десятка запросов к базе. Обычный вызов (без polish=1) квоту не расходует.