Management API

Ü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 > Management API (Kontoeinstellungen > Management API).
2. Klicken Sie auf Create Management Key (Management-Schlüssel erstellen), benennen Sie ihn, legen Sie optional eine IP-Whitelist sowie ein Rate-Limit fest und bestätigen Sie die Eingabe.
3. Wählen Sie nur die Berechtigungen aus, die Ihre Integration benötigt, und kopieren Sie den vollständigen Schlüssel aus dem Bestätigungsdialog. Der Klartext wird nur ein einziges Mal angezeigt.
4. Speichern Sie ihn auf Ihrem Server, nicht im Browser-Code oder in einem öffentlichen Repository. Führen Sie eine schreibgeschützte Anfrage wie GET /v1/usage mit der Berechtigung usage aus, um den Zugriff zu überprüfen.
5. Widerrufen Sie ungenutzte oder kompromittierte Schlüssel über die Seite Management API.

Ein Schlüssel sieht wie folgt aus: 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

Body-Struktur: verschachtelte Abschnitte, die den Reitern der Admin-UI entsprechen

POST und PATCH akzeptieren einen JSON-Body, der in 13 Abschnitte unterteilt ist. Jeder Abschnitt entspricht einem Unterreiter in der Seitenleiste der Boteinstellungen der Admin-App, sodass die JSON-Schlüssel und die sichtbaren Reiter übereinstimmen: Wenn Sie consent.humanSupportRequirePolicyAccept über die API ändern, wird derselbe Schalter im Reiter Einwilligung & Datenschutz (Consent & Privacy) in der Admin-App umgelegt.

• role - Bot-Persona, Roh-Prompt, Antwortlänge, Sprache, Website- / Unternehmenskontext (Reiter „Rolle & Verhalten“ / Role & Behavior)
• conversation - Willkommensnachricht, Abfrageverfeinerung, Konversationskontinuität, Bewertungsschalter + Tooltips, Inhalt für Fragenvorschläge + dynamische Nachfragen (Reiter „Chat-Konversation“ / Chat Conversation)
• chatMemory - Chat-Speicher-Schalter, Zusammenfassungs-Prompts, Kontextzuweisung (Reiter „Zusammenfassungen & Speicher“ / Summaries & Memory)
• appearance - Farben, Texte, Abmessungen, benutzerdefiniertes CSS, Willkommensbildschirm, Design für Fragenvorschläge, Verhalten beim automatischen Öffnen, Simulation menschlichen Tippens, Footer-Markdown (Reiter „Erscheinungsbild“ / Appearance)
• humanSupport - Kontaktformular (Reiter „Kontaktformular“ / Human Contact Form)
• leadCollection - Lead-Erfassungsformular (Reiter „Lead-Erfassung“ / Lead Collection)
• liveChat - Übergabe an den Live Chat (Reiter „Live Chat“)
• consent - Alle vier Datenschutzeinwilligungs-Schalter plus Text des Einwilligungsbildschirms (Reiter „Einwilligung & Datenschutz“ / Consent & Privacy)
• whiteLabel - Logo ausblenden, benutzerdefinierter Logo-Link, Hosting auf eigener Domain (Reiter „Whitelabel“)
• security - Zulässige Domains, Spamfilter, Ratenbegrenzungen für Unterhaltungen (Reiter „Sicherheit“ / Security)
• voice - Spracheingabe und Sprachkonversationen: Modell, Stimme, Sprachen, Prompt, maximale Dauer (Reiter „Sprachkonversation“ / Voice Conversation)
• multilingual - Mehrsprachiger Modus, Basissprache, angebotene Sprachen, Umgang mit Wissenssprachen (Reiter „Sprachen“ / Languages)
• advanced - LLM-Modell, Temperatur, Kontextgröße, Bot-Nachrichtenlimit, internes Gebietsschema, Offer Cards (Reiter „Modell & Erweitert“ / Model & Advanced)

Von den schreibbaren Einstellungen befindet sich nur name auf der obersten Ebene, da es den Bot identifiziert, anstatt zu einem bestimmten Reiter zu gehören.

Die Seitenleiste der Boteinstellungen umfasst derzeit 16 Unterreiter, von denen 13 den oben genannten Abschnitten entsprechen. Die drei Unterreiter ohne entsprechenden Abschnitt sind Flow, Aktionen (Actions) und Formulare (Forms) - alle drei werden weiter unten unter „Außerhalb des API-Bereichs“ behandelt. Die 13 Reiter mit Entsprechung sind Erscheinungsbild, Chat-Konversation, Rolle & Verhalten, Kontaktformular, Lead-Erfassung, Live Chat, Whitelabel, Einwilligung & Datenschutz, Sicherheit, Modell & Erweitert, Zusammenfassungen & Speicher, Sprachkonversation und Sprachen.

Request-Body und Response-Body weisen dieselbe Struktur auf. Die Antwort enthält zwei zusätzliche Elemente:

