Management API

Management API áttekintés

A Management API a háttérmunkákhoz (back-office) használható, amelyek nem járnak csevegési üzenetek küldésével:

• bot programozott létrehozása a POST /v1/management/bots használatával
• egy Ön által birtokolt adott bot adatainak lekérése a GET /v1/management/bots/{bot_id} használatával
• egy adott bot frissítése a PATCH /v1/management/bots/{bot_id} használatával
• az előfizetés felhasználásának lekérése a GET /v1/usage használatával

A Management kulcsok az Ön fiókjához kapcsolódnak, nem egy konkrét bothoz. Szándékosan el vannak különítve a Bot Talk kulcsoktól, így egy kompromittálódott csevegési kulccsal nem lehet módosítani a botjait, sem elolvasni a számlázási adatait.

Alap URL

https://api.chatlab.com/aichat

A jelen cikkben szereplő összes végpont ehhez az alap URL-hez viszonyítva értendő.

Első lépések

1. Nyissa meg az adminisztrációs alkalmazást, és lépjen az Account Settings > Management API (Fiókbeállítások > Management API) menüpontra.
2. Kattintson a Create Management Key (Management kulcs létrehozása) gombra, nevezze el, szükség esetén adjon meg IP-engedélyezési listát és sebességkorlátot (rate limit), majd küldje el az űrlapot.
3. Csak azokat a jogosultságokat válassza ki, amelyekre az integrációjának szüksége van, majd másolja ki a teljes kulcsot a sikeres műveletet jelző felugró ablakból. Az egyszerű szöveges formátum csak egyszer jelenik meg.
4. A kulcsot a szerverén tárolja, ne böngészőoldali kódban vagy nyilvános kódtárban. A hozzáférés ellenőrzéséhez indítson egy csak olvasható kérést, például a GET /v1/usage végpontra a usage jogosultság használatával.
5. A nem használt vagy kompromittálódott kulcsokat vonja vissza a Management API oldalon.

A kulcs formátuma a következőre hasonlít: mk_abcdefghijklmnopqrstuvwxyz012345. Az mk_ előtag különbözteti meg a Bot Talk kulcsoktól (ck_).

Hitelesítés

Authorization: Bearer mk_abcdefghijklmnopqrstuvwxyz012345

