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

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

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

Заметка

Ответы ассистента приходят целиком, без стриминга (модель 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	2000
Business	20000

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

Осторожно

Эндпоинты ассистента требуют client-token (C…) или Basic Auth, и не доступны для расшаренных каналов и для отправляющего app-токена (A…).

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

Минимальный запрос — только text (новая беседа создаётся автоматически):

curl -X POST "$NOTIFLY_URL/assistant/chat" \
     -H "X-Notifly-Key: C_ваш_клиентский_токен" \
     -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: C_ваш_клиентский_токен" \
     -H "Content-Type: application/json" \
     -d '{"threadId":184,"text":"А если бэкап раз в неделю, а не каждый день?"}'

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

REST API

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

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

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

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

Помимо диалога, ассистент умеет сам смотреть на аккаунт и подсказывать, что настроено не до конца. Эти карточки показываются на дашборде админки и доступны через GET /assistant/insights:

curl "$NOTIFLY_URL/assistant/insights" -H "X-Notifly-Key: <client-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-ы, мониторы, устройства, MCP-токены) — модель фактов не придумывает. Коды стабильны и годятся для собственной логики:

code	О чём предупреждает
channel_no_recipient	у канала нет получателей — сообщения некуда доставлять
delivery_enabled_empty	способ доставки включён, но адрес не заполнен
monitor_flapping	монитор «мигает» между up и down
no_ssl_monitor	нет проверки истечения TLS-сертификата
heartbeat_never_pinged	heartbeat создан больше суток назад и не получил ни одного ping
mcp_token_no_scope	MCP-токен выдан без ограничения скоупа

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

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

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