• meta - schreibgeschützt: Bot-ID und Zeitstempel. Entfernen Sie diesen Wert, um eine GET-Antwort in einen gültigen POST-Body umzuwandeln.
• apiKey - nur beim Erstellen vorhanden - der neu erstellte 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 Datei 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 es 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“.

Konstruktion von Rolle und Prompt

Der System-Prompt, den das LLM tatsächlich empfängt, wird abhängig von role.role auf eine von zwei Arten erstellt. Zu wissen, auf welchem Zweig Sie sich befinden, 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 erstellt den Prompt aus einer integrierten Vorlage und ignoriert role.rawPrompt vollständig (der Wert wird weiterhin beim Bot gespeichert, jedoch nicht verwendet). Die Vorlage enthält Folgendes:

• role.role - Rollenbezeichnung (z. B. „Kundensupport“) und rollenspezifische Anweisungen, die automatisch angehängt werden
• name - Bot-Name, eingefügt in den ersten Satz
• role.language - "Auto Detect" sorgt dafür, dass sich der Bot der Sprache des Nutzers anpasst; jeder andere Wert (z. B. "English", "Polish") wird zu „Antworten Sie auf {language}, es sei denn, der Nutzer verwendet eine andere Sprache“
• role.responseLength - zugeordnet zu einer Ziel-Wortanzahl: Concise ≈ 50 Wörter, Normal ≈ 100, Detailed ≈ 200
• role.websiteAddress - optional; wenn nicht leer, angehängt als „für die Nutzer der Website {url}“
• role.companyDescription - optional; wenn nicht leer, vorangestellt als zusätzlicher Absatz vor den Rollenanweisungen

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

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

Das Backend verwendet role.rawPrompt als Rollen-Prompt und hängt die festen Richtlinien der Plattform zur Antwortlänge an. Dies ist unabhängig von role.responseLength: Die optionale Einstellung „Prägnant/Normal/Detailliert“ wird bei einer CUSTOM-Rolle nicht eingefügt. Ebenso werden language, websiteAddress und companyDescription zwar gespeichert, aber nicht in diesen Rollen-Prompt eingefügt. Fügen Sie gewünschte Sprachvorgaben, Ziel-Antwortlängen oder Unternehmenskontexte selbst in rawPrompt ein. Zusätzliche Laufzeitanweisungen und abgerufener Kontext können ebenfalls bereitgestellt werden, sodass rawPrompt nicht die gesamte Modelleingabe darstellt. Die Tonartanweisungen der vordefinierten Rolle werden nicht hinzugefügt; die Wahl von CUSTOM entfernt jedoch nicht alle Plattformanweisungen.

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

Enum- / Wertebereichs-Felder

Enum- und eingeschränkte Felder weisen ungültige Werte mit 400 invalid_parameter ab. Andere Felder sind einfache Strings, selbst wenn die UI eine feste Auswahlliste anbietet. Verwenden Sie die dokumentierte Schreibweise und validieren Sie Ihre Nutzdaten, anstatt anzunehmen, dass jede nicht unterstützte Zeichenfolge abgewiesen wird.

• 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 unverändert 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 abgewiesen, führen jedoch zu fehlerhaften Anweisungen wie „Antworten Sie auf en, es sei denn...“. Standardwert ist Auto Detect, wenn beim Erstellen nichts angegeben wird.
• advanced.model - siehe „KI-Textmodelle“ weiter unten. Dies ist ein String, kein validiertes Enum im Anfrageschema; verwenden Sie einen unterstützten Wert und keinen beliebigen Modellnamen.
• advanced.chatContextSize - verwenden Sie 8000, 16000 oder 32000, passend zur Benutzeroberfläche. Werte über dem Kontomaximum werden stillschweigend begrenzt; das DTO erzwingt diese drei Werte nicht streng.
• chatMemory.clientSummaryPromptType - DEFAULT, CUSTOM
• chatMemory.conversationSummaryPromptType - DEFAULT, CUSTOM
• appearance.chatAlignment - left, right
• appearance.minimizedDisplayMode - icon, minified, pill
• appearance.chatMessageLinkTarget - _blank, _self
• leadCollection.requireBeforeNewConversation - Boolescher Schalter. true zwingt den Nutzer dazu, das Lead-Formular vor Beginn einer Unterhaltung auszufüllen; false überlässt es der KI zu entscheiden, wann das Formular angezeigt wird (Standard).

Strukturierte Felder und Wertebereiche

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

• advanced.temperature - akzeptierter Bereich reicht von 0.0 bis 1.0, passend zum Schieberegler in der Admin-UI. Werte außerhalb dieses Bereichs werden mit 400 invalid_parameter abgewiesen.

