Öffentliche API

Dies sind die Endpunkte, die das eingebettete Widget selbst aufruft. Sie sind öffentlich — keine Benutzeranmeldung — und werden über Ihren Site-Key authentifiziert. Sie können sie direkt verwenden, um eine eigene Chat-Oberfläche zu erstellen.

Authentifizierung

Senden Sie Ihren Site-Key als Header. Anfragen werden außerdem gegen Ihre Domain-Allowlist geprüft, sodass ein durchgesickerter Key nicht von einer anderen Website verwendet werden kann.

X-Site-Key: your-site-key

Widget-Konfiguration abrufen

GET /public/widget-config

Gibt die Erscheinungsbild-Einstellungen zurück. Wird vom Widget beim Laden verwendet.

{
  "widgetPosition": "bottom_right",
  "widgetPrimaryColor": "#075CE5",
  "widgetFontFamily": "inherit",
  "widgetLogoUrl": null,
  "widgetAssistantName": "Minaya",
  "widgetWelcomeMessage": "Hi, I am Minaya your AI assistant...",
  "widgetHeaderTextColor": "#FFFFFF",
  "widgetBotBubbleColor": "#F1F1F3",
  "widgetBotTextColor": "#18181B",
  "widgetUserTextColor": "#FFFFFF",
  "widgetOpenByDefault": false,
  "widgetPathMode": "all",
  "widgetPathRules": [],
  "widgetCustomCss": null
}

widgetAssistantName wird serverseitig aufgelöst — es ist immer ein String, niemals null.

widgetPathMode und widgetPathRules legen fest, wo das Widget erscheinen soll (all, include oder exclude, mit Pfadmustern wie /blog/*). Das mitgelieferte Widget wendet sie an; ein eigener Client sollte das ebenfalls tun.

Caching

Lese-Endpunkte werden serverseitig zwischengespeichert und geleert, sobald sich die zugrunde liegenden Einstellungen ändern – eine gespeicherte Änderung ist also mit der nächsten Anfrage live. Antworten tragen einen X-Cache-Header (HIT oder MISS); senden Sie Cache-Control: no-cache, um den Cache für eine Anfrage zu umgehen.

Nachricht senden

POST /public/chat

{
  "message": "Do you ship to Canada?",
  "sessionId": "optional-existing-session",
  "visitorIdentifier": "optional-stable-visitor-id",
  "stream": false,
  "origin": "https://example.com",
  "country": "CA"
}

Lassen Sie sessionId weg, um eine Unterhaltung zu starten; die Antwort liefert eine ID, die Sie für Folgeanfragen wiederverwenden können.

{ "sessionId": "…", "reply": "Yes — 3 to 5 business days…", "messageId": "…" }

Mit stream: true trifft die Antwort als Server-Sent Events ein, jedes mit einem content-Delta und einem abschließenden done-Event.

Verlauf abrufen

GET /public/chat/history/:sessionId

Gibt die Nachrichten einer Sitzung zurück, begrenzt auf Ihr Unternehmen, sodass das Widget einer Website niemals die Unterhaltungen einer anderen lesen kann. Wird verwendet, um eine Unterhaltung wiederherzustellen, wenn ein Besucher das Widget erneut öffnet.

Nachricht bewerten

POST /public/chat/feedback

{ "messageId": "…", "feedback": "up" }

Akzeptiert up oder down, und nur für Nachrichten des Assistenten. Bewertungen erscheinen in Ihren Dashboard-Analysen.

Analyse-Events

POST /public/track-click
POST /public/track-page-view

Werden ausgelöst, wenn das Widget geöffnet wird und wenn eine Seite geladen wird. Beide akzeptieren optional sessionId, visitorIdentifier, origin und country.

Rate Limits und Obergrenzen

Chat-Anfragen sind pro Site-Key rate-limitiert.
50 Nachrichten pro Sitzung.
500 Zeichen pro Nachricht.
Unternehmen im kostenlosen Tarif haben ein tägliches Nachrichtenlimit.
Kostenpflichtige Pläne haben ein monatliches Kontingent – 2.000 Nachrichten bei Starter, 10.000 bei Pro –, gezählt über alle Gespräche und alle Domains, auf denen das Widget läuft, von Verlängerung zu Verlängerung.
Mit Minayas KI zählt eine Antwort, die eine Aktion ausführt – einen Lead erfasst oder ein MCP-Tool aufruft –, als 3 Nachrichten des Kontingents. Mit eigenem Schlüssel zählt jede Antwort als eine.
Eine Tagesobergrenze bei kostenpflichtigen Plänen, das Dreifache des Tagesdurchschnitts, verhindert, dass eine Endlosschleife den ganzen Monat an einem Tag verbraucht.

Das Überschreiten eines Limits liefert eine normale Antwort, die die Situation erklärt, statt eines Fehlers, sodass eine eigene Oberfläche sie wie jede andere Nachricht anzeigen kann.

Dashboard-API

Die Verwaltung von Wissensquellen, Erscheinungsbild und MCP-Servern erfolgt über authentifizierte Endpunkte unter demselben Host, dokumentiert in der OpenAPI-Spezifikation unter /api/docs auf Ihrer Deployment-Instanz.

ZurückMCP-Integration WeiterTarife und Abrechnung