Интеграция виджета чата 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.

Публичные chat-webhook'и делят rate limit API-ключа. При превышении Mailoo отвечает HTTP 429. Виджет @mailoo/chat классифицирует это (и сбои gateway/сети) и показывает панель недоступности вместо сырого текста API --- хост должен передать unavailableAction (см. chat-widget-nextjs-example{.interpreted-text role="doc"}).

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

Сессии: GET /api/v1/chat/{integrationId}/sessions --- опционально status=OPEN|PENDING|CLOSED и assignedUserId=<userId> или assignedUserId=unassigned.
История: GET /api/v1/chat/{integrationId}/sessions/{sessionPublicId}/messages
Ответ владельца: POST /api/v1/chat/{integrationId}/sessions/{sessionPublicId}/reply с JSON {"content":"..."}.
Назначение / закрытие: PATCH /api/v1/chat/{integrationId}/sessions/{sessionPublicId} с {"assignedUserId":"<userId>"|null} (только участники проекта) или {"action":"close"}.

Статус сессии: OPEN, PENDING или CLOSED. Настройки виджета JSBOX (config.chatWidget):

Автоответ --- первое сообщение посетителя в новой сессии отправляет autoresponder.message; опциональный expectedReplyHours ставит PENDING, пока оператор не ответит.
Шаблоны ответов --- replyTemplates (не кампании FORM); консоль вставляет их в поле ответа.
Сообщение при закрытии --- при action: close посетителю уходят closeFollowUp.message и/или closeFollowUp.reviewUrl. Дальнейшие сообщения в закрытую сессию --- 409.
Опциональный ИИ-агент --- config.chatWidget.agent (enabled, name, опционально imageMediaId, kbIntegrationId Blog того же проекта, markdown instructions / kbDigestPrompt / kbArticlePrompt, kbFiles). При включении агент первым в roster команды (id jsbox_chat_agent). Mailoo API подставляет инструкции и шаблоны (плейсхолдеры {{kb_digest}}, {{visitor_message}}, {{article_title}}, {{article_slug}}, {{article_body}}) и вызывает Wednesday в фоне с дайджестом KB (только title + slug); тело статьи --- по KB_REQUEST:<slug>. Файлы KB хранятся в S3 и пока не отдаются модели. Виджет Wednesday не вызывает. Ответы --- OUTBOUND jsbox_chat_agent, senderName = имя агента. Assign останавливает агента. Агент также может передать человекам через HANDOFF_TO_HUMAN: (текст посетителю + brief оператору); Mailoo ставит handedOffAt, статус PENDING, сохраняет brief как OUTBOUND metadata.source: jsbox_chat_agent_handoff (только dashboard) и больше не вызывает агента. Нужен WEDNESDAY_BASE_URL (dev: http://127.0.0.1:4080).
MCP / настройки агента --- GET/PATCH /api/v1/chat/{projectUid}/integrations/{integrationId}/settings (скоуп chat.manage или MCP-токен) читает/обновляет тот же санитизированный config виджета и возвращает lifetime counts сообщений и сессий (без списка сессий и тел сообщений). Инструмент MCP: manage_jsbox_integration_settings (см. mailoo-mcp{.interpreted-text role="doc"}). Skill агента (минимум правил): configure-chat-mcp{.interpreted-text role="doc"}.

Веб-приложение проксирует эти маршруты через 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"}.

Панель (карточка интеграции)

На странице интеграции JSBOX владельцы проекта используют вкладки:

Виджет --- цвета бренда, приветственный текст, URL политики конфиденциальности, позиция лаунчера (четыре угла плюс middle-left / middle-right; по умолчанию bottom-right) и темы.
Ответы и автоматизация --- видимость операторов, автоответчик, шаблоны ответов и follow-up при закрытии.
ИИ Агент --- настройки владельца для config.chatWidget.agent: тоггл, имя, опциональный аватар, Blog KB, окна markdown-инструкций и загрузка файлов KB (S3). Редакторы открывают вкладку; сохранить может только владелец. При включении агент в команде виджета и в Setup → Operators (без чекбокса). Плавающий чат mailoo.app --- та же JSBOX; dev seed включает агента с именем, Blog KB и шаблонами промптов (Wednesday + WEDNESDAY_BASE_URL).
Подключение и настройки --- библиотека изображений, API-ключи, сниппет окружения сервера и удаление. Сырой config доступен за кнопкой Показать JSON конфигурации (форматированный справочный диалог), а не как постоянно видимый блок.

У JSBOX нет вкладки Products/контент --- статус, число сообщений и последняя активность остаются в шапке страницы. Редакторы видят эти метрики в шапке, Подключение и настройки и вкладку ИИ Агент (тоггл выключен). Редакторы виджета/ответов остаются только у владельца.

CORS и `allowedOrigins`

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

Позиция лаунчера хранится в config.chatWidget.position и отдаётся публичным widget-config. Дефолтный путь хоста (resolveMailooChatHostConfig + MailooSiteChatShell) всегда применяет её через widgetConfig. Явный проп position на MailooSiteChatWidget по-прежнему перекрывает сохранённое значение, если задан.

См. также

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)