Management API

Management API apžvalga

Management API yra skirtas vidiniams procesams (angl. back-office), kurie nėra susiję su pokalbių žinučių siuntimu:

• programiškai sukurti robotą naudojant POST /v1/management/bots
• gauti konkretaus Jums priklausančio roboto duomenis naudojant GET /v1/management/bots/{bot_id}
• atnaujinti konkretų robotą naudojant PATCH /v1/management/bots/{bot_id}
• patikrinti prenumeratos limitų sunaudojimą naudojant GET /v1/usage

Management raktai yra susieti su Jūsų paskyra, o ne su konkrečiu robotu. Jie sąmoningai atskirti nuo Bot Talk raktų, kad nutekintas pokalbių raktas negalėtų keisti Jūsų robotų ar pasiekti atsiskaitymo duomenų.

Bazinis URL

https://api.chatlab.com/aichat

Visi šiame straipsnyje pateikti galiniai taškai (angl. endpoints) yra nurodyti šio bazinio URL atžvilgiu.

Darbo pradžia

1. Atidarykite administravimo programėlę ir eikite į Account Settings > Management API (Paskyros nustatymai > Management API).
2. Spustelėkite Create Management Key (Sukurti Management raktą), suteikite jam pavadinimą, pasirinktinai nustatykite leistinų IP adresų sąrašą bei užklausų dažnio ribojimą (angl. rate limit), tada patvirtinkite.
3. Pasirinkite tik tuos leidimus, kurių reikia Jūsų integracijai, ir nukopijuokite visą raktą iš sėkmingo sukūrimo lango. Paprastas tekstas parodomas tik vieną kartą.
4. Išsaugokite jį savo serveryje, o ne naršyklės kode ar viešoje saugykloje. Atlikite tik skaitymui skirtą užklausą, pavyzdžiui, GET /v1/usage su usage leidimu, kad patikrintumėte prieigą.
5. Nenaudojamus ar pažeistus raktus panaikinkite Management API puslapyje.

Raktas atrodo taip: mk_abcdefghijklmnopqrstuvwxyz012345. Priešdėlis mk_ atskiria jį nuo Bot Talk raktų (ck_).

Autentifikavimas

Authorization: Bearer mk_abcdefghijklmnopqrstuvwxyz012345

