Chat-Widget (JSBOX)

Zuletzt aktualisiert: Oct 12, 2026Abschnitt: Integrationen

Der Integrationstyp JSBOX betreibt Website-Chat: Besucher senden Nachrichten, die in Ihrem Mailoo-Dashboard erscheinen. Sie können über die Chat-Konsole antworten; Besucher sehen Updates über WebSocket oder Polling.

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

Konzepte

  • Integrationstyp: JSBOX (erstellt im Dashboard oder über die öffentliche API mit einem API-Schlüssel).
  • Sessions: Jeder Besucher-Thread ist eine Chat-Session (opake sessionPublicId). Die erste Nachricht erstellt eine Session; spätere Nachrichten enthalten sessionPublicId.
  • API-Schlüssel: Erforderlich für serverseitige Aufrufe an Mailoo-Webhooks (Ihr BFF, Backend oder Automatisierung). Platzieren Sie den API-Schlüssel niemals in Browser-JavaScript.

Öffentliche API (X-API-Key)

Beschränkte Schlüssel können enthalten:

  • webhook.chat-integration-create --- POST /api/v1/webhooks/chat/{projectUid}/integrations (eine JSBOX-Integration erstellen).
  • chat.send-message --- Chat-Nachrichten, Session-Verlauf und Chat-Status unter /api/v1/webhooks/chat/....

JSBOX-Integration erstellen

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"]}}'

Besuchernachricht senden (auf Projekt + Integration begrenzt):

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"}'

Nachrichten einer Session auflisten (für Server-/BFF-Polling):

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

Chat-Integrationsstatus

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

Legacy-Pfad (nur Integrations-ID): POST /api/v1/webhooks/messages/{integrationId} existiert weiterhin, erfordert aber chat.send-message und eine JSBOX-Integration.

Öffentliche Chat-Webhooks teilen das API-Key-Rate-Limit. Bei Überschreitung antwortet Mailoo mit HTTP 429. Das Widget @mailoo/chat klassifiziert das (und Gateway-/Netzwerkfehler) und zeigt ein Unavailable-Panel statt rohem API-Text --- der Host sollte unavailableAction übergeben (siehe chat-widget-nextjs-example{.interpreted-text role="doc"}).

Dashboard (Bearer JWT)

  • Sessions: GET /api/v1/chat/{integrationId}/sessions --- optional status=OPEN|PENDING|CLOSED und assignedUserId=<userId> oder assignedUserId=unassigned.
  • Verlauf: GET /api/v1/chat/{integrationId}/sessions/{sessionPublicId}/messages
  • Eigentümer-Antwort: POST /api/v1/chat/{integrationId}/sessions/{sessionPublicId}/reply mit JSON {"content":"..."}.
  • Zuweisen / schließen: PATCH /api/v1/chat/{integrationId}/sessions/{sessionPublicId} mit {"assignedUserId":"<userId>"|null} (nur Projektmitglieder) oder {"action":"close"}.