• chatMemory.summariesToKnowledgeRatio - ganzzahliger Prozentwert, 10-90; die UI verwendet Schritte von 10, die API akzeptiert jedoch ganze Zahlen im gesamten Bereich. Standardwert 50. Wenn der Speicher aktiviert ist und der Kontext größer als 8k ist, teilt dies das Wissens- und Speicherbudget nach dem reservierten Anteil für Prompt und kürzliche Unterhaltung auf, nicht den gesamten Modellkontext. Bei 8k wird durch diese Einstellung kein Budget für Zusammenfassungen zugewiesen.

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

  • Jeder Wochentagsschlü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, nicht um ein 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 unterdrückt. Die interne Strukturvalidierung erfolgt nur clientseitig in der Admin-UI - fehlerhaftes JSON oder unbekannte Schlüssel werden von der API einfach als String akzeptiert und führen zu einem Darstellungsfehler, wenn später ein Nutzer den Bot im Admin-Bereich öffnet. Validieren Sie die Struktur vor dem Senden auf Ihrer Seite.

• conversation.positiveRatingTooltip / conversation.negativeRatingTooltip - kurze Labels, die bei den Bewertungs-Bedienelementen 👍 / 👎 angezeigt werden, wenn conversation.conversationRatingEnabled=true aktiviert ist. Der Standardtext lautet „Mir gefällt die Antwort“ / „Mir gefällt die Antwort nicht“. 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-Labeling umfasst, wird der Wert zwar gespeichert, aber ignoriert, und die Fußzeile wird immer gerendert.

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

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

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

• advanced.internalLocale - IETF-Sprach- und Regionscode im Format ll_CC (Unterstrich, NICHT ll-CC mit Bindestrich). Akzeptierte Werte stammen aus einer festen Liste von rund 95 Gebietsschemas: 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 viele mehr. Das Senden eines reinen zweistelligen Codes ("en") oder BCP-47 ("en-US") ist in der Liste der zulässigen Werte nicht enthalten. Standardwert en_US. Dies ist das Gebietsschema, das für die Datums-/Zahlenformatierung im Widget-Rahmen verwendet wird, unabhängig von role.language (der Konversationssprache des Bots).

• security.talkMessagesRateLimit / security.talkMessagesRateLimitDurationSeconds - ganze Zahlen (als JSON-Zahlen senden, z. B. 30, nicht "30"). Setzen Sie das Nachrichtenlimit auf 0, um dieses sitzungsbasierte Limit zu deaktivieren. Wenn Sie es aktivieren, geben Sie eine positive Dauer an. Das Backend erzwingt N Nachrichten pro Sitzung pro Dauer in Sekunden, bevor dem Besucher security.talkMessagesRateLimitHitMessage angezeigt wird.

• advanced.botMessagesLimit - ganze Zahl (JSON-Zahl, z. B. 1000). 0 bedeutet keine zusätzliche Obergrenze pro Bot, während das Credit-Budget des Kontos weiterhin gilt; andernfalls muss es ein Vielfaches von 1.000 sein (1000, 2000, 10000, ...). Werte wie 100 oder 1500 werden mit 400 invalid_parameter abgewiesen. Dies ist eine monatliche Bot-Obergrenze für Credits, keine Nachrichtenanzahl pro Unterhaltung. Das Mapping begrenzt diesen Wert nicht auf das Kontobudget; das Budget des Kontos schränkt die tatsächliche Nutzung weiterhin ein.

KI-Textmodelle (advanced.model)

Verwenden Sie die exakte Modellkennung, die in advanced.model zurückgegeben wird, wenn Sie einen Bot auslesen, der unter Einstellungen > Modell & Erweitert (Settings > Model & Advanced) mit Ihrem gewünschten Modell konfiguriert ist. Der aktuelle Standardwert bei der Erstellung ist 5.6-LUNA. Kennungen unterscheiden zwischen Groß- und Kleinschreibung und weichen von den Anzeigenamen ab; beispielsweise wird 5.6-LUNA als GPT 5.6-luna angezeigt.

Der Modellkatalog ändert sich im Laufe der Zeit. Schließen Sie nicht daraus, dass ein beliebiger String oder eine öffentliche Modell-ID eines Anbieters unterstützt wird, nur weil das Anfrageschema eine Zeichenfolge akzeptiert. Lesen Sie die gespeicherte Konfiguration aus und testen Sie den resultierenden Chatbot, bevor Sie ihn bereitstellen.

Feldreferenz (vollständiges Anfrage-Schema)

Die unterstützten Abschnitte und Felder mit ihren Typen und wichtigen Einschränkungen. PATCH-Semantik: Jedes weggelassene (oder als null gesendete) Feld belässt den gespeicherten Wert unverändert. Die gleiche Struktur wird für die Antwort verwendet (abzüglich mehrteiliger Binärinhalte; zuzüglich des schreibgeschützten Blocks meta bei jeder Antwort und apiKey nur bei der Erstellungsantwort).

Oberste Ebene

Feld	Typ	Einschränkung	Beschreibung
name	string	max 150, erforderlich beim Erstellen	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

Nur in der Antwort enthaltene Ergänzungen:

