JSBOX-Chat-Widget-Integration

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.

Dashboard (Bearer JWT)

Sessions: GET /api/v1/chat/{integrationId}/sessions
Verlauf: GET /api/v1/chat/{integrationId}/sessions/{sessionPublicId}/messages
Eigentümer-Antwort: POST /api/v1/chat/{integrationId}/sessions/{sessionPublicId}/reply mit JSON {"content":"..."}.

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

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.

Widget-Position und Willkommensnachricht sind nicht Integrationskonfiguration --- setzen Sie sie in Ihrer Host-App (z. B. @mailoo/chat-Props oder Website-Umgebungsvariablen).

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

Chat-Widget (JSBOX)