Интеграция виджета чата JSBOX

Тип интеграции JSBOX обеспечивает чат на сайте: посетители отправляют сообщения, которые отображаются в панели управления Mailoo. Вы отвечаете из консоли чата; посетители видят обновления через WebSocket или поллинг.

::: {.contents local=""} :::

Концепции

Тип интеграции: JSBOX (создаётся в панели управления или через публичный API с API-ключом).
Сессии: Каждый поток посетителя --- это чат-сессия (непрозрачный sessionPublicId). Первое сообщение создаёт сессию; последующие сообщения содержат sessionPublicId.
API-ключ: Обязателен для серверных вызовов к вебхукам Mailoo (ваш BFF, бэкенд или автоматизация). Никогда не размещайте API-ключ в браузерном JavaScript.

Публичный API (`X-API-Key`)

Ограниченные ключи могут включать:

webhook.chat-integration-create --- POST /api/v1/webhooks/chat/{projectUid}/integrations (создание интеграции JSBOX).
chat.send-message --- сообщения чата, история сессий и статус чата по пути /api/v1/webhooks/chat/....

Создание интеграции JSBOX

curl -X POST "https://api.mailoo.app/api/v1/webhooks/chat/proj_1/integrations" \\
     -H "X-API-Key: YOUR_KEY" \\
     -H "Content-Type: application/json" \\
     -d '{"name":"Support chat","config":{"allowedOrigins":["https://example.com"]}}'

Отправка сообщения посетителя (привязка к проекту + интеграции):

curl -X POST "https://api.mailoo.app/api/v1/webhooks/chat/{projectUid}/{integrationId}/messages" \\
     -H "X-API-Key: YOUR_KEY" \\
     -H "Content-Type: application/json" \\
     -H "Origin: https://your-site.com" \\
     -d '{"content":"Hello","sessionPublicId":"optional-if-continuing"}'

Список сообщений сессии (для серверного/BFF-поллинга):

GET /api/v1/webhooks/chat/{projectUid}/{integrationId}/sessions/{sessionPublicId}/messages?since=ISO8601

Статус интеграции чата

GET /api/v1/webhooks/chat/{projectUid}/{integrationId}/status

Устаревший путь (только id интеграции): POST /api/v1/webhooks/messages/{integrationId} по-прежнему существует, но требует chat.send-message и интеграцию JSBOX.

Панель управления (Bearer JWT)

Сессии: GET /api/v1/chat/{integrationId}/sessions
История: GET /api/v1/chat/{integrationId}/sessions/{sessionPublicId}/messages
Ответ владельца: POST /api/v1/chat/{integrationId}/sessions/{sessionPublicId}/reply с JSON {"content":"..."}.

Веб-приложение проксирует эти маршруты через BFF по тем же путям (с авторизацией сессии).

WebSocket

На хосте Next.js с @mailoo/chat origin WebSocket в браузере --- не переменная NEXT_PUBLIC_* времени сборки: сервер определяет его во время выполнения (MAILOO_CHAT_WS_ORIGIN, иначе базовый URL чата/API --- см. getMailooChatWebSocketOrigin).

Владелец (панель управления): /api/v1/chat/ws?integrationId=...&token=<JWT> --- используйте тот же токен доступа, что и Authorization: Bearer.
Посетитель: /api/v1/chat/visitor-ws?projectUid=...&integrationId=...&sessionPublicId=... --- без API-ключа; сессия должна уже существовать (создаётся при отправке сообщения). Предпочтительнее предоставлять браузеру только sessionPublicId и проводить валидацию в вашем BFF.

Архитектурные детали, полезные нагрузки событий, обратный прокси (wss) и замечания по нескольким репликам см. в chat-websocket-production{.interpreted-text role="doc"}.

CORS и `allowedOrigins`

Браузерные вызовы к вебхукам Mailoo могут отправлять заголовок Origin. При необходимости настройте разрешённые источники на интеграции JSBOX. Если список пуст, Origin не проверяется (API-ключ по-прежнему обязателен). Устаревшее поле domain в хранимой конфигурации остаётся как CORS-фоллбэк для старых записей, но больше не собирается в панели управления.

Позиция виджета и приветственное сообщение не являются конфигурацией интеграции --- задайте их в вашем хост-приложении (например, пропсы @mailoo/chat или переменные окружения сайта).

См. также

chat-widget-nextjs-example{.interpreted-text role="doc"} --- паттерн BFF для Next.js и переменные окружения
chat-websocket-production{.interpreted-text role="doc"} --- поведение WebSocket и заметки по продакшену
OpenAPI: https://api.mailoo.app/docs/v1

Виджет чата (JSBOX)