• meta: { id, createdAt, updatedAt } - schreibgeschützt.
• apiKey - string, nur in der Antwort auf POST /v1/management/bots vorhanden - der neu generierte 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 "Konstruktion von Rolle und Prompt")
language	string	vollständiger englischer Sprachname (English, Polish, ...) oder Auto Detect	Primärsprache, die in die Prompt-Vorlage eingefügt wird
responseLength	string	∈ {Concise, Normal, Detailed}	Gewünschte Ausführlichkeit der KI-Antworten
websiteAddress	string		Für den Prompt-Kontext verwendete Website
companyDescription	string		Für den Prompt-Kontext verwendete Unternehmensbeschreibung
rawPrompt	string		Benutzerdefinierter System-Prompt - wird nur dann wörtlich verwendet, wenn role=CUSTOM

§ 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, werden Steuerelemente zur Bewertung der Unterhaltung (Daumen nach oben/unten) angezeigt
positiveRatingTooltip	string		Tooltip auf der Schaltfläche für positive Bewertung
negativeRatingTooltip	string		Tooltip auf der Schaltfläche für negative Bewertung
suggestedQuestions	string		Durch Zeilenumbrüche getrennte Fragenvorschläge / Gesprächseinstiege
dynamicSuggestedFollowups	boolean		Wenn true, schlägt die KI nach jeder Antwort Folgefragen vor
positiveRatingMessage	string		Nach positivem Feedback angezeigte Nachricht
negativeRatingMessage	string		Nach negativem Feedback angezeigte Nachricht
hideSuggestedQuestionsAfterFirstUse	boolean		Statische Vorschläge nach der Nutzung ausblenden
dynamicFollowupsAutoIcons	boolean		Wenn true, wählt die KI automatisch Emoji-Icons 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}	Ob der standardmäßige oder der benutzerdefinierte Zusammenfassungs-Prompt verwendet werden soll
clientSummaryPrompt	string		Benutzerdefinierter Prompt zur Zusammenfassung des Kunden über mehrere Unterhaltungen hinweg
clientSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Standard- versus benutzerdefinierter Kundenprofil-Prompt
summariesToKnowledgeRatio	int	10-90 (UI-Schritt 10)	Prozentualer Anteil des verfügbaren Wissens-/Memory-Budgets, der bei Kontexten über 8k für Zusammenfassungen reserviert ist

§ appearance

Feld	Typ	Einschränkung	Beschreibung
launcherLabelLine1	string	max 60	Erste Zeile des Launcher-Texts
launcherLabelLine2	string	max 60	Zweite Zeile des Launcher-Texts
launcherTextColor	string		Textfarbe des Launchers
launcherDismissEnabled	boolean		Schließen des Launchers erlauben
widgetFontFamily	string	inter, system, nunito, lato, montserrat, poppins, source-serif, jetbrains-mono	Schriftfamilie des Widgets
chatDrawerEnabled	boolean		Drawer-Darstellung aktivieren
launcherColor	string (hex)		Hintergrundfarbe des Launchers (Chat-Icon)
headerColor	string (hex)		Hintergrundfarbe der Chat-Kopfzeile
titleColor	string (hex)		Titelfarbe der Chat-Kopfzeile
subtitleColor	string (hex)		Untertitelfarbe der Chat-Kopfzeile
clientMessageBubbleColor	string (hex)		Farbe der Nachrichtenblase des Besuchers
clientMessageTextColor	string (hex)		Textfarbe der Nachricht des Besuchers
responseMessageBubbleColor	string (hex)		Farbe der Antwortblase des Bots
responseMessageTextColor	string (hex)		Textfarbe der Antwort des Bots
chatSubheader	string		Unter dem Chat-Titel angezeigte Tagline
senderPlaceholder	string		Platzhaltertext im Nachrichteneingabefeld
resetConversationTooltip	string		Tooltip auf der Schaltfläche "Unterhaltung zurücksetzen"
chatAlignment	string (enum)	∈ {left, right}	An welcher Seite des Bildschirms der Chat verankert ist
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		Unbearbeitetes CSS, das in das Widget-iframe injiziert wird
chatMessageLinkTarget	string (enum)	∈ {_blank, _self}	Wie Links in Bot-Nachrichten geöffnet werden
minimizedDisplayMode	string (enum)	∈ {icon, minified, pill}	Minimierter Zustand: Launcher-Icon, kompakte Nachrichteneingabeleiste oder Pill
chatDesktopWidthPx	int		Widget-Breite auf dem Desktop
chatDesktopHeightPx	int		Widget-Höhe auf dem Desktop
chatMobileSizePercent	int		Mobile Widget-Größe in % des Viewports
messageFontSize	int		Schriftgröße des Nachrichtentexts (px)
showChatbotBubblesDesktop	boolean		Schwebende Vorschau-Blasen auf dem Desktop anzeigen
showChatbotBubblesMobile	boolean		Schwebende Vorschau-Blasen auf Mobilgeräten anzeigen
chatbotBubblesDelaySeconds	int		Verzögerung vor dem Erscheinen der Vorschau-Blasen (Sekunden)
launcherIconFullSize	boolean		Das benutzerdefinierte Launcher-Icon randabfallend statt eingerückt darstellen
welcomeScreenEnabled	boolean		Begrüßungsbildschirm anzeigen, anstatt direkt zum Chat zu wechseln
welcomeScreenQuestionsLabel	string		Beschriftung über den vorgeschlagenen Fragen auf dem Begrüßungsbildschirm
welcomeScreenHideHumanContactForm	boolean		Die Aktion für das menschliche Kontaktformular 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		Die 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	ICONS oder DROPDOWN	Wie Live Chat und das menschliche Kontaktformular in der Chat-Kopfzeile angeboten werden: ICONS (jeweils ein eigenes Icon) oder DROPDOWN (gruppiert im Menü der Kopfzeile). Bei Bots, die vor dem 2026-09-02 erstellt wurden, ist der Standardwert ICONS
stackSuggestedQuestions	boolean		Vorgeschlagene Fragen vertikal anordnen (im Gegensatz zu nebeneinander)
suggestedQuestionsFontSize	int		Schriftgröße der Chips für vorgeschlagene Fragen (px)
suggestedQuestionsTextColor	string (hex)		Textfarbe der Chips für vorgeschlagene Fragen
suggestedQuestionsBackgroundColor	string (hex)		Hintergrundfarbe der Chips für vorgeschlagene Fragen
autoOpenChat	boolean		Den Chat auf dem Desktop automatisch öffnen
autoOpenChatOnMobiles	boolean		Den Chat auf Mobilgeräten automatisch öffnen
autoOpenChatDelay	boolean		Eine Verzögerung vor dem automatischen Öffnen verwenden
autoOpenChatDelaySeconds	int		Verzögerung für das automatische Öffnen (Sekunden)
simulateHumanTyping	boolean		Bot-Antwort in Blasen mit Schreibanimation aufteilen
simulateHumanTypingDelay	int	0-200	Verzögerung zwischen Blasen-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-Teil avatar hochladen

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