Pateikus mk_ raktą į /v1/chat (ar bet kurį kitą Bot Talk galinį tašką), grąžinama klaida 403 key_type_not_allowed. Pateikus ck_ raktą į /v1/management/*, grąžinama ta pati klaida.

Limitai

• Ne daugiau kaip 5 aktyvūs Management API raktai vienam naudotojui
• Ne daugiau kaip 10 užklausų per minutę vienam raktui (žetonų kibiro algoritmas, talpa 10, sklandus papildymas po ~1 žetoną kas 6 sekundes). Sukūrimo metu galima sukonfigūruoti mažesnę reikšmę - nustačius mažesnį rateLimitPerMinute, riba sumažėja, o papildymo greitis proporcingai prisitaiko.

Leidimai

Kiekvienas Management raktas turi bet kurį iš trijų toliau nurodytų leidimų poaibių. Sukūrimo metu būtina pasirinkti bent vieną; priešingu atveju užklausa atmetama su klaida 400 invalid_request_error. Kreipiantis į galinį tašką su raktu, kuris neturi reikiamo leidimo, grąžinama klaida 403 insufficient_permissions.

• bot_read - reikalingas GET /v1/management/bots/{bot_id}
• bot_management - reikalingas POST /v1/management/bots ir PATCH /v1/management/bots/{bot_id}
• usage - reikalingas GET /v1/usage

Užklausos turinio struktūra: įdėtinės sekcijos, atitinkančios administratoriaus sąsajos skirtukus

POST ir PATCH priima JSON turinį, suskirstytą į 13 sekcijų. Kiekviena sekcija atitinka administratoriaus programėlės roboto nustatymų šoninės juostos poskirtukį, todėl JSON raktai sutampa su matomais skirtukais: jei per API pakeisite consent.humanSupportRequirePolicyAccept, pamatysite tą patį perjungiklį pasikeitus administratoriaus programėlės skirtuke Consent & Privacy (Sutikimas ir privatumas).

• role - roboto rolė, pradinis nurodymas (angl. raw prompt), atsakymo ilgis, kalba, svetainės / įmonės kontekstas (skirtukas Role & Behavior (Rolė ir elgsena))
• conversation - pasveikinimo žinutė, užklausos patikslinimas, pokalbio tęstinumas, įvertinimo perjungiklis + paaiškinimai, siūlomų klausimų turinys + dinaminiai tolesni klausimai (skirtukas Chat Conversation (Pokalbis))
• chatMemory - pokalbio atminties perjungiklis, santraukų nurodymai, konteksto paskirstymas (skirtukas Summaries & Memory (Santraukos ir atmintis))
• appearance - spalvos, tekstai, matmenys, pasirinktinis CSS, pasveikinimo ekranas, siūlomų klausimų stilius, automatinio atidarymo elgsena, žmogaus rašymo imitavimas, poraštės markdown (skirtukas Appearance (Išvaizda))
• humanSupport - susisiekimo su žmogumi forma (skirtukas Human Contact Form (Susisiekimo su žmogumi forma))
• leadCollection - potencialių klientų fiksavimo forma (skirtukas Lead Collection (Kontaktų rinkimas))
• liveChat - perdavimas tiesioginiam pokalbiui (skirtukas Live Chat)
• consent - visi keturi privatumo politikos sutikimo perjungikliai bei sutikimo ekrano tekstas (skirtukas Consent & Privacy (Sutikimas ir privatumas))
• whiteLabel - logotipo slėpimas, pasirinktinė logotipo nuoroda, talpinimas pasirinktiniame domene (skirtukas Whitelabel)
• security - leidžiami domenai, šlamšto filtras, pokalbių dažnio limitai (skirtukas Security (Sauga))
• voice - balso įvestis ir balso pokalbiai: modelis, balsas, kalbos, nurodymas, trukmės riba (skirtukas Voice Conversation (Pokalbis balsu))
• multilingual - daugiakalbis režimas, pagrindinė kalba, siūlomos kalbos, žinių bazės kalbos apdorojimas (skirtukas Languages (Kalbos))
• advanced - LLM modelis, temperatūra, konteksto dydis, roboto žinučių limitas, vidinė lokalė, Offer Cards (skirtukas Model & Advanced (Modelis ir išplėstiniai nustatymai))

Iš visų keičiamų nustatymų tik name yra aukščiausiame lygyje, nes jis identifikuoja robotą, o ne priklauso kuriam nors vienam skirtukui.

Roboto nustatymų šoninėje juostoje šiuo metu yra 16 poskirtukių, iš kurių 13 atitinka aukščiau nurodytas sekcijas. Trys poskirtukiai, neturintys atitinkamos sekcijos, yra Flow, Actions ir Forms - visi trys aptariami toliau, skyriuje „Už API ribų“. 13 atitinkančių skirtukų yra Appearance, Chat Conversation, Role & Behavior, Human Contact Form, Lead Collection, Live Chat, Whitelabel, Consent & Privacy, Security, Model & Advanced, Summaries & Memory, Voice Conversation ir Languages.

Užklausos turinys ir atsakymo turinys turi tokią pačią struktūrą. Atsakyme pridedami du papildomi laukai:

• meta - tik skaitymui: roboto id ir laiko žymos. Pašalinkite šį lauką, kad GET atsakymą paverstumėte tinkamu POST turiniu.
• apiKey - pateikiamas tik sukūrimo metu - naujai sugeneruotas naujojo roboto Bot Talk API raktas.

Du bendros struktūros laukai yra tik skaitymui - jie grąžinami atsakyme, bet ignoruojami, jei bandysite juos siųsti per POST/PATCH:

• appearance.avatarUrl - pilnas viešas roboto avataro paveikslėlio URL (pvz., https://api.chatlab.com/aichat/content/avatar_xyz.png). Siųskite tiesioginę GET užklausą, kad atsisiųstumėte failą. Norėdami jį pakeisti, įkelkite naują failą per kelių dalių (angl. multipart) avatar dalį (žr. PATCH).
• whiteLabel.whitelabelLogoUrl - pilnas viešas White Label antraštės logotipo URL. Toks pat principas kaip ir avatarUrl. Norėdami jį pakeisti, įkelkite naują failą per kelių dalių whitelabel_logo dalį (žr. PATCH).

Abu URL naudoja esamos užklausos schemą + pagrindinį kompiuterį (host) + konteksto kelią, todėl White Label pasirinktiniame domene jie grąžinami susieti su tuo domenu (pvz., https://api.acme.com/aichat/content/...).

Norėdami praleisti sekciją atliekant PATCH, nurodykite null; norėdami praleisti vieną sekcijos lauką, nurodykite null tam laukui. Lauko lygio null niekada neištrina išsaugotos reikšmės - tai reiškia tik „neliesti“.

Rolės ir nurodymo sudarymas

Sisteminis nurodymas (angl. system prompt), kurį faktiškai gauna LLM, kuriamas vienu iš dviejų būdų, priklausomai nuo role.role. Žinodami, kurią šaką naudojate, suprasite, kurie laukai yra svarbūs, o kurie išsaugomi, bet ignoruojami.

A šaka - role.role yra CUSTOMER_SUPPORT, SALES arba LEAD_COLLECTION_AGENT (pagrįsta šablonu)

Vidinis serveris surenka nurodymą iš integruoto šablono ir visiškai ignoruoja role.rawPrompt (reikšmė vis tiek išsaugoma robote, tiesiog nenaudojama). Į šabloną įtraukiama:

• role.role - rolės etiketė (pvz., „Klientų aptarnavimas“) ir automatiškai pridedamos konkrečiai rolei skirtos instrukcijos
• name - roboto pavadinimas, įterpiamas į įvadinį sakinį
• role.language - "Auto Detect" nurodo robotui prisitaikyti prie naudotojo kalbos; bet kuri kita reikšmė (pvz., "English", "Polish") virsta „Output in {language}, unless user uses another language“
• role.responseLength - susiejama su tiksliniu žodžių skaičiumi: Concise ≈ 50 žodžių, Normal ≈ 100, Detailed ≈ 200
• role.websiteAddress - pasirinktinai; kai neužpildyta, pridedama kaip „for the users of the website {url}“
• role.companyDescription - pasirinktinai; kai neužpildyta, pridedama kaip papildoma pastraipa prieš rolės instrukcijas

Tai rekomenduojama šaka daugumai robotų - be papildomų pastangų gaunate rolei pritaikytą elgseną ir saugumo ribas.

B šaka - role.role yra CUSTOM (paties naudotojo pateiktas nurodymas)

Vidinis serveris naudoja role.rawPrompt kaip rolės nurodymą ir prideda platformos fiksuotas atsakymo ilgio gaires. Tai nepriklauso nuo role.responseLength: pasirinktinis Concise/Normal/Detailed nustatymas CUSTOM rolei nėra įterpiamas. Taip pat language, websiteAddress ir companyDescription yra išsaugomi, tačiau į šį rolės nurodymą neįterpiami. Bet kokią pageidaujamą kalbą, atsakymo ilgio tikslą ar įmonės kontekstą į rawPrompt įtraukite patys. Taip pat gali būti pateikiamos papildomos vykdymo laiko instrukcijos ir gautas kontekstas, todėl rawPrompt nėra visa modelio įvestis. Iš anksto apibrėžtos rolės tono instrukcijos nėra pridedamos, tačiau pasirinkus CUSTOM nepašalinamos visos platformos instrukcijos.

Naudokite CUSTOM tik tada, kai šablonu pagrįstas nurodymas netinka Jūsų atvejui (pvz., reikalinga itin specifinei sričiai pritaikyta rolė, Jūsų pačių saugumo apribojimai, nestandartinis išvesties formatas).

Išvardijimo tipo (enum) / fiksuoto rinkinio laukai

Išvardijimo tipo ir apriboti laukai atmeta netinkamas reikšmes su klaida 400 invalid_parameter. Kiti laukai yra paprastos eilutės, net jei vartotojo sąsaja siūlo fiksuotą sąrašą. Naudokite dokumentuotą rašybą ir patikrinkite siunčiamus duomenis patys, užuot darę prielaidą, kad kiekviena nepalaikoma eilutė bus atmesta.

• role.role - CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM
• role.responseLength - Concise, Normal, Detailed
• role.language - pilnas kalbos pavadinimas anglų kalba iš administratoriaus išskleidžiamojo sąrašo, pvz., Auto Detect, English, Polish, Spanish, German, French, Italian, Portuguese, Dutch, Russian, Chinese (Simplified), Japanese, Arabic, Hindi ir dar apie 80 kitų. Reikšmė išsaugoma pažodžiui ir įterpiama į nurodymo šabloną, todėl dviejų raidžių ISO kodai (en, pl) ir kitos ne sąrašo reikšmės nėra atmetamos API, tačiau sukuria iškraipytą instrukciją, pvz., „Output in en, unless...“. Jei kuriant praleidžiama, numatytoji reikšmė yra Auto Detect.
• advanced.model - žr. skyrių „AI teksto modeliai“ toliau. Tai yra eilutė, o ne patvirtintas enum užklausos schemoje; naudokite palaikomą reikšmę, o ne laisvai pasirinktą modelio pavadinimą.
• advanced.chatContextSize - naudokite 8000, 16000 arba 32000, atitinkančius vartotojo sąsają. Reikšmės, viršijančios paskyros maksimumą, automatiškai sumažinamos; DTO šio trijų reikšmių rinkinio negriežtina.
• chatMemory.clientSummaryPromptType - DEFAULT, CUSTOM
• chatMemory.conversationSummaryPromptType - DEFAULT, CUSTOM
• appearance.chatAlignment - left, right
• appearance.minimizedDisplayMode - icon, minified, pill
• appearance.chatMessageLinkTarget - _blank, _self
• leadCollection.requireBeforeNewConversation - loginis perjungiklis. true priverčia naudotoją užpildyti kontaktų formą prieš pradedant pokalbį; false leidžia DI pačiam nuspręsti, kada parodyti formą (numatytoji reikšmė).

Struktūrizuoti laukai ir rėžiai

Laukai, kurie atrodo kaip paprastos eilutės ar skaičiai, tačiau turi specifines formas, rėžius ar administratoriaus sąsajos ypatumus, kuriuos verta žinoti.

• advanced.temperature - priimamas rėžis yra nuo 0.0 iki 1.0, atitinkantis šliaužiklį administratoriaus sąsajoje. Reikšmės už šio rėžio ribų atmetamos su klaida 400 invalid_parameter.

• chatMemory.summariesToKnowledgeRatio - sveikasis procentinis skaičius, 10-90; vartotojo sąsaja naudoja 10 žingsnį, tačiau API priima sveikuosius skaičius visame rėžyje. Numatytoji reikšmė 50. Kai atmintis įjungta ir kontekstas didesnis nei 8k, ši reikšmė padalija žinių ir atminties biudžetą po to, kai atidedama vieta nurodymui bei neseniai vykusiam pokalbiui, o ne visą modelio kontekstą. Esant 8k kontekstui, šis nustatymas santraukų biudžeto neišskiria.

• liveChat.schedule - JSON, užkoduotas kaip eilutė, o ne įdėtinis JSON objektas tinkle. Serveris išsaugo neapdorotą eilutę pažodžiui; administratoriaus sąsaja ją išanalizuoja kliento pusėje, kai atvaizduoja tvarkaraščio redaktorių. Išanalizavus, eilutė susideda iš po vieno įrašo kiekvienai savaitės dienai bei timezone rakto:

  • kiekvienos savaitės dienos raktas (monday-sunday) atitinka {enabled: boolean, from: "H:MM", to: "H:MM"} 24 valandų formatu
  • timezone yra IANA laiko juostos pavadinimas (pvz., "Europe/Warsaw", "America/New_York")

  Pavyzdinė reikšmė (atkreipkite dėmesį į išorines kabutes ir ekranuotas vidines kabutes - tai vienas eilutės laukas, o ne įdėtinis objektas):

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

  Ne nurodytomis valandomis lankytojui rodoma liveChat.outOfHoursMessage žinutė, o perdavimas tiesioginiam pokalbiui yra blokuojamas. Vidinės struktūros patikra atliekama tik kliento pusėje administratoriaus sąsajoje - netinkamai suformatuotą JSON ar neatpažintus raktus API priims kaip tiesiog eilutę, o tai vėliau sukels atvaizdavimo klaidą, kai žmogus atidarys robotą administravimo skydelyje. Prieš siųsdami patikrinkite struktūrą savo pusėje.

• conversation.positiveRatingTooltip / conversation.negativeRatingTooltip - trumpi užrašai, rodomi prie 👍 / 👎 pokalbio vertinimo mygtukų, kai conversation.conversationRatingEnabled=true. Numatytasis tekstas yra „I like the response“ / „I don't like the response“. Matoma galutiniams naudotojams.

• whiteLabel.hideRoboAssistLogo - White Label funkcija, priklausanti nuo Jūsų paskyros limitų. Paslepia poraštės eilutę „Powered by ChatLab“. Jei Jūsų paskyroje White Label nenumatytas, reikšmė išsaugoma, bet ignoruojama, o poraštė visada rodoma.

• whiteLabel.whitelabelLogoLink - White Label funkcija, priklausanti nuo Jūsų paskyros limitų. Nukreipimo URL paspaudus ant pasirinktinio logotipo, kai hideRoboAssistLogo=true ir pasirinktinis logotipo failas yra įkeltas per whitelabel_logo kelių dalių užklausą.

• appearance.simulateHumanTypingDelay - sekundės (ne milisekundės), sveikasis skaičius 0-200. Pauzė tarp paeiliui einančių roboto žinučių burbulų, kai simulateHumanTyping=true. Numatytoji reikšmė 5.

• appearance.autoOpenChatDelaySeconds - sekundės, sveikasis skaičius. Uždelsimas prieš valdikliui automatiškai atsidarant, kai autoOpenChat=true ir autoOpenChatDelay=true.

• advanced.internalLocale - IETF lokalės-regiono kodas ll_CC formatu (su pabraukimo brūkšniu, O NE ll-CC su brūkšneliu). Priimamos reikšmės iš fiksuoto ~95 lokalių sąrašo: 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 ir daugelis kitų. Vien tik dviejų raidžių kodo ("en") arba BCP-47 ("en-US") siuntimas nėra leidžiamas. Numatytoji reikšmė en_US. Ši lokalė naudojama datų ir skaičių formatavimui valdiklio sąsajoje, ji skiriasi nuo role.language (roboto pokalbio išvesties kalbos).

• security.talkMessagesRateLimit / security.talkMessagesRateLimitDurationSeconds - sveikieji skaičiai (siųsti kaip JSON skaičius, pvz., 30, o ne "30"). Nustatykite žinučių limitą į 0, kad išjungtumėte šį sesija pagrįstą limitą. Įjungdami nurodykite teigiamą trukmę. Vidinis serveris taiko N žinučių limitą per sesiją nurodytam sekundžių skaičiui, prieš lankytojui parodant security.talkMessagesRateLimitHitMessage.

• advanced.botMessagesLimit - sveikasis skaičius (JSON skaičius, pvz., 1000). 0 reiškia, kad papildomas limitas vienam robotui netaikomas, tačiau paskyros kreditų limitas vis tiek galioja; kitu atveju reikšmė turi būti 1000 kartotinis (1000, 2000, 10000, ...). Reikšmės, tokios kaip 100 ar 1500, atmetamos su klaida 400 invalid_parameter. Tai yra mėnesinis roboto kreditų limitas, o ne vieno pokalbio žinučių skaičius. Duomenų susiejiklis nesumažina šios reikšmės iki paskyros biudžeto; faktinį naudojimą vis tiek riboja paskyros biudžetas.

AI teksto modeliai (advanced.model)

Naudokite tikslų modelio identifikatorių, grąžinamą lauke advanced.model, kai nuskaitote robotą, sukonfigūruotą su norimu modeliu skiltyje Settings > Model & Advanced (Nustatymai > Modelis ir išplėstiniai nustatymai). Šiuo metu numatytasis modelis sukūrimo metu yra 5.6-LUNA. Identifikatoriuose skiriamos didžiosios ir mažosios raidės, jie skiriasi nuo rodomų pavadinimų; pavyzdžiui, 5.6-LUNA rodomas kaip GPT 5.6-luna.

Modelių katalogas laikui bėgant keičiasi. Nedarykite prielaidos, kad bet kokia eilutė ar teikėjo viešas modelio ID yra palaikomas vien todėl, kad užklausos schema priima eilutės tipą. Nuskaitykite išsaugotą konfigūraciją ir išbandykite gautą pokalbių robotą prieš pradėdami jį naudoti.

Lauko aprašas (visa užklausos schema)

Palaikomos skiltys ir laukai, jų tipai bei svarbūs apribojimai. PATCH semantika: bet kuris praleistas (arba kaip null pateiktas) laukas palieka išsaugotą reikšmę nepakeistą. Ta pati struktūra naudojama ir atsakyme (atėmus kelių dalių dvejetainį turinį; pridedant tik skaitomą meta bloką kiekviename atsakyme ir apiKey tik sukūrimo atsakyme).

Aukščiausias lygis

Laukas	Tipas	Apribojimas	Aprašymas
name	string	maks. 150, privalomas kuriant	Rodomas boto vardas
role	object		Žr. § role
conversation	object		Žr. § conversation
chatMemory	object		Žr. § chatMemory
appearance	object		Žr. § appearance
humanSupport	object		Žr. § humanSupport
leadCollection	object		Žr. § leadCollection
liveChat	object		Žr. § liveChat
consent	object		Žr. § consent
whiteLabel	object		Žr. § whiteLabel
security	object		Žr. § security
advanced	object		Žr. § advanced

Papildymai tik atsakyme:

• meta: { id, createdAt, updatedAt } - tik skaitymui.
• apiKey - string, pateikiamas tik POST /v1/management/bots atsakyme - naujai sugeneruotas Bot Talk raktas naujam botui, grąžinamas lygiai vieną kartą.

§ role

Laukas	Tipas	Apribojimas	Aprašymas
role	string (enum)	CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM	Personos išankstinis nustatymas; parenka raginimo šabloną (žr. „Role and prompt construction")
language	string	visas kalbos pavadinimas anglų kalba (English, Polish, ...) arba Auto Detect	Pagrindinė kalba, perduodama į raginimo šabloną
responseLength	string	∈ {Concise, Normal, Detailed}	Pageidaujamas DI atsakymo išsamumas
websiteAddress	string		Svetainė, naudojama raginimo kontekstui
companyDescription	string		Įmonės aprašymas, naudojamas raginimo kontekstui
rawPrompt	string		Individualus sistemos raginimas - naudojamas pažodžiui tik tada, kai role=CUSTOM

§ conversation

Laukas	Tipas	Apribojimas	Aprašymas
welcomeMessage	string		Pirmoji žinutė, rodoma lankytojui atidarius pokalbį
queryRefinementEnabled	boolean		Jei true, patikslina lankytojo klausimą prieš RAG paiešką
conversationContinuityEnabled	boolean		Jei true, sugrįžę lankytojai tęsia paskutinį pokalbį
conversationRatingEnabled	boolean		Jei true, rodo pokalbio vertinimo mygtukus („nykštys aukštyn / žemyn")
positiveRatingTooltip	string		Teigiamo įvertinimo mygtuko paaiškinimas
negativeRatingTooltip	string		Neigiamo įvertinimo mygtuko paaiškinimas
suggestedQuestions	string		Nauja eilute atskirti siūlomi klausimai / pokalbio pradžios frazės
dynamicSuggestedFollowups	boolean		Jei true, DI po kiekvieno atsakymo siūlo tolesnius klausimus
positiveRatingMessage	string		Žinutė, rodoma pateikus teigiamą atsiliepimą
negativeRatingMessage	string		Žinutė, rodoma pateikus neigiamą atsiliepimą
hideSuggestedQuestionsAfterFirstUse	boolean		Paslėpti statinius siūlymus po pirmojo panaudojimo
dynamicFollowupsAutoIcons	boolean		Jei true, DI automatiškai parenka jaustukų piktogramas dinaminiams tolesniems klausimams

§ chatMemory

Laukas	Tipas	Apribojimas	Aprašymas
enabled	boolean		Pagrindinis pokalbių atminties funkcijos jungiklis
summaryConversationsEnabled	boolean		Išsaugoti kiekvieno pokalbio santraukas
conversationSummaryPrompt	string		Individualus raginimas, naudojamas kiekvienam pokalbiui apibendrinti
conversationSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Ar naudoti numatytąjį, ar individualų santraukos raginimą
clientSummaryPrompt	string		Individualus raginimas, naudojamas kliento profiliui apibendrinti per kelis pokalbius
clientSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Numatytasis ar individualus kliento profilio raginimas
summariesToKnowledgeRatio	int	10-90 (sąsajos žingsnis 10)	Galimo žinių / atminties biudžeto dalis (%), skirta santraukoms, kai kontekstas viršija 8 tūkst.

§ appearance

Laukas	Tipas	Apribojimas	Aprašymas
launcherLabelLine1	string	maks. 60	Pirmoji paleidiklio teksto eilutė
launcherLabelLine2	string	maks. 60	Antroji paleidiklio teksto eilutė
launcherTextColor	string		Paleidiklio teksto spalva
launcherDismissEnabled	boolean		Leisti paslėpti paleidiklį
widgetFontFamily	string	inter, system, nunito, lato, montserrat, poppins, source-serif, jetbrains-mono	Valdiklio šriftų šeima
chatDrawerEnabled	boolean		Įjungti išvažiuojančio skydelio (angl. drawer) rodymą
launcherColor	string (hex)		Paleidiklio (pokalbio piktogramos) fono spalva
headerColor	string (hex)		Pokalbio antraštės fono spalva
titleColor	string (hex)		Pokalbio antraštės pavadinimo spalva
subtitleColor	string (hex)		Pokalbio antraštės paantraštės spalva
clientMessageBubbleColor	string (hex)		Lankytojo žinutės debesėlio spalva
clientMessageTextColor	string (hex)		Lankytojo žinutės teksto spalva
responseMessageBubbleColor	string (hex)		Boto atsakymo debesėlio spalva
responseMessageTextColor	string (hex)		Boto atsakymo teksto spalva
chatSubheader	string		Prierašas, rodomas po pokalbio pavadinimu
senderPlaceholder	string		Vietos rezervavimo tekstas žinutės įvedimo lauke
resetConversationTooltip	string		Mygtuko „iš naujo nustatyti pokalbį" paaiškinimas
chatAlignment	string (enum)	∈ {left, right}	Prie kurio ekrano krašto prisegamas pokalbis
launcherBottomMargin	int	0-500	Paleidiklio atstumas nuo apatinio krašto (px)
launcherSideMargin	int	0-500	Paleidiklio atstumas nuo šoninio krašto (px)
displayShadow	boolean		Šešėlis po valdikliu
customCss	string		Neapdorotas CSS, įterpiamas į valdiklio iframe
chatMessageLinkTarget	string (enum)	∈ {_blank, _self}	Kaip atidaromos nuorodos boto žinutėse
minimizedDisplayMode	string (enum)	∈ {icon, minified, pill}	Sutraukta būsena: paleidiklio piktograma, kompaktiška siuntėjo juosta arba piliulė
chatDesktopWidthPx	int		Valdiklio plotis kompiuterio ekrane
chatDesktopHeightPx	int		Valdiklio aukštis kompiuterio ekrane
chatMobileSizePercent	int		Mobiliojo valdiklio dydis kaip matymo srities (viewport) dalis (%)
messageFontSize	int		Žinutės teksto šrifto dydis (px)
showChatbotBubblesDesktop	boolean		Rodyti iškylančius užuominų debesėlius kompiuterio ekrane
showChatbotBubblesMobile	boolean		Rodyti iškylančius užuominų debesėlius mobiliajame įrenginyje
chatbotBubblesDelaySeconds	int		Delsa prieš pasirodant užuominų debesėliams (sekundėmis)
launcherIconFullSize	boolean		Atvaizduoti individualią paleidiklio piktogramą nuo krašto iki krašto vietoj įtrauktos
welcomeScreenEnabled	boolean		Rodyti pasveikinimo ekraną (angl. Welcome Screen) vietoj tiesioginio perėjimo į pokalbį
welcomeScreenQuestionsLabel	string		Užrašas virš siūlomų klausimų pasveikinimo ekrane
welcomeScreenHideHumanContactForm	boolean		Slėpti žmogaus pagalbos kontaktinės formos veiksmą antraštėje, kol rodomas Welcome Screen. Jis vėl atsiranda po pirmosios lankytojo žinutės. Botams, sukurtiems iki 2026-09-02, numatytoji reikšmė yra true
welcomeScreenHideLiveChat	boolean		Slėpti tiesioginio pokalbio veiksmą antraštėje, kol rodomas Welcome Screen. Jis vėl atsiranda po pirmosios lankytojo žinutės. Botams, sukurtiems iki 2026-09-02, numatytoji reikšmė yra true
headerActionsLayout	string	ICONS arba DROPDOWN	Kaip Live Chat ir žmogaus pagalbos kontaktinė forma pateikiami pokalbio antraštėje: ICONS (atskira piktograma kiekvienam) arba DROPDOWN (sugrupuota antraštės meniu). Botams, sukurtiems iki 2026-09-02, numatytoji reikšmė yra ICONS
stackSuggestedQuestions	boolean		Rikiuoti siūlomus klausimus vertikaliai (palyginti su greta vienas kito)
suggestedQuestionsFontSize	int		Siūlomų klausimų elementų šrifto dydis (px)
suggestedQuestionsTextColor	string (hex)		Siūlomų klausimų elementų teksto spalva
suggestedQuestionsBackgroundColor	string (hex)		Siūlomų klausimų elementų fono spalva
autoOpenChat	boolean		Automatiškai atidaryti pokalbį kompiuterio ekrane
autoOpenChatOnMobiles	boolean		Automatiškai atidaryti pokalbį mobiliajame įrenginyje
autoOpenChatDelay	boolean		Naudoti delsą prieš automatinį atidarymą
autoOpenChatDelaySeconds	int		Automatinio atidarymo delsa (sekundėmis)
simulateHumanTyping	boolean		Padalyti boto atsakymą į debesėlius su teksto rinkimo animacija
simulateHumanTypingDelay	int	0-200	Delsa tarp žinučių debesėlių (sekundėmis)
footerMarkdown	string	maks. 255	Individualus poraštės markdown tekstas, rodomas po pokalbiu
avatarUrl	string	tik skaitymui	Visiškai suformuotas viešasis avataro URL; norėdami jį pakeisti, įkelkite naudodami kelių dalių avatar dalį

Kelių dalių parametras POST/PATCH metu: avatar (failo dalis). GET / atsakymo turinyje failo turinys praleidžiamas - tinkle perduodamas tik URL.

§ humanSupport

Laukas	Tipas	Apribojimas	Aprašymas
enabled	boolean		Žmogaus pagalbos (angl. Human Support) eigos jungiklis
email	string	privalomas (griežtai kuriant), kai enabled=true	Adresas, kuriuo gaunami žmogaus pagalbos el. laiškai
dialogMessage	string		Paskatinimo žinutė, rodoma virš formos
thankYouMessage	string		Patvirtinimas, rodomas pateikus formą
emailMessageSubjectTemplate	string		El. laiško, siunčiamo agentui, temos šablonas
emailMessageContentTemplate	string		El. laiško, siunčiamo agentui, teksto šablonas
emailPlaceholder	string		Vietos rezervavimo tekstas el. pašto įvedimo lauke
messagePlaceholder	string		Vietos rezervavimo tekstas žinutės įvedimo lauke
emailWithConversationContent	boolean		Jei true, įtraukti pokalbio nuorašą į el. laiško tekstą
customFormId	long	esamos individualios formos id	Pakeisti integruotą kontaktinę formą individualia forma. Kuriant, praleidus parametrą naudojama integruota forma; atliekant PATCH, null palieka dabartinį pasirinkimą nepakeistą
customFormMapping	string	JSON koduota eilutė	Susieja individualios formos laukus su žmogaus pagalbos el. pašto laukais

requirePolicyAccept yra ties consent.humanSupportRequirePolicyAccept, ne čia.

§ leadCollection

Laukas	Tipas	Apribojimas	Aprašymas
enabled	boolean		Lead formos jungiklis
nameEnabled	boolean		Rinkti vardą
nameLabel	string		Užrašas vardo įvedimo lauke
emailEnabled	boolean		Rinkti el. pašto adresą
emailLabel	string	privalomas (griežtai kuriant), kai enabled=true IR emailEnabled=true	Užrašas el. pašto įvedimo lauke
phoneEnabled	boolean		Rinkti telefono numerį
phoneLabel	string	privalomas (griežtai kuriant), kai enabled=true IR phoneEnabled=true	Užrašas telefono numerio įvedimo lauke
leaveDetailsMessage	string	privalomas (griežtai kuriant), kai enabled=true	Žinutė, skatinanti lankytoją palikti savo kontaktinius duomenis
thankYouMessage	string	privalomas (griežtai kuriant), kai enabled=true	Patvirtinimas, rodomas pateikus formą
requireBeforeNewConversation	boolean		Jei true, forma turi būti pateikta prieš prasidedant pokalbiui; jei false, DI nusprendžia, kada parodyti formą
emailNotificationEnabled	boolean		Siųsti el. laišką savininkui kiekvieną kartą, kai surenkamas lead
emailNotificationAddress	string		Pranešimų gavėjas (pagal numatytuosius nustatymus paskyros el. pašto adresas)
emailWithConversationContent	boolean		Jei true, įtraukti pokalbio nuorašą į pranešimą

| customFormId | long | esamos individualios formos id | Pakeisti integruotą lead formą individualia forma. Kuriant, praleidus parametrą naudojama integruota forma; atliekant PATCH, null palieka dabartinį pasirinkimą nepakeistą | | customFormMapping | string | JSON koduota eilutė | Susieja individualios formos laukus su vardu / el. paštu / telefonu |

Tarpusavio laukų taisyklė kuriant: enabled=true reikalauja bent vieno iš emailEnabled arba phoneEnabled. requirePolicyAccept yra ties consent.leadCollectionRequirePolicyAccept, ne čia.

§ liveChat

Laukas	Tipas	Apribojimas	Aprašymas
enabled	boolean		Live Chat funkcijos jungiklis
infoMessage	string		Paaiškinamoji žinutė prieš perduodant pokalbį
startMessage	string		Žinutė, rodoma prasidėjus tiesioginei sesijai
endMessage	string		Žinutė, rodoma pasibaigus tiesioginei sesijai
nameLabel	string		Užrašas vardo lauke išankstinėje tiesioginio pokalbio formoje
emailLabel	string		Užrašas el. pašto lauke išankstinėje tiesioginio pokalbio formoje
schedule	string	JSON koduota eilutė (savaitės dienų jungikliai + from/to + timezone)	Live Chat darbo grafikas - tikslią struktūrą žr. „Structured fields and ranges"
outOfHoursMessage	string		Žinutė, rodoma ne darbo valandomis pagal grafiką
closeModalMessage	string		Modalinio lango „uždaryti tiesioginį pokalbį?" pavadinimas
closeModalConfirmLabel	string		Patvirtinimo mygtuko užrašas uždarymo modaliniame lange
closeModalCancelLabel	string		Atšaukimo mygtuko užrašas uždarymo modaliniame lange
closeModalTooltipText	string		Pokalbio uždarymo elemento paaiškinimas
operatorHasJoinedLabel	string		Užrašas, rodomas prisijungus operatoriui
operatorDidNotJoinInTimeLabel	string		Užrašas, rodomas, kai operatorius neprisijungia per nustatytą laiką
waitingForOperatorToJoinLabel	string		Užrašas, rodomas laukiant operatoriaus
waitingForOperatorSeconds	int		Laiko limitas, per kurį operatorius turi atsiliepti (sekundėmis)
redirectToHumanSupportForm	boolean		Jei true, nukreipti į Human Support formą, kai joks operatorius neatsiliepia
requireAdminOnline	boolean		Reikalauti pasiekiamo operatoriaus pagal būsenos nustatymus
presenceMode	string		Būsenos režimas; naudokite reikšmę iš boto, sukonfigūruoto naudotojo sąsajoje
hideHumanSupportWhenLiveChatAvailable	boolean		Paslėpti kontaktinę formą, kai prieinamas tiesioginis pokalbis
missedEmailEnabled	boolean	numatytoji reikšmė true	Siųsti el. laišką boto savininkui, kai Live Chat užklausa liko be atsakymo. Senesniuose botuose nebuvo nustatyta, kas traktuojama kaip įjungta

requirePolicyAccept yra ties consent.liveChatRequirePolicyAccept, ne čia.

§ consent

Laukas	Tipas	Apribojimas	Aprašymas
newConversationRequirePolicyAccept	boolean		Reikalauti sutikimo su privatumo politika prieš pradedant naują pokalbį
humanSupportRequirePolicyAccept	boolean		Reikalauti sutikimo su privatumo politika prieš pateikiant žmogaus pagalbos formą
leadCollectionRequirePolicyAccept	boolean		Reikalauti sutikimo su privatumo politika prieš pateikiant lead formą
liveChatRequirePolicyAccept	boolean		Reikalauti sutikimo su privatumo politika prieš pradedant tiesioginio pokalbio sesiją
newConversationConsentDescription	string		Įvadinis tekstas sutikimo ekrane pokalbio pradžioje
privacyPolicyConsentCheckboxLabel	string		Užrašas šalia sutikimo žymimojo langelio (dažniausiai su nuoroda į privatumo politiką)

§ whiteLabel

Laukas	Tipas	Apribojimas	Aprašymas
hideRoboAssistLogo	boolean	White Label galimybė; priklauso nuo paskyros apribojimų	Slėpti numatytąjį ChatLab logotipą poraštėje
whitelabelLogoLink	string	White Label galimybė; priklauso nuo paskyros apribojimų	URL, į kurį veda individualus poraštės logotipas
assignToCustomDomain	boolean	ribojama CUSTOM_DOMAIN funkcijos	Talpinti pokalbį sukonfigūruotame individualiame domene
whitelabelLogoUrl	string	tik skaitymui	Visiškai suformuotas viešasis White Label logotipo URL; norėdami jį pakeisti, įkelkite naudodami kelių dalių whitelabel_logo dalį

Kelių dalių parametras POST/PATCH metu: whitelabel_logo (failo dalis). GET / atsakymo turinyje failo turinys praleidžiamas - tinkle perduodamas tik URL.

§ security

Laukas	Tipas	Apribojimas	Aprašymas
allowedDomains	string		Kableliais atskirtas domenų sąrašas, kuriems leidžiama įterpti valdiklį (tuščias = nėra baltojo sąrašo)
spamFilterEnabled	boolean		Įjungti konkretaus boto gaunamų žinučių apsaugą nuo šlamšto
countryFilterMode	string	BLACKLIST arba WHITELIST	Kaip interpretuojami šalių sąrašai. Patys sąrašai prieinami tik administratoriui
talkMessagesRateLimit	int	>= 0; 0 išjungia	Didžiausias leidžiamas naudotojo žinučių skaičius užklausų ribojimo lange
talkMessagesRateLimitDurationSeconds	int	>= 0	Užklausų ribojimo lango trukmė (sekundėmis)
talkMessagesRateLimitHitMessage	string		Žinutė, rodoma lankytojui pasiekus užklausų limitą

§ voice

Laukas	Tipas	Apribojimas	Aprašymas
inputEnabled	boolean		Leisti lankytojui diktuoti žinutes (balsas į tekstą)
conversationEnabled	boolean	reikalauja balso funkcijos plane	Įjungti visaverčius balso pokalbius
voiceId	string	teikėjui būdingas balso ID (pvz., alloy)	Kuris sintetinis balsas kalba
model	string	pvz., GPT-REALTIME-MINI, GEMINI-LIVE, ELEVENLABS-*	Balso modelis. Apmokestinama už minutę, tarifai skiriasi priklausomai nuo modelio
turnDetection	string	priklauso nuo teikėjo	Replikų kaitos (angl. turn-taking) režimas
audioPrompt	string		Papildomas sistemos raginimas, naudojamas tik balso replikoms
welcomeMessage	string		Sakytinė pradžios frazė
language	string	kalbos kodas	Pagrindinė balso kalba
additionalLanguages	string	kableliais atskirti kalbų kodai	Papildomos kalbos, kurias priima balso agentas
maxDurationSeconds	int		Griežta vieno balso pokalbio trukmės riba
maxDurationMessage	string		Žinutė, rodoma pasiekus laiko limitą

§ multilingual

Laukas	Tipas	Apribojimas	Aprašymas
enabled	boolean		Daugiakalbio režimo jungiklis
mode	string	AUTODETECT arba FIXED_LIST	Kaip botas parenka atsakymo kalbą
baseLanguage	string	kalbos kodas	Kalba, kuria parašyti paties boto tekstai
languages	string	kableliais atskirti kalbų kodai	Lankytojui siūlomos kalbos
knowledgeLanguageMode	string	NONE, MAIN arba DYNAMIC	Kaip elgiamasi su žiniomis kitomis kalbomis
knowledgeLanguageFallback	string	kalbos kodas	Kalba, naudojama neradus atitikmens

§ advanced

Laukas	Tipas	Apribojimas	Aprašymas
model	string	priklauso nuo paskyros apribojimų; žr. „AI text models" aukščiau	LLM identifikatorius (pvz., 5.6-LUNA)
temperature	decimal	0.0-1.0	Imties temperatūra (atitinka sąsajos šliaužiklį)
chatContextSize	int	∈ {8000, 16000, 32000}; automatiškai apribojama iki Jūsų paskyros limito	Sukonfigūruotas konteksto biudžetas, įskaitant nurodymus, istoriją ir žinias
botMessagesLimit	long	0 arba kartotinis iš 1000 (pvz., 1000, 2000, 10000)	Mėnesinė boto žinučių kreditų riba (0 = nėra papildomo boto limito; paskyros biudžetas vis tiek taikomas)
internalLocale	string	lokalės kodas ll_CC formatu	Valdiklio sąsajos etikečių lokalė (skiriasi nuo role.language)
productsViewEnabled	boolean		Jei true, pokalbyje rodomos el. prekybos Offer Cards
includeProductsInKnowledgeBase	boolean		Jei true, produktų katalogas indeksuojamas kaip žinių bazės dalis

Už API ribų

Administratoriaus naudotojo sąsajoje rodomos kelios sritys, kurios šioje Management API versijoje sąmoningai nėra pasiekiamos:

• Apmokymas ir ištrynimas - šios galinės nuorodos neišvardija visų botų, netvarko apmokymo duomenų rinkinių ir netrina botų. Šiems procesams naudokite programėlę.
• Kortelė Flow - vizualus pokalbių eigos redaktorius (angl. Conversation Flow editor: etapai ir perėjimai). Neveikia per Management API.
• Kortelė Actions - valdomos el. prekybos / rezervacijų integracijos, AI Search ir individualios API funkcijos. Įrankių iškvietimas (angl. tool calling) niekada nebuvo Management API dalis.
• Pats individualių formų kūrimo įrankis - individualių formų kūrimas ir redagavimas nėra pasiekiamas per API. Tačiau galite prijungti esamą formą prie boto per leadCollection.customFormId ir humanSupport.customFormId.
• Individualios pokalbio atidarymo / uždarymo piktogramos - customLauncherIconVisible, openChatIcon, closeChatIcon. API pateikia tik pagrindines avatar ir whitelabel_logo kelių dalių dalis.
• IP ir šalių sąrašai - patys įrašai pasiekiami tik administratoriui. Per security.countryFilterMode pateikiamas tik interpretavimo režimas.

Pabaigos taškai (Endpoints)

POST /v1/management/bots

Sukurkite naują robotą. Priimami du lygiaverčiai Content-Type tipai; pasirinkite tą, kuris patogesnis.

A režimas - paprastas JSON (rekomenduojama, kai nereikia tame pačiame užklausoje įkelti avataro / logotipo):

• Content-Type: application/json
• Užklausos turinys yra roboto konfigūracijos JSON (be data apvalkalo)
• Failus (avatarą / logotipą) galima įkelti vėliau per antrąją PATCH užklausą naudojant B režimą

B režimas - multipart/form-data (naudokite, kai failai įkeliami toje pačioje užklausoje):

• Content-Type: multipart/form-data; boundary=...
• data JSON dalis (privaloma, Content-Type: application/json) - roboto konfigūracija anksčiau aprašyta įdėtine struktūra
• avatar failo dalis (pasirenkama) - roboto avataro paveikslėlis
• whitelabel_logo failo dalis (pasirenkama) - prekės ženklo paslėpimo logotipas (taikoma tik jei jūsų paskyroje įtraukta White Label funkcija)

JSON faile privalomas tik name; visiems kitiems laukams taikomos numatytosios reikšmės, kurias nustatytų administratoriaus sąsajos vediklis.

Užklausos turinio pavyzdys

Tai yra maksimalus data JSON - užpildytos visos skiltys. Siųskite tik tas skiltis, kurios jums svarbios; viskam kitam priskiriamos numatytosios reikšmės.

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

Validavimo taisyklės su atitinkamais klaidų pranešimais:

• name - privalomas, ne daugiau kaip 150 simbolių
• advanced.temperature - tarp 0.0 ir 1.0
• chatMemory.summariesToKnowledgeRatio - sveikasis skaičius tarp 10 ir 90 (procentai, žingsnis 10)
• appearance.launcherBottomMargin, appearance.launcherSideMargin - tarp 0 ir 500
• appearance.footerMarkdown - ne daugiau kaip 255 simboliai
• humanSupport.enabled=true reikalauja, kad būtų nustatytas humanSupport.email
• leadCollection.enabled=true reikalauja, kad bent vienas iš leadCollection.emailEnabled arba leadCollection.phoneEnabled būtų nustatytas į true; nepriklausomai nuo to, kuris kanalas įjungtas, taip pat reikalaujama jo etiketės bei leaveDetailsMessage ir thankYouMessage
• advanced.chatContextSize yra apribojamas iki paskyros palaikomo maksimalaus konteksto dydžio. Nemanykite, kad kiti skaitiniai laukai yra automatiškai apribojami.

Laukai, kurių reikšmė serveryje yra null, praleidžiami JSON turinyje - ryšiu perduodami tik tie laukai, kurių reikšmės nėra null.

Atsakymo turinio pavyzdys (201)

Tokia pati struktūra kaip ir užklausos, papildomai įtraukiant tik skaitomą meta bloką ir vienkartinį apiKey aukščiausiame lygyje. Tik skaitomi failų URL (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) serveryje užpildomi tada, kai buvo įkeltos atitinkamos multipart dalys.

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

Laukas apiKey pateikiamas tik sukūrimo metu - tai ką tik sugeneruotas Bot Talk API raktas, susietas su naujuoju robotu. Šis paprasto teksto raktas parodomas vieną kartą ir vėliau jo nebebus galima gauti per API; nedelsdami išsaugokite jį savo sistemoje.

Atsakymo antraštėje Location nurodomas naujojo roboto URL (/v1/management/bots/{id}).

Curl pavyzdžiai

A režimas - paprastas JSON (paprasčiausias variantas):

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 režimas - multipart su avataru:

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}

Pateikia jums priklausančio roboto dabartinę konfigūraciją.

Curl pavyzdys

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

Atsakymo turinio pavyzdys (200)

Tokia pati struktūra kaip ir POST atsakymo, išskyrus vienkartinį apiKey. Įtrauktas meta blokas. Grąžinama 404 not_found_error, jei robotas neegzistuoja arba nepriklauso jūsų paskyrai.

Dabartinis avataras ir prekės ženklo paslėpimo logotipas pateikiami kaip pilnos formos tik skaitomi URL adresai (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) - prasidedantys ta pačia schema + serverio adresu (host) + konteksto keliu, kurie aptarnavo šią užklausą. Gaukite baitus siųsdami GET užklausą tiesiogiai šiais URL; norėdami pakeisti bet kurį failą, įkelkite naują per multipart dalį avatar / whitelabel_logo naudodami PATCH užklausą. Šių URL laukų reikšmės ignoruojamos, jei jos siunčiamos užklausos turinyje.

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

Boto klonavimas

Užklausos POST /v1/management/bots pagrindinė dalis ir atsakymo GET /v1/management/bots/{bot_id} pagrindinė dalis turi tokią pačią struktūrą, todėl klonavimas yra trijų žingsnių procesas: gaukite šaltinio duomenis per GET, pašalinkite serverio valdomus tapatybės laukus ir išsiųskite rezultatą per POST.

1. Gaukite šaltinio boto duomenis per GET.

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

2. Pašalinkite aukščiausio lygio meta bloką. meta objektas (id, createdAt, updatedAt) yra valdomas serverio ir skirtas tik skaitymui - jo palikimas POST kūne žalos nepadarys (serveris jį ignoruoja), tačiau jo pašalinimas aiškiai nurodo ketinimą ir išlaiko duomenis švarius. Jei norite, pakeiskite name, kad klonas skirtųsi nuo šaltinio.

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

3. Išsiųskite išvalytą pagrindinę dalį per POST, kad sukurtumėte kloną. Visą kūno struktūrą ir patvirtinimo taisykles rasite aukščiau esančioje POST /v1/management/bots specifikacijoje.

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

Atsakyme pateikiamas naujojo boto meta.id ir naujai sugeneruotas apiKey (klono Bot Talk raktas). Paprasto teksto apiKey grąžinamas tik šiame sukūrimo atsakyme - nukopijuokite jį prieš uždarydami atsakymo tekstą; vėliau jo gauti nebebus įmanoma.

Taip nukopijuojami palaikomi nustatymai, o ne visiškai apmokytas pokalbių robotas. Šios galinės nuorodos neklonuoja mokymo turinio, pokalbių istorijos, integracijų / veiksmų, Flow ir formų apibrėžimų. Juos sukonfigūruokite atskirai programėlėje.

Papildomi svarbūs aspektai:

• Failai nėra klonuojami. appearance.avatarUrl ir whiteLabel.whitelabelLogoUrl yra skirti tik skaitymui ir nukreipia į šaltinio boto failus. Jei klone reikia to paties pseudoportreto ar White Label logotipo, atsisiųskite failus iš šaltinio URL adresų ir įkelkite juos kaip sudėtines dalis avatar / whitelabel_logo - sukūrimo POST užklausoje (B režimas) arba vėlesnėje PATCH užklausoje.
• Bot Talk raktai nėra klonuojami. Kiekvienas botas turi savo Bot Talk raktų rinkinį. Vienintelis apiKey, grąžinamas sukūrimo POST užklausa, yra sugeneruojamas automatiškai; jei reikia papildomų raktų, sukurkite juos boto API skirtuke.

PATCH /v1/management/bots/{bot_id}

Atnaujinkite vieną ar kelis jums priklausančio boto laukus. Keičiamos tik JSON nurodytos skiltys / laukai; visa kita, kas praleista (arba atsiųsta kaip null), lieka nepakeista. Išsiųstoje skiltyje dalinio atnaujinimo taisyklės taikomos kiekvienam laukui atskirai.

Priimami du lygiaverčiai Content-Type tipai (taip pat, kaip ir POST):

A režimas - grynas JSON (rekomenduojama atnaujinant tik nustatymus):

• Content-Type: application/json
• Užklausos pagrindinė dalis yra pataisos JSON (be data apvalkalo)

B režimas - multipart/form-data (naudokite įkeldami failus):

• data JSON dalis (neprivaloma) - pakeitimas. Siųskite tik tuo atveju, jei norite pakeisti laukus. Visiškai praleiskite, jei norite tik įkelti pseudoportretą ar logotipą.
• avatar failo dalis (neprivaloma) - pakeiskite pseudoportretą
• whitelabel_logo failo dalis (neprivaloma) - pakeiskite White Label logotipą (galioja tik tuo atveju, jei Jūsų paskyroje įtraukta ši funkcija)

Visos trys dalys PATCH užklausoje yra neprivalomos, tačiau bent viena turi būti pateikta, kad iškvietimas turėtų prasmę.

Užklausos pagrindinės dalies pavyzdys (kelios skiltys)

Čia galima siųsti bet kurį lauką, kurį priima POST /v1/management/bots. Toliau pateiktame pavyzdyje parodytos kelios skiltys, o ne visi palaikomi laukai; praktikoje siunčiate tik tuos raktus, kuriuos norite pakeisti (žr. toliau „Minimalus dalinis atnaujinimas") - kiekvienas praleistas raktas (arba atsiųstas kaip null) palieka išsaugotą reikšmę nepaliestą.

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

Minimalus dalinis atnaujinimas

Atnaujinkite vieną lauką naudodami PATCH, siųsdami būtent tuos raktus, kuriuos norite pakeisti - visa kita bus išsaugota.

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

Curl pavyzdžiai

A režimas - paprastas JSON (paprasčiausias būdas):

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 režimas - multipart (keičiant pseudoportretą / logotipą):

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 režimas - tik pseudoportreto keitimas (laukai nekeičiami):

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

Atsakymo pagrindinė dalis (200)

Tokia pati struktūra kaip GET /v1/management/bots/{bot_id} - visa boto konfigūracija pritaikius pakeitimus, įskaitant meta bloką. Be apiKey lauko. Grąžina 404 not_found_error, jei botas neegzistuoja arba nepriklauso Jūsų paskyrai.

Toliau pateiktame pavyzdyje rodomas atsakymas pritaikius aukščiau pateiktą Visos užklausos pagrindinės dalies (kelios skiltys) pakeitimą botui iš GET pavyzdžio - pakeisti laukai rodo naujas reikšmes, nepaliesti laukai išsaugomi, o meta.updatedAt atnaujinamas.

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

Gaukite paskyros, kuriai priklauso Management raktas, dabartinį prenumeratos naudojimą.

Atsakymo pagrindinė dalis (200)

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

• subscriptionType yra paskyros dabartinio plano identifikatorius mažosiomis raidėmis (your-plan-id yra tik pavyzdinis vietos rezervavimo ženklas). Planai pateikiami iš dinaminio katalogo, todėl tikslus identifikatorių rinkinys laikui bėgant gali keistis pervadinant arba pridedant planus - vertinkite tai kaip nepermatomą eilutę, o ne fiksuotą sąrašą.
• messages.used / limit / remaining rodo dabartinio kalendorinio mėnesio žinučių kreditus, kurie atstatomi pirmąją mėnesio dieną, o ne prenumeratos atnaujinimo dieną. Jie skaičiuojami pagal kreditų svorį, o ne kaip grynasis atsakymų skaičius.
• bots.used / limit / remaining skaičiuoja turimus botus, įskaitant pristabdytus botus, pagal Jūsų paskyros bendrą botų limitą.

Užklausų ribojimo antraštės

Atsakymai, pasiekiantys užklausų ribojimo (angl. rate-limit) etapą (t. y. autentifikacija ir IP baltasis sąrašas sėkmingai patikrinti), apima:

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

• X-RateLimit-Limit - šiam iškvietimui faktiškai taikoma vieno rakto riba (pagal numatytuosius nustatymus 10, arba jūsų sukonfigūruota rateLimitPerMinute, jei ji mažesnė).
• X-RateLimit-Remaining - žetonai (angl. tokens), likę talpykloje iškart po šio iškvietimo.
• X-RateLimit-Reset - „Unix epoch“ laikas sekundėmis, kada taps prieinamas kitas žetonas (tai nėra visiškas talpyklos atstatymas; talpykla pildoma nuolat). Kai talpykla pilna, tai yra dabartinis laikas.

Esant 429 rate_limit_exceeded atsakymams, taip pat nustatoma antraštė Retry-After, nurodyta sveikomis sekundėmis, kol atsilaisvins bent vienas žetonas.

Iki autentifikavimo įvykusios klaidos (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) ir 403 ip_not_whitelisted neturi X-RateLimit-* antraščių - užklausų ribotuvas tikrinamas tik sėkmingai praėjus autentifikavimo ir IP patikras.

Klaidų formatas

Toks pat apvalkalas kaip ir Bot Talk API:

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

Validavimo klaidose naudojamas code: "invalid_parameter" ir pranešimo pradžioje pridedamas klaidingo lauko kelias, kad klaidingą vietą būtų lengva pastebėti:

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

Neteisingos reikšmės išvardijimo / uždaros aibės laukams (pvz., chatMemory.clientSummaryPromptType = "BOGUS") apima lauko kelią, atmestą reikšmę ir leidžiamų reikšmių sąrašą:

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

Susijusi informacija

Informacijos apie pokalbių galinius taškus ir SSE srautinį perdavimą ieškokite Bot Talk API.