Hilfezentrum
Chat API

Management API

Zuletzt aktualisiert:

Übersicht über die Management API

Die Management API ist für Back-Office-Aufgaben gedacht, bei denen keine Chat-Nachrichten gesendet werden:

  • Bot programmatisch erstellen mit POST /v1/management/bots
  • Einen bestimmten eigenen Bot abrufen mit GET /v1/management/bots/{bot_id}
  • Einen bestimmten Bot aktualisieren mit PATCH /v1/management/bots/{bot_id}
  • Abonnement-Nutzung abrufen mit GET /v1/usage

Management-Schlüssel sind an Ihr Konto gebunden, nicht an einen bestimmten Bot. Sie werden bewusst getrennt von Bot Talk-Schlüsseln gehalten, damit ein kompromittierter Chat-Schlüssel Ihre Bots nicht verändern oder Ihre Abrechnungsdaten einsehen kann.

Basis-URL

https://api.chatlab.com/aichat

Alle Endpunkte in diesem Artikel beziehen sich auf diese Basis-URL.

Erste Schritte

  1. Öffnen Sie die Admin-App und gehen Sie zu Account Settings (Kontoeinstellungen) > Management API.
  2. Klicken Sie auf Create Management Key (Management-Schlüssel erstellen), vergeben Sie einen Namen, legen Sie optional eine IP-Whitelist und ein Rate-Limit fest und senden Sie das Formular ab.
  3. Kopieren Sie den vollständigen Schlüssel aus dem Erfolgs-Modal. Der Klartext wird nur ein einziges Mal angezeigt.

Ein Schlüssel sieht aus wie mk_abcdefghijklmnopqrstuvwxyz012345. Das Präfix mk_ unterscheidet ihn von Bot Talk-Schlüsseln (ck_).

Authentifizierung

Authorization: Bearer mk_abcdefghijklmnopqrstuvwxyz012345

