Management API

Management API ülevaade

Management API on mõeldud taustasüsteemi toiminguteks, mis ei hõlma vestlussõnumite saatmist:

• boti programmiliseks loomiseks päringuga POST /v1/management/bots
• teile kuuluva konkreetse boti andmete lugemiseks päringuga GET /v1/management/bots/{bot_id}
• konkreetse boti uuendamiseks päringuga PATCH /v1/management/bots/{bot_id}
• tellimuse kasutusmahu lugemiseks päringuga GET /v1/usage

Management-võtmed on seotud teie kontoga, mitte ühegi konkreetse botiga. Neid hoitakse teadlikult lahus Bot Talk võtmetest, et kompromiteeritud vestlusvõtme kaudu ei saaks muuta teie机器人id ega lugeda teie arveldusandmeid.

Baas-URL

https://api.chatlab.com/aichat

Kõik selles artiklis toodud lõpp-punktid on selle baas-URL-i suhtes relatiivsed.

Alustamine

1. Avage administraatorirakendus ja liikuge jaotisse Account Settings > Management API (Konto seaded > Management API).
2. Klõpsake nupul Create Management Key (Loo Management-võti), pange sellele nimi, soovi korral määrake lubatud IP-aadresside loend ja päringulimiit ning kinnitage.
3. Kopeerige täielik võti õnnestumise modaalaknast. Lihttekstina kuvatakse seda ainult üks kord.

Võti näeb välja selline: mk_abcdefghijklmnopqrstuvwxyz012345. Eesliide mk_ eristab seda Bot Talk võtmetest (ck_).

Autentimine

Authorization: Bearer mk_abcdefghijklmnopqrstuvwxyz012345

