MAX Messenger Button — документация

Версия сервиса: 0.0.1 (22.11.2025) Базовый шлюз: http://127.0.0.1:3500 → проксирует http://127.0.0.1:3600.

Быстрый старт

pnpm install
pnpm --filter @saas-apps/service-max-messenger dev
pnpm --filter @saas-apps/gateway dev
  • Сервис по умолчанию слушает http://127.0.0.1:3600.
  • Gateway проксирует путь /api/v1/max-messenger/*.
  • Первый запуск создаёт демо-конфиг (можно отключить MAX_SEED_DEMO=0).

Переменные окружения

Переменная По умолчанию Описание
PORT / HOST 3600 / 0.0.0.0 Сетевые настройки
MAX_STORE memory memory или file
MAX_FILE_PATH ./data/max-messenger.json Путь к JSON, если выбран файловый стор
MAX_SEED_DEMO 1 0 — не создавать демо-конфиг
API_KEY пусто Можно включить защиту приватных маршрутов (hook в index.ts)

CRUD API

Базовый URL через gateway: http://127.0.0.1:3500/api/v1/max-messenger.

Метод Путь Назначение
GET /configs Список конфигов (id, имя, версия, views/clicks).
POST /configs Создать конфиг { name, settings }.
GET /configs/:id Детали конфига.
PUT /configs/:id Обновить имя/настройки.
POST /configs/:id/publish Увеличить версию и отметить published.

settings описаны схемой services/max-messenger/src/schemas/config.ts. Ключевые поля: messengerLink, iconUrl, размеры кнопки, позиция, эффекты, триггеры появления.

Embed

Метод Путь Описание
GET /cfg/:id.json Публичный JSON.
GET /embed/:id.js Готовый скрипт.
GET /embed/health Проверка готовности.

Сниппет:

<!-- MAX Messenger Button -->
<script src="https://word-pres.ru/api/v1/max-messenger/embed/CONFIG_ID.js" async defer></script>

Скрипт автоматически:

  • создаёт фиксированную обёртку (bottom-left/right, top-left/right),
  • подгружает иконку, применяет фон/тень/радиус,
  • учитывает триггеры (triggerScroll, triggerTimeout, triggerImmediately, delaySeconds),
  • отправляет события view и click в /events.

События

POST /events принимает:

{
  "id": "abc123def",
  "event": "view" | "click",
  "t": 1732260000000
}
  • Embed отправляет view при первом показе и click при клике.
  • Стор хранит суммарные счётчики (views/clicks) в конфиге.

HTML-конструктор

  • Файл: gateway/site/templates/maxm-builder.html.
  • Использует fetch('/api/v1/max-messenger/configs', ...) для создания конфигов, поэтому убедитесь, что сервис запущен.
  • После создания ID конструктор автоматически подставляет embed и включает предпросмотр.

Диагностика

  1. GET /health → { status: 'ok' }.
  2. GET /embed/health через gateway https://word-pres.ru/api/v1/max-messenger/embed/health.
  3. Вставьте сниппет на тестовую страницу и проверьте, что в DevTools нет 404 и события view/click появляются в ответах /events.
  4. Список конфигов доступен через SPA (/app → карточка Social Floating/Max) или отдельную HTML-админку (пока не реализована).

Next

  • Добавить полноценную админ-страницу с таблицей конфигов/метрик.
  • Интегрировать авторизацию и тарифы.
  • Сгенерировать статическую doc-страницу /docs/max-messenger (аналог social-floating).