Pagalbos centras
Chat API

Management API

Paskutinį kartą atnaujinta:

Management API apžvalga

Management API skirtas vidiniams sistemos (back-office) darbams, kurie neapima pokalbio pranešimų siuntimo:

  • kurti robotą programiniu būdu naudojant POST /v1/management/bots
  • peržiūrėti konkretų jums priklausantį robotą naudojant GET /v1/management/bots/{bot_id}
  • atnaujinti konkretų robotą naudojant PATCH /v1/management/bots/{bot_id}
  • peržiūrėti prenumeratos naudojimą 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 pažeistas pokalbių raktas negalėtų modifikuoti jūsų robotų ar skaityti sąskaitų duomenų.

Bazinis URL

https://api.chatlab.com/aichat

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

Darbo pradžia

  1. Atidarykite administratoriaus 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 leidžiamų IP adresų sąrašą (whitelist) bei užklausų limitą (rate limit) ir patvirtinkite.
  3. Nukopijuokite visą raktą iš sėkmės pranešimo lango. Neužšifruotas tekstas rodomas tik vieną kartą.

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

Autentifikavimas

Authorization: Bearer mk_abcdefghijklmnopqrstuvwxyz012345

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

Apribojimai

  • Ne daugiau kaip 5 aktyvūs Management API raktai vienam naudotojui
  • Ne daugiau kaip 10 užklausų per minutę vienam raktui (pildomo krepšelio algoritmas [token bucket], talpa 10, tolygus papildymas po maždaug 1 žetoną kas 6 sekundes). Galima sumažinti kūrimo metu - nustatykite mažesnį rateLimitPerMinute, viršutinė riba sumažės, o pildymo greitis proporcingai prisitaikys.

Leidimai

Kiekvienas Management raktas turi bet kurį iš trijų toliau nurodytų leidimų poaibių. Kuriant raktą privaloma pasirinkti bent vieną leidimą; priešingu atveju užklausa atmetama pateikiant klaidą 400 invalid_request_error. Iškvietus galinį tašką su raktu, neturinčiu 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ėtiniai skyriai, atitinkantys administratoriaus sąsajos skirtukus

POST ir PATCH priima JSON turinį, suskirstytą į 13 skyrių. Kiekvienas skyrius atitinka poskirtukį administratoriaus programėlės nustatymų šoninėje juostoje Bot Settings, todėl JSON raktai ir matomi skirtukai sutampa: jei per API pakeisite consent.humanSupportRequirePolicyAccept, pamatysite, kad tas pats perjungiklis pasikeičia administratoriaus programėlės skirtuke Consent & Privacy (Sutikimas ir privatumas).

  • role - roboto personažas, pradinis raginimas (raw prompt), atsakymo ilgis, kalba, svetainės / įmonės kontekstas (skirtukas Role & Behavior [Vaidmuo ir elgsena])
  • conversation - pasveikinimo pranešimas, užklausos patikslinimas, pokalbio tęstinumas, įvertinimo perjungiklis + paaiškinimai, siūlomų klausimų turinys + dinaminiai tolesni veiksmai (skirtukas Chat Conversation [Pokalbis])
  • chatMemory - pokalbių atminties perjungiklis, santraukų raginimai, konteksto paskirstymas (skirtukas Summaries & Memory [Santraukos ir atmintis])
  • appearance - spalvos, tekstai, matmenys, pasirinktinis CSS, pradinis 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ų rinkimo forma (skirtukas Lead Collection [Kontaktų rinkimas])
  • liveChat - perleidimas į tiesioginį pokalbį (skirtukas Live Chat)
  • consent - visi keturi privatumo politikos sutikimo perjungikliai ir sutikimo ekrano tekstas (skirtukas Consent & Privacy [Sutikimas ir privatumas])
  • whiteLabel - logotipo slėpimas, pasirinktinė logotipo nuoroda, talpinimas nuosavame domene (skirtukas Whitelabel)
  • security - leidžiami domenai, šlamšto filtras, pokalbių užklausų limitai (skirtukas Security [Sauga])
  • voice - balso įvestis ir pokalbiai balsu: modelis, balsas, kalbos, raginimas, trukmės riba (skirtukas Voice Conversation [Pokalbis balsu])
  • multilingual - daugiakalbis režimas, pagrindinė kalba, siūlomos kalbos, žinių bazės kalbų apdorojimas (skirtukas Languages [Kalbos])
  • advanced - LLM modelis, temperatūra, konteksto dydis, roboto pranešimų limitas, vidinė lokalė, Offer Cards (skirtukas Model & Advanced [Modelis ir išplėstiniai nustatymai])

Tik name yra aukščiausiame lygyje, nes jis identifikuoja patį robotą, o nepriklauso jokiam atskiram skirtukui.

Šoninėje juostoje Bot Settings šiuo metu yra 15 poskirtukių, iš kurių 13 atitinka aukščiau nurodytus skyrius. Du poskirtukiai, neturintys atitinkamo skyriaus, yra Flow ir Actions - abu aptariami toliau skyriuje „Neįtraukta į API apimtį“. 13 atitinkančių poskirtukių 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 tą pačią struktūrą. Atsakyme papildomai pateikiami du elementai:

  • meta - tik skaitomas: roboto id ir laiko žymos. Pašalinkite šį elementą, kad paverstumėte GET atsakymą galiojančiu POST turiniu.
  • apiKey - pateikiamas tik sukūrimo metu - ką tik naujam robotui sugeneruotas Bot Talk API raktas.