Võtme mk_ saatmisel lõpp-punkti /v1/chat (või mis tahes muusse Bot Talk lõpp-punkti) tagastatakse kood 403 key_type_not_allowed. Võtme ck_ saatmisel lõpp-punkti /v1/management/* tagastatakse sama viga.

Limiidid

• Maksimaalselt 5 aktiivset Management API võtit kasutaja kohta
• Maksimaalselt 10 päringut minutis võtme kohta (token bucket, maht 10, sujuv täitmine kiirusega ~1 token iga 6 sekundi järel). Loomisel allapoole konfigureeritav - määrake madalam väärtus rateLimitPerMinute ning ülempiir langeb ja täitmiskiirus kohandub proportsionaalselt.

Õigused

Iga Management-võti sisaldab mis tahes alamhulka alljärgnevast kolmest õigusest. Loomisel tuleb valida vähemalt üks; vastasel juhul lükatakse päring tagasi veaga 400 invalid_request_error. Lõpp-punkti kutsumine võtmega, millel puudub nõutav õigus, tagastab vea 403 insufficient_permissions.

• bot_read - nõutav päringu GET /v1/management/bots/{bot_id} jaoks
• bot_management - nõutav päringute POST /v1/management/bots ja PATCH /v1/management/bots/{bot_id} jaoks
• usage - nõutav päringu GET /v1/usage jaoks

Päringu keha kuju: administraatori kasutajaliidese vahekaarte peegeldavad pesastatud sektsioonid

POST ja PATCH võtavad vastu JSON-keha, mis on jaotatud 13 sektsiooni. Iga sektsioon vastab administraatorirakenduse boti seadete külgriba alamvahekaardile, seega on JSON-i võtmed ja nähtavad vahekaardid omavahel kooskõlas: kui muudate API kaudu väärtust consent.humanSupportRequirePolicyAccept, näete sama lüliti oleku muutumist administraatorirakenduse vahekaardil Consent & Privacy (Nõusolek ja privaatsus).

• role - boti persoon, algne prompt, vastuse pikkus, keel, veebisaidi / ettevõtte kontekst (vahekaart Role & Behavior (Roll ja käitumine))
• conversation - tervitussõnum, päringu täpsustamine, vestluse järjepidevus, hindamise lüliti + kohtspikrid, soovitatud küsimuste sisu + dünaamilised jätkuküsimused (vahekaart Chat Conversation (Vestlus))
• chatMemory - vestlusmälu lüliti, kokkuvõtte promptid, konteksti jaotus (vahekaart Summaries & Memory (Kokkuvõtted ja mälu))
• appearance - värvid, tekstid, mõõtmed, kohandatud CSS, tervituskuva, soovitatud küsimuste stiil, automaatse avanemise käitumine, inimese tippimise simuleerimine, jaluse markdown (vahekaart Appearance (Välimus))
• humanSupport - inimesega kontakteerumise vorm (vahekaart Human Contact Form (Inimkontaktivorm))
• leadCollection - müügivihjete kogumise vorm (vahekaart Lead Collection (Müügivihjete kogumine))
• liveChat - vestluse üleandmine inimesele (vahekaart Live Chat (Reaalajas vestlus))
• consent - kõik neli privaatsuspoliitika nõusolekulülitit koos nõusolekukuva tekstiga (vahekaart Consent & Privacy (Nõusolek ja privaatsus))
• whiteLabel - logo peitmine, kohandatud logo link, majutamine kohandatud domeenil (vahekaart Whitelabel)
• security - lubatud domeenid, rämpspostifilter, vestluse päringulimiidid (vahekaart Security (Turvalisus))
• voice - häälsisend ja häälvestlused: mudel, hääl, keeled, prompt, kestuse ülempiir (vahekaart Voice Conversation (Häälvestlus))
• multilingual - mitmekeelne režiim, põhikeel, pakutavad keeled, teadmusbaasi keele käsitlemine (vahekaart Languages (Keeled))
• advanced - LLM-mudel, temperatuur, konteksti suurus, boti sõnumite limiit, sisemine lokaat, Offer Cards (vahekaart Model & Advanced (Mudel ja täpsemad seaded))

Ainult name asub juurtasemel, kuna see tuvastab boti tervikuna, mitte ei kuulu ühelegi konkreetsele vahekaardile.

Boti seadete külgribal on praegu 15 alamvahekaarti, millest 13 vastavad ülaltoodud sektsioonidele. Kaks alamvahekaarti, millel puudub vastav sektsioon, on Flow (Voog) ja Actions (Toimingud) - mõlemat käsitletakse allpool jaotises "API ulatusest väljas". Need 13, mis vastavad, on Appearance, Chat Conversation, Role & Behavior, Human Contact Form, Lead Collection, Live Chat, Whitelabel, Consent & Privacy, Security, Model & Advanced, Summaries & Memory, Voice Conversation ja Languages.

Päringu kehal ja vastuse kehal on sama struktuur. Vastus lisab kaks täiendavat välja:

• meta - kirjutuskaitstud: boti id ja ajatemplid. Eemaldage see, et muuta GET-vastus kehtivaks POST-päringu kehaks.
• apiKey - olemas ainult loomisel - äsja genereeritud Bot Talk API võti uue boti jaoks.

Kaks välja ühises struktuuris on kirjutuskaitstud - need tagastatakse vastuses ja neid ignoreeritakse, kui proovite neid saata meetoditega POST/PATCH:

• appearance.avatarUrl - boti avatari pildi täielik avalik URL (nt https://api.chatlab.com/aichat/content/avatar_xyz.png). Baitide allalaadimiseks tehke sellele otse GET-päring. Selle muutmiseks laadige üles uus fail mitmeosalise päringu osa avatar kaudu (vt PATCH).
• whiteLabel.whitelabelLogoUrl - White Label päise logo täielik avalik URL. Sama loogika nagu väljal avatarUrl. Selle muutmiseks laadige üles uus fail mitmeosalise päringu osa whitelabel_logo kaudu (vt PATCH).

Mõlemad URL-id kasutavad praeguse päringu skeemi + hosti + kontekstiteed, seega White Label kohandatud domeenil tagastatakse need selle domeeni juurega (nt https://api.acme.com/aichat/content/...).

PATCH-päringul saatke sektsiooni vahelejätmiseks väärtus null; sektsioonisisese üksiku välja vahelejätmiseks saatke selle välja väärtuseks null. Välja tasemel saadetud null ei kustuta kunagi salvestatud väärtust - see tähendab ainult "ära muuda".

Rolli ja prompti koostamine

Süsteemiprompt, mille LLM tegelikult saab, koostatakse ühel kahest viisist sõltuvalt väärtusest role.role. Teadmine, kummale harule teie bot satub, määrab, millised väljad on olulised ja millised salvestatakse, kuid jäetakse tähelepanuta.

Haru A - role.role on CUSTOMER_SUPPORT, SALES või LEAD_COLLECTION_AGENT (mallipõhine)

Taustasüsteem paneb prompti kokku sisseehitatud mallist ja ignoreerib välja role.rawPrompt täielikult (väärtus salvestatakse endiselt boti juurde, kuid seda ei kasutata). Mall sisaldab järgmist:

• role.role - rolli silt (nt "Customer Support") ja automaatselt lisatavad rollipõhised juhised
• name - boti nimi, mis lisatakse avalausesse
• role.language - "Auto Detect" lülitab boti kasutaja keelt järgima; mis tahes muu väärtus (nt "English", "Polish") teisendatakse kujule "Output in {language}, unless user uses another language"
• role.responseLength - vastendatakse sihtkordsõnade arvule: Concise ≈ 50 sõna, Normal ≈ 100, Detailed ≈ 200
• role.websiteAddress - valikuline; kui see pole tühi, lisatakse kujul "for the users of the website {url}"
• role.companyDescription - valikuline; kui see pole tühi, lisatakse lisalõiguna enne rollijuhiseid

See on soovitatav haru enamiku bottide jaoks - saate automaatselt rollile kohandatud käitumise ja turvapiirded.

Haru B - role.role on CUSTOM (kasutaja määratud prompt)

Taustasüsteem kasutab välja role.rawPrompt muutmata kujul terve süsteemipromptina. Väljad responseLength, language, websiteAddress, companyDescription salvestatakse, kuid neid ei lisata prompti - kui soovite, et mõni neist peegelduks boti käitumises, peate need ise oma rawPrompt teksti lisama. Rollipõhiseid turvapiirdeid ja tooni puudutavaid juhiseid samuti ei lisata; kogu prompt on teie hallata.

Kasutage varianti CUSTOM ainult siis, kui mallipõhine prompt ei sobi teie kasutusjuhuga (nt vajate väga valdkonnapõhist persooni, omaenda turvapiiranguid, mittestandardset väljundvormingut).

Loendiväljad (enum / suletud komplektid)

Mitmed väljad aktsepteerivad ainult fikseeritud sõneväärtuste komplekti. Mis tahes loendivälise väärtuse saatmine lükatakse tagasi veaga 400 validation_failed ja välja teekond märgitakse parameetris error.param. Väärtused on tõstutundlikud.

• role.role - CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM
• role.responseLength - Concise, Normal, Detailed
• role.language - täielik ingliskeelne keelenimi administraatori rippmenüüst, nt Auto Detect, English, Polish, Spanish, German, French, Italian, Portuguese, Dutch, Russian, Chinese (Simplified), Japanese, Arabic, Hindi ja ~80 muud. Väärtus salvestatakse muutmata kujul ja asendatakse prompti malli, seega kahetähelisi ISO-koode (en, pl) ja muid nimekirjaväliseid väärtusi API tagasi ei lükka, kuid need tekitavad vigase juhise, nagu "Output in en, unless...". Kui see jäetakse loomisel määramata, on vaikeväärtuseks Auto Detect.
• advanced.model - vt allpool "Tehisintellekti tekstimudelid"; valitav komplekt sõltub teie konto limiitidest ja mis tahes mudel, mida teie konto ei saa kasutada, tagastab vea 400 invalid_parameter
• advanced.chatContextSize - 8000, 16000, 32000. Sõltub teie konto limiitidest; suuremad väärtused piiratakse vaikselt madalamaks
• chatMemory.clientSummaryPromptType - DEFAULT, CUSTOM
• chatMemory.conversationSummaryPromptType - DEFAULT, CUSTOM
• appearance.chatAlignment - left, right
• appearance.minimizedDisplayMode - icon, minified
• appearance.chatMessageLinkTarget - _blank, _self
• leadCollection.requireBeforeNewConversation - tõeväärtuslüliti. true sunnib kasutajat enne vestluse alustamist täitma müügivihje vormi; false laseb tehisintellektil otsustada, millal vormi kuvada (vaikeseade).

Struktureeritud väljad ja vahemikud

Väljad, mis näevad välja nagu lihtsad sõned või numbrid, kuid omavad tegelikult spetsiifilist kuju, vahemikku või administraatoriliidese eripärasid, millest tasub teadlik olla.

• advanced.temperature - lubatud vahemik on 0.0 kuni 1.0, vastates administraatori kasutajaliidese liugurile. Väljaspool seda vahemikku olevad väärtused lükatakse tagasi veaga 400 validation_failed.

• chatMemory.summariesToKnowledgeRatio - täisarvuline protsent, 10-90 sammuga 10. Määrab, kui palju vestluse kontekstist eraldatakse kliendi ajaloolistele kokkuvõtetele võrreldes ülejäänud osaga (teadmusbaas, praegune vestlus, juhised). Vaikeväärtus on 50. Väärtused väljaspool vahemikku 10-90 lükatakse tagasi veaga 400 validation_failed. Rakendub ainult siis, kui chatMemory.enabled=true NING chatMemory.summaryConversationsEnabled=true.

• liveChat.schedule - JSON, mis on kodeeritud sõnena, mitte pesastatud JSON-objektina võrgupäringus. Server salvestab toore sõne muutmata kujul; administraatori kasutajaliides parsib seda kliendipoolselt ajakava redaktori kuvamisel. Pärast parsimist on sõne struktureeritud nii, et see sisaldab ühte kirjet iga nädalapäeva kohta pluss võtit timezone:

  • iga nädalapäeva võti (monday-sunday) vastab objektile {enabled: boolean, from: "H:MM", to: "H:MM"} 24-tunnises ajavormingus
  • timezone on IANA ajavööndi nimi (nt "Europe/Warsaw", "America/New_York")

  Näidisväärtus (pange tähele välimisi jutumärke ja varjestatud sisemisi jutumärke - see on üks sõneväli, mitte pesastatud objekt):

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

  Väljaspool märgitud aegu kuvatakse külastajale teade liveChat.outOfHoursMessage ja vestluse üleandmine reaalajas vestlusele blokeeritakse. Sisemise struktuuri valideerimine toimub ainult kliendipoolselt administraatori kasutajaliideses - vigane JSON või tundmatud võtmed võetakse API poolt vastu tavalise sõnena ja need tekitavad renderdamisvea alles siis, kui inimene avab hiljem boti administraatorirakenduses. Valideerige struktuur enne saatmist oma poolel.

• conversation.positiveRatingTooltip / conversation.negativeRatingTooltip - lühikesed tekstid, mida kuvatakse nuppudel 👍 / 👎 iga tehisintellekti vastuse kõrval, kui conversation.conversationRatingEnabled=true. Vaiketekst on "I like the response" / "I don't like the response". Nähtav lõppkasutajatele.

• whiteLabel.hideRoboAssistLogo - White Label funktsioon, sõltub teie konto limiitidest. Peidab jaluse rea "Powered by ChatLab". Kui teie konto ei sisalda White Label võimalust, väärtus salvestatakse, kuid seda ignoreeritakse ja jalus kuvatakse alati.

• whiteLabel.whitelabelLogoLink - White Label funktsioon, sõltub teie konto limiitidest. Klõpsatav siht-URL kohandatud logo jaoks, kui hideRoboAssistLogo=true ja kohandatud logofail on üles laaditud mitmeosalise päringu osa whitelabel_logo kaudu.

• appearance.simulateHumanTypingDelay - sekundid (mitte millisekundid), täisarv 0-200. Paus boti järjestikuste sõnumimullide vahel, kui simulateHumanTyping=true. Vaikeväärtus on 5.

• appearance.autoOpenChatDelaySeconds - sekundid, täisarv. Viivitus enne vidina automaatset avanemist, kui autoOpenChat=true ja autoOpenChatDelay=true.

• advanced.internalLocale - IETF-i lokaadi ja piirkonna kood kujul ll_CC (alakriips, MITTE sidekriipsuga ll-CC). Lubatud väärtused pärinevad fikseeritud nimekirjast, mis sisaldab ~95 lokaati: 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 ja paljud teised. Ainult kahetähelise koodi ("en") või BCP-47 koodi ("en-US") saatmine ei ole lubatud loendis. Vaikeväärtus on en_US. Seda lokaati kasutatakse kuupäeva/numbri vormindamiseks vidina raamistikus ning see erineb parameetrist role.language (mis määrab boti vestlusväljundi keele).

• security.talkMessagesRateLimit / security.talkMessagesRateLimitDurationSeconds - täisarvud (saatke JSON-numbritena, nt 30, mitte "30"). Väärtus 0 keelab IP-põhise päringulimiidi. Kui väärtus ei ole null, rakendab vidin piirangut N sõnumit määratud sekundite jooksul, enne kui külastajale kuvatakse teade security.talkMessagesRateLimitHitMessage.

• advanced.botMessagesLimit - täisarv (JSON-number, nt 1000). Väärtus 0 tähendab "limiit puudub"; muul juhul peab see olema 1000 kordne (1000, 2000, 10000, ...). Sellised väärtused nagu 100 või 1500 lükatakse tagasi veaga 400 validation_failed. Lisaks piiratakse see vajadusel vaikselt teie konto limiidiga.

Tehisintellekti tekstimudelid (advanced.model)

Saatke täpne API väärtus (vasakpoolne kaldkriipsudega tähistatud veerg). Kuvamisnimi administraatori kasutajaliideses on toodud sulgudes. Teie konto limiidid määravad, milline alamhulk on valitav; sellise mudeli saatmine, mida teie konto ei saa kasutada, tagastab vea 400 invalid_parameter. Uute bottide vaikeväärtus on 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)

Väljade teatmik (täielik päringuskeem)

Kõik võrgupäringu väljad koos tüübi, piirangu ja üherealise kirjeldusega. PATCH-semantika: iga väli, mis jäetakse välja (või saadetakse väärtusena null), jätab salvestatud väärtuse muutmata. Sama struktuuri kasutatakse ka vastuses (v.a mitmeosalise päringu binaarne sisu; lisaks kirjutuskaitstud plokk meta igas vastuses ning apiKey ainult loomise vastuses).

Tipptase

Väli	Tüüp	Piirang	Kirjeldus
name	string	max 150, loomisel kohustuslik	Boti kuvatav nimi
role	object		Vaadake § role
conversation	object		Vaadake § conversation
chatMemory	object		Vaadake § chatMemory
appearance	object		Vaadake § appearance
humanSupport	object		Vaadake § humanSupport
leadCollection	object		Vaadake § leadCollection
liveChat	object		Vaadake § liveChat
consent	object		Vaadake § consent
whiteLabel	object		Vaadake § whiteLabel
security	object		Vaadake § security
advanced	object		Vaadake § advanced

Ainult vastuses esinevad täiendused:

• meta: { id, createdAt, updatedAt } - kirjutuskaitstud.
• apiKey - string, olemas ainult vastuses POST /v1/management/bots - vastloodud Bot Talki võti uue boti jaoks, tagastatakse täpselt üks kord.

§ role

Väli	Tüüp	Piirang	Kirjeldus
role	string (enum)	CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM	Persooni eelseadistus; valib viiba malli (vaadake "Role and prompt construction")
language	string	täielik ingliskeelne keelenimi (English, Polish, ...) või Auto Detect	Põhikeel, mis suunatakse viiba malli
responseLength	string	∈ {Concise, Normal, Detailed}	Tehisintellekti vastuse soovitud detailsus
websiteAddress	string		Veebisait, mida kasutatakse viiba kontekstina
companyDescription	string		Ettevõtte kirjeldus, mida kasutatakse viiba kontekstina
rawPrompt	string		Kohandatud süsteemiviip - kasutatakse muutmata kujul ainult siis, kui role=CUSTOM

§ conversation

Väli	Tüüp	Piirang	Kirjeldus
welcomeMessage	string		Esimene sõnum, mida külastajale avamisel kuvatakse
queryRefinementEnabled	boolean		Kui tõene, täpsustatakse külastaja küsimust enne RAG-päringut
conversationContinuityEnabled	boolean		Kui tõene, jätkavad naasvad külastajad oma viimast vestlust
conversationRatingEnabled	boolean		Kui tõene, kuvatakse boti sõnumitel pöial püsti/alla hindamist
positiveRatingTooltip	string		Positiivse hindamise nupu kohtspikker
negativeRatingTooltip	string		Negatiivse hindamise nupu kohtspikker
suggestedQuestions	string		Reavahetusega eraldatud soovitatud küsimused / vestluse alustajad
dynamicSuggestedFollowups	boolean		Kui tõene, pakub tehisintellekt pärast iga vastust dünaamilisi jätkuküsimusi
dynamicFollowupsAutoIcons	boolean		Kui tõene, valib tehisintellekt dünaamilistele jätkuküsimustele automaatselt emojid

§ chatMemory

Väli	Tüüp	Piirang	Kirjeldus
enabled	boolean		Vestlusmälu funktsiooni pealüliti
summaryConversationsEnabled	boolean		Salvesta vestlusepõhised kokkuvõtted
conversationSummaryPrompt	string		Kohandatud viip, mida kasutatakse iga vestluse kokkuvõtmiseks
conversationSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Kas kasutada vaikimisi või kohandatud kokkuvõtteviipa
clientSummaryPrompt	string		Kohandatud viip, mida kasutatakse kliendi kokkuvõtmiseks läbi vestluste
clientSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Vaikimisi vs kohandatud kliendiprofiili viip
summariesToKnowledgeRatio	int	10-90, samm 10	% vestluse kontekstiaknast, mis on eraldatud kokkuvõtetele vs RAG-teadmusbaasile

§ appearance

Väli	Tüüp	Piirang	Kirjeldus
launcherColor	string (hex)		Käivitusnupu (vestluse ikooni) taustavärv
headerColor	string (hex)		Vestluse päise taustavärv
titleColor	string (hex)		Vestluse päise pealkirja värv
subtitleColor	string (hex)		Vestluse päise alapealkirja värv
clientMessageBubbleColor	string (hex)		Külastaja sõnumimulli värv
clientMessageTextColor	string (hex)		Külastaja sõnumi tekstivärv
responseMessageBubbleColor	string (hex)		Boti vastusemulli värv
responseMessageTextColor	string (hex)		Boti vastuse tekstivärv
chatSubheader	string		Vestluse pealkirja all kuvatav tunnuslause
senderPlaceholder	string		Kohahoidja tekst sõnumi sisestusväljal
resetConversationTooltip	string		Nupu "reset conversation" (lähtesta vestlus) kohtspikker
chatAlignment	string (enum)	∈ {left, right}	Kumbale poole ekraani vestlusankur kinnitub
launcherBottomMargin	int	0-500	Käivitusnupu kaugus allservast (px)
launcherSideMargin	int	0-500	Käivitusnupu kaugus külgservast (px)
displayShadow	boolean		Vidina all kuvatav vari
customCss	string		Vidinasse iframe'i kaudu süstitav kohandatud CSS
chatMessageLinkTarget	string (enum)	∈ {_blank, _self}	Kuidas avanevad lingid boti sõnumites
minimizedDisplayMode	string (enum)	∈ {icon, minified}	Minimeeritud olek: käivitusikoon või kompaktne sisestusriba
chatDesktopWidthPx	int		Vidina laius töölaual
chatDesktopHeightPx	int		Vidina kõrgus töölaual
chatMobileSizePercent	int		Mobiilividina suurus protsendina vaateavast
messageFontSize	int		Sõnumiteksti kirjasuurus (px)
showChatbotBubblesDesktop	boolean		Kuva hõljuvaid eelvaatemulle töölaual
showChatbotBubblesMobile	boolean		Kuva hõljuvaid eelvaatemulle mobiilis
chatbotBubblesDelaySeconds	int		Viivitus enne eelvaatemullide ilmumist (sekundites)
launcherIconFullSize	boolean		Kujunda kohandatud käivitusikoon servast servani, mitte ääristusega
welcomeScreenEnabled	boolean		Kuva tervituskuva (Welcome Screen) otse vestlusesse minemise asemel
welcomeScreenQuestionsLabel	string		Soovitatud küsimuste kohal olev silt tervituskuval
welcomeScreenHideHumanContactForm	boolean		Peida päises inimkontaktvormi toiming sel ajal, kui kuvatakse tervituskuva. See ilmub uuesti pärast külastaja esimest sõnumit. Enne 2026-09-02 loodud bottidel on vaikeväärtuseks true
welcomeScreenHideLiveChat	boolean		Peida päises vestluse toiming sel ajal, kui kuvatakse tervituskuva. See ilmub uuesti pärast külastaja esimest sõnumit. Enne 2026-09-02 loodud bottidel on vaikeväärtuseks true
headerActionsLayout	string	DROPDOWN	Kuidas vestlust ja inimkontaktvormi vestluse päises pakutakse: ICONS (kumbki eraldi ikoonina) või DROPDOWN (rühmitatuna päise menüüsse). Enne 2026-09-02 loodud bottidel on vaikeväärtuseks ICONS
stackSuggestedQuestions	boolean		Paiguta soovitatud küsimused vertikaalselt (mitte kõrvuti)
suggestedQuestionsFontSize	int		Soovitatud küsimuste siltide kirjasuurus (px)
suggestedQuestionsTextColor	string (hex)		Soovitatud küsimuste siltide tekstivärv
suggestedQuestionsBackgroundColor	string (hex)		Soovitatud küsimuste siltide taustavärv
autoOpenChat	boolean		Ava vestlus töölaual automaatselt
autoOpenChatOnMobiles	boolean		Ava vestlus mobiilis automaatselt
autoOpenChatDelay	boolean		Kasuta enne automaatset avamist viivitust
autoOpenChatDelaySeconds	int		Automaatse avamise viivitus (sekundites)
simulateHumanTyping	boolean		Jaga boti vastus mullideks koos tippimise animatsiooniga
simulateHumanTypingDelay	int	0-200	Viivitus sõnumimullide vahel (sekundites)
footerMarkdown	string	max 255	Kohandatud jaluse markdown, mida kuvatakse vestluse all
avatarUrl	string	kirjutuskaitstud	Avatari täielik avalik URL; selle muutmiseks laadige fail üles mitmeosalise päringu osaga avatar

Mitmeosaline sisu POST-/PATCH-päringul: avatar (failiosa). GET-päringute ja vastuste keha jätab failisisu välja - võrgupäringus liigub ainult URL.

§ humanSupport

Väli	Tüüp	Piirang	Kirjeldus
enabled	boolean		Human Supporti (inimetoe) voo lüliti
email	string	kohustuslik (range loomine), kui enabled=true	Aadress, mis võtab vastu inimetoe e-kirju
dialogMessage	string		Vormi kohal kuvatav julgustav sõnum
thankYouMessage	string		Pärast saatmist kuvatav kinnitussõnum
emailMessageSubjectTemplate	string		Agendile saadetava e-kirja teemamall
emailMessageContentTemplate	string		Agendile saadetava e-kirja sisumall
emailPlaceholder	string		E-posti sisestusvälja kohahoidja
messagePlaceholder	string		Sõnumi tekstiala kohahoidja
emailWithConversationContent	boolean		Kui tõene, lisatakse e-kirja sisusse vestluse transkriptsioon
customFormId	long	olemasoleva kohandatud vormi id	Asendage sisseehitatud kontaktvorm kohandatud vormiga. null säilitab sisseehitatud vormi
customFormMapping	string	JSON-kodeeringus string	Vastendab kohandatud vormi väljad inimetoe e-kirja väljadega

requirePolicyAccept asub väljal consent.humanSupportRequirePolicyAccept, mitte siin.

§ leadCollection

Väli	Tüüp	Piirang	Kirjeldus
enabled	boolean		Müügivihjevormi lüliti
nameEnabled	boolean		Kogu nime
nameLabel	string		Nime sisestusvälja silt
emailEnabled	boolean		Kogu e-posti aadressi
emailLabel	string	kohustuslik (range loomine), kui enabled=true NING emailEnabled=true	E-posti sisestusvälja silt
phoneEnabled	boolean		Kogu telefoninumbrit
phoneLabel	string	kohustuslik (range loomine), kui enabled=true NING phoneEnabled=true	Telefoni sisestusvälja silt
leaveDetailsMessage	string	kohustuslik (range loomine), kui enabled=true	Sõnum, mis julgustab külastajat oma andmeid jätma
thankYouMessage	string	kohustuslik (range loomine), kui enabled=true	Pärast saatmist kuvatav kinnitussõnum
requireBeforeNewConversation	boolean		Kui true, tuleb vorm esitada enne vestluse algust; kui false, otsustab tehisintellekt, millal vormi kuvada
emailNotificationEnabled	boolean		Saada omanikule e-kiri iga kord, kui uus müügivihje laekub
emailNotificationAddress	string		Teavituse saaja (vaikimisi konto e-posti aadress)
emailWithConversationContent	boolean		Kui tõene, lisatakse teavitusele vestluse transkriptsioon

Väljadeülene range loomise reegel: enabled=true nõuab, et vähemalt üks väljadest emailEnabled või phoneEnabled oleks lubatud. requirePolicyAccept asub väljal consent.leadCollectionRequirePolicyAccept, mitte siin.

| customFormId | long | olemasoleva kohandatud vormi id | Asendage sisseehitatud müügivihjevorm kohandatud vormiga. null säilitab sisseehitatud vormi | | customFormMapping | string | JSON-kodeeringus string | Vastendab kohandatud vormi väljad väljadega nimi / e-post / telefon |

§ liveChat

Väli	Tüüp	Piirang	Kirjeldus
enabled	boolean		Funktsiooni Live Chat lüliti
infoMessage	string		Selgitav sõnum enne üleandmist
startMessage	string		Sõnum, mida kuvatakse reaalajas seansi alguses
endMessage	string		Sõnum, mida kuvatakse reaalajas seansi lõpus
nameLabel	string		Nime sisestusvälja silt Live Chati eelvormis
emailLabel	string		E-posti sisestusvälja silt Live Chati eelvormis
schedule	string	JSON-kodeeringus string (nädalapäevade lülitid + from/to + timezone)	Live Chati töögraafik - täpse kuju leiate jaotisest "Structured fields and ranges"
outOfHoursMessage	string		Sõnum, mida kuvatakse väljaspool tööaega
closeModalMessage	string		Modaalakna "close live chat?" (sulge reaalajas vestlus?) pealkiri
closeModalConfirmLabel	string		Kinnitusnupu silt sulgemise modaalaknas
closeModalCancelLabel	string		Tühistamisnupu silt sulgemise modaalaknas
closeModalTooltipText	string		Vestluse sulgemise nupu kohtspikker
operatorHasJoinedLabel	string		Silt, mida kuvatakse operaatori liitumisel
operatorDidNotJoinInTimeLabel	string		Silt, mida kuvatakse juhul, kui operaator ei liitu määratud aja jooksul
waitingForOperatorToJoinLabel	string		Silt, mida kuvatakse operaatori ootamise ajal
waitingForOperatorSeconds	int		Ooteaeg operaatori vastamiseni (sekundites)
redirectToHumanSupportForm	boolean		Kui tõene, suunatakse vestlus edasi inimetoe (Human Support) vormile, kui ükski operaator ei vasta
missedEmailEnabled	boolean	vaikimisi true	Saada boti omanikule e-kiri, kui reaalajas vestluse päring jäi vastuseta. Vanematel boti versioonidel määramata, mis loetakse lubatuks

requirePolicyAccept asub väljal consent.liveChatRequirePolicyAccept, mitte siin.

§ consent

Väli	Tüüp	Piirang	Kirjeldus
newConversationRequirePolicyAccept	boolean		Nõua privaatsuspoliitikaga nõustumist enne uue vestluse alustamist
humanSupportRequirePolicyAccept	boolean		Nõua privaatsuspoliitikaga nõustumist enne inimetoe vormi esitamist
leadCollectionRequirePolicyAccept	boolean		Nõua privaatsuspoliitikaga nõustumist enne müügivihje vormi esitamist
liveChatRequirePolicyAccept	boolean		Nõua privaatsuspoliitikaga nõustumist enne Live Chati seansi alustamist
newConversationConsentDescription	string		Nõusoleku kuva sissejuhatav tekst vestluse alguses
privacyPolicyConsentCheckboxLabel	string		Silt nõusoleku märkeruudu kõrval (sisaldab tavaliselt linki privaatsuspoliitikale)

§ whiteLabel

Väli	Tüüp	Piirang	Kirjeldus
hideRoboAssistLogo	boolean	White Labeli võimalus; sõltub konto piirangutest	Peida jaluses olev ChatLabi vaikelogo
whitelabelLogoLink	string	White Labeli võimalus; sõltub konto piirangutest	URL, kuhu kohandatud jaluselogo lingib
assignToCustomDomain	boolean	piiratud funktsiooniga CUSTOM_DOMAIN	Majuta vestlust konfigureeritud kohandatud domeenil
whitelabelLogoUrl	string	kirjutuskaitstud	White Labeli logo täielik avalik URL; selle muutmiseks laadige fail üles mitmeosalise päringu osaga whitelabel_logo

Mitmeosaline sisu POST-/PATCH-päringul: whitelabel_logo (failiosa). GET-päringute ja vastuste keha jätab failisisu välja - võrgupäringus liigub ainult URL.

§ security

Väli	Tüüp	Piirang	Kirjeldus
allowedDomains	string		Komadega eraldatud nimekiri domeenidest, millel on lubatud vidinat manustada (tühi = valget nimekirja pole)
spamFilterEnabled	boolean		Luba sissetulevatele sõnumitele botipõhine rämpspostifilter
countryFilterMode	string	BLACKLIST või WHITELIST	Kuidas riikide nimekirju tõlgendatakse. Nimekirjad ise jäävad ainult administraatorile nähtavaks
talkMessagesRateLimit	int	>= 0; 0 keelab	Maksimaalne kasutaja sõnumite arv päringupiirangu aknas
talkMessagesRateLimitDurationSeconds	int	>= 0	Päringupiirangu akna pikkus (sekundites)
talkMessagesRateLimitHitMessage	string		Sõnum, mida kuvatakse külastajale päringupiirangu ületamisel

§ voice

Väli	Tüüp	Piirang	Kirjeldus
inputEnabled	boolean		Luba külastajal sõnumeid dikteerida (kõnest tekstiks)
conversationEnabled	boolean	nõuab paketis häälefunktsiooni	Luba täielikud häälvestlused
voiceId	string	teenusepakkujapõhine hääle id (nt alloy)	Milline sünteetiline hääl räägib
model	string	nt GPT-REALTIME-MINI, GEMINI-LIVE, ELEVENLABS-*	Häälemudel. Arveldatakse minuti alusel, hinnad erinevad mudelite lõikes
turnDetection	string	teenusepakkujapõhine	Rääkimisjärje tuvastamise režiim
audioPrompt	string		Täiendav süsteemiviip, mida kasutatakse ainult häälsuhtluse käikudes
welcomeMessage	string		Räägitav avasõnum
language	string	keelekood	Peamine hääle keel
additionalLanguages	string	komadega eraldatud keelekoodid	Lisakeeled, mida häälagent aktsepteerib
maxDurationSeconds	int		Ühe häälvestluse range ülempiir
maxDurationMessage	string		Sõnum, mida kuvatakse limiidi täitumisel

§ multilingual

Väli	Tüüp	Piirang	Kirjeldus
enabled	boolean		Mitmekeelse režiimi lüliti
mode	string	AUTODETECT või fikseeritud loendi režiim	Kuidas bot vastuse keele valib
baseLanguage	string	keelekood	Keel, milles boti enda tekstid on koostatud
languages	string	komadega eraldatud keelekoodid	Külastajale pakutavad keeled
knowledgeLanguageMode	string		Kuidas koheldakse teistes keeltes olevat teadmusbaasi
knowledgeLanguageFallback	string	keelekood	Keel, mida kasutatakse vaste puudumisel

§ advanced

Väli	Tüüp	Piirang	Kirjeldus
model	string	sõltub konto piirangutest; vaadake eespool jaotist "AI text models"	Suure keelemudeli (LLM) identifikaator (nt 5-MINI)
temperature	decimal	0.0-1.0	Diskreetimistemperatuur (vastab kasutajaliidese liugurile)
chatContextSize	int	∈ {8000, 16000, 32000}; kohandatakse vaikselt teie konto limiidiga	Vestluse ajaloo märgiseaken (token window)
botMessagesLimit	long	0 või arvu 1000 kordne (nt 1000, 2000, 10000)	Boti vastuste maksimaalne arv vestluse kohta (0 = piiranguta)
internalLocale	string	lokaadikood kujul ll_CC	Vidina raami siltide lokaat (erineb parameetrist role.language)
productsViewEnabled	boolean		Kui tõene, kuvatakse e-kaubanduse funktsiooni Offer Cards vestluses
includeProductsInKnowledgeBase	boolean		Kui tõene, indekseeritakse tootekataloog osana teadmusbaasist

Väljaspool API ulatust

Administraatori kasutajaliides sisaldab mõningaid alasid, mis on Management API selles versioonis teadlikult avaldamata:

• Vahekaart Flow (Töövoog) - visuaalne vestlusvoo redaktor Flow Editor (etapid ja üleminekud). Pole Management API kaudu kättesaadav.
• Vahekaart Actions (Toimingud) - hallatavad e-kaubanduse / broneerimise integratsioonid, AI Search ja kohandatud API funktsioonid. Tööriistade väljakutsumine (tool calling) pole kunagi olnud Management API osa.
• Kohandatud vormide koostaja ise - kohandatud vormide loomine ja muutmine pole avaldatud. Samas saate olemasoleva vormi botiga siduda parameetrite leadCollection.customFormId ja humanSupport.customFormId kaudu.
• Kohandatud vestluse avamise/sulgemise ikoonid - customLauncherIconVisible, openChatIcon, closeChatIcon. API teeb kättesaadavaks ainult peamised mitmeosalise sisu osad avatar ja whitelabel_logo.
• IP- ja riikide nimekirjad - kirjed ise on kättesaadavad ainult administraatorile. Avaldatud on vaid tõlgendusrežiim välja security.countryFilterMode kaudu.

Lõpp-punktid

POST /v1/management/bots

Looge uus robot. Aktsepteeritakse kahte samaväärset Content-Type päist; valige see, mis on mugavam.

Režiim A - tavaline JSON (soovitatav, kui teil pole vaja sama päringuga avatari / logo üles laadida):

• Content-Type: application/json
• Päringu keha (request body) on roboti konfiguratsiooni JSON (ilma data mähiseta)
• Faile (avatar / logo) saab laadida üles hiljem teise PATCH päringuga, kasutades režiimi B

Režiim B - multipart/form-data (kasutage failide üleslaadimiseks samas päringus):

• Content-Type: multipart/form-data; boundary=...
• data JSON-osa (kohustuslik, Content-Type: application/json) - roboti konfiguratsioon eelpool kirjeldatud pesastatud struktuuris
• avatar failiosa (valikuline) - roboti avataripilt
• whitelabel_logo failiosa (valikuline) - White Label logo (kehtib ainult juhul, kui teie konto sisaldab White Label funktsiooni)

Ainult name on JSON-is kohustuslik; kõigi teiste väljade vaikeväärtuseks määratakse sama vaikeväärtus, mille seadistaks administraatori kasutajaliidese viisard.

Täielik päringu keha

See on maksimaalne data JSON - kõik jaotised on täidetud. Saatke ainult need jaotised, mida vajate; kõik ülejäänu võtab vaikeväärtused.

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

Valideerimisreeglid koos vastavate veateadetega:

• name - kohustuslik, kuni 150 tähemärki
• advanced.temperature - vahemikus 0.0 kuni 1.0
• chatMemory.summariesToKnowledgeRatio - täisarv vahemikus 10 kuni 90 (protsent, sammuga 10)
• appearance.launcherBottomMargin, appearance.launcherSideMargin - vahemikus 0 kuni 500
• appearance.footerMarkdown - kuni 255 tähemärki
• humanSupport.enabled=true nõuab välja humanSupport.email määramist
• leadCollection.enabled=true nõuab, et vähemalt üks väljadest leadCollection.emailEnabled või leadCollection.phoneEnabled oleks true; mis tahes kanal on sisse lülitatud, nõuab ka vastavat silti ning välju leaveDetailsMessage ja thankYouMessage
• Piiranguga väljad (advanced.chatContextSize, advanced.botMessagesLimit jne) viiakse vaikselt vastavusse teie konto limiitidega

Väljad, mille väärtus serveris on null, jäetakse JSON-i kehast välja - võrgu kaudu edastatakse ainult väljad, millel on mitte-null väärtus.

Täielik vastuse keha (201)

Sama struktuur nagu päringul, millele lisanduvad kirjutuskaitstud plokk meta ja ühekordne apiKey tipptasemel. Kirjutuskaitstud failide URL-id (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) täidetakse serveri poolt, kui vastavad multipart-osad laaditi üles.

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

Väli apiKey kuvatakse ainult loomisel - see on värskelt loodud Bot Talk võti, mis on seotud uue robotiga. Lihtteksti kuvatakse üks kord ja seda ei saa hiljem API kaudu uuesti hankida; salvestage see kohe enda poolel.

Vastuse päis Location sisaldab uue roboti URL-i (/v1/management/bots/{id}).

Curl-näited

Režiim A - tavaline JSON (kõige lihtsam):

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žiim B - multipart koos avatariga:

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}

Tagastab teile kuuluva roboti praeguse konfiguratsiooni.

Curl-näide

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

Täielik vastuse keha (200)

Sama struktuur nagu POST vastusel, välja arvatud ühekordne apiKey. Plokk meta on kaasatud. Tagastab 404 not_found_error, kui robotit pole olemas või see ei kuulu teie kontole.

Praegune avatar ja White Label logo esitatakse täielike kirjutuskaitstud URL-idena (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) - samal skeemil, hostil ja kontekstiteel, mis seda päringut teenindas. Hankige baidid otse nendele URL-idele GET-päringut tehes; kummagi faili asendamiseks laadige PATCH-päringus üles uus fail multipart-osade avatar / whitelabel_logo kaudu. Neid URL-i välju eiratakse, kui need saadetakse päringu kehas.

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

Roboti kloonimine

Päringu POST /v1/management/bots keha ja vastuse GET /v1/management/bots/{bot_id} keha on sama kujuga, mistõttu kloonimine on kolmesammuline protsess: tehke allikale GET, eemaldage serveri hallatavad identiteediväljad ning tehke tulemusele POST.

1. Tehke allikrobotile GET.

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

2. Eemaldage tipptaseme plokk meta. Objekt meta (id, createdAt, updatedAt) on serveri hallatav ja kirjutuskaitstud - selle jätmine POST-päringu kehasse ei tee halba (server ignoreerib seda), kuid selle eemaldamine väljendab selget kavatsust ja hoiab andmevoo puhtana. Soovi korral muutke välja name, et kloon oleks allikast eristatav.

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

3. Klooni loomiseks tehke eemaldatud plokkidega kehale POST. Päringu keha täieliku kuju ja valideerimisreeglid leiate ülaltoodud viitest POST /v1/management/bots.

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

Vastus sisaldab uue roboti väärtust meta.id ja värskelt loodud võtit apiKey (klooni Bot Talk võti). Välja apiKey lihttekst tagastatakse ainult selles loomisvastuses - kopeerige see enne vastuse keha sulgemist; hiljem pole seda võimalik enam kätte saada.

Kaks hoiatust:

• Faile ei kloonita. Väljad appearance.avatarUrl ja whiteLabel.whitelabelLogoUrl on kirjutuskaitstud ning viitavad allikroboti failidele. Kui vajate kloonil sama avatari või White Label logo, laadige baidid allika URL-idelt alla ning laadige need üles mitmeosaliste (multipart) osadena avatar / whitelabel_logo - kas loomise POST-päringuga (režiim B) või hilisema PATCH-päringuga.
• Bot Talk võtmeid ei kloonita. Igal robotil on oma Bot Talk võtmete kogum. Loomise POST-päringu tagastatud üksik apiKey on ainus automaatselt loodav võti; vajadusel looge lisavõtmeid roboti API vahekaardilt (API tab).

PATCH /v1/management/bots/{bot_id}

Uuendage ühte või mitut välja teile kuuluval robotil. Muudetakse ainult JSON-is olevaid jaotisi/välju; kõik välja jäetud (või väärtusena null saadetud) andmed jäetakse puutumata. Saadetud jaotise sees kehtib osalise uuendamise semantika välja kohta.

Aktsepteeritakse kahte samaväärset sisutüüpi (Content-Type) (sama mis POST puhul):

Režiim A - tavaline JSON (soovitatav, kui uuendatakse ainult seadeid):

• Content-Type: application/json
• Päringu keha on patch JSON (ilma data mähiseta)

Režiim B - multipart/form-data (kasutage failide üleslaadimisel):

• data JSON-osa (valikuline) - muudatused. Saatke ainult siis, kui soovite välju muuta. Jätke täielikult välja, kui soovite üles laadida ainult avatari või logo.
• avatar failiosa (valikuline) - asendage avatar
• whitelabel_logo failiosa (valikuline) - asendage White Label logo (kehtib ainult juhul, kui teie konto sisaldab White Label funktsiooni)

Kõik kolm osa on PATCH-päringu puhul valikulised, kuid päringu mõttekuse tagamiseks peab vähemalt üks neist olemas olema.

Täielik päringu keha (maksimaalne maht)

Siin võib saata mis tahes välja, mida aktsepteerib POST /v1/management/bots. Allpool toodud näide on täielik maht; praktikas saadate ainult need võtmed, mida soovite muuta (vt allpool "Minimaalne osaline uuendus") - iga välja jäetud (või väärtusena null saadetud) võti jätab salvestatud väärtuse muutmata.

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

Minimaalne osaline uuendus

Tehke PATCH ühele väljale, saates täpselt need võtmed, mida soovite muuta - kõik muu säilitatakse.

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

Curl näited

Režiim A - tavaline JSON (kõige lihtsam):

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

Režiim B - multipart (avatari/logo asendamisel):

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'

Režiim B - asendage ainult avatar (välju ei muudeta):

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

Vastuse keha (200)

Sama kuju nagu GET /v1/management/bots/{bot_id} puhul - roboti täielik konfiguratsioon pärast patch-uuenduse rakendamist, sealhulgas plokk meta. Välja apiKey ei ole. Tagastab 404 not_found_error, kui robotit ei eksisteeri või see ei kuulu teie kontole.

Alltoodud näide kuvab vastust pärast ülaltoodud Täieliku päringu keha (maksimaalne maht) patch-uuenduse rakendamist GET-näite robotile - muudetud väljad kajastavad uusi väärtusi, puutumata väljad säilitatakse ning meta.updatedAt uueneb.

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

Lugege Management võtit omava konto praegust tellimuse kasutust.

Vastuse keha (200)

{
  "subscriptionType": "standard",
  "messages": {"used": 4123, "limit": 11000, "remaining": 6877},
  "bots": {"used": 3, "limit": 5, "remaining": 2}
}

• subscriptionType on konto praeguse paketi väiketähtedega identifikaator (nt näites standard). Paketid pärinevad dünaamilisest kataloogist, mistõttu identifikaatorite täpne hulk võib aja jooksul pakettide ümbernimetamisel või lisamisel muutuda - käsitlege seda läbipaistmatu stringina, mitte fikseeritud loendina (enum).
• messages.used / limit / remaining on praeguse arveldusperioodi sõnumikrediidid.
• bots.used / limit / remaining loendavad aktiivseid roboteid teie konto robotite limiidi suhtes.

Päringulimiidi päised

Vastused, mis jõuavad päringulimiidi kontrolli etapini (st autentimine ja IP-lubatud nimekiri on läbitud), sisaldavad järgmisi päiseid:

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

• X-RateLimit-Limit - sellele päringule tegelikult rakendatud võtmepõhine ülempiir (vaikimisi 10 või teie seadistatud rateLimitPerMinute, kui see on madalam).
• X-RateLimit-Remaining - salves vahetult pärast seda päringut järele jäänud märkide arv.
• X-RateLimit-Reset - Unixi ajatempli sekundid, millal järgmine märk muutub kättesaadavaks (see ei ole kogu salve lähtestamine; salve täidetakse pidevalt uuesti). Kui salv on täis, on see praegune kellaaeg.

Vastuste 429 rate_limit_exceeded korral määratakse ka päis Retry-After, mis väljendab täissekundeid seni, kuni vabaneb vähemalt üks märk.

Autentimiseelsed vead (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) ja 403 ip_not_whitelisted ei sisalda päiseid X-RateLimit-* - limiidihaldurit kontrollitakse alles pärast autentimise ja IP kontrolli edukat läbimist.

Vigade vorming

Sama ümbrik nagu funktsioonil Bot Talk API:

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

Valideerimisvead kasutavad väärtust code: "invalid_parameter" ja lisavad vea tekitanud välja teekonna sõnumi algusesse, et vigast jaotist oleks lihtne märgata:

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

Loetelu / piiratud väärtustega väljade valed väärtused (nt chatMemory.clientSummaryPromptType = "BOGUS") sisaldavad välja teekonda, tagasilükatud väärtust ja lubatud väärtuste loendit:

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

Seotud teemad

Vestluse lõpp-punktide ja SSE-voogedastuse kohta lugege juhendist Bot Talk API.