§ humanSupport

Feld	Typ	Einschränkung	Beschreibung
enabled	boolean		Umschalter für den Ablauf des menschlichen Supports
email	string	erforderlich (create-strict), wenn enabled=true	Adresse, die E-Mails mit Anfragen an den menschlichen Support empfängt
dialogMessage	string		Über dem Formular angezeigte motivierende Nachricht
thankYouMessage	string		Nach dem Absenden angezeigte Bestätigung
emailMessageSubjectTemplate	string		Betreffvorlage für die an den Agenten gesendete E-Mail
emailMessageContentTemplate	string		Textvorlage 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 Text der E-Mail eingefügt
customFormId	long	ID eines vorhandenen benutzerdefinierten Formulars	Ersetzt das integrierte Kontaktformular durch ein benutzerdefiniertes Formular. Beim Erstellen verwendet ein Weglassen das integrierte Formular; bei PATCH belässt null die aktuelle Auswahl unverändert
customFormMapping	string	JSON-kodierter String	Ordnet Felder des benutzerdefinierten Formulars den E-Mail-Feldern des menschlichen Supports zu

requirePolicyAccept befindet sich in consent.humanSupportRequirePolicyAccept, nicht hier.

§ leadCollection

Feld	Typ	Einschränkung	Beschreibung
enabled	boolean		Umschalter für das Lead-Formular
nameEnabled	boolean		Namen erfassen
nameLabel	string		Beschriftung auf dem Namenseingabefeld
emailEnabled	boolean		E-Mail erfassen
emailLabel	string	erforderlich (create-strict), wenn enabled=true UND emailEnabled=true	Beschriftung auf dem E-Mail-Eingabefeld
phoneEnabled	boolean		Telefonnummer erfassen
phoneLabel	string	erforderlich (create-strict), wenn enabled=true UND phoneEnabled=true	Beschriftung auf dem Telefoneingabefeld
leaveDetailsMessage	string	erforderlich (create-strict), wenn enabled=true	Nachricht, die den Besucher dazu animiert, seine Daten zu hinterlassen
thankYouMessage	string	erforderlich (create-strict), wenn enabled=true	Nach dem Absenden angezeigte Bestätigung
requireBeforeNewConversation	boolean		Wenn true, muss das Formular vor Beginn des Chats gesendet werden; wenn false, entscheidet die KI, wann das Formular eingeblendet wird
emailNotificationEnabled	boolean		Den Eigentümer jedes Mal per E-Mail benachrichtigen, wenn ein Lead erfasst wird
emailNotificationAddress	string		Benachrichtigungsempfänger (standardmäßig die Konto-E-Mail-Adresse)
emailWithConversationContent	boolean		Wenn true, wird das Transkript der Unterhaltung in die Benachrichtigung aufgenommen