Du laukai bendroje struktūroje yra tik skaitomi - grąžinami atsakyme, tačiau ignoruojami, jei bandote 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ų (multipart) dalį avatar (ž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ų dalį whitelabel_logo (žr. PATCH).

Abu URL naudoja esamos užklausos schemą + pagrindinį kompiuterį (host) + konteksto kelią, todėl naudojant White Label pasirinktinį domeną jie grąžinami su to domeno šaknimi (pvz., https://api.acme.com/aichat/content/...).

Norėdami praleisti skyrių vykdydami PATCH, nurodykite null; norėdami praleisti vieną lauką skyriuje, nurodykite null tam konkrečiam laukui. Lauko lygiu nurodytas null niekada neištrina išsaugotos vertės - tai reiškia tik „neliesti“.

Vaidmuo ir raginimo sudarymas

Sisteminis raginimas, kurį faktiškai gauna LLM, sukuriamas vienu iš dviejų būdų, priklausomai nuo role.role. Žinodami, kurioje atšakoje esate, suprasite, kurie laukai yra svarbūs, o kurie išsaugomi, bet ignoruojami.

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

Galinė sistema surenka raginimą iš integruoto šablono ir visiškai ignoruoja role.rawPrompt (vertė vis tiek išsaugoma robote, tik nenaudojama). Į šabloną įtraukiama:

  • role.role - vaidmens etiketė (pvz., „Customer Support“) ir automatiškai pridedamos konkrečiam vaidmeniui skirtos instrukcijos
  • name - roboto pavadinimas, įterpiamas į įvadinį sakinį
  • role.language - parinktis "Auto Detect" nustato robotą prisitaikyti prie naudotojo kalbos; bet kuri kita vertė (pvz., "English", "Polish") virsta instrukcija „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 - neprivaloma; jei laukas neužpildytas, pridedama kaip „for the users of the website {url}“
  • role.companyDescription - neprivaloma; jei laukas neužpildytas, pridedama kaip papildoma pastraipa prieš vaidmens instrukcijas

Tai yra rekomenduojama atšaka daugumai robotų - be papildomų pastangų gaunate konkrečiam vaidmeniui pritaikytą elgseną ir apsauginius apribojimus.

B atšaka - role.role yra CUSTOM (iškvietėjo pateiktas raginimas)

Galinė sistema naudoja role.rawPrompt pažodžiui kaip visą sisteminį raginimą. Laukai responseLength, language, websiteAddress, companyDescription yra išsaugomi, bet nėra įterpiami į raginimą - jei norite, kad kuris nors iš jų atsispindėtų roboto elgsenoje, turite patys juos įtraukti į savo rawPrompt tekstą. Konkrečiam vaidmeniui skirti saugos apribojimai ir tono nurodymai taip pat nepridedami; visą raginimą valdote patys.

Naudokite CUSTOM tik tada, kai šablonu pagrįstas raginimas netinka jūsų atvejui (pvz., jums reikia labai specifinės srities personažo, savų saugos apribojimų, nestandartinio išvesties formato).

Enum / fiksuotų verčių rinkinio laukai

Keli laukai priima tik fiksuotą eilučių verčių rinkinį. Atsiuntus bet kokią reikšmę, neesančią sąraše, užklausa atmetama su klaida 400 validation_failed, o lauko kelias nurodomas error.param. Reikšmėse skiriamos didžiosios ir mažosios raidės.

  • 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ų. Vertė išsaugoma pažodžiui ir įterpiama į raginimo šabloną, todėl dviejų raidžių ISO kodai (en, pl) ir kitos sąraše nesančios reikšmės nėra atmetamos API, tačiau sukuria iškraipytą instrukciją, pvz., „Output in en, unless...“. Kuriant ir nenurodžius reikšmės, numatytoji vertė yra Auto Detect.
  • advanced.model - žr. skyrių „DI teksto modeliai“ toliau; pasirenkamas rinkinys priklauso nuo jūsų paskyros apribojimų, o nurodžius modelį, kurio jūsų paskyra negali naudoti, grąžinama klaida 400 invalid_parameter
  • advanced.chatContextSize - 8000, 16000, 32000. Priklauso nuo jūsų paskyros apribojimų; didesnės vertės automatiškai sumažinamos iki leistinos ribos
  • chatMemory.clientSummaryPromptType - DEFAULT, CUSTOM
  • chatMemory.conversationSummaryPromptType - DEFAULT, CUSTOM
  • appearance.chatAlignment - left, right
  • appearance.minimizedDisplayMode - icon, minified
  • appearance.chatMessageLinkTarget - _blank, _self
  • leadCollection.requireBeforeNewConversation - loginis (boolean) perjungiklis. true priverčia naudotoją užpildyti kontaktų formą prieš pradedant pokalbį; false leidžia DI pačiam nuspręsti, kada pateikti formą (numatytoji parinktis).

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 - leistinas rėžis yra nuo 0.0 iki 1.0, atitinkantis slankiklį administratoriaus sąsajoje. Vertės už šio rėžio ribų atmetamos su klaida 400 validation_failed.

  • chatMemory.summariesToKnowledgeRatio - sveikasis skaičius procentais, 10-90 kas 10. Valdo, kiek pokalbio konteksto skiriama kliento ankstesnėms santraukoms, palyginti su likusia dalimi (žinių baze, dabartiniu pokalbiu, instrukcijomis). Numatytoji vertė yra 50. Vertės už 10-90 ribų atmetamos su klaida 400 validation_failed. Taikoma tik tada, kai chatMemory.enabled=true IR chatMemory.summaryConversationsEnabled=true.

  • 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 išanalizuoja ją kliento pusėje, kai atvaizduoja tvarkaraščio redaktorių. Išanalizavus, eilutė turi vieną įrašą kiekvienai savaitės dienai ir raktą timezone:

    • kiekvienas 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")

    Reikšmės pavyzdys (atkreipkite dėmesį į išorines kabutes ir apsaugotas vidines kabutes - tai yra 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 rodomas liveChat.outOfHoursMessage, o perleidimas į tiesioginį pokalbį yra blokuojamas. Vidinės struktūros patikra atliekama tik kliento pusėje administratoriaus sąsajoje - netinkamai suformuotas JSON arba neatpažinti raktai API priimami tiesiog kaip eilutė, o atvaizdavimo klaida pasirodys vėliau, žmogui atidarius robotą administratoriaus skydelyje. Prieš siųsdami patikrinkite struktūrą savo pusėje.

  • conversation.positiveRatingTooltip / conversation.negativeRatingTooltip - trumpi užrašai, rodomi ant 👍 / 👎 mygtukų šalia kiekvieno DI atsakymo, 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 apribojimų. Paslepia poraštės eilutę „Powered by ChatLab“. Jei jūsų paskyroje nėra White Label funkcijos, reikšmė išsaugoma, bet ignoruojama, o poraštė rodoma visada.

  • whiteLabel.whitelabelLogoLink - White Label funkcija, priklausanti nuo jūsų paskyros apribojimų. Pasirinktinio logotipo paspaudimo tikslinis URL, kai hideRoboAssistLogo=true ir pasirinktinis logotipo failas įkeliamas per whitelabel_logo kelių dalių parametrą.

  • 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 vertė yra 5.

  • appearance.autoOpenChatDelaySeconds - sekundės, sveikasis skaičius. Delsa prieš automatinį valdiklio atidarymą, kai autoOpenChat=true ir autoOpenChatDelay=true.

  • advanced.internalLocale - IETF lokalės ir regiono kodas formatu ll_CC (su pabraukimo brūkšniu, NE ll-CC su brūkšneliu). Priimamos reikšmės iš fiksuoto maždaug 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 vertė yra en_US. Ši lokalė naudojama datų ir skaičių formatavimui valdiklio sąsajoje ir skiriasi nuo role.language (roboto pokalbio išvesties kalbos).

  • security.talkMessagesRateLimit / security.talkMessagesRateLimitDurationSeconds - sveikieji skaičiai (siųskite kaip JSON skaičius, pvz., 30, o ne "30"). 0 išjungia užklausų limitą pagal IP. Nustačius nelygų nuliui, valdiklis taiko N žinučių limitą per nurodytą trukmę sekundėmis, prieš parodydamas lankytojui security.talkMessagesRateLimitHitMessage.

  • advanced.botMessagesLimit - sveikasis skaičius (JSON skaičius, pvz., 1000). 0 reiškia „be limito“; priešingu atveju turi būti 1000 kartotinis (1000, 2000, 10000, ...). Tokios reikšmės kaip 100 ar 1500 atmetamos su klaida 400 validation_failed. Vėliau reikšmė dar automatiškai apribojama pagal jūsų paskyros limitą.

DI teksto modeliai (advanced.model)

Siųskite tikslią API vertę (kairysis stulpelis su formatavimu). Rodomas pavadinimas administratoriaus sąsajoje pateiktas skliausteliuose. Jūsų paskyros limitai nustato, kurį poaibį galima pasirinkti; nurodžius modelį, kurio jūsų paskyra negali naudoti, grąžinama klaida 400 invalid_parameter. Naujų robotų numatytoji parinktis yra 5-MINI.

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

Laukų aprašas (visa užklausos schema)

Kiekvienas tinklu perduodamas laukas kartu su jo tipu, apribojimais ir vienos eilutės aprašymu. PATCH semantika: bet kuris praleistas (arba kaip null pateiktas) laukas palieka išsaugotą reikšmę nepakeistą. Ta pati struktūra naudojama ir atsakyme (atmetus kelių dalių dvejetainį turinį; prie kiekvieno atsakymo pridedamas tik skaitomas blokas meta, o apiKey pateikiamas tik kūrimo atsakyme).

Aukščiausias lygis

Laukas Tipas Apribojimas Aprašymas
name string maks. 150, privalomas kuriant Rodomas boto pavadinimas
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

Papildomi laukai 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 šablonas; parenka prompt šabloną (žr. „Role and prompt construction“)
language string visas kalbos pavadinimas anglų kalba (English, Polish, ...) arba Auto Detect Pagrindinė kalba, perduodama į prompt šabloną
responseLength string ∈ {Concise, Normal, Detailed} Pageidaujamas DI atsakymo išsamumas
websiteAddress string Svetainė, naudojama prompt kontekstui
companyDescription string Įmonės aprašymas, naudojamas prompt kontekstui
rawPrompt string Pasirinktinis sistemos prompt - pažodžiui naudojamas 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įžtantys lankytojai pratęsia savo paskutinį pokalbį
conversationRatingEnabled boolean Jei true, prie boto žinučių rodo vertinimą nykščiu aukštyn / žemyn
positiveRatingTooltip string Teigiamo įvertinimo mygtuko paaiškinimas
negativeRatingTooltip string Neigiamo įvertinimo mygtuko paaiškinimas
suggestedQuestions string Eilutėmis atskirti siūlomi klausimai / pokalbio pradžios frazės
dynamicSuggestedFollowups boolean Jei true, po kiekvieno atsakymo DI pasiūlo tolesnius klausimus
dynamicFollowupsAutoIcons boolean Jei true, DI automatiškai parenka jaustukų piktogramas dinaminiams pasiūlymams

§ chatMemory

Laukas Tipas Apribojimas Aprašymas
enabled boolean Pagrindinis pokalbių atminties funkcijos jungiklis
summaryConversationsEnabled boolean Išsaugoti atskirų pokalbių santraukas
conversationSummaryPrompt string Pasirinktinis prompt, naudojamas kiekvienam pokalbiui apibendrinti
conversationSummaryPromptType string (enum) ∈ {DEFAULT, CUSTOM} Ar naudoti numatytąjį, ar pasirinktinį santraukos prompt
clientSummaryPrompt string Pasirinktinis prompt, naudojamas kliento profilio santraukai per visus pokalbius sudaryti
clientSummaryPromptType string (enum) ∈ {DEFAULT, CUSTOM} Numatytasis ar pasirinktinis kliento profilio prompt
summariesToKnowledgeRatio int 10-90, žingsnis 10 Pokalbio konteksto lango dalis (%), skirta santraukoms, palyginti su RAG žiniomis

§ appearance

Laukas Tipas Apribojimas Aprašymas
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 Paantraštė, rodoma po pokalbio pavadinimu
senderPlaceholder string Vietos rezervavimo tekstas žinutės įvesties lauke
resetConversationTooltip string Mygtuko „reset conversation“ (išvalyti 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 Grynas CSS, įterpiamas į valdiklio iframe
chatMessageLinkTarget string (enum) ∈ {_blank, _self} Kaip atidaromos nuorodos boto žinutėse
minimizedDisplayMode string (enum) ∈ {icon, minified} Sutraukta būsena: paleidiklio piktograma arba kompaktiška siuntėjo juosta
chatDesktopWidthPx int Valdiklio plotis kompiuterio ekrane
chatDesktopHeightPx int Valdiklio aukštis kompiuterio ekrane
chatMobileSizePercent int Mobiliojo valdiklio dydis ekrano srities procentais
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 Vaizduoti pasirinktinę paleidiklio piktogramą per visą plotą be paraščių
welcomeScreenEnabled boolean Rodyti Welcome Screen (pasveikinimo ekraną) užuot iškart atidarius pokalbį
welcomeScreenQuestionsLabel string Užrašas virš siūlomų klausimų pasveikinimo ekrane
welcomeScreenHideHumanContactForm boolean Slėpti susisiekimo su žmogumi 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 DROPDOWN Kaip Live Chat ir susisiekimo su žmogumi forma pateikiami pokalbio antraštėje: ICONS (kiekvienam po atskirą piktogramą) arba DROPDOWN (sugrupuoti antraštės meniu). Botams, sukurtiems iki 2026-09-02, numatytoji reikšmė yra ICONS
stackSuggestedQuestions boolean Išdėstyti siūlomus klausimus vertikaliai vieną po kito (vietoj išdėstymo greta)
suggestedQuestionsFontSize int Siūlomų klausimų kortelių šrifto dydis (px)
suggestedQuestionsTextColor string (hex) Siūlomų klausimų kortelių teksto spalva
suggestedQuestionsBackgroundColor string (hex) Siūlomų klausimų kortelių fono spalva
autoOpenChat boolean Automatiškai atidaryti pokalbį kompiuterio ekrane
autoOpenChatOnMobiles boolean Automatiškai atidaryti pokalbį mobiliajame įrenginyje
autoOpenChatDelay boolean Taikyti delsą prieš automatinį atidarymą
autoOpenChatDelaySeconds int Automatinio atidarymo delsa (sekundėmis)
simulateHumanTyping boolean Skaidyti boto atsakymą į kelis debesėlius su rašymo animacija
simulateHumanTypingDelay int 0-200 Delsa tarp žinučių debesėlių (sekundėmis)
footerMarkdown string maks. 255 Pasirinktinis poraštės markdown tekstas, rodomas po pokalbiu
avatarUrl string tik skaitymui Pilnas viešas avataro URL; norėdami jį pakeisti, įkelkite naudodami kelių dalių dalį avatar

Kelių dalių užklausa POST/PATCH metu: avatar (failo dalis). GET / atsakymo kūne failo turinys praleidžiamas - perduodamas tik URL.

§ humanSupport

Laukas Tipas Apribojimas Aprašymas
enabled boolean Žmogaus pagalbos proceso 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 Agentui siunčiamo el. laiško temos šablonas
emailMessageContentTemplate string Agentui siunčiamo el. laiško teksto šablonas
emailPlaceholder string Vietos rezervavimo tekstas el. pašto įvesties lauke
messagePlaceholder string Vietos rezervavimo tekstas žinutės teksto lauke
emailWithConversationContent boolean Jei true, į el. laiško tekstą įtraukti pokalbio išklotinę
customFormId long esamos pasirinktinės formos id Pakeisti integruotą kontaktų formą pasirinktine forma. null palieka integruotą formą
customFormMapping string JSON koduotės eilutė Susieja pasirinktinės formos laukus su žmogaus pagalbos el. laiško laukais

requirePolicyAccept yra ties consent.humanSupportRequirePolicyAccept, o ne čia.

§ leadCollection

Laukas Tipas Apribojimas Aprašymas
enabled boolean Kontaktų rinkimo formos jungiklis
nameEnabled boolean Rinkti vardą
nameLabel string Vardo įvesties lauko etiketė
emailEnabled boolean Rinkti el. pašto adresą
emailLabel string privalomas (griežtai kuriant), kai enabled=true IR emailEnabled=true El. pašto įvesties lauko etiketė
phoneEnabled boolean Rinkti telefono numerį
phoneLabel string privalomas (griežtai kuriant), kai enabled=true IR phoneEnabled=true Telefono įvesties lauko etiketė
leaveDetailsMessage string privalomas (griežtai kuriant), kai enabled=true Žinutė, raginanti lankytoją palikti savo duomenis
thankYouMessage string privalomas (griežtai kuriant), kai enabled=true Patvirtinimas, rodomas pateikus formą
requireBeforeNewConversation boolean Jei true, formą privaloma pateikti prieš prasidedant pokalbiui; jei false, DI nusprendžia, kada pateikti formą
emailNotificationEnabled boolean Siųsti el. laišką savininkui kaskart surinkus kontaktą
emailNotificationAddress string Pranešimų gavėjas (pagal nutylėjimą - paskyros el. paštas)
emailWithConversationContent boolean Jei true, į pranešimą įtraukti pokalbio išklotinę

Kelių laukų taisyklė kuriant: esant enabled=true, privaloma įjungti bent vieną iš emailEnabled arba phoneEnabled. requirePolicyAccept yra ties consent.leadCollectionRequirePolicyAccept, o ne čia.

| customFormId | long | esamos pasirinktinės formos id | Pakeisti integruotą kontaktų rinkimo formą pasirinktine forma. null palieka integruotą formą | | customFormMapping | string | JSON koduotės eilutė | Susieja pasirinktinės formos laukus su vardo / el. pašto / telefono laukais |

§ liveChat

Laukas Tipas Apribojimas Aprašymas
enabled boolean Live Chat funkcijos jungiklis
infoMessage string Paaiškinamoji žinutė prieš perleidžiant pokalbį
startMessage string Žinutė, rodoma prasidėjus tiesioginio pokalbio seansui
endMessage string Žinutė, rodoma pasibaigus tiesioginio pokalbio seansui
nameLabel string Vardo įvesties lauko etiketė tiesioginio pokalbio pradinėje formoje
emailLabel string El. pašto įvesties lauko etiketė tiesioginio pokalbio pradinėje formoje
schedule string JSON koduotės eilutė (savaitės dienų jungikliai + from/to + timezone) Tiesioginio pokalbio darbo grafikas - tikslią struktūrą žr. „Structured fields and ranges“
outOfHoursMessage string Žinutė, rodoma ne darbo valandomis pagal grafiką
closeModalMessage string Modalinio lango „close live chat?“ (uždaryti tiesioginį pokalbį?) pavadinimas
closeModalConfirmLabel string Patvirtinimo mygtuko etiketė uždarymo modaliniame lange
closeModalCancelLabel string Atšaukimo mygtuko etiketė 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 operatoriui atsiliepti (sekundėmis)
redirectToHumanSupportForm boolean Jei true, nukreipti į Human Support formą, kai joks operatorius neatsiliepia
missedEmailEnabled boolean numatytoji reikšmė true Siųsti el. laišką boto savininkui, kai tiesioginio pokalbio užklausa liko neatsakyta. Senesniuose botuose ši reikšmė nenustatyta, kas traktuojama kaip įjungta

requirePolicyAccept yra ties consent.liveChatRequirePolicyAccept, o 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 kontaktų rinkimo formą
liveChatRequirePolicyAccept boolean Reikalauti sutikimo su privatumo politika prieš pradedant tiesioginį pokalbį
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 funkcija; taikomi paskyros limitai Slėpti numatytąjį ChatLab logotipą poraštėje
whitelabelLogoLink string White Label funkcija; taikomi paskyros limitai URL, į kurį veda pasirinktinis poraštės logotipas
assignToCustomDomain boolean ribojama funkcijos CUSTOM_DOMAIN Talpinti pokalbį sukonfigūruotame nuosavame domene
whitelabelLogoUrl string tik skaitymui Pilnas viešas White Label logotipo URL; norėdami jį pakeisti, įkelkite naudodami kelių dalių dalį whitelabel_logo

Kelių dalių užklausa POST/PATCH metu: whitelabel_logo (failo dalis). GET / atsakymo kūne failo turinys praleidžiamas - perduodamas tik URL.

§ security

Laukas Tipas Apribojimas Aprašymas
allowedDomains string Kableliais atskirtas domenų, kuriuose leidžiama įterpti valdiklį, sąrašas (tuščias = nėra baltojo sąrašo)
spamFilterEnabled boolean Įjungti konkretaus boto gaunamų žinučių apsaugos nuo šlamšto filtrą
countryFilterMode string BLACKLIST arba WHITELIST Kaip interpretuojami šalių sąrašai. Patys sąrašai prieinami tik administratoriui
talkMessagesRateLimit int >= 0; 0 išjungia Maksimalus naudotojo žinučių skaičius per užklausų ribojimo langą
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 balsu (kalba į tekstą)
conversationEnabled boolean plane reikalinga balso funkcija Įjungti pilnus pokalbius balsu
voiceId string teikėjo nurodytas balso id (pvz., alloy) Kuris sintetinis balsas kalba
model string pvz., GPT-REALTIME-MINI, GEMINI-LIVE, ELEVENLABS-* Balso modelis. Apvaldoma už minutes, tarifai skiriasi priklausomai nuo modelio
turnDetection string priklauso nuo teikėjo Kalbėjimo eiliškumo nustatymo režimas
audioPrompt string Papildomas sistemos prompt, naudojamas tik balso replikoms
welcomeMessage string Įgarsinta pasveikinimo 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 fiksuoto sąrašo režimas Kaip botas pasirenka 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 Kaip traktuojamos žinios kitomis kalbomis
knowledgeLanguageFallback string kalbos kodas Kalba, naudojama neradus atitikmens

§ advanced

Laukas Tipas Apribojimas Aprašymas
model string taikomi paskyros limitai; žr. aukščiau „AI text models“ LLM identifikatorius (pvz., 5-MINI)
temperature decimal 0.0-1.0 Diskretizavimo temperatūra (atitinka sąsajos slankiklį)
chatContextSize int ∈ {8000, 16000, 32000}; automatiškai apribojama iki jūsų paskyros limito Prieigos raktų langas pokalbių istorijai
botMessagesLimit long 0 arba 1000 kartotinis (pvz., 1000, 2000, 10000) Maksimalus boto atsakymų skaičius viename pokalbyje (0 = be apribojimų)
internalLocale string lokalės kodas pavidalu ll_CC Valdiklio sąsajos elementų lokalė (skiriasi nuo role.language)
productsViewEnabled boolean Jei true, pokalbyje rodyti el. prekybos Offer Cards (pasiūlymų korteles)
includeProductsInKnowledgeBase boolean Jei true, indeksuoti produktų katalogą kaip žinių bazės dalį

Neįtraukta į API apimtį

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

  • Flow tab (skirtukas „Flow“) - vaizdinė pokalbių eigos redagavimo priemonė (etapai ir perėjimai). Neatskleidžiama per Management API.
  • Actions tab (skirtukas „Actions“) - valdomos el. prekybos / rezervavimo integracijos, AI Search ir pasirinktinės API funkcijos. Įrankių iškvietimas (angl. tool calling) niekada nebuvo Management API dalis.
  • Pati pasirinktinių formų kūrimo priemonė - pasirinktinių formų kūrimas ir redagavimas nėra pasiekiamas per API. Tačiau galite priskirti esamą formą botui per leadCollection.customFormId ir humanSupport.customFormId.
  • Pasirinktinės pokalbio atidarymo / uždarymo piktogramos - customLauncherIconVisible, openChatIcon, closeChatIcon. API atskleidžia tik pagrindines avatar ir whitelabel_logo kelių dalių užklausos dalis.
  • IP ir šalių sąrašai - patys įrašai pasiekiami tik administratoriui. Per security.countryFilterMode atskleidžiamas 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.

Režimas A - paprastas JSON (rekomenduojama, kai nereikia tame pačiame užklausos pranešime įkelti pseudoportreto / logotipo):

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

Režimas B - multipart/form-data (naudokite įkeldami failus toje pačioje užklausoje):

  • Content-Type: multipart/form-data; boundary=...
  • data JSON dalis (privaloma, Content-Type: application/json) - roboto konfigūracija aukščiau aprašyta įdėtine struktūra
  • avatar failo dalis (neprivaloma) - roboto pseudoportreto atvaizdas
  • whitelabel_logo failo dalis (neprivaloma) - White Label logotipas (taikoma tik jei Jūsų paskyrai priklauso White Label funkcija)

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

Visas užklausos turinys

Tai yra maksimalus data JSON - užpildytos visos sekcijos. Siųskite tik tas sekcijas, kurios Jums aktualios; visoms kitoms 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-MINI",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  }
}

Validavimo taisyklės su atskiromis klaidų žinutėmis:

  • name - privalomas, daugiausiai 150 simbolių
  • advanced.temperature - tarp 0.0 ir 1.0
  • chatMemory.summariesToKnowledgeRatio - sveikasis skaičius tarp 10 ir 90 (procentais, žingsnis 10)
  • appearance.launcherBottomMargin, appearance.launcherSideMargin - tarp 0 ir 500
  • appearance.footerMarkdown - daugiausiai 255 simboliai
  • Kai humanSupport.enabled=true, būtina nurodyti humanSupport.email
  • Kai leadCollection.enabled=true, bent vieno iš leadCollection.emailEnabled arba leadCollection.phoneEnabled reikšmė turi būti true; įjungtam kanalui taip pat būtina nurodyti jo etiketę, taip pat leaveDetailsMessage ir thankYouMessage
  • Apriboti laukai (advanced.chatContextSize, advanced.botMessagesLimit ir kt.) yra automatiškai apkerpami pagal Jūsų paskyros limitus

Laukai, kurių reikšmė serveryje yra null, yra praleidžiami JSON turinyje - ryšio kanalu perduodami tik laukai su ne null reikšmėmis.

Visas atsakymo turinys (201)

Struktūra tokia pati kaip užklausos, papildomai pridedamas tik skaitomas blokas meta ir vienkartinis apiKey aukščiausiame lygyje. Tik skaitomus failų URL adresus (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) serveris sugeneruoja tada, kai buvo įkeltos atitinkamos kelių dalių (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-MINI",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  },
  "meta": {
    "id": 4287,
    "createdAt": "2026-06-01T10:11:02Z",
    "updatedAt": "2026-06-01T10:11:02Z"
  },
  "apiKey": "ck_freshly_minted_bot_talk_key_here"
}

Laukas apiKey pateikiamas tik sukūrimo metu - tai naujai sugeneruotas Bot Talk raktas, susietas su naujuoju robotu. Paprastasis tekstas parodomas vieną kartą ir vėliau per API jo gauti nebeįmanoma; nedelsdami išsaugokite jį savo sistemoje.

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

Curl pavyzdžiai

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

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

Režimas B - multipart su pseudoportretu:

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}

Grąžina dabartinę Jums priklausančio roboto konfigūraciją.

Curl pavyzdys

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

Visas atsakymo turinys (200)

Struktūra tokia pati kaip ir POST atsakymo, išskyrus vienkartinį apiKey. Blokas meta yra įtrauktas. Grąžinama klaida 404 not_found_error, jei robotas neegzistuoja arba nepriklauso Jūsų paskyrai.

Dabartinis pseudoportretas ir White Label logotipas pateikiami kaip pilni, tik skaitomi URL adresai (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) - turintys tą pačią schemą, pagrindinį kompiuterį (host) ir konteksto kelią, iš kurių buvo aptarnauta ši užklausa. Gaukite baitus tiesiogiai atlikdami GET užklausą šiais URL adresais; norėdami pakeisti bet kurį failą, įkelkite naują per multipart dalį avatar / whitelabel_logo, naudodami PATCH. Šie URL laukai yra ignoruojami, jei siunčiami 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-MINI",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  },
  "meta": {
    "id": 4287,
    "createdAt": "2026-06-01T10:11:02Z",
    "updatedAt": "2026-06-01T11:02:19Z"
  }
}

Boto klonavimas

Užklausos POST /v1/management/bots turinys ir atsakymo GET /v1/management/bots/{bot_id} turinys turi tą pačią struktūrą, todėl klonavimas susideda iš trijų etapų: gaukite (GET) šaltinį, pašalinkite serverio valdomus tapatybės laukus ir išsiųskite (POST) rezultatą.

1. Gaukite (GET) šaltinio botą.

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

2. Pašalinkite viršutinio lygio meta bloką. Objektas meta (id, createdAt, updatedAt) yra valdomas serverio ir skirtas tik skaityti - palikus jį POST užklausos turinyje nieko blogo nenutiks (serveris jį tiesiog ignoruos), tačiau jį pašalinus užklausos ketinimas tampa aiškus, o duomenų paketas išlieka švarus. Pasirinktinai pakeiskite name, kad kloną būtų galima atskirti nuo šaltinio.

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

3. Išsiųskite (POST) išvalytą turinį, kad sukurtumėte kloną. Visą užklausos turinio 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 bus naujojo boto meta.id bei naujai sugeneruotas apiKey (šio klono Bot Talk raktas). Nešifruotas apiKey tekstas grąžinamas tik šiame sukūrimo atsake - nukopijuokite jį prieš išvalydami atsakymo turinį, nes vėliau jo gauti nebebus įmanoma.

Du svarbūs aspektai:

  • Failai nėra klonuojami. Laukai appearance.avatarUrl ir whiteLabel.whitelabelLogoUrl yra skirti tik skaityti ir nukreipia į šaltinio boto failus. Jei klone reikia to paties avataro ar White Label logotipo, atsisiųskite failus iš šaltinio URL adresų ir įkelkite juos kaip multipart dalis avatar / whitelabel_logo - siųsdami sukūrimo POST užklausą (B režimas) arba vėlesne PATCH užklausa.
  • Bot Talk raktai nėra klonuojami. Kiekvienas botas turi savo Bot Talk raktų rinkinį. Vienintelis apiKey, grąžinamas sukūrimo POST užklausos, yra vienintelis automatiškai sugeneruotas raktas; prireikus papildomus raktus galite sukurti boto API skirtuke (API tab).

PATCH /v1/management/bots/{bot_id}

Atnaujinkite vieną ar kelis jums priklausančio boto laukus. Pakeičiamos tik tos skiltys ar laukai, kurie yra pateikti JSON; viskas, kas praleista (arba atsiųsta kaip null), lieka nepakeista. Dalinio atnaujinimo taisyklės taikomos kiekvienam laukui atsiųstoje skiltyje.

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

A režimas - paprastas JSON (rekomenduojama, kai atnaujinami tik nustatymai):

  • Content-Type: application/json
  • Užklausos turinys yra atnaujinimo (patch) JSON (be data apvalkalo)

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

  • data JSON dalis (pasirinktinai) - atnaujinimo duomenys. Siųskite tik tuo atveju, jei norite pakeisti laukus. Praleiskite visiškai, jei norite tik įkelti avatarą ar logotipą.
  • avatar failo dalis (pasirinktinai) - pakeisti avatarą
  • whitelabel_logo failo dalis (pasirinktinai) - pakeisti White Label logotipą (taikoma tik tuo atveju, jei Jūsų planas apima White Label)

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

Visas užklausos turinys (maksimali apimtis)

Čia galima siųsti bet kurį lauką, kurį priima POST /v1/management/bots. Žemiau pateiktas pavyzdys apima visus galimus laukus; praktikoje siunčiate tik tuos raktus, kuriuos norite pakeisti (žr. „Minimalus dalinis atnaujinimas" toliau) - kiekvienas praleistas (arba kaip null atsiųstas) raktas išlaiko 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 (PATCH) vieną lauką siųsdami tiksliai tuos raktus, kuriuos norite pakeisti - visa kita išsaugoma.

{
  "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 avatarą ar 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 - pakeisti tik avatarą (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 turinys (200)

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

Žemiau esančiame pavyzdyje rodomas atsakymas pritaikius aukščiau pateiktą Viso užklausos turinio (maksimali apimtis) atnaujinimą botui iš GET pavyzdžio - pakeisti laukai rodo naujas reikšmes, nepaliesti laukai išsaugomi, o meta.updatedAt atsinaujina.

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

Nuskaitykite paskyros, kuriai priklauso Management raktas, dabartinį prenumeratos sunaudojimą.

Atsakymo turinys (200)

{
  "subscriptionType": "standard",
  "messages": {"used": 4123, "limit": 11000, "remaining": 6877},
  "bots": {"used": 3, "limit": 5, "remaining": 2}
}
  • subscriptionType yra mažosiomis raidėmis pateiktas paskyros dabartinio plano identifikatorius (pvz., standard šiame pavyzdyje). Planai imami iš dinaminio katalogo, todėl tikslus identifikatorių rinkinys laikui bėgant gali kisti pervadinus ar pridėjus naujų planų - traktuokite tai kaip nepermatomą eilutę (opaque string), o ne fiksuotą sąrašą (enum).
  • messages.used / limit / remaining nurodo dabartinio atsiskaitymo laikotarpio pranešimų kreditus.
  • bots.used / limit / remaining skaičiuoja aktyvius botus pagal Jūsų paskyros botų limitą.

Užklausų ribojimo antraštės

Atsakymai, kurie pasiekia užklausų ribojimo (angl. rate limit) etapą (t. y. autentifikavimas ir IP baltasis sąrašas sėkmingai praeiti), apima:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1715430000
  • X-RateLimit-Limit - vienam raktui taikomas limitas, faktiškai pritaikytas šiam iškvietimui (pagal numatytuosius nustatymus 10 arba Jūsų sukonfigūruotas rateLimitPerMinute, jei jis mažesnis).
  • X-RateLimit-Remaining - krepšelyje likę prieigos raktai (angl. tokens) iškart po šio iškvietimo.
  • X-RateLimit-Reset - „Unix epoch“ laikas sekundėmis, kada taps pasiekiamas kitas prieigos raktas (tai nėra visiškas krepšelio atstatymas; krepšelis pildomas nuolatos). Kai krepšelis pilnas, tai yra dabartinis laikas.

429 rate_limit_exceeded atsakymuose taip pat nurodoma Retry-After antraštė, išreikšta sveikomis sekundėmis, kol atsilaisvins bent vienas prieigos raktas.

Klaidos prieš autentifikavimą (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) ir 403 ip_not_whitelisted neturi X-RateLimit-* antraščių - ribotuvas tikrinamas tik sėkmingai atlikus autentifikavimą 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 klaidoms naudojamas code: "invalid_parameter", o pranešimo pradžioje pateikiamas klaidingo lauko kelias, kad būtų lengva pastebėti klaidą sukėlusią dalį:

{
  "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 / fiksuoto rinkinio 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"
  }
}

Susiję

Pokalbių galiniams taškams ir SSE srautiniam perdavimui žr. Bot Talk API.

Ieškoti visuose straipsniuoseKlauskite asistento