Das Senden eines mk_-Schlüssels an /v1/chat (oder einen beliebigen anderen Bot Talk-Endpunkt) gibt 403 key_type_not_allowed zurück. Das Senden eines ck_-Schlüssels an /v1/management/* gibt denselben Fehler zurück.

Limits

  • Maximal 5 aktive Management API-Schlüssel pro Benutzer
  • Maximal 10 Anfragen pro Minute pro Schlüssel (Token-Bucket-Verfahren, Kapazität 10, gleichmäßiges Nachfüllen von ~1 Token alle 6 Sekunden). Beim Erstellen nach unten konfigurierbar - setzen Sie ein niedrigeres rateLimitPerMinute, sinkt die Obergrenze und die Nachfüllrate skaliert entsprechend mit.

Berechtigungen

Jeder Management-Schlüssel verfügt über eine beliebige Teilmenge der folgenden drei Berechtigungen. Mindestens eine muss beim Erstellen ausgewählt werden; andernfalls wird die Anfrage mit 400 invalid_request_error abgelehnt. Der Aufruf eines Endpunkts mit einem Schlüssel, dem die erforderliche Berechtigung fehlt, gibt 403 insufficient_permissions zurück.

  • bot_read - erforderlich für GET /v1/management/bots/{bot_id}
  • bot_management - erforderlich für POST /v1/management/bots und PATCH /v1/management/bots/{bot_id}
  • usage - erforderlich für GET /v1/usage

Struktur des Request-Bodys: verschachtelte Abschnitte spiegeln die Admin-UI-Tabs wider

POST und PATCH akzeptieren einen JSON-Body, der in 13 Abschnitte unterteilt ist. Jeder Abschnitt entspricht einem Unter-Tab in der Seitenleiste "Bot Settings" der Admin-App, sodass die JSON-Schlüssel und die sichtbaren Tabs übereinstimmen: Wenn Sie consent.humanSupportRequirePolicyAccept über die API ändern, wird derselbe Umschalter auf dem Tab Consent & Privacy (Einwilligung & Datenschutz) in der Admin-App umgelegt.

  • role - Bot-Persona, Raw-Prompt, Antwortlänge, Sprache, Kontext der Website / des Unternehmens (Tab "Role & Behavior" / Rolle & Verhalten)
  • conversation - Begrüßungsnachricht, Anfrageverfeinerung, Konversationskontinuität, Bewertungs-Umschalter + Tooltips, vorgeschlagene Fragen + dynamische Nachfragen (Tab "Chat Conversation" / Chat-Konversation)
  • chatMemory - Chat-Gedächtnis-Umschalter, Zusammenfassungs-Prompts, Kontextzuweisung (Tab "Summaries & Memory" / Zusammenfassungen & Gedächtnis)
  • appearance - Farben, Texte, Abmessungen, benutzerdefiniertes CSS, Begrüßungsbildschirm, Styling für vorgeschlagene Fragen, Verhalten beim automatischen Öffnen, Simulation menschlichen Tippens, Footer-Markdown (Tab "Appearance" / Erscheinungsbild)
  • humanSupport - menschliches Kontaktformular (Tab "Human Contact Form" / Menschliches Kontaktformular)
  • leadCollection - Lead-Erfassungsformular (Tab "Lead Collection" / Lead-Erfassung)
  • liveChat - Übergabe an den Live Chat (Tab "Live Chat")
  • consent - alle vier Datenschutzrichtlinien-Einwilligungsschalter sowie der Text des Einwilligungsbildschirms (Tab "Consent & Privacy" / Einwilligung & Datenschutz)
  • whiteLabel - Logo ausblenden, benutzerdefinierter Logo-Link, Hosting auf eigener Domain (Tab "Whitelabel")
  • security - zulässige Domains, Spamfilter, Talk-Rate-Limits (Tab "Security" / Sicherheit)
  • voice - Spracheingabe und Sprachunterhaltungen: Modell, Stimme, Sprachen, Prompt, maximale Dauer (Tab "Voice Conversation" / Sprachunterhaltung)
  • multilingual - mehrsprachiger Modus, Basissprache, angebotene Sprachen, Handhabung der Wissenssprachen (Tab "Languages" / Sprachen)
  • advanced - LLM-Modell, Temperatur, Kontextgröße, Limit für Bot-Nachrichten, internes Locale, Offer Cards (Tab "Model & Advanced" / Modell & Erweitert)

Nur name befindet sich auf oberster Ebene, da es den Bot identifiziert und nicht zu einem einzelnen Tab gehört.

Die Seitenleiste "Bot Settings" verfügt derzeit über 15 Unter-Tabs, von denen 13 den oben genannten Abschnitten entsprechen. Die beiden Unter-Tabs ohne entsprechenden Abschnitt sind Flow und Actions - beide werden unten unter "Außerhalb des API-Umfangs" behandelt. Die 13 Tabs mit Entsprechung sind Appearance, Chat Conversation, Role & Behavior, Human Contact Form, Lead Collection, Live Chat, Whitelabel, Consent & Privacy, Security, Model & Advanced, Summaries & Memory, Voice Conversation und Languages.

Request-Body und Response-Body teilen sich dieselbe Struktur. Die Antwort enthält zwei zusätzliche Angaben:

  • meta - schreibgeschützt: Bot-ID und Zeitstempel. Entfernen Sie diesen Abschnitt, um eine GET-Antwort in einen gültigen POST-Body zu verwandeln.
  • apiKey - nur beim Erstellen vorhanden - der neu generierte Bot Talk API-Schlüssel für den neuen Bot.

Zwei Felder innerhalb der gemeinsamen Struktur sind schreibgeschützt - sie werden in der Antwort zurückgegeben und ignoriert, wenn Sie versuchen, sie per POST/PATCH zu senden:

  • appearance.avatarUrl - vollständig qualifizierte öffentliche URL des Bot-Avatar-Bildes (z. B. https://api.chatlab.com/aichat/content/avatar_xyz.png). Führen Sie einen direkten GET-Aufruf aus, um die Rohdaten herunterzuladen. Um sie zu ändern, laden Sie eine neue Datei über den Multipart-Teil avatar hoch (siehe PATCH).
  • whiteLabel.whitelabelLogoUrl - vollständig qualifizierte öffentliche URL des White-Label-Header-Logos. Gleiches Muster wie bei avatarUrl. Um sie zu ändern, laden Sie eine neue Datei über den Multipart-Teil whitelabel_logo hoch (siehe PATCH).

Beide URLs verwenden Schema + Host + Kontextpfad der aktuellen Anfrage; bei einer benutzerdefinierten White-Label-Domain verweisen sie daher direkt auf diese Domain (z. B. https://api.acme.com/aichat/content/...).

Senden Sie null für einen Abschnitt, um ihn bei PATCH zu überspringen; senden Sie null für ein Feld innerhalb eines Abschnitts, um dieses einzelne Feld zu überspringen. Ein null auf Feldebene löscht niemals einen gespeicherten Wert - es bedeutet lediglich "nicht ändern".

Rolle und Prompt-Erstellung

Der System-Prompt, den das LLM tatsächlich erhält, wird abhängig von role.role auf eine von zwei Arten erstellt. Zu wissen, welcher Zweig aktiv ist, zeigt Ihnen, welche Felder relevant sind und welche zwar gespeichert, aber ignoriert werden.

Zweig A - role.role ist CUSTOMER_SUPPORT, SALES oder LEAD_COLLECTION_AGENT (vorlagenbasiert)

Das Backend setzt den Prompt aus einer integrierten Vorlage zusammen und ignoriert role.rawPrompt vollständig (der Wert wird dennoch beim Bot gespeichert, nur nicht verwendet). Die Vorlage berücksichtigt:

  • role.role - Rollenbezeichnung (z. B. "Customer Support") und rollenspezifische Anweisungen werden automatisch angehängt
  • name - Bot-Name, der in den einleitenden Satz eingefügt wird
  • role.language - "Auto Detect" stellt den Bot so ein, dass er der Sprache des Nutzers folgt; jeder andere Wert (z. B. "English", "Polish") wird zu "Output in {language}, unless user uses another language"
  • role.responseLength - wird auf eine Ziel-Wortanzahl abgebildet: Concise ≈ 50 Wörter, Normal ≈ 100, Detailed ≈ 200
  • role.websiteAddress - optional; wenn ausgefüllt, angehängt als "for the users of the website {url}"
  • role.companyDescription - optional; wenn ausgefüllt, als zusätzlicher Absatz vor den Rollenanweisungen vorangestellt

Dies ist der empfohlene Zweig für die meisten Bots - Sie erhalten automatisch auf die Rolle abgestimmtes Verhalten und Sicherheitsleitplanken.

Zweig B - role.role ist CUSTOM (vom Aufrufer bereitgestellter Prompt)

Das Backend verwendet role.rawPrompt wortwörtlich als gesamten System-Prompt. responseLength, language, websiteAddress und companyDescription werden gespeichert, aber nicht in den Prompt eingefügt - wenn Sie möchten, dass sich eines dieser Felder im Verhalten des Bots widerspiegelt, müssen Sie es selbst in Ihren rawPrompt-Text aufnehmen. Rollenspezifische Sicherheitsleitplanken und Tonfall-Anweisungen werden ebenfalls nicht hinzugefügt; Sie steuern den gesamten Prompt selbst.

Verwenden Sie CUSTOM nur, wenn der vorlagenbasierte Prompt nicht zu Ihrem Anwendungsfall passt (z. B. wenn Sie eine sehr domänenspezifische Persona, eigene Sicherheitsvorgaben oder ein nicht standardmäßiges Ausgabeformat benötigen).

Enum- / Wertebereich-Felder

Mehrere Felder akzeptieren nur eine feste Auswahl an String-Werten. Das Senden eines Werts außerhalb der Liste wird mit 400 validation_failed und dem Feldpfad in error.param abgewiesen. Bei den Werten wird zwischen Groß- und Kleinschreibung unterschieden.

  • role.role - CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM
  • role.responseLength - Concise, Normal, Detailed
  • role.language - vollständiger englischer Sprachname aus dem Admin-Dropdown, z. B. Auto Detect, English, Polish, Spanish, German, French, Italian, Portuguese, Dutch, Russian, Chinese (Simplified), Japanese, Arabic, Hindi und rund 80 weitere. Der Wert wird wörtlich gespeichert und in die Prompt-Vorlage eingesetzt; zweistellige ISO-Codes (en, pl) und andere Werte außerhalb der Liste werden von der API zwar nicht abgelehnt, führen aber zu einer fehlerhaften Anweisung wie "Output in en, unless...". Standardmäßig Auto Detect, wenn beim Erstellen weggelassen.
  • advanced.model - siehe "KI-Textmodelle" unten; die auswählbare Menge unterliegt Ihren Kontolimits, und jeder Wert, den Ihr Konto nicht nutzen kann, gibt 400 invalid_parameter zurück
  • advanced.chatContextSize - 8000, 16000, 32000. Unterliegt Ihren Kontolimits; höhere Werte werden stillschweigend nach unten korrigiert
  • chatMemory.clientSummaryPromptType - DEFAULT, CUSTOM
  • chatMemory.conversationSummaryPromptType - DEFAULT, CUSTOM
  • appearance.chatAlignment - left, right
  • appearance.minimizedDisplayMode - icon, minified
  • appearance.chatMessageLinkTarget - _blank, _self
  • leadCollection.requireBeforeNewConversation - boolescher Umschalter. true zwingt den Nutzer dazu, das Lead-Formular auszufüllen, bevor ein Gespräch begonnen werden kann; false überlässt es der KI zu entscheiden, wann das Formular angezeigt wird (Standard).

Strukturierte Felder und Wertebereiche

Felder, die wie einfache Strings oder Zahlen aussehen, aber spezifische Formate, Bereiche oder Besonderheiten in der Admin-UI aufweisen, die man kennen sollte.

  • advanced.temperature - zulässiger Bereich ist 0.0 bis 1.0, passend zum Schieberegler in der Admin-UI. Werte außerhalb dieses Bereichs werden mit 400 validation_failed abgewiesen.

  • chatMemory.summariesToKnowledgeRatio - ganzzahliger Prozentwert, 10-90 in 10er-Schritten (step 10). Steuert, wie viel des Chat-Kontexts für historische Zusammenfassungen des Clients im Vergleich zum Rest (Wissensdatenbank, aktuelle Konversation, Anweisungen) reserviert ist. Standard ist 50. Werte außerhalb von 10-90 werden mit 400 validation_failed abgewiesen. Gilt nur, wenn chatMemory.enabled=true UND chatMemory.summaryConversationsEnabled=true.

  • liveChat.schedule - als String codiertes JSON, kein verschachteltes JSON-Objekt bei der Übertragung. Der Server speichert den Roh-String unverändert; die Admin-UI parst ihn clientseitig beim Rendern des Zeitplan-Editors. Nach dem Parsen enthält der String einen Eintrag pro Wochentag sowie einen timezone-Schlüssel:

    • jeder Wochentags-Schlüssel (monday-sunday) verweist auf {enabled: boolean, from: "H:MM", to: "H:MM"} im 24-Stunden-Format
    • timezone ist ein IANA-Zonenname (z. B. "Europe/Warsaw", "America/New_York")

    Beispielwert (beachten Sie die äußeren Anführungszeichen und die maskierten inneren Anführungszeichen - es handelt sich um ein einzelnes String-Feld, kein verschachteltes Objekt):

    "{\"monday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"tuesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"wednesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"thursday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"friday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"saturday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"sunday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"timezone\":\"Europe/Warsaw\"}"

    Außerhalb der angegebenen Zeiten wird dem Besucher liveChat.outOfHoursMessage angezeigt und die Übergabe an den Live Chat unterbunden. Die Validierung der inneren Struktur findet nur clientseitig in der Admin-UI statt - fehlerhaftes JSON oder unbekannte Schlüssel werden von der API einfach als String akzeptiert und führen später zu einem Darstellungsfehler, wenn ein Benutzer den Bot im Admin-Bereich öffnet. Validieren Sie die Struktur vor dem Absenden auf Ihrer Seite.

  • conversation.positiveRatingTooltip / conversation.negativeRatingTooltip - kurze Beschriftungen auf den Schaltflächen 👍 / 👎 neben jeder KI-Antwort, wenn conversation.conversationRatingEnabled=true. Standardtext ist "I like the response" / "I don't like the response". Für Endnutzer sichtbar.

  • whiteLabel.hideRoboAssistLogo - White-Label-Funktion, abhängig von Ihren Kontolimits. Blendet die Footer-Zeile "Powered by ChatLab" aus. Wenn Ihr Konto kein White-Labelling umfasst, wird der Wert zwar gespeichert, aber ignoriert, und der Footer wird immer dargestellt.

  • whiteLabel.whitelabelLogoLink - White-Label-Funktion, abhängig von Ihren Kontolimits. Klick-Ziel-URL für das benutzerdefinierte Logo, wenn hideRoboAssistLogo=true und eine benutzerdefinierte Logo-Datei über den Multipart-Teil whitelabel_logo hochgeladen wurde.

  • appearance.simulateHumanTypingDelay - Sekunden (nicht Millisekunden), ganze Zahl 0-200. Pause zwischen aufeinanderfolgenden Bot-Nachrichtenblasen, wenn simulateHumanTyping=true. Standard ist 5.

  • appearance.autoOpenChatDelaySeconds - Sekunden, ganze Zahl. Verzögerung, bevor sich das Widget automatisch öffnet, wenn autoOpenChat=true und autoOpenChatDelay=true.

  • advanced.internalLocale - IETF-Locale-Regionscode im Format ll_CC (Unterstrich, NICHT ll-CC mit Bindestrich). Akzeptierte Werte stammen aus einer festen Liste von rund 95 Locales: en_US, pl_PL, de_DE, fr_FR, es_ES, it_IT, pt_PT, nl_NL, ru_RU, zh_CN, zh_TW, ja_JP, ko_KR, ar_SA, hi_IN, tr_TR, cs_CZ, da_DK, fi_FI, sv_SE, no_NO, el_GR, he_IL und vielen weiteren. Das Senden eines reinen zweistelligen Codes ("en") oder BCP-47 ("en-US") ist nicht in der Liste der erlaubten Werte enthalten. Standard ist en_US. Dies ist das Locale, das für die Datums-/Zahlenformatierung in der Widget-Benutzeroberfläche verwendet wird, unabhängig von role.language (der Konversations-Ausgabesprache des Bots).

  • security.talkMessagesRateLimit / security.talkMessagesRateLimitDurationSeconds - ganze Zahlen (als JSON-Zahlen senden, z. B. 30, nicht "30"). 0 deaktiviert das Rate-Limit pro IP. Wenn ungleich null, erzwingt das Widget N Nachrichten pro Zeitspanne in Sekunden, bevor dem Besucher security.talkMessagesRateLimitHitMessage angezeigt wird.

  • advanced.botMessagesLimit - ganze Zahl (JSON-Zahl, z. B. 1000). 0 bedeutet "kein Limit"; andernfalls muss es ein Vielfaches von 1.000 sein (1000, 2000, 10000, ...). Werte wie 100 oder 1500 werden mit 400 validation_failed abgewiesen. Anschließend wird der Wert stillschweigend auf Ihr Kontolimit begrenzt.

KI-Textmodelle (advanced.model)

Senden Sie den exakten API-Wert (linke Spalte im Code-Format). Der Anzeigename in der Admin-UI steht in Klammern. Ihre Kontolimits bestimmen, welche Teilmenge auswählbar ist; das Senden eines Modells, das Ihr Konto nicht verwenden darf, gibt 400 invalid_parameter zurück. Der Standardwert für neue Bots ist 5-MINI.

  • 4-O-MINI (GPT 4-o mini)
  • 4-O (GPT 4-o)
  • 4.1-MINI (GPT 4.1-mini)
  • 4.1 (GPT 4.1)
  • 5-MINI (GPT 5-mini)
  • 5 (GPT 5)
  • 5.1 (GPT 5.1)
  • 5.4-MINI (GPT 5.4-mini)
  • 5.4 (GPT 5.4)
  • 5.5 (GPT 5.5)
  • GEMINI 2.5 PRO (Gemini 2.5 Pro)
  • GEMINI 3 Flash (Gemini 3 Flash)
  • GEMINI 3.5 Flash (Gemini 3.5 Flash)
  • GEMINI 3.7 Flash (Gemini 3.7 Flash)
  • GEMINI 3.8 Flash (Gemini 3.8 Flash)
  • GEMINI 3.1 Flash-Lite (Gemini 3.1 Flash-Lite)
  • GEMINI 3 PRO (Gemini 3 Pro)

Feldreferenz (vollständiges Anfrage-Schema)

Jedes Feld bei der Übertragung, mit Typ, Einschränkung und einzeiliger Beschreibung. PATCH-Semantik: Jedes weggelassene (oder als null gesendete) Feld belässt den gespeicherten Wert unverändert. Dieselbe Struktur wird für die Antwort verwendet (abzüglich mehrteiliger Binärinhalte; zuzüglich des schreibgeschützten meta-Blocks bei jeder Antwort und apiKey ausschließlich bei der Antwort auf die Erstellung).

Oberste Ebene

Feld Typ Einschränkung Beschreibung
name string max. 150, erforderlich bei Erstellung Anzeigename des Bots
role object Siehe § role
conversation object Siehe § conversation
chatMemory object Siehe § chatMemory
appearance object Siehe § appearance
humanSupport object Siehe § humanSupport
leadCollection object Siehe § leadCollection
liveChat object Siehe § liveChat
consent object Siehe § consent
whiteLabel object Siehe § whiteLabel
security object Siehe § security
advanced object Siehe § advanced

Ausschließliche Zusätze in Antworten:

  • meta: { id, createdAt, updatedAt } - schreibgeschützt.
  • apiKey - String, nur in der Antwort auf POST /v1/management/bots vorhanden - der neu erstellte Bot-Talk-Schlüssel für den neuen Bot, der genau einmal zurückgegeben wird.

§ role

Feld Typ Einschränkung Beschreibung
role string (enum) CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM Persona-Voreinstellung; wählt die Prompt-Vorlage aus (siehe "Rollen- und Prompt-Erstellung")
language string vollständiger englischer Sprachname (English, Polish, ...) oder Auto Detect Primärsprache, die an die Prompt-Vorlage übergeben wird
responseLength string ∈ {Concise, Normal, Detailed} Gewünschte Ausführlichkeit der KI-Antwort
websiteAddress string Website, die für den Prompt-Kontext verwendet wird
companyDescription string Unternehmensbeschreibung, die für den Prompt-Kontext verwendet wird
rawPrompt string Benutzerdefinierter System-Prompt - wird nur bei role=CUSTOM wortwörtlich verwendet

§ conversation

Feld Typ Einschränkung Beschreibung
welcomeMessage string Erste Nachricht, die dem Besucher beim Öffnen angezeigt wird
queryRefinementEnabled boolean Wenn true, wird die Frage des Besuchers vor dem RAG-Abruf präzisiert
conversationContinuityEnabled boolean Wenn true, setzen wiederkehrende Besucher ihre letzte Unterhaltung fort
conversationRatingEnabled boolean Wenn true, wird eine Bewertung mit Daumen nach oben/unten bei Bot-Nachrichten angezeigt
positiveRatingTooltip string Tooltip auf der Schaltfläche für positive Bewertungen
negativeRatingTooltip string Tooltip auf der Schaltfläche für negative Bewertungen
suggestedQuestions string Durch Zeilenumbrüche getrennte Fragevorschläge / Gesprächseinstiege
dynamicSuggestedFollowups boolean Wenn true, schlägt die KI nach jeder Antwort dynamische Folgefragen vor
dynamicFollowupsAutoIcons boolean Wenn true, wählt die KI automatisch Emoji-Symbole für die dynamischen Folgefragen aus

§ chatMemory

Feld Typ Einschränkung Beschreibung
enabled boolean Hauptschalter für die Chat-Memory-Funktion
summaryConversationsEnabled boolean Zusammenfassungen pro Unterhaltung dauerhaft speichern
conversationSummaryPrompt string Benutzerdefinierter Prompt zur Zusammenfassung jeder Unterhaltung
conversationSummaryPromptType string (enum) ∈ {DEFAULT, CUSTOM} Bestimmt, ob der standardmäßige oder der benutzerdefinierte Zusammenfassungs-Prompt verwendet wird
clientSummaryPrompt string Benutzerdefinierter Prompt zur Zusammenfassung des Kunden über mehrere Unterhaltungen hinweg
clientSummaryPromptType string (enum) ∈ {DEFAULT, CUSTOM} Standard- vs. benutzerdefinierter Kundenprofil-Prompt
summariesToKnowledgeRatio int 10-90, Schritt 10 Prozentualer Anteil des Chat-Kontextfensters, der für Zusammenfassungen im Vergleich zum RAG-Wissen reserviert ist

§ appearance

Feld Typ Einschränkung Beschreibung
launcherColor string (hex) Hintergrundfarbe des Launchers (Chat-Symbol)
headerColor string (hex) Hintergrundfarbe der Chat-Kopfzeile
titleColor string (hex) Titelfarbe der Chat-Kopfzeile
subtitleColor string (hex) Untertitelfarbe der Chat-Kopfzeile
clientMessageBubbleColor string (hex) Sprechblasenfarbe von Besuchernachrichten
clientMessageTextColor string (hex) Textfarbe von Besuchernachrichten
responseMessageBubbleColor string (hex) Sprechblasenfarbe von Bot-Antworten
responseMessageTextColor string (hex) Textfarbe von Bot-Antworten
chatSubheader string Unterzeile, die unter dem Chat-Titel angezeigt wird
senderPlaceholder string Platzhaltertext im Eingabefeld für Nachrichten
resetConversationTooltip string Tooltip auf der Schaltfläche "Unterhaltung zurücksetzen"
chatAlignment string (enum) ∈ {left, right} An welcher Bildschirmseite der Chat verankert wird
launcherBottomMargin int 0-500 Abstand des Launchers vom unteren Rand (px)
launcherSideMargin int 0-500 Abstand des Launchers vom Seitenrand (px)
displayShadow boolean Schlagschatten unter dem Widget
customCss string Reines CSS, das in das Widget-Iframe eingefügt wird
chatMessageLinkTarget string (enum) ∈ {_blank, _self} Wie Links innerhalb von Bot-Nachrichten geöffnet werden
minimizedDisplayMode string (enum) ∈ {icon, minified} Minimierter Zustand: Launcher-Symbol oder kompakte Absenderleiste
chatDesktopWidthPx int Widget-Breite auf dem Desktop
chatDesktopHeightPx int Widget-Höhe auf dem Desktop
chatMobileSizePercent int Widget-Größe auf Mobilgeräten in % des Viewports
messageFontSize int Schriftgröße des Nachrichtentexts (px)
showChatbotBubblesDesktop boolean Schwebende Teaser-Blasen auf dem Desktop anzeigen
showChatbotBubblesMobile boolean Schwebende Teaser-Blasen auf Mobilgeräten anzeigen
chatbotBubblesDelaySeconds int Verzögerung vor dem Erscheinen der Teaser-Blasen (Sekunden)
launcherIconFullSize boolean Benutzerdefiniertes Launcher-Symbol randlos statt eingerückt darstellen
welcomeScreenEnabled boolean Welcome Screen (Begrüßungsbildschirm) anzeigen, anstatt direkt zum Chat zu wechseln
welcomeScreenQuestionsLabel string Beschriftung über den Fragenvorschlägen auf dem Begrüßungsbildschirm
welcomeScreenHideHumanContactForm boolean Aktion für das Formular zur Kontaktaufnahme mit Menschen in der Kopfzeile ausblenden, während der Begrüßungsbildschirm angezeigt wird. Sie erscheint nach der ersten Nachricht des Besuchers wieder. Bei Bots, die vor dem 2026-09-02 erstellt wurden, ist der Standardwert true
welcomeScreenHideLiveChat boolean Live-Chat-Aktion in der Kopfzeile ausblenden, während der Begrüßungsbildschirm angezeigt wird. Sie erscheint nach der ersten Nachricht des Besuchers wieder. Bei Bots, die vor dem 2026-09-02 erstellt wurden, ist der Standardwert true
headerActionsLayout string DROPDOWN Wie Live Chat und das Formular zur Kontaktaufnahme mit Menschen in der Chat-Kopfzeile angeboten werden: ICONS (jeweils ein separates Symbol) oder DROPDOWN (im Kopfzeilenmenü gruppiert). Bei Bots, die vor dem 2026-09-02 erstellt wurden, ist der Standardwert ICONS
stackSuggestedQuestions boolean Fragenvorschläge vertikal anordnen (statt nebeneinander)
suggestedQuestionsFontSize int Schriftgröße der Chips für Fragenvorschläge (px)
suggestedQuestionsTextColor string (hex) Textfarbe der Chips für Fragenvorschläge
suggestedQuestionsBackgroundColor string (hex) Hintergrundfarbe der Chips für Fragenvorschläge
autoOpenChat boolean Chat auf dem Desktop automatisch öffnen
autoOpenChatOnMobiles boolean Chat auf Mobilgeräten automatisch öffnen
autoOpenChatDelay boolean Verzögerung vor dem automatischen Öffnen anwenden
autoOpenChatDelaySeconds int Verzögerung für das automatische Öffnen (Sekunden)
simulateHumanTyping boolean Bot-Antwort in mehrere Sprechblasen mit Tipp-Animation aufteilen
simulateHumanTypingDelay int 0-200 Verzögerung zwischen den Sprechblasen-Nachrichten (Sekunden)
footerMarkdown string max. 255 Benutzerdefiniertes Footer-Markdown, das unter dem Chat angezeigt wird
avatarUrl string schreibgeschützt Vollqualifizierte öffentliche URL des Avatars; zum Ändern über den Multipart-Abschnitt avatar hochladen

Multipart bei POST/PATCH: avatar (Datei-Abschnitt). GET- / Antwort-Bodies lassen den Dateiinhalt weg - übertragen wird nur die URL.

§ humanSupport

Feld Typ Einschränkung Beschreibung
enabled boolean Umschalter für den Flow für menschlichen Support
email string erforderlich (streng bei Erstellung), wenn enabled=true Adresse, die Support-E-Mails von Menschen empfängt
dialogMessage string Aufforderungsnachricht, die über dem Formular angezeigt wird
thankYouMessage string Bestätigung, die nach dem Absenden angezeigt wird
emailMessageSubjectTemplate string Betreffvorlage für die an den Agenten gesendete E-Mail
emailMessageContentTemplate string Textkörpervorlage für die an den Agenten gesendete E-Mail
emailPlaceholder string Platzhalter im E-Mail-Eingabefeld
messagePlaceholder string Platzhalter im Textbereich für Nachrichten
emailWithConversationContent boolean Wenn true, wird das Transkript der Unterhaltung in den Textkörper der E-Mail eingefügt
customFormId long ID eines bestehenden benutzerdefinierten Formulars Ersetzt das integrierte Kontaktformular durch ein benutzerdefiniertes Formular. null behält das integrierte Formular bei
customFormMapping string JSON-kodierter String Ordnet Felder des benutzerdefinierten Formulars den E-Mail-Feldern des menschlichen Supports zu

requirePolicyAccept befindet sich unter consent.humanSupportRequirePolicyAccept, nicht hier.

§ leadCollection

Feld Typ Einschränkung Beschreibung
enabled boolean Umschalter für das Lead-Formular
nameEnabled boolean Name erfassen
nameLabel string Beschriftung des Namens-Eingabefelds
emailEnabled boolean E-Mail erfassen
emailLabel string erforderlich (streng bei Erstellung), wenn enabled=true UND emailEnabled=true Beschriftung des E-Mail-Eingabefelds
phoneEnabled boolean Telefonnummer erfassen
phoneLabel string erforderlich (streng bei Erstellung), wenn enabled=true UND phoneEnabled=true Beschriftung des Telefon-Eingabefelds
leaveDetailsMessage string erforderlich (streng bei Erstellung), wenn enabled=true Nachricht, die den Besucher dazu animiert, Kontaktdaten zu hinterlassen
thankYouMessage string erforderlich (streng bei Erstellung), wenn enabled=true Bestätigung, die nach dem Absenden angezeigt wird
requireBeforeNewConversation boolean Wenn true, muss das Formular vor Beginn des Chats abgesendet werden; wenn false, entscheidet die KI, wann das Formular eingeblendet wird
emailNotificationEnabled boolean Den Inhaber jedes Mal per E-Mail benachrichtigen, wenn ein Lead erfasst wird
emailNotificationAddress string Benachrichtigungsempfänger (standardmäßig die Konto-E-Mail)
emailWithConversationContent boolean Wenn true, wird das Transkript der Unterhaltung in die Benachrichtigung eingefügt

Feldübergreifende Regel (streng bei Erstellung): enabled=true erfordert mindestens eine der Optionen emailEnabled oder phoneEnabled. requirePolicyAccept befindet sich unter consent.leadCollectionRequirePolicyAccept, nicht hier.

| customFormId | long | ID eines bestehenden benutzerdefinierten Formulars | Ersetzt das integrierte Lead-Formular durch ein benutzerdefiniertes Formular. null behält das integrierte Formular bei | | customFormMapping | string | JSON-kodierter String | Ordnet Felder des benutzerdefinierten Formulars Name / E-Mail / Telefonnummer zu |

§ liveChat

Feld Typ Einschränkung Beschreibung
enabled boolean Umschalter für die Funktion Live Chat
infoMessage string Erklärende Nachricht vor der Übergabe
startMessage string Nachricht, die beim Start der Live-Sitzung angezeigt wird
endMessage string Nachricht, die beim Beenden der Live-Sitzung angezeigt wird
nameLabel string Beschriftung des Namens-Eingabefelds im Vorab-Formular für Live Chat
emailLabel string Beschriftung des E-Mail-Eingabefelds im Vorab-Formular für Live Chat
schedule string JSON-kodierter String (Wochentagsschalter + from/to + timezone) Betriebszeiten für Live Chat - die genaue Struktur finden Sie unter "Strukturierte Felder und Bereiche"
outOfHoursMessage string Nachricht, die angezeigt wird, wenn der Zeitplan außerhalb der Betriebszeiten liegt
closeModalMessage string Titel des Modals "Live-Chat schließen?"
closeModalConfirmLabel string Beschriftung der Bestätigungsschaltfläche im Schließen-Modal
closeModalCancelLabel string Beschriftung der Abbrechen-Schaltfläche im Schließen-Modal
closeModalTooltipText string Tooltip am Bedienelement zum Schließen des Chats
operatorHasJoinedLabel string Text, der angezeigt wird, wenn ein Operator beitritt
operatorDidNotJoinInTimeLabel string Text, der angezeigt wird, wenn innerhalb des Timeouts kein Operator beitritt
waitingForOperatorToJoinLabel string Text, der angezeigt wird, während auf einen Operator gewartet wird
waitingForOperatorSeconds int Timeout für die Annahme durch einen Operator (Sekunden)
redirectToHumanSupportForm boolean Wenn true, wird auf das Formular für menschlichen Support zurückgegriffen, falls kein Operator annimmt
missedEmailEnabled boolean Standard: true Sendet eine E-Mail an den Bot-Inhaber, wenn eine Live-Chat-Anfrage unbeantwortet blieb. Bei älteren Bots nicht gesetzt, was als aktiviert interpretiert wird

requirePolicyAccept befindet sich unter consent.liveChatRequirePolicyAccept, nicht hier.

§ consent

Feld Typ Einschränkung Beschreibung
newConversationRequirePolicyAccept boolean Zustimmung zur Datenschutzerklärung vor Beginn einer neuen Unterhaltung verlangen
humanSupportRequirePolicyAccept boolean Zustimmung zur Datenschutzerklärung vor dem Absenden des Formulars für menschlichen Support verlangen
leadCollectionRequirePolicyAccept boolean Zustimmung zur Datenschutzerklärung vor dem Absenden des Lead-Erfassungsformulars verlangen
liveChatRequirePolicyAccept boolean Zustimmung zur Datenschutzerklärung vor Beginn einer Live-Chat-Sitzung verlangen
newConversationConsentDescription string Einleitungstext für den Zustimmungsbildschirm zu Beginn der Unterhaltung
privacyPolicyConsentCheckboxLabel string Beschriftung neben dem Zustimmungs-Kontrollkästchen (enthält üblicherweise einen Link zur Datenschutzerklärung)

§ whiteLabel

Feld Typ Einschränkung Beschreibung
hideRoboAssistLogo boolean White-Label-Funktion; unterliegt den Kontolimits Standardmäßiges ChatLab-Logo in der Fußzeile ausblenden
whitelabelLogoLink string White-Label-Funktion; unterliegt den Kontolimits URL, auf die das benutzerdefinierte Fußzeilenlogo verlinkt
assignToCustomDomain boolean abhängig von der Funktion CUSTOM_DOMAIN Den Chat auf der konfigurierten benutzerdefinierten Domain hosten
whitelabelLogoUrl string schreibgeschützt Vollqualifizierte öffentliche URL des White-Label-Logos; zum Ändern über den Multipart-Abschnitt whitelabel_logo hochladen

Multipart bei POST/PATCH: whitelabel_logo (Datei-Abschnitt). GET- / Antwort-Bodies lassen den Dateiinhalt weg - übertragen wird nur die URL.

§ security

Feld Typ Einschränkung Beschreibung
allowedDomains string Kommagetrennte Liste von Domains, die das Widget einbinden dürfen (leer = keine Whitelist)
spamFilterEnabled boolean Bot-spezifischen Spam-Filter für eingehende Nachrichten aktivieren
countryFilterMode string BLACKLIST oder WHITELIST Wie die Länderlisten interpretiert werden. Die Listen selbst bleiben Administratoren vorbehalten
talkMessagesRateLimit int >= 0; 0 deaktiviert Maximale Anzahl an Benutzernachrichten innerhalb des Zeitfensters für das Rate-Limit
talkMessagesRateLimitDurationSeconds int >= 0 Dauer des Zeitfensters für das Rate-Limit (Sekunden)
talkMessagesRateLimitHitMessage string Nachricht, die dem Besucher angezeigt wird, wenn das Rate-Limit erreicht wurde

§ voice

Feld Typ Einschränkung Beschreibung
inputEnabled boolean Dem Besucher erlauben, Nachrichten zu diktieren (Speech-to-Text)
conversationEnabled boolean erfordert die Sprachfunktion im Plan Vollständige Sprachunterhaltungen aktivieren
voiceId string anbieterspezifische Sprach-ID (z. B. alloy) Welche synthetische Stimme spricht
model string z. B. GPT-REALTIME-MINI, GEMINI-LIVE, ELEVENLABS-* Sprachmodell. Wird minutengenau abgerechnet, Tarife variieren je nach Modell
turnDetection string anbieterspezifisch Modus für den Sprecherwechsel
audioPrompt string Zusätzlicher System-Prompt, der ausschließlich für Sprachbeiträge verwendet wird
welcomeMessage string Gesprochene Begrüßungszeile
language string Sprachcode Primäre Sprache der Sprachausgabe
additionalLanguages string kommagetrennte Sprachcodes Zusätzliche Sprachen, die der Sprach-Agent akzeptiert
maxDurationSeconds int Feste Obergrenze für eine einzelne Sprachunterhaltung
maxDurationMessage string Nachricht, die angezeigt wird, wenn die Obergrenze erreicht ist

§ multilingual

Feld Typ Einschränkung Beschreibung
enabled boolean Umschalter für den mehrsprachigen Modus
mode string AUTODETECT oder ein Modus mit fester Liste Wie der Bot die Antwortsprache auswählt
baseLanguage string Sprachcode Sprache, in der die Texte des Bots selbst verfasst sind
languages string kommagetrennte Sprachcodes Dem Besucher angebotene Sprachen
knowledgeLanguageMode string Wie Wissen in anderen Sprachen behandelt wird
knowledgeLanguageFallback string Sprachcode Ersatzsprache, wenn kein Treffer gefunden wird

§ advanced

Feld Typ Einschränkung Beschreibung
model string unterliegt Kontolimits; siehe "KI-Textmodelle" oben LLM-Bezeichner (z. B. 5-MINI)
temperature decimal 0.0-1.0 Sampling-Temperatur (entspricht dem Schieberegler in der UI)
chatContextSize int ∈ {8000, 16000, 32000}; wird stillschweigend auf Ihr Kontolimit begrenzt Token-Fenster für den Chat-Verlauf
botMessagesLimit long 0 oder ein Vielfaches von 1000 (z. B. 1000, 2000, 10000) Maximale Bot-Antworten pro Unterhaltung (0 = unbegrenzt)
internalLocale string Locale-Code im Format ll_CC Locale für Oberflächenbeschriftungen des Widgets (unterscheidet sich von role.language)
productsViewEnabled boolean Wenn true, werden die Offer Cards (Angebotskarten) für den E-Commerce im Chat angezeigt
includeProductsInKnowledgeBase boolean Wenn true, wird der Produktkatalog als Teil der Wissensdatenbank indexiert

Außerhalb des API-Umfangs

Die Administrationsoberfläche stellt einige Bereiche bereit, die in dieser Version der Management API absichtlich nicht freigegeben sind:

  • Flow-Tab (Flow) - der visuelle Flow Editor (Unterhaltungsablauf-Editor für Phasen und Übergänge). Nicht über die Management API zugänglich.
  • Actions-Tab (Aktionen) - verwaltete E-Commerce- / Buchungsintegrationen, AI Search und benutzerdefinierte API-Funktionen. Das Aufrufen von Tools war nie Teil der Management API.
  • Der Builder für benutzerdefinierte Formulare selbst - das Erstellen und Bearbeiten benutzerdefinierter Formulare ist nicht zugänglich. Sie können jedoch über leadCollection.customFormId und humanSupport.customFormId ein bestehendes Formular an einen Bot anhängen.
  • Benutzerdefinierte Symbole zum Öffnen / Schließen des Chats - customLauncherIconVisible, openChatIcon, closeChatIcon. Die API stellt nur die primären Multipart-Abschnitte avatar und whitelabel_logo bereit.
  • IP- und Länderlisten - die Einträge selbst bleiben Administratoren vorbehalten. Über security.countryFilterMode ist lediglich der Interpretationsmodus zugänglich.

Endpunkte

POST /v1/management/bots

Erstellt einen neuen Bot. Zwei gleichwertige Content-Types werden akzeptiert; wählen Sie den für Sie praktischeren.

Modus A - einfaches JSON (empfohlen, wenn Sie im selben Request keinen Avatar / kein Logo hochladen müssen):

  • Content-Type: application/json
  • Request-Body ist das Bot-Konfigurations-JSON (kein data-Wrapper)
  • Dateien (Avatar / Logo) können später über einen zweiten PATCH-Aufruf mit Modus B hochgeladen werden

Modus B - multipart/form-data (verwenden Sie diesen Modus, wenn Dateien im selben Request hochgeladen werden):

  • Content-Type: multipart/form-data; boundary=...
  • data-JSON-Teil (erforderlich, Content-Type: application/json) - Bot-Konfiguration in der oben beschriebenen verschachtelten Struktur
  • avatar-Dateiteil (optional) - Avatar-Bild des Bots
  • whitelabel_logo-Dateiteil (optional) - White-Label-Logo (gilt nur, wenn Ihr Konto White-Labeling enthält)

Im JSON ist lediglich name erforderlich; alle anderen Felder fallen auf denselben Standardwert zurück, den auch der Einrichtungsassistent der Admin-Benutzeroberfläche festlegen würde.

Vollständiger Request-Body

Dies ist das maximale data-JSON - alle Abschnitte sind ausgefüllt. Senden Sie nur die Abschnitte, die für Sie relevant sind; für alles andere werden die Standardwerte übernommen.

{
  "name": "Helpdesk Bot",
  "role": {
    "rawPrompt": "You are a friendly support assistant for Acme Inc.",
    "role": "CUSTOMER_SUPPORT",
    "language": "English",
    "responseLength": "Normal",
    "websiteAddress": "https://acme.com",
    "companyDescription": "Acme sells industrial widgets."
  },
  "conversation": {
    "welcomeMessage": "Hi! How can I help today?",
    "queryRefinementEnabled": true,
    "conversationContinuityEnabled": true,
    "conversationRatingEnabled": true,
    "positiveRatingTooltip": "Helpful",
    "negativeRatingTooltip": "Not helpful",
    "suggestedQuestions": "What are your hours?\nHow do I cancel?\nWhere is my order?",
    "dynamicSuggestedFollowups": true,
    "dynamicFollowupsAutoIcons": true
  },
  "chatMemory": {
    "enabled": true,
    "summaryConversationsEnabled": true,
    "conversationSummaryPrompt": "Summarize this conversation in 3 sentences.",
    "clientSummaryPrompt": "Summarize what we know about this customer.",
    "clientSummaryPromptType": "DEFAULT",
    "conversationSummaryPromptType": "DEFAULT",
    "summariesToKnowledgeRatio": 50
  },
  "appearance": {
    "launcherColor": "#1A73E8",
    "headerColor": "#1A73E8",
    "titleColor": "#FFFFFF",
    "subtitleColor": "#FFFFFF",
    "clientMessageBubbleColor": "#000000",
    "clientMessageTextColor": "#FFFFFF",
    "responseMessageBubbleColor": "#F4F4F4",
    "responseMessageTextColor": "#000000",
    "chatSubheader": "AI support assistant",
    "senderPlaceholder": "Type a message...",
    "resetConversationTooltip": "Restart conversation",
    "chatAlignment": "right",
    "launcherBottomMargin": 20,
    "launcherSideMargin": 20,
    "displayShadow": true,
    "customCss": ".rcw-conversation-container { border-radius: 16px; }",
    "chatMessageLinkTarget": "_blank",
    "minimizedDisplayMode": "icon",
    "chatDesktopWidthPx": 400,
    "chatDesktopHeightPx": 600,
    "chatMobileSizePercent": 100,
    "messageFontSize": 14,
    "showChatbotBubblesDesktop": true,
    "showChatbotBubblesMobile": false,
    "chatbotBubblesDelaySeconds": 5,
    "welcomeScreenEnabled": false,
    "welcomeScreenQuestionsLabel": "Quick start",
    "welcomeScreenHideHumanContactForm": false,
    "welcomeScreenHideLiveChat": false,
    "headerActionsLayout": "DROPDOWN",
    "stackSuggestedQuestions": false,
    "suggestedQuestionsFontSize": 14,
    "suggestedQuestionsTextColor": "#000000",
    "suggestedQuestionsBackgroundColor": "#F4F4F4",
    "autoOpenChat": false,
    "autoOpenChatOnMobiles": false,
    "autoOpenChatDelay": false,
    "autoOpenChatDelaySeconds": 5,
    "simulateHumanTyping": true,
    "simulateHumanTypingDelay": 5,
    "footerMarkdown": "Powered by Acme"
  },
  "humanSupport": {
    "enabled": true,
    "email": "support@acme.com",
    "dialogMessage": "Leave us a message and we will get back to you.",
    "thankYouMessage": "Thanks - we received your message.",
    "emailMessageSubjectTemplate": "[Acme support] New message from {customerName}",
    "emailMessageContentTemplate": "{message}\n\n - \n{conversationTranscript}",
    "emailPlaceholder": "your@email.com",
    "messagePlaceholder": "How can we help?",
    "emailWithConversationContent": true
  },
  "leadCollection": {
    "enabled": true,
    "nameEnabled": true,
    "nameLabel": "Your name",
    "emailEnabled": true,
    "emailLabel": "Email",
    "phoneEnabled": false,
    "phoneLabel": "Phone",
    "leaveDetailsMessage": "Please leave your details and we will get in touch.",
    "thankYouMessage": "Thanks - we will be in touch shortly.",
    "requireBeforeNewConversation": false,
    "emailNotificationEnabled": true,
    "emailNotificationAddress": "leads@acme.com",
    "emailWithConversationContent": true
  },
  "liveChat": {
    "enabled": false,
    "infoMessage": "Connecting you with a human agent...",
    "startMessage": "You are now chatting with our team.",
    "endMessage": "Live chat has ended.",
    "nameLabel": "Your name",
    "emailLabel": "Email",
    "schedule": "{\"monday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"tuesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"wednesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"thursday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"friday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"saturday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"sunday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"timezone\":\"Europe/Warsaw\"}",
    "outOfHoursMessage": "We are currently offline.",
    "closeModalMessage": "End the live chat session?",
    "closeModalConfirmLabel": "Yes, end",
    "closeModalCancelLabel": "Cancel",
    "closeModalTooltipText": "End live chat",
    "operatorHasJoinedLabel": "An agent has joined.",
    "operatorDidNotJoinInTimeLabel": "No agent available right now.",
    "waitingForOperatorToJoinLabel": "Waiting for an agent...",
    "waitingForOperatorSeconds": 60,
    "redirectToHumanSupportForm": true
  },
  "consent": {
    "newConversationRequirePolicyAccept": false,
    "humanSupportRequirePolicyAccept": false,
    "leadCollectionRequirePolicyAccept": true,
    "liveChatRequirePolicyAccept": false,
    "newConversationConsentDescription": "By starting a conversation you agree to our terms.",
    "privacyPolicyConsentCheckboxLabel": "I have read and accepted the privacy policy."
  },
  "whiteLabel": {
    "hideRoboAssistLogo": false,
    "whitelabelLogoLink": "https://acme.com",
    "assignToCustomDomain": false
  },
  "security": {
    "allowedDomains": "acme.com,support.acme.com",
    "spamFilterEnabled": true,
    "talkMessagesRateLimit": 30,
    "talkMessagesRateLimitDurationSeconds": 60,
    "talkMessagesRateLimitHitMessage": "Please slow down."
  },
  "advanced": {
    "model": "5-MINI",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  }
}

Validierungsregeln mit eigenen Fehlermeldungen:

  • name - erforderlich, maximal 150 Zeichen
  • advanced.temperature - zwischen 0.0 und 1.0
  • chatMemory.summariesToKnowledgeRatio - Ganzzahl zwischen 10 und 90 (Prozent, Schrittweite 10)
  • appearance.launcherBottomMargin, appearance.launcherSideMargin - zwischen 0 und 500
  • appearance.footerMarkdown - maximal 255 Zeichen
  • humanSupport.enabled=true erfordert, dass humanSupport.email gesetzt ist
  • leadCollection.enabled=true erfordert, dass mindestens leadCollection.emailEnabled oder leadCollection.phoneEnabled auf true gesetzt ist; der jeweils aktive Kanal erfordert zudem seine Beschriftung sowie leaveDetailsMessage und thankYouMessage
  • Gedeckelte Felder (advanced.chatContextSize, advanced.botMessagesLimit usw.) werden stillschweigend auf Ihre Kontolimits begrenzt

Felder, deren Wert auf dem Server null ist, werden im JSON-Body weggelassen - übertragen werden nur Felder mit Nicht-Null-Werten.

Vollständiger Response-Body (201)

Gleiche Struktur wie der Request, zuzüglich des schreibgeschützten meta-Blocks und des einmaligen apiKey auf oberster Ebene. Schreibgeschützte Datei-URLs (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) werden vom Server befüllt, wenn die entsprechenden Multipart-Teile hochgeladen wurden.

{
  "name": "Helpdesk Bot",
  "role": {
    "rawPrompt": "You are a friendly support assistant for Acme Inc.",
    "role": "CUSTOMER_SUPPORT",
    "language": "English",
    "responseLength": "Normal",
    "websiteAddress": "https://acme.com",
    "companyDescription": "Acme sells industrial widgets."
  },
  "conversation": {
    "welcomeMessage": "Hi! How can I help today?",
    "queryRefinementEnabled": true,
    "conversationContinuityEnabled": true,
    "conversationRatingEnabled": true,
    "positiveRatingTooltip": "Helpful",
    "negativeRatingTooltip": "Not helpful",
    "suggestedQuestions": "What are your hours?\nHow do I cancel?\nWhere is my order?",
    "dynamicSuggestedFollowups": true,
    "dynamicFollowupsAutoIcons": true
  },
  "chatMemory": {
    "enabled": true,
    "summaryConversationsEnabled": true,
    "conversationSummaryPrompt": "Summarize this conversation in 3 sentences.",
    "clientSummaryPrompt": "Summarize what we know about this customer.",
    "clientSummaryPromptType": "DEFAULT",
    "conversationSummaryPromptType": "DEFAULT",
    "summariesToKnowledgeRatio": 50
  },
  "appearance": {
    "launcherColor": "#1A73E8",
    "headerColor": "#1A73E8",
    "titleColor": "#FFFFFF",
    "subtitleColor": "#FFFFFF",
    "clientMessageBubbleColor": "#000000",
    "clientMessageTextColor": "#FFFFFF",
    "responseMessageBubbleColor": "#F4F4F4",
    "responseMessageTextColor": "#000000",
    "chatSubheader": "AI support assistant",
    "senderPlaceholder": "Type a message...",
    "resetConversationTooltip": "Restart conversation",
    "chatAlignment": "right",
    "launcherBottomMargin": 20,
    "launcherSideMargin": 20,
    "displayShadow": true,
    "customCss": ".rcw-conversation-container { border-radius: 16px; }",
    "chatMessageLinkTarget": "_blank",
    "minimizedDisplayMode": "icon",
    "chatDesktopWidthPx": 400,
    "chatDesktopHeightPx": 600,
    "chatMobileSizePercent": 100,
    "messageFontSize": 14,
    "showChatbotBubblesDesktop": true,
    "showChatbotBubblesMobile": false,
    "chatbotBubblesDelaySeconds": 5,
    "welcomeScreenEnabled": false,
    "welcomeScreenQuestionsLabel": "Quick start",
    "welcomeScreenHideHumanContactForm": false,
    "welcomeScreenHideLiveChat": false,
    "headerActionsLayout": "DROPDOWN",
    "stackSuggestedQuestions": false,
    "suggestedQuestionsFontSize": 14,
    "suggestedQuestionsTextColor": "#000000",
    "suggestedQuestionsBackgroundColor": "#F4F4F4",
    "autoOpenChat": false,
    "autoOpenChatOnMobiles": false,
    "autoOpenChatDelay": false,
    "autoOpenChatDelaySeconds": 5,
    "simulateHumanTyping": true,
    "simulateHumanTypingDelay": 5,
    "footerMarkdown": "Powered by Acme",
    "avatarUrl": "https://api.chatlab.com/aichat/content/avatar_a8f3b2c1_2026060110.png"
  },
  "humanSupport": {
    "enabled": true,
    "email": "support@acme.com",
    "dialogMessage": "Leave us a message and we will get back to you.",
    "thankYouMessage": "Thanks - we received your message.",
    "emailMessageSubjectTemplate": "[Acme support] New message from {customerName}",
    "emailMessageContentTemplate": "{message}\n\n - \n{conversationTranscript}",
    "emailPlaceholder": "your@email.com",
    "messagePlaceholder": "How can we help?",
    "emailWithConversationContent": true
  },
  "leadCollection": {
    "enabled": true,
    "nameEnabled": true,
    "nameLabel": "Your name",
    "emailEnabled": true,
    "emailLabel": "Email",
    "phoneEnabled": false,
    "phoneLabel": "Phone",
    "leaveDetailsMessage": "Please leave your details and we will get in touch.",
    "thankYouMessage": "Thanks - we will be in touch shortly.",
    "requireBeforeNewConversation": false,
    "emailNotificationEnabled": true,
    "emailNotificationAddress": "leads@acme.com",
    "emailWithConversationContent": true
  },
  "liveChat": {
    "enabled": false,
    "infoMessage": "Connecting you with a human agent...",
    "startMessage": "You are now chatting with our team.",
    "endMessage": "Live chat has ended.",
    "nameLabel": "Your name",
    "emailLabel": "Email",
    "schedule": "{\"monday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"tuesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"wednesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"thursday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"friday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"saturday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"sunday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"timezone\":\"Europe/Warsaw\"}",
    "outOfHoursMessage": "We are currently offline.",
    "closeModalMessage": "End the live chat session?",
    "closeModalConfirmLabel": "Yes, end",
    "closeModalCancelLabel": "Cancel",
    "closeModalTooltipText": "End live chat",
    "operatorHasJoinedLabel": "An agent has joined.",
    "operatorDidNotJoinInTimeLabel": "No agent available right now.",
    "waitingForOperatorToJoinLabel": "Waiting for an agent...",
    "waitingForOperatorSeconds": 60,
    "redirectToHumanSupportForm": true
  },
  "consent": {
    "newConversationRequirePolicyAccept": false,
    "humanSupportRequirePolicyAccept": false,
    "leadCollectionRequirePolicyAccept": true,
    "liveChatRequirePolicyAccept": false,
    "newConversationConsentDescription": "By starting a conversation you agree to our terms.",
    "privacyPolicyConsentCheckboxLabel": "I have read and accepted the privacy policy."
  },
  "whiteLabel": {
    "hideRoboAssistLogo": false,
    "whitelabelLogoLink": "https://acme.com",
    "assignToCustomDomain": false,
    "whitelabelLogoUrl": "https://api.chatlab.com/aichat/content/custom_logo_4287_2026060110.png"
  },
  "security": {
    "allowedDomains": "acme.com,support.acme.com",
    "spamFilterEnabled": true,
    "talkMessagesRateLimit": 30,
    "talkMessagesRateLimitDurationSeconds": 60,
    "talkMessagesRateLimitHitMessage": "Please slow down."
  },
  "advanced": {
    "model": "5-MINI",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  },
  "meta": {
    "id": 4287,
    "createdAt": "2026-06-01T10:11:02Z",
    "updatedAt": "2026-06-01T10:11:02Z"
  },
  "apiKey": "ck_freshly_minted_bot_talk_key_here"
}

Das Feld apiKey erscheint nur bei der Erstellung - es ist der neu generierte Bot Talk-Schlüssel, der an den neuen Bot gebunden ist. Der Klartext wird nur einmal angezeigt und kann später nicht mehr über die API abgerufen werden; speichern Sie ihn umgehend auf Ihrer Seite.

Der Location-Response-Header enthält die URL des neuen Bots (/v1/management/bots/{id}).

Curl-Beispiele

Modus A - einfaches JSON (am einfachsten):

curl -X POST https://api.chatlab.com/aichat/v1/management/bots \
  -H "Authorization: Bearer mk_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Helpdesk Bot","conversation":{"welcomeMessage":"Hi!"}}'

Modus B - multipart mit Avatar:

curl -X POST https://api.chatlab.com/aichat/v1/management/bots \
  -H "Authorization: Bearer mk_..." \
  -F 'data={"name":"Helpdesk Bot","conversation":{"welcomeMessage":"Hi!"}};type=application/json' \
  -F 'avatar=@./avatar.png'

GET /v1/management/bots/{bot_id}

Gibt die aktuelle Konfiguration eines Bots zurück, der Ihnen gehört.

Curl-Beispiel

curl https://api.chatlab.com/aichat/v1/management/bots/4287 \
  -H "Authorization: Bearer mk_..."

Vollständiger Response-Body (200)

Gleiche Struktur wie die POST-Antwort, abzüglich des einmaligen apiKey. Der meta-Block ist enthalten. Gibt 404 not_found_error zurück, wenn der Bot nicht existiert oder nicht zu Ihrem Konto gehört.

Der aktuelle Avatar und das White-Label-Logo werden als vollqualifizierte, schreibgeschützte URLs bereitgestellt (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) - ausgehend von demselben Schema + Host + Kontextpfad, über den diese Anfrage bedient wurde. Rufen Sie die Bytes ab, indem Sie diese URLs direkt per GET anfragen; um eine der beiden Dateien zu ersetzen, laden Sie über den multipart-Teil avatar / whitelabel_logo bei einem PATCH-Aufruf eine neue Datei hoch. Diese URL-Felder werden ignoriert, wenn sie in einem Request-Body übermittelt werden.

{
  "name": "Helpdesk Bot",
  "role": {
    "rawPrompt": "You are a friendly support assistant for Acme Inc.",
    "role": "CUSTOMER_SUPPORT",
    "language": "English",
    "responseLength": "Normal",
    "websiteAddress": "https://acme.com",
    "companyDescription": "Acme sells industrial widgets."
  },
  "conversation": {
    "welcomeMessage": "Hi! How can I help today?",
    "queryRefinementEnabled": true,
    "conversationContinuityEnabled": true,
    "conversationRatingEnabled": true,
    "positiveRatingTooltip": "Helpful",
    "negativeRatingTooltip": "Not helpful",
    "suggestedQuestions": "What are your hours?\nHow do I cancel?\nWhere is my order?",
    "dynamicSuggestedFollowups": true,
    "dynamicFollowupsAutoIcons": true
  },
  "chatMemory": {
    "enabled": true,
    "summaryConversationsEnabled": true,
    "conversationSummaryPrompt": "Summarize this conversation in 3 sentences.",
    "clientSummaryPrompt": "Summarize what we know about this customer.",
    "clientSummaryPromptType": "DEFAULT",
    "conversationSummaryPromptType": "DEFAULT",
    "summariesToKnowledgeRatio": 50
  },
  "appearance": {
    "launcherColor": "#1A73E8",
    "headerColor": "#1A73E8",
    "titleColor": "#FFFFFF",
    "subtitleColor": "#FFFFFF",
    "clientMessageBubbleColor": "#000000",
    "clientMessageTextColor": "#FFFFFF",
    "responseMessageBubbleColor": "#F4F4F4",
    "responseMessageTextColor": "#000000",
    "chatSubheader": "AI support assistant",
    "senderPlaceholder": "Type a message...",
    "resetConversationTooltip": "Restart conversation",
    "chatAlignment": "right",
    "launcherBottomMargin": 20,
    "launcherSideMargin": 20,
    "displayShadow": true,
    "customCss": ".rcw-conversation-container { border-radius: 16px; }",
    "chatMessageLinkTarget": "_blank",
    "minimizedDisplayMode": "icon",
    "chatDesktopWidthPx": 400,
    "chatDesktopHeightPx": 600,
    "chatMobileSizePercent": 100,
    "messageFontSize": 14,
    "showChatbotBubblesDesktop": true,
    "showChatbotBubblesMobile": false,
    "chatbotBubblesDelaySeconds": 5,
    "welcomeScreenEnabled": false,
    "welcomeScreenQuestionsLabel": "Quick start",
    "welcomeScreenHideHumanContactForm": false,
    "welcomeScreenHideLiveChat": false,
    "headerActionsLayout": "DROPDOWN",
    "stackSuggestedQuestions": false,
    "suggestedQuestionsFontSize": 14,
    "suggestedQuestionsTextColor": "#000000",
    "suggestedQuestionsBackgroundColor": "#F4F4F4",
    "autoOpenChat": false,
    "autoOpenChatOnMobiles": false,
    "autoOpenChatDelay": false,
    "autoOpenChatDelaySeconds": 5,
    "simulateHumanTyping": true,
    "simulateHumanTypingDelay": 5,
    "footerMarkdown": "Powered by Acme",
    "avatarUrl": "https://api.chatlab.com/aichat/content/avatar_a8f3b2c1_2026060110.png"
  },
  "humanSupport": {
    "enabled": true,
    "email": "support@acme.com",
    "dialogMessage": "Leave us a message and we will get back to you.",
    "thankYouMessage": "Thanks - we received your message.",
    "emailMessageSubjectTemplate": "[Acme support] New message from {customerName}",
    "emailMessageContentTemplate": "{message}\n\n - \n{conversationTranscript}",
    "emailPlaceholder": "your@email.com",
    "messagePlaceholder": "How can we help?",
    "emailWithConversationContent": true
  },
  "leadCollection": {
    "enabled": true,
    "nameEnabled": true,
    "nameLabel": "Your name",
    "emailEnabled": true,
    "emailLabel": "Email",
    "phoneEnabled": false,
    "phoneLabel": "Phone",
    "leaveDetailsMessage": "Please leave your details and we will get in touch.",
    "thankYouMessage": "Thanks - we will be in touch shortly.",
    "requireBeforeNewConversation": false,
    "emailNotificationEnabled": true,
    "emailNotificationAddress": "leads@acme.com",
    "emailWithConversationContent": true
  },
  "liveChat": {
    "enabled": false,
    "infoMessage": "Connecting you with a human agent...",
    "startMessage": "You are now chatting with our team.",
    "endMessage": "Live chat has ended.",
    "nameLabel": "Your name",
    "emailLabel": "Email",
    "schedule": "{\"monday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"tuesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"wednesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"thursday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"friday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"saturday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"sunday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"timezone\":\"Europe/Warsaw\"}",
    "outOfHoursMessage": "We are currently offline.",
    "closeModalMessage": "End the live chat session?",
    "closeModalConfirmLabel": "Yes, end",
    "closeModalCancelLabel": "Cancel",
    "closeModalTooltipText": "End live chat",
    "operatorHasJoinedLabel": "An agent has joined.",
    "operatorDidNotJoinInTimeLabel": "No agent available right now.",
    "waitingForOperatorToJoinLabel": "Waiting for an agent...",
    "waitingForOperatorSeconds": 60,
    "redirectToHumanSupportForm": true
  },
  "consent": {
    "newConversationRequirePolicyAccept": false,
    "humanSupportRequirePolicyAccept": false,
    "leadCollectionRequirePolicyAccept": true,
    "liveChatRequirePolicyAccept": false,
    "newConversationConsentDescription": "By starting a conversation you agree to our terms.",
    "privacyPolicyConsentCheckboxLabel": "I have read and accepted the privacy policy."
  },
  "whiteLabel": {
    "hideRoboAssistLogo": false,
    "whitelabelLogoLink": "https://acme.com",
    "assignToCustomDomain": false,
    "whitelabelLogoUrl": "https://api.chatlab.com/aichat/content/custom_logo_4287_2026060110.png"
  },
  "security": {
    "allowedDomains": "acme.com,support.acme.com",
    "spamFilterEnabled": true,
    "talkMessagesRateLimit": 30,
    "talkMessagesRateLimitDurationSeconds": 60,
    "talkMessagesRateLimitHitMessage": "Please slow down."
  },
  "advanced": {
    "model": "5-MINI",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  },
  "meta": {
    "id": 4287,
    "createdAt": "2026-06-01T10:11:02Z",
    "updatedAt": "2026-06-01T11:02:19Z"
  }
}

Einen Bot klonen

Der Request-Body von POST /v1/management/bots und der Response-Body von GET /v1/management/bots/{bot_id} haben dieselbe Struktur. Das Klonen ist daher ein dreistufiger Prozess: Den Quell-Bot per GET abrufen, serververwaltete Identitätsfelder entfernen und das Ergebnis per POST senden.

1. Den Quell-Bot per GET abrufen.

curl https://api.chatlab.com/aichat/v1/management/bots/4287 \
  -H "Authorization: Bearer mk_..." \
  -o source-bot.json

2. Den übergeordneten meta-Block entfernen. Das meta-Objekt (id, createdAt, updatedAt) wird vom Server verwaltet und ist schreibgeschützt - es im POST-Body zu belassen schadet nicht (der Server ignoriert es), aber das Entfernen stellt die Absicht klar heraus und hält die Payload sauber. Optional können Sie name bearbeiten, damit sich der Klon vom Quell-Bot unterscheidet.

jq 'del(.meta) | .name = "Helpdesk Bot (clone)"' source-bot.json > clone-body.json

3. Den bereinigten Body per POST senden, um den Klon zu erstellen. Die vollständige Struktur des Bodys und die Validierungsregeln finden Sie oben in der Referenz zu POST /v1/management/bots.

curl -X POST https://api.chatlab.com/aichat/v1/management/bots \
  -H "Authorization: Bearer mk_..." \
  -H "Content-Type: application/json" \
  -d @clone-body.json

Die Antwort enthält die meta.id des neuen Bots sowie einen neu generierten apiKey (den Bot Talk-Schlüssel für den Klon). Der Klartext des apiKey wird nur bei dieser Erstellungsantwort zurückgegeben - kopieren Sie ihn, bevor Sie den Response-Body verwerfen; er kann später nicht mehr abgerufen werden.

Zwei wichtige Hinweise:

  • Dateien werden nicht geklont. appearance.avatarUrl und whiteLabel.whitelabelLogoUrl sind schreibgeschützt und verweisen auf die Dateien des Quell-Bots. Wenn Sie denselben Avatar oder dasselbe White Label-Logo für den Klon benötigen, laden Sie die Bytes von den Quell-URLs herunter und laden Sie sie als mehrteilige avatar- / whitelabel_logo-Parts hoch - entweder beim Erstellungs-POST (Modus B) oder über einen nachfolgenden PATCH.
  • Bot Talk-Schlüssel werden nicht geklont. Jeder Bot verfügt über seinen eigenen Pool an Bot Talk-Schlüsseln. Der einzelne apiKey, der vom Erstellungs-POST zurückgegeben wird, ist der einzige, der automatisch generiert wird; erstellen Sie bei Bedarf zusätzliche Schlüssel im API-Tab des Bots.

PATCH /v1/management/bots/{bot_id}

Aktualisieren Sie ein oder mehrere Felder eines Bots, der Ihnen gehört. Es werden nur Abschnitte / Felder geändert, die im JSON vorhanden sind; alles Ausgelassene (oder als null Gesendete) bleibt unberührt. Innerhalb eines gesendeten Abschnitts gelten die Regeln für partielle Aktualisierungen pro Feld.

Es werden zwei gleichwertige Content-Types akzeptiert (wie bei POST):

Modus A - einfaches JSON (empfohlen, wenn nur Einstellungen aktualisiert werden):

  • Content-Type: application/json
  • Request-Body ist das Patch-JSON (kein data-Wrapper)

Modus B - multipart/form-data (verwenden Sie dies beim Hochladen von Dateien):

  • data-JSON-Part (optional) - der Patch. Nur senden, wenn Sie Felder ändern möchten. Ganz weglassen, wenn Sie nur einen Avatar oder ein Logo hochladen möchten.
  • avatar-Datei-Part (optional) - ersetzt den Avatar
  • whitelabel_logo-Datei-Part (optional) - ersetzt das White Label-Logo (gilt nur, wenn Ihr Konto White Labeling umfasst)

Alle drei Parts sind bei PATCH optional, aber mindestens einer muss vorhanden sein, damit der Aufruf sinnvoll ist.

Vollständiger Request-Body (maximale Struktur)

Jedes von POST /v1/management/bots akzeptierte Feld kann auch hier gesendet werden. Das folgende Beispiel zeigt die vollständige Struktur; in der Praxis senden Sie nur die Schlüssel, die Sie ändern möchten (siehe "Minimales partielles Update" weiter unten) - jeder ausgelassene (oder als null gesendete) Schlüssel lässt den gespeicherten Wert unberührt.

{
  "name": "Helpdesk Bot",
  "role": {
    "rawPrompt": "You are a friendly support assistant for Acme Inc. Be concise.",
    "role": "CUSTOMER_SUPPORT",
    "language": "English",
    "responseLength": "Concise",
    "websiteAddress": "https://acme.com",
    "companyDescription": "Acme sells industrial widgets."
  },
  "conversation": {
    "welcomeMessage": "Hello there!",
    "queryRefinementEnabled": true,
    "conversationContinuityEnabled": true,
    "conversationRatingEnabled": true,
    "positiveRatingTooltip": "Helpful",
    "negativeRatingTooltip": "Not helpful",
    "suggestedQuestions": "Pricing\nShipping times\nReturns policy",
    "dynamicSuggestedFollowups": true,
    "dynamicFollowupsAutoIcons": true
  },
  "chatMemory": {
    "enabled": true,
    "summaryConversationsEnabled": true,
    "conversationSummaryPrompt": "Summarize the conversation in 3 sentences.",
    "clientSummaryPrompt": "Summarize what we know about the customer.",
    "clientSummaryPromptType": "DEFAULT",
    "conversationSummaryPromptType": "DEFAULT",
    "summariesToKnowledgeRatio": 50
  },
  "appearance": {
    "launcherColor": "#abcdef",
    "headerColor": "#abcdef",
    "titleColor": "#FFFFFF",
    "subtitleColor": "#FFFFFF",
    "clientMessageBubbleColor": "#000000",
    "clientMessageTextColor": "#FFFFFF",
    "responseMessageBubbleColor": "#F4F4F4",
    "responseMessageTextColor": "#000000",
    "chatSubheader": "AI assistant",
    "senderPlaceholder": "Type a message",
    "resetConversationTooltip": "Restart conversation",
    "chatAlignment": "right",
    "launcherBottomMargin": 20,
    "launcherSideMargin": 20,
    "displayShadow": true,
    "customCss": ".rcw-conversation-container { border-radius: 16px; }",
    "chatMessageLinkTarget": "_blank",
    "minimizedDisplayMode": "icon",
    "chatDesktopWidthPx": 400,
    "chatDesktopHeightPx": 600,
    "chatMobileSizePercent": 100,
    "messageFontSize": 14,
    "showChatbotBubblesDesktop": true,
    "showChatbotBubblesMobile": false,
    "chatbotBubblesDelaySeconds": 5,
    "welcomeScreenEnabled": false,
    "welcomeScreenQuestionsLabel": "Quick start",
    "welcomeScreenHideHumanContactForm": false,
    "welcomeScreenHideLiveChat": false,
    "headerActionsLayout": "DROPDOWN",
    "stackSuggestedQuestions": false,
    "suggestedQuestionsFontSize": 14,
    "suggestedQuestionsTextColor": "#000000",
    "suggestedQuestionsBackgroundColor": "#F4F4F4",
    "autoOpenChat": false,
    "autoOpenChatOnMobiles": false,
    "autoOpenChatDelay": false,
    "autoOpenChatDelaySeconds": 5,
    "simulateHumanTyping": true,
    "simulateHumanTypingDelay": 5,
    "footerMarkdown": "Powered by Acme"
  },
  "humanSupport": {
    "enabled": true,
    "email": "support@acme.com",
    "dialogMessage": "Leave us a message and we'll get back to you.",
    "thankYouMessage": "Thanks!",
    "emailMessageSubjectTemplate": "[Acme support] New message from {customerName}",
    "emailMessageContentTemplate": "{message}\n\n - \n{conversationTranscript}",
    "emailPlaceholder": "your@email.com",
    "messagePlaceholder": "How can we help?",
    "emailWithConversationContent": true
  },
  "leadCollection": {
    "enabled": true,
    "nameEnabled": true,
    "nameLabel": "Your name",
    "emailEnabled": true,
    "emailLabel": "Email",
    "phoneEnabled": false,
    "phoneLabel": "Phone",
    "leaveDetailsMessage": "Please leave your details.",
    "thankYouMessage": "Thanks!",
    "requireBeforeNewConversation": true,
    "emailNotificationEnabled": true,
    "emailNotificationAddress": "leads@acme.com",
    "emailWithConversationContent": true
  },
  "liveChat": {
    "enabled": false,
    "infoMessage": "Connecting you with a human agent...",
    "startMessage": "You are now chatting with our team.",
    "endMessage": "Live chat has ended.",
    "nameLabel": "Your name",
    "emailLabel": "Email",
    "schedule": "{\"monday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"tuesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"wednesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"thursday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"friday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"saturday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"sunday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"timezone\":\"Europe/Warsaw\"}",
    "outOfHoursMessage": "We are currently offline.",
    "closeModalMessage": "End the live chat session?",
    "closeModalConfirmLabel": "Yes, end",
    "closeModalCancelLabel": "Cancel",
    "closeModalTooltipText": "End live chat",
    "operatorHasJoinedLabel": "An agent has joined.",
    "operatorDidNotJoinInTimeLabel": "No agent available right now.",
    "waitingForOperatorToJoinLabel": "Waiting for an agent...",
    "waitingForOperatorSeconds": 60,
    "redirectToHumanSupportForm": true
  },
  "consent": {
    "newConversationRequirePolicyAccept": false,
    "humanSupportRequirePolicyAccept": false,
    "leadCollectionRequirePolicyAccept": true,
    "liveChatRequirePolicyAccept": false,
    "newConversationConsentDescription": "By starting a conversation you agree to our terms.",
    "privacyPolicyConsentCheckboxLabel": "I have read and accepted the privacy policy."
  },
  "whiteLabel": {
    "hideRoboAssistLogo": false,
    "whitelabelLogoLink": "https://acme.com",
    "assignToCustomDomain": false
  },
  "security": {
    "allowedDomains": "acme.com,support.acme.com",
    "spamFilterEnabled": true,
    "talkMessagesRateLimit": 30,
    "talkMessagesRateLimitDurationSeconds": 60,
    "talkMessagesRateLimitHitMessage": "Please slow down."
  },
  "advanced": {
    "model": "5",
    "temperature": 0.2,
    "chatContextSize": 32000,
    "botMessagesLimit": 2000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  }
}

Minimales partielles Update

Aktualisieren Sie ein einzelnes Feld per PATCH, indem Sie genau die Schlüssel senden, die Sie ändern möchten - alles andere bleibt erhalten.

{
  "appearance": {
    "launcherColor": "#abcdef"
  }
}

Curl-Beispiele

Modus A - einfaches JSON (am einfachsten):

curl -X PATCH https://api.chatlab.com/aichat/v1/management/bots/4287 \
  -H "Authorization: Bearer mk_..." \
  -H "Content-Type: application/json" \
  -d '{"appearance":{"launcherColor":"#abcdef"}}'

Modus B - Multipart (beim Ersetzen von Avatar / Logo):

curl -X PATCH https://api.chatlab.com/aichat/v1/management/bots/4287 \
  -H "Authorization: Bearer mk_..." \
  -F 'data={"appearance":{"launcherColor":"#abcdef"}};type=application/json' \
  -F 'avatar=@./new-avatar.png'

Modus B - nur den Avatar ersetzen (keine Feldänderungen):

curl -X PATCH https://api.chatlab.com/aichat/v1/management/bots/4287 \
  -H "Authorization: Bearer mk_..." \
  -F 'avatar=@./new-avatar.png'

Response-Body (200)

Gleiche Struktur wie bei GET /v1/management/bots/{bot_id} - die vollständige Konfiguration des Bots nach Anwendung des Patches, einschließlich des meta-Blocks. Kein apiKey-Feld. Gibt 404 not_found_error zurück, wenn der Bot nicht existiert oder nicht zu Ihrem Konto gehört.

Das folgende Beispiel zeigt die Antwort nach Anwendung des obigen Patches Vollständiger Request-Body (maximale Struktur) auf den Bot aus dem GET-Beispiel - geänderte Felder spiegeln die neuen Werte wider, unberührte Felder bleiben erhalten und meta.updatedAt wird aktualisiert.

{
  "name": "Helpdesk Bot",
  "role": {
    "rawPrompt": "You are a friendly support assistant for Acme Inc. Be concise.",
    "role": "CUSTOMER_SUPPORT",
    "language": "English",
    "responseLength": "Concise",
    "websiteAddress": "https://acme.com",
    "companyDescription": "Acme sells industrial widgets."
  },
  "conversation": {
    "welcomeMessage": "Hello there!",
    "queryRefinementEnabled": true,
    "conversationContinuityEnabled": true,
    "conversationRatingEnabled": true,
    "positiveRatingTooltip": "Helpful",
    "negativeRatingTooltip": "Not helpful",
    "suggestedQuestions": "Pricing\nShipping times\nReturns policy",
    "dynamicSuggestedFollowups": true,
    "dynamicFollowupsAutoIcons": true
  },
  "chatMemory": {
    "enabled": true,
    "summaryConversationsEnabled": true,
    "conversationSummaryPrompt": "Summarize the conversation in 3 sentences.",
    "clientSummaryPrompt": "Summarize what we know about the customer.",
    "clientSummaryPromptType": "DEFAULT",
    "conversationSummaryPromptType": "DEFAULT",
    "summariesToKnowledgeRatio": 50
  },
  "appearance": {
    "launcherColor": "#abcdef",
    "headerColor": "#abcdef",
    "titleColor": "#FFFFFF",
    "subtitleColor": "#FFFFFF",
    "clientMessageBubbleColor": "#000000",
    "clientMessageTextColor": "#FFFFFF",
    "responseMessageBubbleColor": "#F4F4F4",
    "responseMessageTextColor": "#000000",
    "chatSubheader": "AI assistant",
    "senderPlaceholder": "Type a message",
    "resetConversationTooltip": "Restart conversation",
    "chatAlignment": "right",
    "launcherBottomMargin": 20,
    "launcherSideMargin": 20,
    "displayShadow": true,
    "customCss": ".rcw-conversation-container { border-radius: 16px; }",
    "chatMessageLinkTarget": "_blank",
    "minimizedDisplayMode": "icon",
    "chatDesktopWidthPx": 400,
    "chatDesktopHeightPx": 600,
    "chatMobileSizePercent": 100,
    "messageFontSize": 14,
    "showChatbotBubblesDesktop": true,
    "showChatbotBubblesMobile": false,
    "chatbotBubblesDelaySeconds": 5,
    "welcomeScreenEnabled": false,
    "welcomeScreenQuestionsLabel": "Quick start",
    "welcomeScreenHideHumanContactForm": false,
    "welcomeScreenHideLiveChat": false,
    "headerActionsLayout": "DROPDOWN",
    "stackSuggestedQuestions": false,
    "suggestedQuestionsFontSize": 14,
    "suggestedQuestionsTextColor": "#000000",
    "suggestedQuestionsBackgroundColor": "#F4F4F4",
    "autoOpenChat": false,
    "autoOpenChatOnMobiles": false,
    "autoOpenChatDelay": false,
    "autoOpenChatDelaySeconds": 5,
    "simulateHumanTyping": true,
    "simulateHumanTypingDelay": 5,
    "footerMarkdown": "Powered by Acme",
    "avatarUrl": "https://api.chatlab.com/aichat/content/avatar_a8f3b2c1_2026060110.png"
  },
  "humanSupport": {
    "enabled": true,
    "email": "support@acme.com",
    "dialogMessage": "Leave us a message and we'll get back to you.",
    "thankYouMessage": "Thanks!",
    "emailMessageSubjectTemplate": "[Acme support] New message from {customerName}",
    "emailMessageContentTemplate": "{message}\n\n - \n{conversationTranscript}",
    "emailPlaceholder": "your@email.com",
    "messagePlaceholder": "How can we help?",
    "emailWithConversationContent": true
  },
  "leadCollection": {
    "enabled": true,
    "nameEnabled": true,
    "nameLabel": "Your name",
    "emailEnabled": true,
    "emailLabel": "Email",
    "phoneEnabled": false,
    "phoneLabel": "Phone",
    "leaveDetailsMessage": "Please leave your details.",
    "thankYouMessage": "Thanks!",
    "requireBeforeNewConversation": true,
    "emailNotificationEnabled": true,
    "emailNotificationAddress": "leads@acme.com",
    "emailWithConversationContent": true
  },
  "liveChat": {
    "enabled": false,
    "infoMessage": "Connecting you with a human agent...",
    "startMessage": "You are now chatting with our team.",
    "endMessage": "Live chat has ended.",
    "nameLabel": "Your name",
    "emailLabel": "Email",
    "schedule": "{\"monday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"tuesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"wednesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"thursday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"friday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"saturday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"sunday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"timezone\":\"Europe/Warsaw\"}",
    "outOfHoursMessage": "We are currently offline.",
    "closeModalMessage": "End the live chat session?",
    "closeModalConfirmLabel": "Yes, end",
    "closeModalCancelLabel": "Cancel",
    "closeModalTooltipText": "End live chat",
    "operatorHasJoinedLabel": "An agent has joined.",
    "operatorDidNotJoinInTimeLabel": "No agent available right now.",
    "waitingForOperatorToJoinLabel": "Waiting for an agent...",
    "waitingForOperatorSeconds": 60,
    "redirectToHumanSupportForm": true
  },
  "consent": {
    "newConversationRequirePolicyAccept": false,
    "humanSupportRequirePolicyAccept": false,
    "leadCollectionRequirePolicyAccept": true,
    "liveChatRequirePolicyAccept": false,
    "newConversationConsentDescription": "By starting a conversation you agree to our terms.",
    "privacyPolicyConsentCheckboxLabel": "I have read and accepted the privacy policy."
  },
  "whiteLabel": {
    "hideRoboAssistLogo": false,
    "whitelabelLogoLink": "https://acme.com",
    "assignToCustomDomain": false,
    "whitelabelLogoUrl": "https://api.chatlab.com/aichat/content/custom_logo_4287_2026060110.png"
  },
  "security": {
    "allowedDomains": "acme.com,support.acme.com",
    "spamFilterEnabled": true,
    "talkMessagesRateLimit": 30,
    "talkMessagesRateLimitDurationSeconds": 60,
    "talkMessagesRateLimitHitMessage": "Please slow down."
  },
  "advanced": {
    "model": "5",
    "temperature": 0.2,
    "chatContextSize": 32000,
    "botMessagesLimit": 2000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  },
  "meta": {
    "id": 4287,
    "createdAt": "2026-06-01T10:11:02Z",
    "updatedAt": "2026-06-01T12:45:08Z"
  }
}

GET /v1/usage

Liest die aktuelle Abonnement-Nutzung für das Konto aus, dem der Management-Schlüssel gehört.

Response-Body (200)

{
  "subscriptionType": "standard",
  "messages": {"used": 4123, "limit": 11000, "remaining": 6877},
  "bots": {"used": 3, "limit": 5, "remaining": 2}
}
  • subscriptionType ist eine in Kleinbuchstaben gehaltene Kennung des aktuellen Plans des Kontos (z. B. standard im Beispiel). Tarife stammen aus einem dynamischen Katalog, sodass sich die genaue Gruppe von Kennungen im Laufe der Zeit ändern kann, wenn Tarife umbenannt oder hinzugefügt werden - behandeln Sie dies als intransparenten String und nicht als festes Enum.
  • messages.used / limit / remaining sind die Nachrichten-Credits des aktuellen Abrechnungszeitraums.
  • bots.used / limit / remaining zählen aktive Bots im Verhältnis zum Bot-Limit Ihres Kontos.

Rate-Limit-Header

Antworten, die die Rate-Limit-Stufe erreichen (d. h. Authentifizierung und IP-Whitelist wurden erfolgreich durchlaufen), enthalten Folgendes:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1715430000
  • X-RateLimit-Limit - das für diesen Aufruf tatsächlich angewendete Limit pro Schlüssel (standardmäßig 10 oder Ihr konfigurierter Wert für rateLimitPerMinute, falls dieser niedriger ist).
  • X-RateLimit-Remaining - verbleibende Token im Bucket direkt nach diesem Aufruf.
  • X-RateLimit-Reset - Unix-Epochensekunden, zu denen das nächste Token verfügbar wird (kein vollständiger Bucket-Reset; der Bucket füllt sich kontinuierlich wieder auf). Wenn der Bucket voll ist, entspricht dies der aktuellen Zeit.

Bei 429 rate_limit_exceeded-Antworten wird zusätzlich Retry-After gesetzt, angegeben in ganzen Sekunden, bis mindestens ein Token wieder frei wird.

Fehler vor der Authentifizierung (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) und 403 ip_not_whitelisted enthalten keine X-RateLimit-*-Header - der Limiter wird erst konsultiert, nachdem die Authentifizierung und die IP-Prüfungen erfolgreich abgeschlossen wurden.

Fehlerformat

Dieselbe Hülle wie bei der Bot Talk API:

{
  "error": {
    "type": "permission_error",
    "code": "key_type_not_allowed",
    "message": "This endpoint requires a MANAGEMENT API key.",
    "param": null
  }
}

Validierungsfehler verwenden code: "invalid_parameter" und stellen den fehlerhaften Feldpfad vor die Nachricht, damit der betroffene Abschnitt leicht zu erkennen ist:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "humanSupport.email Human support email is required when humanSupport.enabled=true"
  }
}

Ungültige Werte für Enum- / geschlossene Wertebereichs-Felder (z. B. chatMemory.clientSummaryPromptType = "BOGUS") enthalten den Feldpfad, den abgelehnten Wert und die Liste der zulässigen Werte:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "chatMemory.clientSummaryPromptType 'BOGUS' is not a valid value. Allowed: CUSTOM, DEFAULT"
  }
}

Verwandte Themen

Informationen zu Konversations-Endpunkten und SSE-Streaming finden Sie unter Bot Talk API.

Alle Artikel durchsuchenDen Agenten fragen