Виджет чата --- Next.js (`@mailoo/chat`)

Обновлено: Aug 31, 2026Раздел: Интеграции

Предоставьте чат на сайте из хоста Next.js без размещения API-ключа в браузере. Используйте @mailoo/chat для BFF-маршрутов и опционального плавающего виджета. Контракт API и заметки по WebSocket: chat-widget{.interpreted-text role="doc"}, chat-websocket-production{.interpreted-text role="doc"}.

Поток

  1. Браузер вызывает только маршруты того же домена вашего приложения Next.js:
  • POST /api/v1/webhooks/chat/submit --- тело { "content": "...", "sessionPublicId?": "..." }
  • GET /api/v1/webhooks/chat/messages?sessionPublicId=... --- опциональный поллинг (since поддерживается)
  • GET /api/v1/webhooks/chat/status --- опциональный статус интеграции
  1. Обработчик маршрута пересылает в Mailoo с X-API-Key из серверного окружения (createChatSubmitHandler / createChatMessagesHandler / createChatStatusHandler из @mailoo/chat/routes). Опционально внедрите senderEmail / senderName через resolveSender, чтобы в панели управления отображалась личность посетителя вместо Guest.
  2. Опционально: виджет открывает WebSocket к API. Хост определяется во время выполнения на сервере (без NEXT_PUBLIC_* для origin API):
  • Порядок по умолчанию: MAILOO_CHAT_WS_ORIGIN → MAILOO_CHAT_INTEGRATION_API → API_BASE_URL (getMailooChatWebSocketOrigin из @mailoo/chat)
  • Установите MAILOO_CHAT_WS_ORIGIN, когда видимое браузеру имя хоста API отличается от URL, по которому Node-сервер обращается к API

Интерфейс пакета

// app/api/v1/webhooks/chat/submit/route.ts
import { createChatSubmitHandler } from '@mailoo/chat/routes'

export const POST = createChatSubmitHandler({
  resolveSender: async () => {
    const session = await auth()
    return session?.user?.email
      ? { email: session.user.email, name: session.user.name ?? undefined }
      : null
  },
})

// app/api/v1/webhooks/chat/messages/route.ts
import { createChatMessagesHandler } from '@mailoo/chat/routes'
export const GET = createChatMessagesHandler()

// app/api/v1/webhooks/chat/status/route.ts
import { createChatStatusHandler } from '@mailoo/chat/routes'
export const GET = createChatStatusHandler()

Headless-сессия (собственный UI) через @mailoo/chat/hooks:

import { useMailooChatSession } from '@mailoo/chat/hooks'

const chat = useMailooChatSession({
  apiOrigin,
  projectUid,
  integrationId,
  isAuthenticated,
  enabled: panelOpen,
})

Переменные окружения (только сервер)

MAILOO_CHAT_INTEGRATION_API=https://api.mailoo.app
MAILOO_CHAT_INTEGRATION_API_KEY=your-api-key-here
MAILOO_CHAT_INTEGRATION_PROJECT_UID=your-project-uid
MAILOO_CHAT_INTEGRATION_ID=your-jsbox-integration-id
MAILOO_CHAT_WELCOME_MESSAGE=Hello! How can we help?

# Необязательно: публичный API origin для ws/wss, если отличается от серверного URL API


# MAILOO_CHAT_WS_ORIGIN=https://api.mailoo.app

API-ключ должен иметь область chat.send-message (или FULL). Скопируйте projectUid и integrationId из раздела Подключение и настройки / фрагмента встраивания в панели управления.

Плавающий виджет

import { MailooSiteChatWidget } from '@mailoo/chat/client'

<MailooSiteChatWidget
  apiOrigin={wsOrigin}
  projectUid={projectUid}
  integrationId={integrationId}
  welcomeMessage={welcome}
  locale={locale}
  isAuthenticated={isAuthenticated}
/>

Консоль чата в панели управления

Для интеграций JSBOX Открыть консоль чата открывает интерфейс оператора для этой интеграции. Операторы используют сессию панели управления; посетители --- публичные вебхуки и WebSocket-пути выше.

Связанные материалы

  • chat-widget{.interpreted-text role="doc"} --- публичные вебхуки и области действия
  • chat-websocket-production{.interpreted-text role="doc"} --- заметки по продакшен WebSocket
  • nextjs-packages{.interpreted-text role="doc"} --- обзор пакетов
📚