Ha egy mk_ kulcsot küld a /v1/chat (vagy bármely más Bot Talk) végpontra, a rendszer 403 key_type_not_allowed hibát ad vissza. Ha egy ck_ kulcsot küld a /v1/management/* végpontra, az ugyanezt a hibát eredményezi.

Korlátok

• Felhasználónként legfeljebb 5 aktív Management API kulcs
• Kulcsonként legfeljebb 10 kérés percenként (token bucket algoritmus, 10-es kapacitás, egyenletes újratöltés kb. 6 másodpercenként 1 tokennel). Létrehozáskor lefelé konfigurálható - állítson be alacsonyabb rateLimitPerMinute értéket, és a felső korlát csökken, az újratöltési sebesség pedig ezzel arányosan változik.

Jogosultságok

Minden egyes Management kulcs az alábbi három jogosultság bármely részhalmazával rendelkezhet. Létrehozáskor legalább egyet ki kell választani, különben a kérés elutasításra kerül 400 invalid_request_error hibával. Ha egy végpontot olyan kulccsal hív meg, amelyből hiányzik a szükséges jogosultság, a válasz 403 insufficient_permissions lesz.

• bot_read - szükséges a GET /v1/management/bots/{bot_id} híváshoz
• bot_management - szükséges a POST /v1/management/bots és a PATCH /v1/management/bots/{bot_id} híváshoz
• usage - szükséges a GET /v1/usage híváshoz

Törzs struktúrája: az admin felület lapjait tükröző beágyazott szakaszok

A POST és a PATCH kérések egy 13 szakaszra osztott JSON törzset fogadnak el. Mindegyik szakasz az adminisztrációs alkalmazás Bot Settings oldalsávjának egy-egy allapjának felel meg, így a JSON-kulcsok és a látható lapok egymáshoz igazodnak: ha API-n keresztül módosítja a consent.humanSupportRequirePolicyAccept értékét, ugyanez a kapcsoló fog átváltani a Consent & Privacy (Hozzájárulás és adatvédelem) lapon az admin felületen.

• role - bot személyisége, nyers prompt, válaszhossz, nyelv, webhely / vállalati kontextus (Role & Behavior lap)
• conversation - üdvözlő üzenet, lekérdezés pontosítása, beszélgetés folytonossága, értékelés kapcsolója + elemleírások, javasolt kérdések tartalma + dinamikus folytatások (Chat Conversation lap)
• chatMemory - csevegési memória kapcsolója, összefoglaló promptok, kontextusallokáció (Summaries & Memory lap)
• appearance - színek, szövegek, méretek, egyéni CSS, üdvözlőképernyő, javasolt kérdések stílusa, automatikus megnyitás viselkedése, emberi gépelés szimulációja, lábléc markdown (Appearance lap)
• humanSupport - emberi kapcsolatfelvételi űrlap (Human Contact Form lap)
• leadCollection - leadgyűjtő űrlap (Lead Collection lap)
• liveChat - átadás élő chatnek (Live Chat lap)
• consent - mind a négy adatvédelmi hozzájárulási kapcsoló, valamint a hozzájárulási képernyő szövege (Consent & Privacy lap)
• whiteLabel - logó elrejtése, egyéni logó hivatkozása, egyéni doménes tárhely (Whitelabel lap)
• security - engedélyezett domének, spamszűrő, beszélgetési sebességkorlátok (Security lap)
• voice - hangbevitel és hangalapú beszélgetések: modell, hang, nyelvek, prompt, időtartamkorlát (Voice Conversation lap)
• multilingual - többnyelvű mód, alapnyelv, felkínált nyelvek, tudásbázis nyelvének kezelése (Languages lap)
• advanced - LLM modell, hőmérséklet (temperature), kontextusméret, bot üzenetkorlátja, belső területi beállítás (internal locale), Offer Cards (Model & Advanced lap)

Az írható beállítások közül egyedül a name található a legfelső szinten, mivel ez a botot azonosítja, és nem tartozik egyik konkrét laphoz sem.

A Bot Settings oldalsáv jelenleg 16 allappal rendelkezik, és ezek közül 13 felel meg a fenti szakaszoknak. A három olyan allap, amelyhez nem tartozik megfelelő szakasz: a Flow, az Actions és a Forms - mindháromra kitérünk az alábbi "API hatókörén kívül eső elemek" részben. A 13 lefedett lap: Appearance, Chat Conversation, Role & Behavior, Human Contact Form, Lead Collection, Live Chat, Whitelabel, Consent & Privacy, Security, Model & Advanced, Summaries & Memory, Voice Conversation és Languages.

A kéréstörzs és a választörzs struktúrája megegyezik. A válasz két extra elemet tartalmaz:

• meta - csak olvasható: bot azonosítója és időbélyegek. Ennek eltávolításával a GET válasz érvényes POST törzzsé alakítható.
• apiKey - kizárólag létrehozáskor van jelen - az új bot újonnan generált Bot Talk API kulcsa.

A megosztott struktúrán belül két mező csak olvasható - megjelenik a válaszban, de a rendszer figyelmen kívül hagyja őket, ha a POST/PATCH kérésben próbálja elküldeni őket:

• appearance.avatarUrl - a bot avatárképének teljes, nyilvános URL-je (pl. https://api.chatlab.com/aichat/content/avatar_xyz.png). Közvetlen GET kéréssel tölthetők le a bájtok. Módosításához töltsön fel egy új fájlt a többrészes avatar részen keresztül (lásd a PATCH részt).
• whiteLabel.whitelabelLogoUrl - a White Label fejléclogó teljes, nyilvános URL-je. Ugyanaz a minta, mint az avatarUrl esetében. Módosításához töltsön fel egy új fájlt a többrészes whitelabel_logo részen keresztül (lásd a PATCH részt).

Mindkét URL az aktuális kérés protokollját + hosztját + környezeti elérési útját (context path) használja, így egy White Label egyéni doménen az adott domén gyökerével térnek vissza (pl. https://api.acme.com/aichat/content/...).

Egy szakasz kihagyásához a PATCH során küldjön null értéket; egy szakaszon belüli mező kihagyásához küldjön null értéket az adott mezőre. A mezőszintű null soha nem törli a tárolt értéket - csupán annyit jelent: "ne nyúlj hozzá".

Szerepkör és prompt összeállítása

Az LLM által ténylegesen megkapott rendszerprompt a role.role értékétől függően a két módszer egyikével épül fel. Ha tisztában van azzal, melyik ágon van, tudni fogja, mely mezők számítanak, és melyek azok, amelyeket a rendszer eltárol, de figyelmen kívül hagy.

A ág - a role.role értéke CUSTOMER_SUPPORT, SALES vagy LEAD_COLLECTION_AGENT (sablon alapú)

A háttérrendszer egy beépített sablonból állítja össze a promptot, és a role.rawPrompt értékét teljesen figyelmen kívül hagyja (az érték továbbra is el lesz mentve a botnál, csak nem kerül felhasználásra). A sablon a következőket tartalmazza:

• role.role - a szerepkör címkéje (pl. "Customer Support") és az automatikusan hozzáfűzött szerepkör-specifikus utasítások
• name - a bot neve, beillesztve a kezdő mondatba
• role.language - az "Auto Detect" beállítás hatására a bot a felhasználó nyelvét követi; minden más érték (pl. "English", "Polish") a következő formát ölti: "Output in {language}, unless user uses another language"
• role.responseLength - célzott szószámhoz rendelve: Concise ≈ 50 szó, Normal ≈ 100, Detailed ≈ 200
• role.websiteAddress - opcionális; ha nem üres, a következő formában kerül hozzáfűzésre: "for the users of the website {url}"
• role.companyDescription - opcionális; ha nem üres, egy extra bekezdésként kerül beszúrásra a szerepkörre vonatkozó utasítások elé

A legtöbb bot esetében ez az ajánlott ág - a szerepkörre finomhangolt viselkedést és biztonsági korlátokat kap automatikusan.

B ág - a role.role értéke CUSTOM (hívó által megadott prompt)

A háttérrendszer a role.rawPrompt mezőt használja szerepkör-promptként, és hozzáfűzi a platform rögzített válaszhossz-útmutatását. Ez független a role.responseLength mezőtől: az opcionális Concise/Normal/Detailed beállítás nem kerül beillesztésre CUSTOM szerepkör esetén. Hasonlóképpen a language, a websiteAddress és a companyDescription értékek elmentésre kerülnek, de nem kerülnek beillesztésre ebbe a szerepkör-promptba. A kívánt nyelvet, célzott válaszhosszt vagy vállalati kontextust saját kezűleg kell belefoglalnia a rawPrompt szövegébe. További futásidejű utasítások és lekért kontextus is hozzáadható, így nem a rawPrompt jelenti a modell teljes bemenetét. Az előre meghatározott szerepkör hangnemre vonatkozó utasításai nem adódnak hozzá, de a CUSTOM kiválasztása nem távolítja el az összes platformutasítást.

Csak akkor használja a CUSTOM értéket, ha a sablon alapú prompt nem felel meg a használati esetének (pl. kifejezetten szakterület-specifikus személyiségre, saját biztonsági megkötésekre vagy nem szabványos kimeneti formátumra van szüksége).

Enum / zárt készletű mezők

Az enum és megkötésekkel rendelkező mezők érvénytelen értékek esetén 400 invalid_parameter hibával elutasításra kerülnek. Más mezők egyszerű karakterláncok, még akkor is, ha a kezelőfelület rögzített listát kínál. Használja a dokumentált írásmódot, és érvényesítse az adatcsomagot ahelyett, hogy feltételezné: minden nem támogatott karakterlánc elutasításra kerül.

• role.role - CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM
• role.responseLength - Concise, Normal, Detailed
• role.language - teljes angol nyelvnév az admin felület legördülő menüjéből, pl. Auto Detect, English, Polish, Spanish, German, French, Italian, Portuguese, Dutch, Russian, Chinese (Simplified), Japanese, Arabic, Hindi és még kb. 80 egyéb. Az érték szó szerint kerül tárolásra és behelyettesítésre a promptsablonba, így a kétbetűs ISO-kódokat (en, pl) és a listán kívüli egyéb értékeket az API nem utasítja el, de olyan zagyva utasítást eredményeznek, mint az "Output in en, unless...". Létrehozáskor elhagyva az alapértelmezett érték Auto Detect.
• advanced.model - lásd az alábbi "Szöveges AI modellek" részt. Ez egy karakterlánc, nem pedig egy validált enum a kéréssémában; támogatott értéket használjon, ne tetszőleges modellnevet.
• advanced.chatContextSize - a kezelőfelülethez igazodva a következő értékeket használja: 8000, 16000 vagy 32000. A fiók maximális értéke feletti értékek csendben levágásra kerülnek; a DTO nem kényszeríti ki ezt a háromértékű készletet.
• chatMemory.clientSummaryPromptType - DEFAULT, CUSTOM
• chatMemory.conversationSummaryPromptType - DEFAULT, CUSTOM
• appearance.chatAlignment - left, right
• appearance.minimizedDisplayMode - icon, minified, pill
• appearance.chatMessageLinkTarget - _blank, _self
• leadCollection.requireBeforeNewConversation - logikai kapcsoló. A true érték arra kényszeríti a felhasználót, hogy kitöltse a leadgyűjtő űrlapot a beszélgetés megkezdése előtt; a false érték az AI-ra bízza, mikor jelenítse meg az űrlapot (alapértelmezett).

Strukturált mezők és tartományok

Olyan mezők, amelyek egyszerű karakterláncnak vagy számnak tűnnek, de valójában sajátos formátumuk, tartományuk vagy adminisztrációs felületi sajátosságuk van, amelyeket érdemes ismerni.

• advanced.temperature - az elfogadott tartomány 0.0 és 1.0 között van, igazodva az adminisztrációs felület csúszkájához. Az ezen a tartományon kívüli értékek elutasításra kerülnek 400 invalid_parameter hibával.

• chatMemory.summariesToKnowledgeRatio - egész szám százalékban, 10-90; a kezelőfelület 10-es lépésközt használ, de az API a teljes tartományban elfogad egész számokat. Alapértelmezett érték: 50. Bekapcsolt memória és 8k-nál nagyobb kontextus esetén a prompt/legutóbbi beszélgetések számára fenntartott rész után fennmaradó tudásbázis- és memóriakeretet osztja fel, nem a modell teljes kontextusát. 8k méretnél ez a beállítás nem különít el összefoglaló keretet.

• liveChat.schedule - karakterláncként kódolt JSON, nem pedig egy beágyazott JSON objektum a hálózati adatforgalomban. A szerver szó szerint tárolja a nyers karakterláncot; az adminisztrációs felület a kliensoldalon elemzi azt a menetrendszerkesztő megjelenítésekor. Az elemzést követően a karakterlánc felépítése: hétköznaponként egy bejegyzés, plusz egy timezone kulcs:

  • minden hétköznap kulcs (monday-sunday) a következőre képeződik le: {enabled: boolean, from: "H:MM", to: "H:MM"} 24 órás formátumban
  • a timezone egy IANA zónanév (pl. "Europe/Warsaw", "America/New_York")

  Példaérték (figyelje meg a külső idézőjeleket és a feloldott belső idézőjeleket - ez egyetlen string mező, nem egy beágyazott objektum):

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

  A megadott órákon kívül a látogatónak a liveChat.outOfHoursMessage üzenet jelenik meg, és az élő chatnek történő átadás letiltásra kerül. A belső struktúra érvényesítése csak kliensoldalon fut le az admin felületen - a hibás formátumú JSON-t vagy az ismeretlen kulcsokat az API sima karakterláncként elfogadja, és megjelenítési hibaként fog felszínre kerülni, amikor egy ember később megnyitja a botot az adminban. Küldés előtt érvényesítse a struktúrát a saját oldalán.

• conversation.positiveRatingTooltip / conversation.negativeRatingTooltip - rövid címkék, amelyek a 👍 / 👎 beszélgetésértékelő vezérlőkön jelennek meg, ha conversation.conversationRatingEnabled=true. Az alapértelmezett szöveg: "I like the response" / "I don't like the response". Látható a végfelhasználók számára.

• whiteLabel.hideRoboAssistLogo - White Label funkció, a fiókja korlátaitól függően. Elrejti a "Powered by ChatLab" láblécet. Ha fiókja nem tartalmazza a White Label lehetőséget, az érték elmentésre kerül, de a rendszer figyelmen kívül hagyja, és a lábléc mindig megjelenik.

• whiteLabel.whitelabelLogoLink - White Label funkció, a fiókja korlátaitól függően. Kattintási cél URL az egyéni logóhoz, ha hideRoboAssistLogo=true, és egy egyéni logófájl van feltöltve a whitelabel_logo többrészes részen keresztül.

• appearance.simulateHumanTypingDelay - másodperc (nem ezredmásodperc), egész szám 0-200. Szünet az egymást követő bot-üzenetbuborékok között, ha simulateHumanTyping=true. Alapértelmezett érték: 5.

• appearance.autoOpenChatDelaySeconds - másodperc, egész szám. Késleltetés a widget automatikus megnyitása előtt, ha autoOpenChat=true és autoOpenChatDelay=true.

• advanced.internalLocale - IETF területi-régiókód ll_CC formátumban (alsóvonás, NEM ll-CC kötőjellel). Az elfogadott értékek egy kb. 95 területi beállítást tartalmazó rögzített listából származnak: 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 és még sok más. Egyedül kétbetűs kód ("en") vagy BCP-47 ("en-US") küldése nem szerepel az engedélyezett listán. Alapértelmezett: en_US. Ez a widget keretében a dátum-/számformázáshoz használt területi beállítás, amely eltér a role.language értéktől (a bot beszélgetési kimeneti nyelvétől).

• security.talkMessagesRateLimit / security.talkMessagesRateLimitDurationSeconds - egész számok (JSON számként küldendők, pl. 30, nem pedig "30"). Állítsa az üzenetkorlátot 0 értékre ezen munkamenet-alapú korlát kikapcsolásához. Bekapcsolásakor adjon meg egy pozitív időtartamot. A háttérrendszer másodpercben megadott időtartamonként és munkamenetenként N üzenetet kényszerít ki, mielőtt megjelenítené a látogatónak a security.talkMessagesRateLimitHitMessage üzenetet.

• advanced.botMessagesLimit - egész szám (JSON szám, pl. 1000). A 0 azt jelenti, hogy nincs további botonkénti korlát, miközben a fiók kreditkerete továbbra is érvényes; ellenkező esetben 1000 többszörösének kell lennie (1000, 2000, 10000, ...). Az olyan értékek, mint a 100 vagy az 1500, elutasításra kerülnek 400 invalid_parameter hibával. Ez egy havi botkredit-korlát, nem pedig beszélgetésenkénti üzenetszám. A leképező nem vágja le ezt az értéket a fiókkeretre; a fiók kerete továbbra is korlátozza a tényleges használatot.

Szöveges AI modellek (advanced.model)

Használja pontosan azt a modellazonosítót, amely az advanced.model mezőben tér vissza, amikor a kívánt modellel konfigurált botot olvassa be a Settings > Model & Advanced menüpontban. A jelenlegi alapértelmezett érték létrehozáskor: 5.6-LUNA. Az azonosítók érzékenyek a kis- és nagybetűkre, és eltérnek a megjelenített nevektől; például a 5.6-LUNA a felületen GPT 5.6-luna néven jelenik meg.

A modellkatalógus idővel változik. Ne vonja le azt a következtetést, hogy egy tetszőleges karakterlánc vagy egy szolgáltató nyilvános modellazonosítója támogatott pusztán azért, mert a kérésséma elfogad egy karakterláncot. Olvassa vissza a mentett konfigurációt, és tesztelje az eredményül kapott chatbotot a telepítés előtt.

Mezőreferencia (teljes kérelemséma)

A támogatott szakaszok és mezők típusukkal és fontos korlátozásaikkal. PATCH szemantika: a kihagyott (vagy null értékként elküldött) mezők érintetlenül hagyják a tárolt értéket. Ugyanez a struktúra vonatkozik a válaszra is (a többrészes bináris tartalom kivételével; kiegészülve az írásvédett meta blokkal minden válaszban, valamint az apiKey mezővel kizárólag a létrehozási válaszban).

Felső szint

Mező	Típus	Megkötés	Leírás
name	string	max. 150, létrehozáskor kötelező	A bot megjelenített neve
role	object		Lásd: § role
conversation	object		Lásd: § conversation
chatMemory	object		Lásd: § chatMemory
appearance	object		Lásd: § appearance
humanSupport	object		Lásd: § humanSupport
leadCollection	object		Lásd: § leadCollection
liveChat	object		Lásd: § liveChat
consent	object		Lásd: § consent
whiteLabel	object		Lásd: § whiteLabel
security	object		Lásd: § security
advanced	object		Lásd: § advanced

Csak a válaszban szereplő kiegészítések:

• meta: { id, createdAt, updatedAt } - írásvédett.
• apiKey - string, kizárólag a POST /v1/management/bots válaszában van jelen - az újonnan generált Bot Talk kulcs az új bothoz, amely pontosan egyszer kerül visszaadásra.

§ role

Mező	Típus	Megkötés	Leírás
role	string (enum)	CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM	Személyiség-előbeállítás; kiválasztja a promptsablont (lásd: "Role and prompt construction")
language	string	a nyelv teljes angol neve (English, Polish, ...) vagy Auto Detect	A promptsablonba bemenő elsődleges nyelv
responseLength	string	∈ {Concise, Normal, Detailed}	A kívánt AI-válasz részletessége
websiteAddress	string		A prompt kontextusaként használt webhely
companyDescription	string		A prompt kontextusaként használt cégleírás
rawPrompt	string		Egyéni rendszerprompt - szó szerint csak akkor használatos, ha role=CUSTOM

§ conversation

Mező	Típus	Megkötés	Leírás
welcomeMessage	string		A látogatónak megnyitáskor megjelenített első üzenet
queryRefinementEnabled	boolean		Ha igaz, pontosítja a látogató kérdését a RAG-lekérés előtt
conversationContinuityEnabled	boolean		Ha igaz, a visszatérő látogatók ott folytatják a beszélgetést, ahol legutóbb abbahagyták
conversationRatingEnabled	boolean		Ha igaz, megjeleníti a beszélgetést értékelő hüvelykujj fel/le vezérlőket
positiveRatingTooltip	string		Eszköztipp a pozitív értékelés gombon
negativeRatingTooltip	string		Eszköztipp a negatív értékelés gombon
suggestedQuestions	string		Új sorokkal elválasztott javasolt kérdések / beszélgetésindítók
dynamicSuggestedFollowups	boolean		Ha igaz, az AI minden válasz után javasolt folytató kérdéseket ajánl fel
positiveRatingMessage	string		Pozitív visszajelzés után megjelenített üzenet
negativeRatingMessage	string		Negatív visszajelzés után megjelenített üzenet
hideSuggestedQuestionsAfterFirstUse	boolean		A statikus javaslatok elrejtése használat után
dynamicFollowupsAutoIcons	boolean		Ha igaz, az AI automatikusan emojikat választ a dinamikus folytató javaslatokhoz

§ chatMemory

Mező	Típus	Megkötés	Leírás
enabled	boolean		Főkapcsoló a chatmemória funkcióhoz
summaryConversationsEnabled	boolean		Beszélgetésenkénti összefoglalók megőrzése
conversationSummaryPrompt	string		Egyéni prompt az egyes beszélgetések összefoglalásához
conversationSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Az alapértelmezett vagy az egyéni összefoglaló prompt használata
clientSummaryPrompt	string		Egyéni prompt az ügyfél beszélgetéseken átívelő profiljának összefoglalásához
clientSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Alapértelmezett kontra egyéni ügyfélprofil-prompt
summariesToKnowledgeRatio	int	10-90 (felületi lépték: 10)	A rendelkezésre álló tudásbázis-/memóriakeret hány százaléka jut az összefoglalókra 8k feletti kontextusoknál

§ appearance

Mező	Típus	Megkötés	Leírás
launcherLabelLine1	string	max. 60	Az indítógomb szövegének első sora
launcherLabelLine2	string	max. 60	Az indítógomb szövegének második sora
launcherTextColor	string		Az indítógomb szövegszíne
launcherDismissEnabled	boolean		Az indítógomb elvetésének engedélyezése
widgetFontFamily	string	inter, system, nunito, lato, montserrat, poppins, source-serif, jetbrains-mono	A widget betűcsaládja
chatDrawerEnabled	boolean		Oldalsávos (drawer) megjelenítés bekapcsolása
launcherColor	string (hex)		Az indítógomb (chat ikon) háttérszíne
headerColor	string (hex)		A chat fejlécének háttérszíne
titleColor	string (hex)		A chat fejlécében lévő cím színe
subtitleColor	string (hex)		A chat fejlécében lévő alcím színe
clientMessageBubbleColor	string (hex)		A látogatói üzenetbuborék színe
clientMessageTextColor	string (hex)		A látogatói üzenet szövegszíne
responseMessageBubbleColor	string (hex)		A bot válaszbuborékának színe
responseMessageTextColor	string (hex)		A bot válaszának szövegszíne
chatSubheader	string		A chat címe alatt megjelenő alcím
senderPlaceholder	string		Helyőrző szöveg az üzenetbeviteli mezőben
resetConversationTooltip	string		Eszköztipp a beszélgetés visszaállítása gombon
chatAlignment	string (enum)	∈ {left, right}	A képernyő melyik oldalához igazodjon a chat
launcherBottomMargin	int	0-500	Az indítógomb távolsága az alsó széltől (px)
launcherSideMargin	int	0-500	Az indítógomb távolsága az oldalsó széltől (px)
displayShadow	boolean		Vetett árnyék a widget alatt
customCss	string		Nyers CSS, amely beillesztésre kerül a widget iframe-jébe
chatMessageLinkTarget	string (enum)	∈ {_blank, _self}	Hogyan nyíljanak meg a botüzenetekben lévő linkek
minimizedDisplayMode	string (enum)	∈ {icon, minified, pill}	Minimalizált állapot: launcher icon (indítóikon), compact sender bar (kompakt küldősáv) vagy pill (kapszula)
chatDesktopWidthPx	int		Az asztali widget szélessége
chatDesktopHeightPx	int		Az asztali widget magassága
chatMobileSizePercent	int		A mobil widget mérete a nézetablak százalékában
messageFontSize	int		Az üzenetszöveg betűmérete (px)
showChatbotBubblesDesktop	boolean		Lebegő figyelemfelkeltő buborékok megjelenítése asztali gépen
showChatbotBubblesMobile	boolean		Lebegő figyelemfelkeltő buborékok megjelenítése mobilon
chatbotBubblesDelaySeconds	int		A felugró buborékok megjelenése előtti késleltetés (másodperc)
launcherIconFullSize	boolean		Az egyéni indítóikon renderelése a keretig kifutva, belső margó nélkül
welcomeScreenEnabled	boolean		A Welcome Screen (üdvözlőképernyő) megjelenítése a közvetlen chat helyett
welcomeScreenQuestionsLabel	string		Címke az üdvözlőképernyőn megjelenő javasolt kérdések felett
welcomeScreenHideHumanContactForm	boolean		Az emberi kapcsolatfelvételi űrlap műveletének elrejtése a fejlécben, amíg a Welcome Screen látható. A látogató első üzenete után újra megjelenik. A 2026-09-02 előtt létrehozott botoknál az alapérték true
welcomeScreenHideLiveChat	boolean		A Live Chat művelet elrejtése a fejlécben, amíg a Welcome Screen látható. A látogató első üzenete után újra megjelenik. A 2026-09-02 előtt létrehozott botoknál az alapérték true
headerActionsLayout	string	ICONS vagy DROPDOWN	Hogyan jelenjen meg a Live Chat és az emberi kapcsolatfelvételi űrlap a chat fejlécében: ICONS (különálló ikonként) vagy DROPDOWN (a fejlécmenübe csoportosítva). A 2026-09-02 előtt létrehozott botoknál az alapérték ICONS
stackSuggestedQuestions	boolean		A javasolt kérdések egymás alá rendezése (a vízszintes elrendezés helyett)
suggestedQuestionsFontSize	int		A javasolt kérdések chipjeinek betűmérete (px)
suggestedQuestionsTextColor	string (hex)		A javasolt kérdések chipjeinek szövegszíne
suggestedQuestionsBackgroundColor	string (hex)		A javasolt kérdések chipjeinek háttérszíne
autoOpenChat	boolean		A chat automatikus megnyitása asztali gépen
autoOpenChatOnMobiles	boolean		A chat automatikus megnyitása mobilon
autoOpenChatDelay	boolean		Késleltetés használata az automatikus megnyitás előtt
autoOpenChatDelaySeconds	int		Automatikus megnyitási késleltetés (másodperc)
simulateHumanTyping	boolean		A bot válaszának buborékokra bontása gépelési animációval
simulateHumanTypingDelay	int	0-200	Az egyes üzenetbuborékok közötti késleltetés (másodperc)
footerMarkdown	string	max. 255	Egyéni lábléc-markdown a chat alatt
avatarUrl	string	írásvédett	A profilkép teljes nyilvános URL-címe; a módosításához a többrészes kérelem avatar részén keresztül kell feltölteni

Multipart a POST/PATCH hívásokban: avatar (fájlrész). A GET kérések és a válaszok törzse elhagyja a fájltartalmat - kizárólag az URL szerepel az adatátvitelben.

§ humanSupport

Mező	Típus	Megkötés	Leírás
enabled	boolean		A Human Support folyamat kapcsolója
email	string	kötelező (szigorú létrehozáskor), ha enabled=true	Az emberi ügyfélszolgálati e-maileket fogadó cím
dialogMessage	string		Az űrlap felett megjelenő buzdító üzenet
thankYouMessage	string		Az elküldés után megjelenő visszaigazolás
emailMessageSubjectTemplate	string		Az ügynöknek küldött e-mail tárgysablonja
emailMessageContentTemplate	string		Az ügynöknek küldött e-mail törzssablonja
emailPlaceholder	string		Helyőrző az e-mail beviteli mezőben
messagePlaceholder	string		Helyőrző az üzenet szövegterületén
emailWithConversationContent	boolean		Ha igaz, a beszélgetés leiratát is tartalmazza az e-mail törzse
customFormId	long	egy létező egyéni űrlap azonosítója	A beépített kapcsolatfelvételi űrlap lecserélése egyéni űrlapra. Létrehozáskor az elhagyása a beépített űrlapot használja; PATCH esetén a null változatlanul hagyja a jelenlegi kijelölést
customFormMapping	string	JSON-kódolású szöveg	Összerendeli az egyéni űrlap mezőit a humán ügyfélszolgálati e-mail mezőivel

A requirePolicyAccept mező a consent.humanSupportRequirePolicyAccept helyen található, nem itt.

§ leadCollection

Mező	Típus	Megkötés	Leírás
enabled	boolean		A leadgyűjtő űrlap kapcsolója
nameEnabled	boolean		Név bekérése
nameLabel	string		Címke a név beviteli mezőjén
emailEnabled	boolean		E-mail bekérése
emailLabel	string	kötelező (szigorú létrehozáskor), ha enabled=true ÉS emailEnabled=true	Címke az e-mail beviteli mezőjén
phoneEnabled	boolean		Telefonszám bekérése
phoneLabel	string	kötelező (szigorú létrehozáskor), ha enabled=true ÉS phoneEnabled=true	Címke a telefon beviteli mezőjén
leaveDetailsMessage	string	kötelező (szigorú létrehozáskor), ha enabled=true	A látogatót az adatai megadására ösztönző üzenet
thankYouMessage	string	kötelező (szigorú létrehozáskor), ha enabled=true	Az elküldés után megjelenő visszaigazolás
requireBeforeNewConversation	boolean		Ha true, az űrlapot kötelező elküldeni a beszélgetés kezdete előtt; ha false, az AI dönti el, mikor jeleníti meg az űrlapot
emailNotificationEnabled	boolean		E-mail küldése a tulajdonosnak minden egyes begyűjtött lead után
emailNotificationAddress	string		Az értesítés címzettje (alapértelmezetten a fiók e-mail-címe)
emailWithConversationContent	boolean		Ha igaz, a beszélgetés leiratát is tartalmazza az értesítés

| customFormId | long | egy létező egyéni űrlap azonosítója | A beépített leadűrlap lecserélése egyéni űrlapra. Létrehozáskor az elhagyása a beépített űrlapot használja; PATCH esetén a null változatlanul hagyja a jelenlegi kijelölést | | customFormMapping | string | JSON-kódolású szöveg | Összerendeli az egyéni űrlap mezőit a név / e-mail / telefon adatokkal |

Mezők közötti szabály szigorú létrehozáskor: az enabled=true beállítás megköveteli az emailEnabled vagy a phoneEnabled legalább egyikének bekapcsolását. A requirePolicyAccept mező a consent.leadCollectionRequirePolicyAccept helyen található, nem itt.

§ liveChat

Mező	Típus	Megkötés	Leírás
enabled	boolean		A Live Chat funkció kapcsolója
infoMessage	string		Átadás előtti tájékoztató üzenet
startMessage	string		Az élő munkamenet kezdetekor megjelenő üzenet
endMessage	string		Az élő munkamenet végén megjelenő üzenet
nameLabel	string		Címke a név beviteli mezőjén a Live Chat előűrlapján
emailLabel	string		Címke az e-mail beviteli mezőjén a Live Chat előűrlapján
schedule	string	JSON-kódolású szöveg (hétköznap-kapcsolók + from/to + timezone)	A Live Chat nyitvatartási rendje - a pontos struktúráért lásd: "Structured fields and ranges"
outOfHoursMessage	string		A munkaidőn kívül megjelenő üzenet
closeModalMessage	string		A "Live Chat bezárása?" modális ablak címe
closeModalConfirmLabel	string		Megerősítő gomb felirata a bezárási modális ablakban
closeModalCancelLabel	string		Mégse gomb felirata a bezárási modális ablakban
closeModalTooltipText	string		Eszköztipp a chat bezárására szolgáló gombon
operatorHasJoinedLabel	string		Címke, amely akkor jelenik meg, ha egy operátor csatlakozik
operatorDidNotJoinInTimeLabel	string		Címke, amely akkor jelenik meg, ha nem csatlakozik operátor az időkorláton belül
waitingForOperatorToJoinLabel	string		Az operátorra való várakozás közben megjelenő címke
waitingForOperatorSeconds	int		Az operátor válaszára szabott időkorlát (másodperc)
redirectToHumanSupportForm	boolean		Ha igaz, átirányít a Human Support űrlapra, ha egyetlen operátor sem fogadja a hívást
requireAdminOnline	boolean		Elérhető operátor megkövetelése a jelenléti beállításoknak megfelelően
presenceMode	string		Jelenléti mód; használja a felületen konfigurált bot értékét
hideHumanSupportWhenLiveChatAvailable	boolean		A kapcsolatfelvételi űrlap elrejtése, ha a Live Chat elérhető
missedEmailEnabled	boolean	alapértelmezett: true	E-mail küldése a bot tulajdonosának, ha egy Live Chat kérés megválaszolatlan maradt. Korábbi botoknál nincs kitöltve, ami bekapcsoltként értelmeződik

A requirePolicyAccept mező a consent.liveChatRequirePolicyAccept helyen található, nem itt.

§ consent

Mező	Típus	Megkötés	Leírás
newConversationRequirePolicyAccept	boolean		Adatvédelmi tájékoztató elfogadásának megkövetelése új beszélgetés indítása előtt
humanSupportRequirePolicyAccept	boolean		Adatvédelmi tájékoztató elfogadásának megkövetelése az emberi ügyfélszolgálati űrlap beküldése előtt
leadCollectionRequirePolicyAccept	boolean		Adatvédelmi tájékoztató elfogadásának megkövetelése a leadgyűjtő űrlap beküldése előtt
liveChatRequirePolicyAccept	boolean		Adatvédelmi tájékoztató elfogadásának megkövetelése Live Chat munkamenet indítása előtt
newConversationConsentDescription	string		Bevezető szöveg a beleegyezési képernyőhöz a beszélgetés kezdetén
privacyPolicyConsentCheckboxLabel	string		Címke a beleegyezési jelölőnégyzet mellett (általában linket tartalmaz az adatvédelmi tájékoztatóhoz)

§ whiteLabel

Mező	Típus	Megkötés	Leírás
hideRoboAssistLogo	boolean	White Label funkció; a fiók korlátozásaitól függ	Az alapértelmezett ChatLab logó elrejtése a láblécben
whitelabelLogoLink	string	White Label funkció; a fiók korlátozásaitól függ	URL, amelyre az egyéni lábléclogó mutat
assignToCustomDomain	boolean	a CUSTOM_DOMAIN funkcióhoz kötött	A chat futtatása a beállított egyéni tartományon
whitelabelLogoUrl	string	írásvédett	A White Label logó teljes nyilvános URL-címe; módosításához a többrészes kérelem whitelabel_logo részén keresztül kell feltölteni

Multipart a POST/PATCH hívásokban: whitelabel_logo (fájlrész). A GET kérések és a válaszok törzse elhagyja a fájltartalmat - kizárólag az URL szerepel az adatátvitelben.

§ security

Mező	Típus	Megkötés	Leírás
allowedDomains	string		A widget beágyazására jogosult tartományok vesszővel elválasztott listája (üres = nincs engedélyezési lista)
spamFilterEnabled	boolean		A bejövő üzenetek botszintű spamszűrőjének bekapcsolása
countryFilterMode	string	BLACKLIST vagy WHITELIST	Az országlisták értelmezési módja. Maguk a listák csak adminisztrátorok számára érhetők el
talkMessagesRateLimit	int	>= 0; a 0 kikapcsolja	A gyakoriságkorlátozási időablakban engedélyezett maximális felhasználói üzenetszám
talkMessagesRateLimitDurationSeconds	int	>= 0	A gyakoriságkorlátozási időablak hossza (másodperc)
talkMessagesRateLimitHitMessage	string		A látogatónak megjelenített üzenet a gyakorisági korlát elérésekor

§ voice

Mező	Típus	Megkötés	Leírás
inputEnabled	boolean		Annak engedélyezése, hogy a látogató diktálhassa az üzeneteket (beszédfelismerés)
conversationEnabled	boolean	hangfunkció meglétét igényli a csomagban	Teljes hangbeszélgetések bekapcsolása
voiceId	string	szolgáltatóspecifikus hangazonosító (pl. alloy)	Melyik szintetikus hang beszél
model	string	pl. GPT-REALTIME-MINI, GEMINI-LIVE, ELEVENLABS-*	Hangmodell. Percenkénti számlázású, a díjak modellenként eltérnek
turnDetection	string	szolgáltatóspecifikus	Megszólalás-észlelési (turn-taking) mód
audioPrompt	string		Kiegészítő rendszerprompt kizárólag a hang alapú megszólalásokhoz
welcomeMessage	string		Kimondott nyitómondat
language	string	nyelvkód	Elsődleges hangnyelv
additionalLanguages	string	vesszővel elválasztott nyelvkódok	További nyelvek, amelyeket a hangágens elfogad
maxDurationSeconds	int		Egyetlen hangbeszélgetés felső időkorlátja
maxDurationMessage	string		Az időkorlát elérésekor megjelenített üzenet

§ multilingual

Mező	Típus	Megkötés	Leírás
enabled	boolean		Többnyelvű mód kapcsolója
mode	string	AUTODETECT vagy FIXED_LIST	Hogyan válassza ki a bot a válasz nyelvét
baseLanguage	string	nyelvkód	A nyelv, amelyen a bot saját szövegei készültek
languages	string	vesszővel elválasztott nyelvkódok	A látogatónak felkínált nyelvek
knowledgeLanguageMode	string	NONE, MAIN vagy DYNAMIC	A más nyelvű tudásbázis-elemek kezelési módja
knowledgeLanguageFallback	string	nyelvkód	Egyezés hiányában használt tartalék nyelv

§ advanced

Mező	Típus	Megkötés	Leírás
model	string	a fiók korlátozásaitól függ; lásd: "AI text models" fent	LLM-azonosító (pl. 5.6-LUNA)
temperature	decimal	0.0-1.0	Mintavételi hőmérséklet (megegyezik a felületi csúszkával)
chatContextSize	int	∈ {8000, 16000, 32000}; csendben a fiókkerethez igazítva	Beállított kontextuskeret, beleértve az utasításokat, az előzményeket és a tudásbázist
botMessagesLimit	long	0 vagy 1000 többszöröse (pl. 1000, 2000, 10000)	Havi bot üzenetkredit-korlát (0 = nincs további botszintű korlát; a fiókkeret továbbra is érvényes)
internalLocale	string	nyelvi kód ll_CC formátumban	A widget kezelőfelületi elemeinek nyelve (nem azonos a role.language értékkel)
productsViewEnabled	boolean		Ha igaz, megjeleníti az e-kereskedelmi Offer Cards elemeket a chaten belül
includeProductsInKnowledgeBase	boolean		Ha igaz, a termékkatalógust a tudásbázis részeként indexeli

Az API hatókörén kívül eső elemek

Az adminisztrációs felület tartalmaz néhány olyan területet, amely a Management API ezen verziójában szándékosan nem érhető el:

• Betanítás és törlés - ezek a végpontok nem listázzák az összes botot, nem kezelik a tanítási adatkészleteket, és nem törölnek botokat. Ezekhez a munkafolyamatokhoz használja az alkalmazást.
• Flow tab (Flow lap) - a vizuális beszélgetésifolyamat-szerkesztő (Flow Editor - szakaszok és átmenetek). Nem érhető el a Management API-n keresztül.
• Actions tab (Műveletek lap) - menedzselt e-kereskedelmi / foglalási integrációk, AI Search és egyéni API-funkciók. Az eszközhívás (tool calling) soha nem képezte a Management API részét.
• Maga az egyéni űrlapkészítő - az egyéni űrlapok létrehozása és szerkesztése nem érhető el. Ugyanakkor létező űrlap hozzácsatolható a bothoz a leadCollection.customFormId és a humanSupport.customFormId mezőkön keresztül.
• Egyéni chatnyitó / -záró ikonok - customLauncherIconVisible, openChatIcon, closeChatIcon. Az API kizárólag a fő avatar és whitelabel_logo multipart részeket teszi elérhetővé.
• IP- és országlisták - maguk a bejegyzések csak az adminisztrátorok számára hozzáférhetők. Kizárólag az értelmezési mód érhető el a security.countryFilterMode mezőn keresztül.

Végpontok

POST /v1/management/bots

Új bot létrehozása. Két egyenértékű Content-Type elfogadott; válassza azt, amelyik kényelmesebb.

A mód - egyszerű JSON (ajánlott, ha nem szükséges avatárt / logót feltölteni ugyanabban a kérésben):

• Content-Type: application/json
• A kérés törzse maga a botkonfigurációs JSON (data csomagolás nélkül)
• A fájlok (avatár / logó) később is feltölthetők egy második PATCH kéréssel a B mód használatával

B mód - multipart/form-data (akkor használja, ha fájlokat tölt fel ugyanabban a kérésben):

• Content-Type: multipart/form-data; boundary=...
• data JSON-rész (kötelező, Content-Type: application/json) - botkonfiguráció a fent leírt beágyazott struktúrában
• avatar fájlrész (opcionális) - bot avatárképe
• whitelabel_logo fájlrész (opcionális) - White Label logó (csak akkor érvényes, ha a fiókja tartalmazza a White Label funkciót)

A JSON-ban kizárólag a name kötelező; minden más mező ugyanarra az alapértelmezett értékre áll vissza, amelyet az adminisztrátori felület varázslója is beállítana.

Példa kéréstörzs

Ez a maximális data JSON - minden szekció kitöltve. Csak azokat a szekciókat küldje el, amelyekre szüksége van; minden más az alapértelmezett értéket veszi fel.

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

Validációs szabályok saját hibaüzenetekkel:

• name - kötelező, legfeljebb 150 karakter
• advanced.temperature - 0.0 és 1.0 között
• chatMemory.summariesToKnowledgeRatio - egész szám 10 és 90 között (százalék, 10-es lépésközzel)
• appearance.launcherBottomMargin, appearance.launcherSideMargin - 0 és 500 között
• appearance.footerMarkdown - legfeljebb 255 karakter
• humanSupport.enabled=true esetén a humanSupport.email megadása kötelező
• leadCollection.enabled=true esetén a leadCollection.emailEnabled vagy a leadCollection.phoneEnabled közül legalább az egyiknek igaznak kell lennie; amelyik csatorna be van kapcsolva, annak a címkéjét is meg kell adni, valamint a leaveDetailsMessage és a thankYouMessage mezőket is
• Az advanced.chatContextSize értéke a fiók által támogatott maximális kontextusmérethez igazodik. Ne feltételezze, hogy más numerikus mezők értéke is automatikusan korlátozásra kerül.

Azok a mezők, amelyek értéke null a szerveren, kimaradnak a JSON törzsből - a hálózaton csak a nem null értékű mezők továbbítódnak.

Példa választörzs (201)

Ugyanaz a struktúra, mint a kérésnél, kiegészítve a csak olvasható meta blokkal és az egyszer használatos apiKey-vel a legfelső szinten. A csak olvasható fájl-URL-eket (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) a szerver tölti ki, ha a megfelelő multipart részek feltöltésre kerültek.

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

Az apiKey mező kizárólag a létrehozáskor jelenik meg - ez az újonnan generált Bot Talk kulcs, amely az új bothoz kapcsolódik. Az egyszerű szöveges érték csak egyszer látható, és később nem kérhető le újra az API-ból; haladéktalanul mentse el a saját oldalán.

A Location válaszfejléc az új bot URL-jét tartalmazza (/v1/management/bots/{id}).

Curl-példák

A mód - egyszerű JSON (legegyszerűbb):

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

B mód - multipart avatárral:

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}

Visszaadja egy meglévő saját bot aktuális konfigurációját.

Curl-példa

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

Példa választörzs (200)

Ugyanaz a struktúra, mint a POST válasznál, az egyszer használatos apiKey nélkül. A meta blokkot tartalmazza. 404 not_found_error hibát ad vissza, ha a bot nem létezik, vagy nem az Ön fiókjához tartozik.

Az aktuális avatár és a White Label logó teljes körűen minősített, csak olvasható URL-ként jelenik meg (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) - amelynek gyökere ugyanaz a séma + gazdagép + környezeti útvonal, amely ezt a kérést kiszolgálta. A bájtok lekéréséhez intézzen GET kérést közvetlenül ezekre az URL-ekre; bármelyik fájl cseréjéhez töltsön fel egy újat a PATCH multipart avatar / whitelabel_logo részén keresztül. Ezeket az URL-mezőket a rendszer figyelmen kívül hagyja, ha a kéréstörzsben küldik el őket.

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

Bot klónozása

A POST /v1/management/bots kéréstörzse és a GET /v1/management/bots/{bot_id} választörzse azonos felépítésű, így a klónozás egy háromlépéses folyamat: kérje le a forrást (GET), távolítsa el a szerver által kezelt azonosító mezőket, majd küldje el az eredményt (POST).

1. A forrásbot lekérése (GET).

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

2. A legfelső szintű meta blokk eltávolítása. A meta objektum (id, createdAt, updatedAt) a szerver által kezelt és csak olvasható - ha a POST törzsében hagyja, az nem okoz gondot (a szerver figyelmen kívül hagyja), de az eltávolításával egyértelművé válik a szándék, és a payload is tiszta marad. Szükség esetén módosítsa a name mezőt, hogy a klón megkülönböztethető legyen a forrástól.

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

3. A megtisztított törzs elküldése (POST) a klón létrehozásához. A törzs teljes szerkezetét és az érvényesítési szabályokat lásd a fenti POST /v1/management/bots leírásban.

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

A válasz tartalmazza az új bot meta.id azonosítóját, valamint egy újonnan generált apiKey kulcsot (a klónhoz tartozó Bot Talk kulcsot). Az apiKey egyszerű szöveges formátumban kizárólag ebben a létrehozási válaszban érhető el - másolja ki, mielőtt elvetné a választörzset; később már nem kérhető le.

Ez a támogatott beállításokat másolja át, nem egy teljesen betanított chatbotot. A tanítási tartalmat, a beszélgetési előzményeket, az integrációkat/műveleteket, a Flow-t és az űrlapdefiníciókat ezek a végpontok nem klónozzák. Ezeket külön kell konfigurálni az alkalmazásban.

További fontos tudnivalók:

• A fájlok nem kerülnek klónozásra. Az appearance.avatarUrl és a whiteLabel.whitelabelLogoUrl mezők csak olvashatók, és a forrásbot fájljaira mutatnak. Ha ugyanazt az avatárt vagy White Label logót szeretné használni a klónon is, töltse le a bájtokat a forrás URL-ekről, majd töltse fel őket többrészes avatar / whitelabel_logo részekként - vagy a létrehozási POST kérésben (B mód), vagy egy azt követő PATCH kérésben.
• A Bot Talk kulcsok nem kerülnek klónozásra. Minden bot saját Bot Talk kulcskészlettel rendelkezik. A létrehozási POST kérés által visszaadott egyetlen apiKey az egyetlen, amely automatikusan generálódik; szükség esetén hozzon létre további kulcsokat a bot API fülén.

PATCH /v1/management/bots/{bot_id}

Egy vagy több mező frissítése egy saját tulajdonú boton. Csak a JSON-ban szereplő szakaszok / mezők módosulnak; minden elhagyott (vagy null értékként elküldött) elem érintetlen marad. A részleges frissítés szemantikája mezőnként érvényesül az elküldött szakaszon belül.

Két egyenértékű Content-Type fogadható el (ugyanúgy, mint a POST esetében):

A mód - sima JSON (csak beállítások frissítésekor ajánlott):

• Content-Type: application/json
• A kéréstörzs maga a módosítási JSON (nincs data burkoló)

B mód - multipart/form-data (fájlok feltöltésekor használandó):

• data JSON rész (opcionális) - a módosítás. Csak akkor küldje el, ha mezőket kíván módosítani. Teljesen hagyja el, ha csak avatárt vagy logót szeretne feltölteni.
• avatar fájlrész (opcionális) - az avatár cseréje
• whitelabel_logo fájlrész (opcionális) - a White Label logó cseréje (csak akkor érvényes, ha a fiókja tartalmazza a White Label funkciót)

PATCH esetén mindhárom rész opcionális, de a hívás értelmezhetőségéhez legalább az egyiknek szerepelnie kell.

Példa kéréstörzs (több szakasz)

Bármely mező elküldhető itt is, amelyet a POST /v1/management/bots elfogad. Az alábbi példa több szakaszt mutat be, nem az összes támogatott mezőt; a gyakorlatban csak azokat a kulcsokat kell elküldenie, amelyeket módosítani szeretne (lásd a lenti "Minimális részleges frissítés" részt) - minden elhagyott (vagy null értékként megadott) kulcs változatlanul hagyja a mentett értéket.

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

Minimális részleges frissítés

Egyetlen mező módosítása (PATCH) kizárólag a módosítani kívánt kulcsok elküldésével - minden más megmarad.

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

Curl-példák

A mód - sima JSON (a legegyszerűbb):

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

B mód - multipart (avatár / logó cseréjekor):

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'

B mód - kizárólag az avatár cseréje (mezőmódosítás nélkül):

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

Választörzs (200)

Ugyanolyan szerkezetű, mint a GET /v1/management/bots/{bot_id} - a bot teljes konfigurációja a módosítás alkalmazása után, beleértve a meta blokkot is. Nem tartalmazza az apiKey mezőt. 404 not_found_error hibát ad vissza, ha a bot nem létezik, vagy nem az Ön fiókjához tartozik.

Az alábbi példa azt a választ mutatja be, amely a fenti Teljes kéréstörzs (több szakasz) módosításnak a GET példában szereplő botra történő alkalmazása után érkezik - a módosított mezők az új értékeket tükrözik, az érintetlen mezők megmaradnak, a meta.updatedAt értéke pedig frissül.

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

A Management kulcsot birtokló fiók aktuális előfizetési használatának lekérdezése.

Választörzs (200)

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

• A subscriptionType a fiók aktuális csomagjának kisbetűs azonosítója (a your-plan-id egy szemléltető helyőrző). A csomagok egy dinamikus katalógusból származnak, így az azonosítók pontos köre idővel változhat a csomagok átnevezésével vagy hozzáadásával - kezelje ezt kötetlen karaktersorozatként, nem pedig rögzített enumként.
• A messages.used / limit / remaining az aktuális naptári hónap üzenetegyenlegét mutatja, amely a hónap első napján nullázódik, nem pedig az előfizetés megújításának napján. Ezek kreditalapon számított értékek, nem pedig nyers válaszszámok.
• A bots.used / limit / remaining a fiókhoz tartozó botok számát összegzi - beleértve a szüneteltetett botokat is - a fiók teljes botkeretéhez viszonyítva.

Sebességkorlátozási fejlécek

Azok a válaszok, amelyek elérik a kéréskorlátozási szakaszt (azaz a hitelesítés és az IP-engedélyezőlista ellenőrzése sikeresen lezajlott), a következőket tartalmazzák:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1715430000

• X-RateLimit-Limit - az ehhez a híváshoz ténylegesen alkalmazott kulcsonkénti felső korlát (alapértelmezés szerint 10, vagy az Ön által konfigurált rateLimitPerMinute, ha az alacsonyabb).
• X-RateLimit-Remaining - a tokenkeretben közvetlenül a hívás után fennmaradó tokenek száma.
• X-RateLimit-Reset - Unix epoch másodpercben megadott időbélyeg, amikor a következő token elérhetővé válik (nem a teljes keret újratöltése; a keret folyamatosan töltődik újra). Ha a keret tele van, ez a jelenlegi időpont.

A 429 rate_limit_exceeded válaszok esetén a Retry-After fejléc is beállításra kerül, amely egész másodpercekben jelzi, amíg legalább egy token fel nem szabadul.

A hitelesítés előtti hibák (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) és a 403 ip_not_whitelisted nem tartalmazzák az X-RateLimit-* fejléceket - a sebességkorlátozó csak a sikeres hitelesítés és az IP-ellenőrzések után lép működésbe.

Hibaformátum

Ugyanaz a borítékolás (envelope), mint a Bot Talk API esetében:

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

Az érvényesítési hibák a code: "invalid_parameter" értéket használják, és az üzenet elejére fűzik a hibás mező elérési útját, hogy a hibás rész könnyen beazonosítható legyen:

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

Az enum / zárt készletű mezők érvénytelen értékei (pl. chatMemory.clientSummaryPromptType = "BOGUS") tartalmazzák a mező elérési útját, az elutasított értéket, valamint az engedélyezett értékek listáját:

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

Kapcsolódó témakörök

A beszélgetési végpontokkal és az SSE-adatfolyamokkal kapcsolatban tekintse meg a Bot Talk API dokumentációját.