Sessions sind OPEN, PENDING oder CLOSED. Widget-Einstellungen der JSBOX-Integration (config.chatWidget):

  • Autoresponder --- die erste Besuchernachricht in einer neuen Session sendet autoresponder.message; optionales expectedReplyHours setzt den Status auf PENDING, bis ein Operator antwortet.
  • Antwortvorlagen --- replyTemplates (keine FORM-Kampagnenvorlagen); die Konsole fügt sie in das Antwortfeld ein.
  • Follow-up beim Schließen --- bei action: close werden closeFollowUp.message und/oder closeFollowUp.reviewUrl gesendet. Weitere Besuchernachrichten in einer geschlossenen Session liefern 409.
  • Optionaler KI-Agent --- config.chatWidget.agent (enabled, name, optional imageMediaId, kbIntegrationId für einen Blog im gleichen Projekt, plus Markdown instructions, kbDigestPrompt, kbArticlePrompt und kbFiles). Wenn aktiv, erscheint der Agent zuerst in der Team-Liste (id jsbox_chat_agent). Die API stellt instructions voran, füllt die Digest-/Artikel-Templates und ruft Wednesday im Hintergrund mit einem KB-Digest (nur Titel + Slug) auf; Artikeltext per KB_REQUEST:<slug>. KB-Dateien liegen in S3 und gehen noch nicht an das Modell. Das Widget spricht Wednesday nicht an. Antworten sind OUTBOUND jsbox_chat_agent mit senderName = Anzeigename. Zuweisen stoppt den Agenten. Der Agent kann per HANDOFF_TO_HUMAN: an einen Menschen übergeben (Besuchertext plus Operator-Briefing); Mailoo setzt handedOffAt, Status PENDING, speichert das Briefing als OUTBOUND metadata.source: jsbox_chat_agent_handoff (nur Dashboard) und stoppt weitere Agent-Turns. WEDNESDAY_BASE_URL erforderlich (Dev: http://127.0.0.1:4080).
  • MCP / Agent-Einstellungen --- GET/PATCH /api/v1/chat/{projectUid}/integrations/{integrationId}/settings (Scope chat.manage oder MCP-Token) liest/aktualisiert dieselbe sanitisierte Widget-Config und liefert Lifetime-Zähler für Nachrichten und Sessions (keine Session-Liste / Nachrichteninhalte). MCP-Tool: manage_jsbox_integration_settings (siehe mailoo-mcp{.interpreted-text role="doc"}). Agent-Skill (minimale Regeln): configure-chat-mcp{.interpreted-text role="doc"}.

Die Web-App leitet diese über ihr BFF unter denselben Pfaden weiter (mit Session-Authentifizierung).

WebSocket

Auf einem Next.js-Host mit @mailoo/chat ist der Browser-WebSocket-Origin keine NEXT_PUBLIC_*-Build-Time-Variable: Der Server löst ihn zur Laufzeit auf (MAILOO_CHAT_WS_ORIGIN, sonst Chat-/API-Basis-Umgebung --- siehe getMailooChatWebSocketOrigin).

  • Eigentümer (Dashboard): /api/v1/chat/ws?integrationId=...&token=<JWT> --- verwenden Sie dasselbe Zugriffstoken wie Authorization: Bearer.
  • Besucher: /api/v1/chat/visitor-ws?projectUid=...&integrationId=...&sessionPublicId=... --- kein API-Schlüssel; die Session muss bereits existieren (erstellt durch das Senden einer Nachricht). Bevorzugen Sie es, dem Browser nur sessionPublicId bereitzustellen und wenn möglich auf Ihrem BFF zu validieren.

Für Architekturdetails, Ereignisnutzlasten, Reverse Proxy (wss) und Multi-Replikat-Einschränkungen siehe chat-websocket-production{.interpreted-text role="doc"}.

Dashboard (Integrationsdetail)

Auf der JSBOX-Integrationsseite nutzen Projektinhaber Registerkarten:

  • Widget --- Markenfarben, Willkommenstext, Datenschutz-URL, Launcher-Position (vier Ecken plus middle-left / middle-right; Standard bottom-right) und Themen-Chips.
  • Antworten & Automatisierung --- Operator-Sichtbarkeit, Autoresponder, Antwortvorlagen und Follow-up beim Schließen.
  • KI-Agent --- Einstellungen nur für den Inhaber: Schalter, Anzeigename, optionaler Avatar, Blog-KB, Markdown-Anweisungsfenster und Wissensbasis-Dateien (S3). Editoren können den Tab öffnen; speichern kann nur der Inhaber. Wenn aktiv, steht der Agent im Widget-Team und unter Setup → Operators (nicht umschaltbar). Der mailoo.app-Floating-Chat ist dieselbe JSBOX; der Dev-Seed aktiviert den Agenten mit Name, Blog-KB und Standard-Prompts (Wednesday + WEDNESDAY_BASE_URL).
  • Anbindung & Einstellungen --- Bildbibliothek, API-Schlüssel, Server-Env-Snippet und Löschen. Die gespeicherte Roh-config liegt hinter Konfigurations-JSON anzeigen (formatiertes Referenzdialog), nicht als dauerhaft sichtbarer Block.

JSBOX hat keinen Products-/Content-Tab --- Status, Nachrichtenanzahl und letzte Aktivität stehen in der Seitenkopfzeile. Editoren sehen diese Kopfzeilen-Metriken, Anbindung & Einstellungen und den Tab KI-Agent (Schalter deaktiviert). Widget-/Antwort-Editoren bleiben nur für den Inhaber.

CORS und allowedOrigins

Browser-Aufrufe an Mailoo-Webhooks können einen Origin-Header senden. Konfigurieren Sie optional allowed origins auf der JSBOX-Integration. Wenn die Liste leer ist, wird der Origin nicht geprüft (API-Schlüssel weiterhin erforderlich). Legacy-domain in gespeicherter Konfiguration bleibt ein CORS-Fallback für ältere Einträge, wird aber im Dashboard nicht mehr erfasst.

Die Launcher-Position wird als config.chatWidget.position gespeichert und über den öffentlichen widget-config-Endpunkt geliefert. Der Standard-Host-Pfad (resolveMailooChatHostConfig + MailooSiteChatShell) wendet sie immer über widgetConfig an. Ein explizites position-Prop an MailooSiteChatWidget überschreibt den gespeicherten Wert weiterhin, wenn gesetzt.

Siehe auch

  • chat-widget-nextjs-example{.interpreted-text role="doc"} --- Next.js-BFF-Muster und Umgebungsvariablen
  • chat-websocket-production{.interpreted-text role="doc"} --- WebSocket-Verhalten und Produktionshinweise
  • OpenAPI: https://api.mailoo.app/docs/v1
📚