| customFormId | long | ID eines vorhandenen benutzerdefinierten Formulars | Ersetzt das integrierte Lead-Formular durch ein benutzerdefiniertes Formular. Beim Erstellen verwendet ein Weglassen das integrierte Formular; bei PATCH belässt null die aktuelle Auswahl unverändert | | customFormMapping | string | JSON-kodierter String | Ordnet Felder des benutzerdefinierten Formulars Name / E-Mail / Telefon zu |

Feldübergreifende create-strict-Regel: enabled=true erfordert mindestens eines von emailEnabled oder phoneEnabled. requirePolicyAccept befindet sich in consent.leadCollectionRequirePolicyAccept, nicht hier.

§ liveChat

Feld	Typ	Einschränkung	Beschreibung
enabled	boolean		Umschalter für die Live Chat-Funktion
infoMessage	string		Erläuternde Nachricht vor der Übergabe
startMessage	string		Nachricht, die angezeigt wird, wenn die Live-Sitzung beginnt
endMessage	string		Nachricht, die angezeigt wird, wenn die Live-Sitzung endet
nameLabel	string		Beschriftung auf dem Namenseingabefeld im Live-Chat-Vorformular
emailLabel	string		Beschriftung auf dem E-Mail-Eingabefeld im Live-Chat-Vorformular
schedule	string	JSON-kodierter String (Wochentags-Schalter + from/to + timezone)	Betriebszeiten für Live-Chat - die genaue Struktur finden Sie unter "Strukturierte Felder und Wertebereiche"
outOfHoursMessage	string		Nachricht, die angezeigt wird, wenn die Betriebszeiten besagen, dass wir nicht erreichbar sind
closeModalMessage	string		Titel des Modalfensters "Live-Chat schließen?"
closeModalConfirmLabel	string		Beschriftung der Bestätigungsschaltfläche im Schließen-Modalfenster
closeModalCancelLabel	string		Beschriftung der Abbrechen-Schaltfläche im Schließen-Modalfenster
closeModalTooltipText	string		Tooltip auf dem Bedienelement zum Schließen des Chats
operatorHasJoinedLabel	string		Angezeigte Beschriftung, wenn ein Operator beitritt
operatorDidNotJoinInTimeLabel	string		Angezeigte Beschriftung, wenn innerhalb des Timeouts kein Operator beitritt
waitingForOperatorToJoinLabel	string		Angezeigte Beschriftung während des Wartens auf einen Operator
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, wenn kein Operator annimmt
requireAdminOnline	boolean		Erfordert einen verfügbaren Operator gemäß den Anwesenheitseinstellungen
presenceMode	string		Anwesenheitsmodus; verwenden Sie den Wert eines in der Benutzeroberfläche konfigurierten Bots
hideHumanSupportWhenLiveChatAvailable	boolean		Kontaktformular ausblenden, wenn Live-Chat verfügbar ist
missedEmailEnabled	boolean	Standard true	E-Mail an den Bot-Eigentümer senden, wenn eine Live-Chat-Anfrage unbeantwortet blieb. Bei älteren Bots nicht gesetzt, was als aktiviert interpretiert wird

requirePolicyAccept befindet sich in consent.liveChatRequirePolicyAccept, nicht hier.

§ consent

Feld	Typ	Einschränkung	Beschreibung
newConversationRequirePolicyAccept	boolean		Zustimmung zur Datenschutzerklärung vor dem Start 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 dem Start 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 normalerweise 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 Footer-Logo verlinkt
assignToCustomDomain	boolean	beschränkt durch Feature 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-Teil whitelabel_logo hochladen

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

§ security

Feld	Typ	Einschränkung	Beschreibung
allowedDomains	string		Kommagetrennte Liste von Domains, die das Widget einbetten dürfen (leer = keine Whitelist)
spamFilterEnabled	boolean		Den botspezifischen Spam-Filter für eingehende Nachrichten aktivieren
countryFilterMode	string	BLACKLIST oder WHITELIST	Wie die Länderlisten interpretiert werden. Die Listen selbst bleiben administratorenexklusiv
talkMessagesRateLimit	int	>= 0; 0 deaktiviert	Maximal zulässige Benutzernachrichten im Rate-Limit-Zeitfenster
talkMessagesRateLimitDurationSeconds	int	>= 0	Dauer des Rate-Limit-Zeitfensters (Sekunden)
talkMessagesRateLimitHitMessage	string		Nachricht, die dem Besucher angezeigt wird, wenn das Rate-Limit erreicht ist

§ 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 Stimmen-ID (z. B. alloy)	Welche synthetische Stimme spricht
model	string	z. B. GPT-REALTIME-MINI, GEMINI-LIVE, ELEVENLABS-*	Sprachmodell. Abrechnung pro Minute, Tarife variieren je nach Modell
turnDetection	string	anbieterspezifisch	Modus für den Gesprächswechsel (Turn-Taking)
audioPrompt	string		Zusätzlicher System-Prompt, der nur für Sprachbeiträge verwendet wird
welcomeMessage	string		Gesprochener Einstiegssatz
language	string	Sprachcode	Primäre Sprachausgabe-Sprache
additionalLanguages	string	kommagetrennte Sprachcodes	Zusätzliche Sprachen, die der Sprachagent akzeptiert
maxDurationSeconds	int		Feste Obergrenze für eine einzelne Sprachunterhaltung
maxDurationMessage	string		Angezeigte Nachricht, wenn die Obergrenze erreicht ist

