Chat-Widget --- Next.js (`@mailoo/chat`)

Stellen Sie Site-Chat von einem Next.js-Host bereit, ohne einen API-Schlüssel im Browser zu platzieren. Verwenden Sie @mailoo/chat für BFF-Routen und das optionale schwebende Widget. API-Vertrag und WebSocket-Hinweise: chat-widget{.interpreted-text role="doc"}, chat-websocket-production{.interpreted-text role="doc"}.

Ablauf

1. Der Browser ruft nur Same-Origin-Routen Ihrer Next.js-App auf:

• POST /api/v1/webhooks/chat/submit --- Body { "content": "...", "sessionPublicId?": "..." }
• GET /api/v1/webhooks/chat/messages?sessionPublicId=... --- optionales Polling (since unterstützt)
• GET /api/v1/webhooks/chat/status --- optionaler Integrationsstatus

2. Der Routenhandler leitet an Mailoo mit X-API-Key aus Server-Umgebung weiter (createChatSubmitHandler / createChatMessagesHandler / createChatStatusHandler aus @mailoo/chat/routes). Optional senderEmail / senderName via resolveSender injizieren, damit das Dashboard die Besucheridentität statt Guest anzeigt.
3. Optional: das Widget öffnet WebSocket zur API. Der Host wird zur Laufzeit auf dem Server aufgelöst (kein NEXT_PUBLIC_* für API-Origin):

• Standardreihenfolge: MAILOO_CHAT_WS_ORIGIN → MAILOO_CHAT_INTEGRATION_API → API_BASE_URL (getMailooChatWebSocketOrigin aus @mailoo/chat)
• Setzen Sie MAILOO_CHAT_WS_ORIGIN, wenn sich der browsersichtbare API-Hostname von der URL unterscheidet, die der Node-Server zum Aufrufen der API verwendet

Paketoberfläche

// 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-Session (eigene UI) über @mailoo/chat/hooks:

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

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

Umgebungsvariablen (nur serverseitig)

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?

# Optionaler öffentlicher API-Origin für ws/wss wenn abweichend von der serverseitigen API-URL


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

Der API-Schlüssel benötigt chat.send-message (oder FULL). Kopieren Sie projectUid und integrationId aus den Dashboard-Connection & settings / dem Einbettungs-Snippet.

Schwebendes Widget

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

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

Dashboard-Chat-Konsole

Für JSBOX-Integrationen öffnet Open chat console die Operator-UI für diese Integration. Operatoren verwenden die Dashboard-Session; Besucher verwenden die öffentlichen Webhook- und WebSocket-Pfade oben.

Verwandt

• chat-widget{.interpreted-text role="doc"} --- Öffentliche Webhooks und Berechtigungen
• chat-websocket-production{.interpreted-text role="doc"} --- Produktions-WebSocket-Hinweise
• nextjs-packages{.interpreted-text role="doc"} --- Paketübersicht