§ multilingual

Feld	Typ	Einschränkung	Beschreibung
enabled	boolean		Umschalter für den mehrsprachigen Modus
mode	string	AUTODETECT oder FIXED_LIST	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	NONE, MAIN oder DYNAMIC	Wie Wissen in anderen Sprachen behandelt wird
knowledgeLanguageFallback	string	Sprachcode	Verwendete Sprache, wenn keine Übereinstimmung gefunden wird

§ advanced

Feld	Typ	Einschränkung	Beschreibung
model	string	unterliegt Kontolimits; siehe "KI-Textmodelle" oben	LLM-Kennung (z. B. 5.6-LUNA)
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	Konfiguriertes Kontextbudget, einschließlich Anweisungen, Historie und Wissen
botMessagesLimit	long	0 oder Vielfaches von 1000 (z. B. 1000, 2000, 10000)	Monatliche Message-Credits-Obergrenze des Bots (0 = keine zusätzliche Bot-Obergrenze; Kontobudget gilt weiterhin)
internalLocale	string	Gebietsschema-Code in der Form ll_CC	Gebietsschema für Beschriftungen der Widget-Bedienelemente (unterscheidet sich von role.language)
productsViewEnabled	boolean		Wenn true, werden die Offer Cards für den E-Commerce im Chat angezeigt
includeProductsInKnowledgeBase	boolean		Wenn true, wird der Produktkatalog als Teil der Wissensdatenbank indexiert

Außerhalb des API-Bereichs

Die Admin-UI bietet einige Bereiche, die in dieser Version der Management API absichtlich nicht offengelegt werden:

• Training und Löschung - Diese Endpunkte listen nicht alle Bots auf, verwalten keine Trainingsdatensätze und löschen keine Bots. Verwenden Sie die App für diese Arbeitsabläufe.
• Tab "Flow" - Der visuelle Conversation Flow-Editor (Stufen und Übergänge). Nicht über die Management API zugänglich.
• Tab "Actions" - Verwaltete Integrationen für E-Commerce / Buchungen, AI Search und benutzerdefinierte API-Funktionen. Das Aufrufen von Tools gehörte noch nie zur Management API.
• Der benutzerdefinierte Formular-Builder selbst - Das Erstellen und Bearbeiten benutzerdefinierter Formulare ist nicht offengelegt. Sie können jedoch über leadCollection.customFormId und humanSupport.customFormId ein vorhandenes Formular an einen Bot anhängen.
• Benutzerdefinierte Icons zum Öffnen / Schließen des Chats - customLauncherIconVisible, openChatIcon, closeChatIcon. Die API legt nur die Haupt-Multipart-Teile avatar und whitelabel_logo offen.
• IP- und Länderlisten - Die Einträge selbst sind ausschließlich für Administratoren bestimmt. Nur der Interpretationsmodus wird über security.countryFilterMode offengelegt.

Endpunkte

POST /v1/management/bots

Erstellen Sie einen neuen Bot. Es werden zwei gleichwertige Content-Types akzeptiert; wählen Sie die für Sie bequemere Variante.

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

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

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

• 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) - Bot-Avatar-Bild
• whitelabel_logo-Dateiteil (optional) - White-Label-Logo (gilt nur, wenn Ihr Konto White Label beinhaltet)

Im JSON ist nur name erforderlich; jedes andere Feld fällt auf denselben Standardwert zurück, den auch der Einrichtungsassistent in der Admin-Benutzeroberfläche festlegen würde.

Beispiel für einen Request-Body

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

{
  "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.6-LUNA",
    "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; welcher Kanal auch immer aktiv ist, erfordert zusätzlich sein Label sowie leaveDetailsMessage und thankYouMessage
• advanced.chatContextSize wird auf die vom Konto maximal unterstützte Kontextgröße begrenzt. Gehen Sie nicht davon aus, dass andere numerische Felder automatisch begrenzt werden.

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

Beispiel für einen Response-Body (201)

Gleiche Struktur wie der Request, zuzüglich des schreibgeschützten meta-Blocks und des einmaligen apiKey auf der obersten Ebene. Schreibgeschützte Datei-URLs (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) werden vom Server ausgefü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.6-LUNA",
    "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 beim Erstellen - es ist der frisch 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 unkompliziertesten):

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

Beispiel für einen Response-Body (200)

Gleiche Struktur wie die POST-Antwort, abzüglich des einmaligen apiKey. Der Block meta 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 (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) bereitgestellt - basierend auf demselben Schema + Host + Kontextpfad, der diesen Request bedient hat. Rufen Sie die Bytes ab, indem Sie diese URLs direkt per GET anfragen; um eine der Dateien zu ersetzen, laden Sie über den Multipart-Teil avatar / whitelabel_logo bei PATCH eine neue Datei hoch. Diese URL-Felder werden ignoriert, wenn sie in einem Request-Body gesendet 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.6-LUNA",
    "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, sodass das Klonen in drei Schritten abläuft: Rufen Sie die Quelle per GET ab, entfernen Sie die vom Server verwalteten Identitätsfelder und senden Sie das Ergebnis per POST.

1. Rufen Sie den Quell-Bot per GET ab.

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

2. Entfernen Sie den übergeordneten meta-Block. Das meta-Objekt (id, createdAt, updatedAt) ist serververwaltet und schreibgeschützt - wenn Sie es im POST-Body belassen, schadet dies nicht (der Server ignoriert es), aber das Entfernen macht die Absicht eindeutig und hält die Payload sauber. Bearbeiten Sie optional name, damit sich der Klon von der Quelle unterscheidet.

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

3. Senden Sie den bereinigten Body per POST, um den Klon zu erstellen. Siehe die obige POST /v1/management/bots-Referenz für die vollständige Body-Struktur und Validierungsregeln.

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 erstellten apiKey (den Bot-Talk-Schlüssel für den Klon). Der Klartext von 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.

Dadurch werden unterstützte Einstellungen kopiert, kein vollständig trainierter Chatbot. Trainingsinhalte, Chat-Verlauf, Integrationen/Aktionen, Flow und Formulardefinitionen werden von diesen Endpunkten nicht geklont. Konfigurieren Sie diese separat in der App.

Zusätzliche 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 auf dem 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 bei einem nachfolgenden PATCH.
• Bot-Talk-Schlüssel werden nicht geklont. Jeder Bot verfügt über einen eigenen Pool von Bot-Talk-Schlüsseln. Der einzelne apiKey, der durch den Erstellungs-POST zurückgegeben wird, ist der einzige, der automatisch generiert wird; erstellen Sie bei Bedarf zusätzliche Schlüssel auf dem API-Tab des Bots.

PATCH /v1/management/bots/{bot_id}

Aktualisieren Sie ein oder mehrere Felder eines Bots, den Sie besitzen. Es werden nur Abschnitte / Felder geändert, die im JSON vorhanden sind; alles, was weggelassen (oder als null gesendet) wird, bleibt unberührt. Für jedes gesendete Feld innerhalb eines Abschnitts gelten Semantiken für partielle Aktualisierungen.

Zwei gleichwertige Content-Types werden 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) - Avatar ersetzen
• whitelabel_logo-Datei-Part (optional) - White-Label-Logo ersetzen (gilt nur, wenn Ihr Konto White Label beinhaltet)

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

Beispiel-Request-Body (mehrere Abschnitte)

Jedes von POST /v1/management/bots akzeptierte Feld kann auch hier gesendet werden. Das folgende Beispiel veranschaulicht mehrere Abschnitte, nicht jedes unterstützte Feld; in der Praxis senden Sie nur die Schlüssel, die Sie ändern möchten (siehe „Minimale partielle Aktualisierung“ weiter unten) - jeder weggelassene (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
  }
}

Minimale partielle Aktualisierung

Führen Sie einen PATCH für ein einzelnes Feld durch, indem Sie genau die Schlüssel senden, die Sie geändert haben 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)

Dieselbe Struktur wie 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 (mehrere Abschnitte) auf den Bot aus dem GET-Beispiel - geänderte Felder spiegeln die neuen Werte wider, unberührte Felder bleiben erhalten und meta.updatedAt wird auf den neuen Aktualisierungszeitpunkt gesetzt.

{
  "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

Aktuelle Abonnement-Nutzung für das Konto abrufen, dem der Management-Schlüssel gehört.

Response-Body (200)

{
  "subscriptionType": "your-plan-id",
  "messages": {"used": 4123, "limit": 11000, "remaining": 6877},
  "bots": {"used": 3, "limit": 5, "remaining": 2}
}

• subscriptionType ist eine kleingeschriebene Kennung des aktuellen Plans des Kontos (your-plan-id ist ein anschaulicher Platzhalter). Pläne stammen aus einem dynamischen Katalog, sodass sich die genaue Gruppe von Kennungen im Laufe der Zeit ändern kann, wenn Pläne umbenannt oder hinzugefügt werden - behandeln Sie dies als intransparenten String, nicht als festes Enum.
• messages.used / limit / remaining sind die Message-Credits des aktuellen Kalendermonats, die am ersten Tag des Monats zurückgesetzt werden, nicht am Tag der Abonnementverlängerung. Sie sind nach Credits gewichtet, keine reinen Antwortanzahlen.
• bots.used / limit / remaining zählen eigene Bots, einschließlich pausierter Bots, im Rahmen des Gesamt-Bot-Limits 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.