Management API

Management API:n yleiskatsaus

Management API on tarkoitettu taustajärjestelmien tehtäviin, joihin ei liity chat-viestien lähettämistä:

• luo botti ohjelmallisesti kutsulla POST /v1/management/bots
• lue omistamasi botin tiedot kutsulla GET /v1/management/bots/{bot_id}
• päivitä tiettyä bottia kutsulla PATCH /v1/management/bots/{bot_id}
• lue tilauksen käyttömäärät kutsulla GET /v1/usage

Management-avaimet on sidottu tiliisi, ei mihinkään tiettyyn bottiin. Ne pidetään tietoisesti erillään Bot Talk -avaimista, jotta kompromettoitunut chat-avain ei voisi muokata bottejasi tai lukea laskutustietojasi.

Base URL

https://api.chatlab.com/aichat

Kaikki tämän artikkelin päätepisteet suhteutetaan tähän perusosoitteeseen (base URL).

Aloittaminen

1. Avaa hallintasovellus ja siirry kohtaan Account Settings > Management API (Tilin asetukset > Management API).
2. Napsauta Create Management Key (Luo Management-avain), nimeä se, määritä valinnaisesti IP-osoitteiden sallittujen lista (whitelist) ja nopeusrajoitus (rate limit) sekä lähetä tiedot.
3. Valitse vain ne käyttöoikeudet, joita integraatiosi tarvitsee, ja kopioi koko avain onnistumisikkunasta. Selväkielinen avain näytetään vain kerran.
4. Tallenna se palvelimellesi, älä selaimen koodiin tai julkiseen koodipankkiin. Vahvista käyttöoikeus tekemällä vain lukuoikeutta vaativa pyyntö, kuten GET /v1/usage usage-käyttöoikeudella.
5. Kumoa käyttämättömät tai kompromettoituneet avaimet Management API -sivulta.

Avain näyttää tältä: mk_abcdefghijklmnopqrstuvwxyz012345. Etuliite mk_ erottaa sen Bot Talk -avaimista (ck_).

Todennus

Authorization: Bearer mk_abcdefghijklmnopqrstuvwxyz012345

mk_-avaimen lähettäminen osoitteeseen /v1/chat (tai mihin tahansa muuhun Bot Talk -päätepisteeseen) palauttaa virheen 403 key_type_not_allowed. ck_-avaimen lähettäminen osoitteeseen /v1/management/* palauttaa saman virheen.

Rajoitukset

• Enintään 5 aktiivista Management API -avainta käyttäjää kohden
• Enintään 10 pyyntöä minuutissa per avain (token bucket, kapasiteetti 10, tasainen täyttö noin 1 token joka 6. sekunti). Arvoa voi säätää alaspäin luontihetkellä - aseta pienempi rateLimitPerMinute, jolloin katto laskee ja täyttönopeus skaalautuu sen mukana.

Käyttöoikeudet

Kukin Management-avain sisältää minkä tahansa osajoukon alla mainituista kolmesta käyttöoikeudesta. Vähintään yksi on valittava luontihetkellä, muuten pyyntö hylätään virheellä 400 invalid_request_error. Päätepisteen kutsuminen avaimella, jolta puuttuu vaadittu käyttöoikeus, palauttaa virheen 403 insufficient_permissions.

• bot_read - vaaditaan kutsulle GET /v1/management/bots/{bot_id}
• bot_management - vaaditaan kutsuille POST /v1/management/bots ja PATCH /v1/management/bots/{bot_id}
• usage - vaaditaan kutsulle GET /v1/usage

Pyynnön runko: sisäkkäiset osiot, jotka heijastavat hallintapaneelin välilehtiä

POST ja PATCH hyväksyvät JSON-rungon, joka on jaettu 13 osioon. Kukin osio vastaa hallintasovelluksen Bot Settings -sivupalkin alavälilehteä, joten JSON-avaimet ja näkyvät välilehdet vastaavat toisiaan: jos muutat kenttää consent.humanSupportRequirePolicyAccept API:n kautta, näet saman valintakytkimen kääntyvän hallintasovelluksen välilehdellä Consent & Privacy (Suostumus ja tietosuoja).

• role - botin rooli (persona), raakaprompti, vastauksen pituus, kieli, verkkosivuston/yrityksen konteksti (Role & Behavior -välilehti)
• conversation - tervetuloviesti, kyselyn tarkennus, keskustelun jatkuvuus, arviointipainike ja työkaluvihjeet, ehdotettujen kysymysten sisältö sekä dynaamiset jatkokysymykset (Chat Conversation -välilehti)
• chatMemory - keskustelumuistin kytkin, tiivistelmäpromptit, kontekstin allokointi (Summaries & Memory -välilehti)
• appearance - värit, tekstit, mitat, mukautettu CSS, aloitusnäkymä, ehdotettujen kysymysten tyyli, automaattisen avaamisen toiminta, ihmiskirjoituksen simulointi, alatunnisteen markdown (Appearance -välilehti)
• humanSupport - yhteydenottolomake ihmisasiakaspalvelulle (Human Contact Form -välilehti)
• leadCollection - liidien keruulomake (Lead Collection -välilehti)
• liveChat - siirto live chatiin (Live Chat -välilehti)
• consent - kaikki neljä tietosuojaselosteen suostumuskytkintä sekä suostumusnäkymän teksti (Consent & Privacy -välilehti)
• whiteLabel - logon piilotus, mukautettu logolinkki, omalla verkkotunnuksella (custom domain) isännöinti (Whitelabel -välilehti)
• security - sallitut verkkotunnukset, roskapostisuodatin, keskustelun nopeusrajoitukset (Security -välilehti)
• voice - äänisyöte ja äänikeskustelut: malli, ääni, kielet, prompti, keston enimmäisraja (Voice Conversation -välilehti)
• multilingual - monikielisyystila, peruskieli, tarjotut kielet, tietopohjan kielen käsittely (Languages -välilehti)
• advanced - LLM-malli, lämpötila (temperature), kontekstin koko, botin viestirajoitus, sisäinen lokaali, Offer Cards (Model & Advanced -välilehti)

Muokattavista asetuksista vain name sijaitsee päätasolla, koska se yksilöi botin eikä kuulu millekään yksittäiselle välilehdelle.

Bot Settings -sivupalkissa on tällä hetkellä 16 alavälilehteä, ja niistä 13 vastaa yllä olevia osioita. Ne kolme alavälilehteä, joilla ei ole vastaavaa osiota, ovat Flow, Actions ja Forms - kaikki kolme käsitellään jäljempänä kohdassa "API:n soveltamisalan ulkopuolella". Ne 13, jotka vastaavat API-osioita, ovat Appearance, Chat Conversation, Role & Behavior, Human Contact Form, Lead Collection, Live Chat, Whitelabel, Consent & Privacy, Security, Model & Advanced, Summaries & Memory, Voice Conversation sekä Languages.

Pyynnön rungolla ja vastauksen rungolla on sama rakenne. Vastaus sisältää kaksi lisäkenttää:

• meta - vain luku: botin tunniste ja aikaleimat. Poista tämä kenttä muuttaaksesi GET-vastauksen kelvolliseksi POST-pyynnön rungoksi.
• apiKey - mukana vain luotaessa - vasta luotu Bot Talk API -avain uudelle botille.

Kaksi kenttää yhteisessä rakenteessa ovat vain luku -kenttiä - ne palautetaan vastauksessa, mutta ne jätetään huomiotta, jos yrität lähettää ne POST/PATCH-pyynnössä:

• appearance.avatarUrl - botin avatar-kuvan täydellinen julkinen URL-osoite (esim. https://api.chatlab.com/aichat/content/avatar_xyz.png). Tee siihen suora GET-pyyntö ladataksesi tiedoston. Jos haluat muuttaa sitä, lataa uusi tiedosto moniosaisen pyynnön (multipart) osan avatar kautta (katso PATCH).
• whiteLabel.whitelabelLogoUrl - whitelabel-ylätunnisteen logon täydellinen julkinen URL-osoite. Sama malli kuin avatarUrl-kentässä. Jos haluat muuttaa sitä, lataa uusi tiedosto moniosaisen pyynnön osan whitelabel_logo kautta (katso PATCH).

Molemmat URL-osoitteet käyttävät nykyisen pyynnön skeemaa, isäntää ja kontekstipolkua (scheme + host + context path), joten mukautetulla whitelabel-verkkotunnuksella ne palautetaan kyseiseen verkkotunnukseen pohjautuvina (esim. https://api.acme.com/aichat/content/...).

Lähetä osiolle arvo null ohittaaksesi sen PATCH-pyynnössä; lähetä arvo null osion sisällä olevalle yksittäiselle kentälle ohittaaksesi vain kyseisen kentän. Kenttätason null ei koskaan tyhjennä tallennettua arvoa - se tarkoittaa ainoastaan "älä muokkaa".

Roolin ja promptin muodostaminen

Järjestelmäprompti, jonka LLM lopulta saa, rakennetaan toisella kahdesta tavasta riippuen kentästä role.role. Kun tiedät kumpaa haaraa käytetään, tiedät mitkä kentät vaikuttavat toimintaan ja mitkä vain tallennetaan ilman vaikutusta.

Haara A - role.role on CUSTOMER_SUPPORT, SALES tai LEAD_COLLECTION_AGENT (mallipohjainen)

Taustajärjestelmä kokoaa promptin valmiista mallipohjasta ja jättää kentän role.rawPrompt täysin huomiotta (arvo tallennetaan silti botille, sitä ei vain käytetä). Mallipohjaan sisällytetään:

• role.role - roolin nimi (esim. "Customer Support") ja roolikohtaiset ohjeet, jotka lisätään automaattisesti
• name - botin nimi, joka syötetään aloituslauseeseen
• role.language - "Auto Detect" asettaa botin mukautumaan käyttäjän kieleen; mikä tahansa muu arvo (esim. "English", "Polish") muuttuu muotoon "Output in {language}, unless user uses another language"
• role.responseLength - yhdistetään tavoitesanamäärään: Concise ≈ 50 sanaa, Normal ≈ 100, Detailed ≈ 200
• role.websiteAddress - valinnainen; jos kenttä ei ole tyhjä, se lisätään muodossa "for the users of the website {url}"
• role.companyDescription - valinnainen; jos kenttä ei ole tyhjä, se lisätään lisäkappaleena ennen rooliohjeita

Tämä on suositeltu haara useimmille boteille - saat rooliin sovitetun toiminnan ja turvarajoitteet automaattisesti.

Haara B - role.role on CUSTOM (kutsujan määrittämä prompti)

Taustajärjestelmä käyttää kenttää role.rawPrompt roolipromptina ja liittää siihen alustan kiinteän vastauksen pituutta koskevan ohjeistuksen. Tämä on erillinen kentästä role.responseLength: valinnaista Concise/Normal/Detailed-asetusta ei syötetä CUSTOM-roolille. Samoin kentät language, websiteAddress ja companyDescription tallennetaan, mutta niitä ei lisätä tähän roolipromptiin. Sisällytä haluamasi kieli, vastauksen pituustavoite tai yrityskonteksti kenttään rawPrompt itse. Lisäksi voidaan toimittaa ajonaikaisia lisäohjeita ja haettua kontekstitietoa, joten rawPrompt ei muodosta mallin koko syötettä. Valmiin roolin sävyohjeita ei lisätä, mutta CUSTOM-vaihtoehdon valitseminen ei poista kaikkia alustan ohjeita.

Käytä arvoa CUSTOM vain silloin, kun mallipohjainen prompti ei sovi käyttötapaukseesi (esim. tarvitset hyvin toimialakohtaisen persoonan, omat turvarajoitteet tai epästandardin tulostemuodon).

Enum- ja suljetun joukon kentät

Enum- ja rajoitetut kentät hylkäävät virheelliset arvot koodilla 400 invalid_parameter. Muut kentät ovat tavallisia merkkijonoja, vaikka käyttöliittymä tarjoaisi kiinteän valintalistan. Käytä dokumentoitua kirjoitusasua ja validoi hyötykuormasi sen sijaan, että olettaisit kaikkien tukemattomien merkkijonojen tulevan hylätyiksi.

• role.role - CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM
• role.responseLength - Concise, Normal, Detailed
• role.language - kielen täydellinen englanninkielinen nimi hallintapaneelin pudotusvalikosta, esim. Auto Detect, English, Polish, Spanish, German, French, Italian, Portuguese, Dutch, Russian, Chinese (Simplified), Japanese, Arabic, Hindi ja noin 80 muuta. Arvo tallennetaan sellaisenaan ja sijoitetaan promptipohjaan, joten kaksikirjaimisia ISO-koodeja (en, pl) tai muita listan ulkopuolisia arvoja ei hylätä API:ssa, mutta ne aiheuttavat virheellisen ohjeen, kuten "Output in en, unless...". Oletusarvo on Auto Detect, jos kenttä jätetään pois luotaessa.
• advanced.model - katso jäljempää kohta "Tekoälyn tekstilaskentamallit". Tämä on merkkijono, ei validoitu enum-arvo pyynnön skeemassa; käytä tuettua arvoa, älä mielivaltaista mallin nimeä.
• advanced.chatContextSize - käytä arvoja 8000, 16000 tai 32000 käyttöliittymää vastaavasti. Tilin enimmäismäärän ylittävät arvot rajataan hiljaisesti; DTO ei pakota tätä kolmen arvon joukkoa.
• chatMemory.clientSummaryPromptType - DEFAULT, CUSTOM
• chatMemory.conversationSummaryPromptType - DEFAULT, CUSTOM
• appearance.chatAlignment - left, right
• appearance.minimizedDisplayMode - icon, minified, pill
• appearance.chatMessageLinkTarget - _blank, _self
• leadCollection.requireBeforeNewConversation - boolean-kytkin. Arvo true pakottaa käyttäjän täyttämään liidilomakkeen ennen keskustelun aloittamista; false antaa tekoälyn päättää, milloin lomake näytetään (oletus).

Rakenteiset kentät ja arvoalueet

Kentät, jotka näyttävät yksinkertaisilta merkkijonoilta tai numeroilta, mutta joilla on todellisuudessa tiettyjä muotoja, arvoalueita tai hallintapaneelin erityispiirteitä, jotka on hyvä tietää.

• advanced.temperature - sallittu arvoalue on 0.0 - 1.0, mikä vastaa hallintasovelluksen liukusäädintä. Tämän alueen ulkopuoliset arvot hylätään virheellä 400 invalid_parameter.

• chatMemory.summariesToKnowledgeRatio - kokonaislukuprosentti, 10-90; käyttöliittymä käyttää 10:n askelia, mutta API hyväksyy kaikki kokonaisluvut tältä väliltä. Oletusarvo on 50. Kun muisti on käytössä ja konteksti on suurempi kuin 8k, tämä asetus jakaa tietopohjan ja muistin budjetin sen jälkeen, kun prompti ja viimeaikainen keskustelu on varattu, ei koko mallin kontekstia. Arvolla 8k tämä asetus ei varaa budjettia tiivistelmille.

• liveChat.schedule - merkkijonoksi koodattu JSON, ei sisäkkäinen JSON-objekti verkkoliikenteessä. Palvelin tallentaa raakamerkkijonon sellaisenaan; hallintasovellus jäsentää sen asiakaspuolella aikataulueditoria renderöidessään. Jäsennettynä merkkijonon rakenne sisältää yhden tietueen viikonpäivää kohden sekä avaimen timezone:

  • kukin viikonpäivän avain (monday-sunday) vastaa rakennetta {enabled: boolean, from: "H:MM", to: "H:MM"} 24 tunnin muodossa
  • timezone on IANA-aikavyöhykkeen nimi (esim. "Europe/Warsaw", "America/New_York")

  Esimerkkiarvo (huomaa ulommat lainausmerkit ja suojatut sisemmät lainausmerkit - kyseessä on yksi merkkijonokenttä, ei sisäkkäinen objekti):

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

  Määritettyjen aikojen ulkopuolella vierailijalle näytetään teksti liveChat.outOfHoursMessage ja live chatiin siirto estetään. Sisäisen rakenteen validointi suoritetaan vain asiakaspuolella hallintapaneelissa - API hyväksyy virheellisen JSON-muodon tai tuntemattomat avaimet pelkkänä merkkijonona, ja ne näkyvät renderöintivirheenä vasta, kun käyttäjä avaa botin myöhemmin hallintasovelluksessa. Validoi rakenne omalla puolellasi ennen lähettämistä.

• conversation.positiveRatingTooltip / conversation.negativeRatingTooltip - lyhyet tekstit, jotka näytetään keskustelun arviointipainikkeiden 👍 / 👎 päällä, kun conversation.conversationRatingEnabled=true. Oletustekstit ovat "I like the response" / "I don't like the response". Näkyvät loppukäyttäjille.

• whiteLabel.hideRoboAssistLogo - White Label -ominaisuus, jota koskevat tilisi rajoitukset. Piilottaa alatunnisteen tekstin "Powered by ChatLab". Jos tilisi ei sisällä White Label -toimintoa, arvo tallennetaan mutta jätetään huomiotta ja alatunniste näytetään aina.

• whiteLabel.whitelabelLogoLink - White Label -ominaisuus, jota koskevat tilisi rajoitukset. Kohdeosoite, johon siirrytään mukautettua logoa napsautettaessa, kun hideRoboAssistLogo=true ja mukautettu logotiedosto on ladattu moniosaisen pyynnön osan whitelabel_logo kautta.

• appearance.simulateHumanTypingDelay - sekunteja (ei millisekunteja), kokonaisluku 0-200. Tauko peräkkäisten botin viestikuplien välillä, kun simulateHumanTyping=true. Oletusarvo on 5.

• appearance.autoOpenChatDelaySeconds - sekunteja, kokonaisluku. Viive ennen kuin widget avautuu automaattisesti, kun autoOpenChat=true ja autoOpenChatDelay=true.

• advanced.internalLocale - IETF:n lokaali-aluekoodi muodossa ll_CC (alaviiva, EI ll-CC yhdysmerkillä). Hyväksytyt arvot tulevat noin 95 lokaalin kiinteästä listasta: 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 monet muut. Pelkän kaksikirjaimisen koodin ("en") tai BCP-47-muodon ("en-US") lähettäminen ei ole sallittujen listalla. Oletusarvo on en_US. Tätä lokaalia käytetään päivämäärien ja numeroiden muotoiluun widgetin käyttöliittymässä, ja se on erillinen kentästä role.language (botin keskustelussa käyttämä kieli).

• security.talkMessagesRateLimit / security.talkMessagesRateLimitDurationSeconds - kokonaislukuja (lähetä JSON-numeroina, esim. 30, ei "30"). Aseta viestiraja arvoon 0 poistaaksesi tämän istuntokohtaisen rajoituksen käytöstä. Kun otat sen käyttöön, anna positiivinen kesto. Taustajärjestelmä valvoo, että istuntoa kohden sallitaan enintään N viestiä määritetyn sekuntimäärän aikana, ennen kuin vierailijalle näytetään viesti security.talkMessagesRateLimitHitMessage.

• advanced.botMessagesLimit - kokonaisluku (JSON-numero, esim. 1000). Arvo 0 tarkoittaa, ettei bottikohtaista lisäkattoa ole, jolloin tilin saldo (Credits) pätee edelleen sellaisenaan; muussa tapauksessa arvon on oltava 1000:n kerrannainen (1000, 2000, 10000, ...). Arvot kuten 100 tai 1500 hylätään virheellä 400 invalid_parameter. Tämä on botin kuukausittainen Credit-katto, ei keskustelukohtainen viestimäärä. Käsittelijä ei rajoita tätä arvoa tilin kokonaissaldomäärään; tilin saldo rajoittaa aina todellista käyttöä.

Tekoälyn tekstilaskentamallit (advanced.model)

Käytä tarkkaa mallitunnistetta, joka palautuu kentässä advanced.model, kun luet botin tietoja, johon haluamasi malli on määritetty kohdassa Settings > Model & Advanced (Asetukset > Malli ja lisäasetukset). Nykyinen oletusarvo luotaessa on 5.6-LUNA. Tunnisteet ovat merkkikokoriippuvaisia (case-sensitive) ja eroavat näyttönimistä; esimerkiksi 5.6-LUNA näytetään muodossa GPT 5.6-luna.

Mallivalikoima muuttuu ajan myötä. Älä oleta, että mikä tahansa merkkijono tai palveluntarjoajan julkinen mallitunniste olisi tuettu vain siksi, että pyynnön skeema hyväksyy merkkijonon. Lue tallennetut asetukset takaisin ja testaa luotua chatbotia ennen sen käyttöönottoa.

Kenttäviite (koko pyyntökaava)

Tuetut osiot ja kentät tyyppeineen ja tärkeine rajoituksineen. PATCH-semantiikka: minkä tahansa kentän pois jättäminen (tai arvon lähettäminen arvona null) jättää tallennetun arvon ennalleen. Samaa muotoa käytetään vastauksessa (pois lukien multipart-binaarisisältö; lisäksi mukana on vain luku -muotoinen meta-lohko jokaisessa vastauksessa sekä apiKey vain luontivastauksessa).

Päätaso

Field	Type	Constraint	Description
name	string	max 150, pakollinen luotaessa	Botin näyttönimi
role	object		Katso § role
conversation	object		Katso § conversation
chatMemory	object		Katso § chatMemory
appearance	object		Katso § appearance
humanSupport	object		Katso § humanSupport
leadCollection	object		Katso § leadCollection
liveChat	object		Katso § liveChat
consent	object		Katso § consent
whiteLabel	object		Katso § whiteLabel
security	object		Katso § security
advanced	object		Katso § advanced

Vain vastauksessa esiintyvät lisäykset:

• meta: { id, createdAt, updatedAt } - vain luku.
• apiKey - string, läsnä vain POST /v1/management/bots -vastauksessa - uuden botin juuri luotu Bot Talk -avain, joka palautetaan tasan kerran.

§ role

Field	Type	Constraint	Description
role	string (enum)	CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM	Persoonan esiasetus; valitsee kehotepohjan (katso "Role and prompt construction")
language	string	kielen koko englanninkielinen nimi (English, Polish, ...) tai Auto Detect	Ensisijainen kieli, joka syötetään kehotepohjaan
responseLength	string	∈ {Concise, Normal, Detailed}	Toivottu tekoälyvastauksen pituus
websiteAddress	string		Kehotekontekstina käytettävä verkkosivusto
companyDescription	string		Kehotekontekstina käytettävä yrityksen kuvaus
rawPrompt	string		Mukautettu järjestelmäkehote - käytetään sellaisenaan vain, kun role=CUSTOM

§ conversation

Field	Type	Constraint	Description
welcomeMessage	string		Ensimmäinen viesti, joka näytetään vierailijalle avattaessa
queryRefinementEnabled	boolean		Jos tosi, tarkenna vierailijan kysymystä ennen RAG-hakua
conversationContinuityEnabled	boolean		Jos tosi, palaavat vierailijat jatkavat viimeisintä keskusteluaan
conversationRatingEnabled	boolean		Jos tosi, näytä peukalo ylös/alas -arviointipainikkeet keskustelulle
positiveRatingTooltip	string		Positiivisen arviointipainikkeen työkaluvihje
negativeRatingTooltip	string		Negatiivisen arviointipainikkeen työkaluvihje
suggestedQuestions	string		Rivinvaihdoin erotellut kysysehdotukset / keskustelunavaukset
dynamicSuggestedFollowups	boolean		Jos tosi, tekoäly ehdottaa jatkokysymyksiä jokaisen vastauksen jälkeen
positiveRatingMessage	string		Positiivisen palautteen jälkeen näytettävä viesti
negativeRatingMessage	string		Negatiivisen palautteen jälkeen näytettävä viesti
hideSuggestedQuestionsAfterFirstUse	boolean		Piilota staattiset ehdotukset käytön jälkeen
dynamicFollowupsAutoIcons	boolean		Jos tosi, tekoäly valitsee emojikuvakkeet dynaamisille jatkoehdotuksille automaattisesti

§ chatMemory

Field	Type	Constraint	Description
enabled	boolean		Chat-muistiominaisuuden pääkytkin
summaryConversationsEnabled	boolean		Tallenna keskustelukohtaiset yhteenvedot
conversationSummaryPrompt	string		Mukautettu kehote kunkin keskustelun tiivistämiseen
conversationSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Käytetäänkö oletus- vai mukautettua yhteenvetokehotetta
clientSummaryPrompt	string		Mukautettu kehote asiakasprofiilin tiivistämiseen keskustelujen välillä
clientSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Oletus- vs. mukautettu asiakasprofiilikehote
summariesToKnowledgeRatio	int	10-90 (käyttöliittymän askelväli 10)	Yhteenvedoille varattu osuus (%) käytettävissä olevasta tieto-/muistibudjetista yli 8k:n konteksteissa

§ appearance

Field	Type	Constraint	Description
launcherLabelLine1	string	max 60	Avauspainikkeen tekstin ensimmäinen rivi
launcherLabelLine2	string	max 60	Avauspainikkeen tekstin toinen rivi
launcherTextColor	string		Avauspainikkeen tekstin väri
launcherDismissEnabled	boolean		Salli avauspainikkeen sulkeminen
widgetFontFamily	string	inter, system, nunito, lato, montserrat, poppins, source-serif, jetbrains-mono	Widgetin fonttiperhe
chatDrawerEnabled	boolean		Ota vetolaatikkotyylinen esitystapa käyttöön
launcherColor	string (hex)		Avauspainikkeen (chat-kuvakkeen) taustaväri
headerColor	string (hex)		Chatin ylätunnisteen taustaväri
titleColor	string (hex)		Chatin ylätunnisteen otsikkoväri
subtitleColor	string (hex)		Chatin ylätunnisteen alaotsikon väri
clientMessageBubbleColor	string (hex)		Vierailijan viestikuplan väri
clientMessageTextColor	string (hex)		Vierailijan viestitekstin väri
responseMessageBubbleColor	string (hex)		Botin vastauskuplan väri
responseMessageTextColor	string (hex)		Botin vastaustekstin väri
chatSubheader	string		Chatin otsikon alla näytettävä esittelyteksti
senderPlaceholder	string		Viestikentän paikkamerkkiteksti
resetConversationTooltip	string		Työkaluvihje "reset conversation" (nollaa keskustelu) -painikkeessa
chatAlignment	string (enum)	∈ {left, right}	Kummalle puolelle näyttöä chat kiinnitetään
launcherBottomMargin	int	0-500	Avauspainikkeen etäisyys alareunasta (px)
launcherSideMargin	int	0-500	Avauspainikkeen etäisyys sivureunasta (px)
displayShadow	boolean		Varjostus widgetin alla
customCss	string		Widgetin iframe-kehykseen lisättävä mukautettu CSS
chatMessageLinkTarget	string (enum)	∈ {_blank, _self}	Miten botin viesteissä olevat linkit avautuvat
minimizedDisplayMode	string (enum)	∈ {icon, minified, pill}	Pienennetty tila: käynnistyskuvake, kompakti viestipalkki tai pilleri
chatDesktopWidthPx	int		Työpöytäwidgetin leveys
chatDesktopHeightPx	int		Työpöytäwidgetin korkeus
chatMobileSizePercent	int		Mobiiliwidgetin koko prosentteina näkymästä
messageFontSize	int		Viestitekstin fonttikoko (px)
showChatbotBubblesDesktop	boolean		Näytä leijuvat herätekuplat työpöytänäkymässä
showChatbotBubblesMobile	boolean		Näytä leijuvat herätekuplat mobiilinäkymässä
chatbotBubblesDelaySeconds	int		Viive ennen herätekuplien ilmestymistä (sekuntia)
launcherIconFullSize	boolean		Näytä mukautettu avauspainikkeen kuvake reunasta reunaan upotetun sijaan
welcomeScreenEnabled	boolean		Näytä Welcome Screen (tervetulonäyttö) suoraan chattiin siirtymisen sijaan
welcomeScreenQuestionsLabel	string		Kysysehdotusten yläpuolella oleva teksti tervetulonäytössä
welcomeScreenHideHumanContactForm	boolean		Piilota asiakaspalvelijan yhteydenottolomakkeen toiminto ylätunnisteesta Welcome Screenin ollessa näkyvissä. Se tulee uudelleen näkyviin vierailijan ensimmäisen viestin jälkeen. Ennen 2026-09-02 luoduissa boteissa oletusarvo on true
welcomeScreenHideLiveChat	boolean		Piilota live-chatin toiminto ylätunnisteesta Welcome Screenin ollessa näkyvissä. Se tulee uudelleen näkyviin vierailijan ensimmäisen viestin jälkeen. Ennen 2026-09-02 luoduissa boteissa oletusarvo on true
headerActionsLayout	string	ICONS tai DROPDOWN	Miten Live Chat ja asiakaspalvelijan yhteydenottolomake tarjotaan chatin ylätunnisteessa: ICONS (oma kuvake kummallekin) tai DROPDOWN (ryhmiteltynä ylätunnisteen valikkoon). Ennen 2026-09-02 luoduissa boteissa oletusarvo on ICONS
stackSuggestedQuestions	boolean		Asettele kysysehdotukset allekkain (vs. rinnakkain)
suggestedQuestionsFontSize	int		Kysysehdotuspainikkeiden fonttikoko (px)
suggestedQuestionsTextColor	string (hex)		Kysysehdotuspainikkeen tekstin väri
suggestedQuestionsBackgroundColor	string (hex)		Kysysehdotuspainikkeen taustaväri
autoOpenChat	boolean		Avaa chat automaattisesti työpöydällä
autoOpenChatOnMobiles	boolean		Avaa chat automaattisesti mobiililaitteilla
autoOpenChatDelay	boolean		Käytä viivettä ennen automaattista avaamista
autoOpenChatDelaySeconds	int		Automaattisen avaamisen viive (sekuntia)
simulateHumanTyping	boolean		Jaa botin vastaus kupliin kirjoitusanimaation kera
simulateHumanTypingDelay	int	0-200	Viive kuplaviestien välillä (sekuntia)
footerMarkdown	string	max 255	Chatin alla näytettävä mukautettu markdown-alatunniste
avatarUrl	string	vain luku	Avatarin täydellinen julkinen URL-osoite; vaihtaaksesi sen lähetä tiedosto multipart-osan avatar kautta

Multipart-osiot POST/PATCH-pyynnöissä: avatar (tiedosto-osa). GET-pyynnöt / vastausrungot jättävät tiedostosisällön pois - vain URL-osoite siirretään verkossa.

§ humanSupport

Field	Type	Constraint	Description
enabled	boolean		Asiakaspalvelijan tuki -työnkulun kytkin
email	string	pakollinen (create-strict) kun enabled=true	Osoite, johon asiakaspalvelusähköpostit lähetetään
dialogMessage	string		Lomakkeen yläpuolella näytettävä kannustava viesti
thankYouMessage	string		Lähettämisen jälkeen näytettävä vahvistus
emailMessageSubjectTemplate	string		Asiakaspalvelijalle lähetettävän sähköpostin aihemalli
emailMessageContentTemplate	string		Asiakaspalvelijalle lähetettävän sähköpostin runkomalli
emailPlaceholder	string		Sähköpostikentän paikkamerkki
messagePlaceholder	string		Viestikentän paikkamerkki
emailWithConversationContent	boolean		Jos tosi, liitä keskusteluloki sähköpostin runkoon
customFormId	long	olemassa olevan mukautetun lomakkeen id	Korvaa sisäänrakennettu yhteydenottolomake mukautetulla lomakkeella. Luotaessa pois jättäminen käyttää sisäänrakennettua lomaketta; PATCH-pyynnössä null jättää nykyisen valinnan ennalleen
customFormMapping	string	JSON-koodattu merkkijono	Määrittää mukautetun lomakkeen kentät asiakaspalvelusähköpostin kenttiin

requirePolicyAccept sijaitsee kohdassa consent.humanSupportRequirePolicyAccept, ei täällä.

§ leadCollection

Field	Type	Constraint	Description
enabled	boolean		Liidilomakkeen kytkin
nameEnabled	boolean		Kerää nimi
nameLabel	string		Nimikentän otsikko
emailEnabled	boolean		Kerää sähköpostiosoite
emailLabel	string	pakollinen (create-strict) kun enabled=true JA emailEnabled=true	Sähköpostikentän otsikko
phoneEnabled	boolean		Kerää puhelinnumero
phoneLabel	string	pakollinen (create-strict) kun enabled=true JA phoneEnabled=true	Puhelinkentän otsikko
leaveDetailsMessage	string	pakollinen (create-strict) kun enabled=true	Viesti, joka kannustaa vierailijaa jättämään yhteystietonsa
thankYouMessage	string	pakollinen (create-strict) kun enabled=true	Lähettämisen jälkeen näytettävä vahvistus
requireBeforeNewConversation	boolean		Jos true, lomake on lähetettävä ennen keskustelun aloittamista; jos false, tekoäly päättää, milloin lomake esitetään
emailNotificationEnabled	boolean		Lähetä sähköposti omistajalle aina, kun liidi kerätään
emailNotificationAddress	string		Ilmoituksen vastaanottaja (oletuksena tilin sähköpostiosoite)
emailWithConversationContent	boolean		Jos tosi, liitä keskusteluloki ilmoitukseen

| customFormId | long | olemassa olevan mukautetun lomakkeen id | Korvaa sisäänrakennettu liidilomake mukautetulla lomakkeella. Luotaessa pois jättäminen käyttää sisäänrakennettua lomaketta; PATCH-pyynnössä null jättää nykyisen valinnan ennalleen | | customFormMapping | string | JSON-koodattu merkkijono | Määrittää mukautetun lomakkeen kentät kenttiin name / email / phone |

Kenttien välinen create-strict-sääntö: enabled=true vaatii vähintään toisen kentistä emailEnabled tai phoneEnabled. requirePolicyAccept sijaitsee kohdassa consent.leadCollectionRequirePolicyAccept, ei täällä.

§ liveChat

Field	Type	Constraint	Description
enabled	boolean		Live Chat -ominaisuuden kytkin
infoMessage	string		Ennen siirtoa näytettävä selittävä viesti
startMessage	string		Viesti, joka näytetään live-istunnon alkaessa
endMessage	string		Viesti, joka näytetään live-istunnon päättyessä
nameLabel	string		Nimikentän otsikko live-chatin esilomakkeessa
emailLabel	string		Sähköpostikentän otsikko live-chatin esilomakkeessa
schedule	string	JSON-koodattu merkkijono (viikonpäivävalinnat + from/to + timezone)	Live-chatin aukioloaikataulu - katso tarkka muoto kohdasta "Structured fields and ranges"
outOfHoursMessage	string		Viesti, joka näytetään aikataulun mukaisen aukioloajan ulkopuolella
closeModalMessage	string		"Suljetaanko live-chat?" -vahvistusikkunan otsikko
closeModalConfirmLabel	string		Vahvistuspainikkeen teksti sulkemisikkunassa
closeModalCancelLabel	string		Peruutuspainikkeen teksti sulkemisikkunassa
closeModalTooltipText	string		Chatin sulkemispainikkeen työkaluvihje
operatorHasJoinedLabel	string		Teksti, joka näytetään asiakaspalvelijan liittyessä
operatorDidNotJoinInTimeLabel	string		Teksti, joka näytetään, jos asiakaspalvelija ei liity aikarajan kuluessa
waitingForOperatorToJoinLabel	string		Teksti, joka näytetään odotettaessa asiakaspalvelijaa
waitingForOperatorSeconds	int		Asiakaspalvelijan vastausaikaraja (sekuntia)
redirectToHumanSupportForm	boolean		Jos tosi, siirry Human Support -lomakkeeseen, jos asiakaspalvelija ei vastaa
requireAdminOnline	boolean		Edellytä paikalla olevaa asiakaspalvelijaa läsnäoloasetusten mukaisesti
presenceMode	string		Läsnäolotila; käytä arvoa, joka on peräisin käyttöliittymässä määritetystä botista
hideHumanSupportWhenLiveChatAvailable	boolean		Piilota yhteydenottolomake, kun live-chat on käytettävissä
missedEmailEnabled	boolean	oletus true	Lähetä sähköposti botin omistajalle, kun live-chatin pyyntöön ei vastattu. Jätetty asettamatta aiemmissa boteissa, mikä tulkitaan käytössä olevaksi

requirePolicyAccept sijaitsee kohdassa consent.liveChatRequirePolicyAccept, ei täällä.

§ consent

Field	Type	Constraint	Description
newConversationRequirePolicyAccept	boolean		Edellytä tietosuojaselosteen hyväksymistä ennen uuden keskustelun aloittamista
humanSupportRequirePolicyAccept	boolean		Edellytä tietosuojaselosteen hyväksymistä ennen asiakaspalvelulomakkeen lähettämistä
leadCollectionRequirePolicyAccept	boolean		Edellytä tietosuojaselosteen hyväksymistä ennen liidilomakkeen lähettämistä
liveChatRequirePolicyAccept	boolean		Edellytä tietosuojaselosteen hyväksymistä ennen live-chat-istunnon aloittamista
newConversationConsentDescription	string		Suostumusnäkymän johdantoteksti keskustelun alussa
privacyPolicyConsentCheckboxLabel	string		Suostumusruudun vieressä oleva teksti (sisältää yleensä linkin tietosuojaselosteeseen)

§ whiteLabel

Field	Type	Constraint	Description
hideRoboAssistLogo	boolean	white-label-ominaisuus; tilin rajoitusten alainen	Piilota ChatLabin oletuslogo alatunnisteesta
whitelabelLogoLink	string	white-label-ominaisuus; tilin rajoitusten alainen	URL-osoite, johon mukautettu alatunnisteen logo linkittää
assignToCustomDomain	boolean	vaatii ominaisuuden CUSTOM_DOMAIN	Isännöi chattia määritetyssä mukautetussa verkkotunnuksessa
whitelabelLogoUrl	string	vain luku	White Label -logon täydellinen julkinen URL-osoite; vaihtaaksesi sen lähetä tiedosto multipart-osan whitelabel_logo kautta

Multipart-osiot POST/PATCH-pyynnöissä: whitelabel_logo (tiedosto-osa). GET-pyynnöt / vastausrungot jättävät tiedostosisällön pois - vain URL-osoite siirretään verkossa.

§ security

Field	Type	Constraint	Description
allowedDomains	string		Pilkuilla eroteltu luettelo verkkotunnuksista, joille widgetin upottaminen on sallittu (tyhjä = ei sallittujen luetteloa)
spamFilterEnabled	boolean		Ota käyttöön bottikohtainen roskapostisuodatin saapuville viesteille
countryFilterMode	string	BLACKLIST tai WHITELIST	Miten maaluetteloita tulkitaan. Itse luettelot ovat vain ylläpitäjien saatavilla
talkMessagesRateLimit	int	>= 0; 0 poistaa käytöstä	Käyttäjäviestien enimmäismäärä rajoitusikkunan aikana
talkMessagesRateLimitDurationSeconds	int	>= 0	Rajoitusikkunan kesto (sekuntia)
talkMessagesRateLimitHitMessage	string		Vierailijalle näytettävä viesti, kun viestiraja saavutetaan

§ voice

Field	Type	Constraint	Description
inputEnabled	boolean		Salli vierailijan sanella viestejä (puheesta tekstiksi)
conversationEnabled	boolean	vaatii tilauspakettiin kuuluvan äänitoiminnon	Ota käyttöön täydet äänikeskustelut
voiceId	string	palveluntarjoajakohtainen ääni-id (esim. alloy)	Mikä synteettinen ääni puhuu
model	string	esim. GPT-REALTIME-MINI, GEMINI-LIVE, ELEVENLABS-*	Äänimalli. Laskutetaan minuuttipohjaisesti, hinnat vaihtelevat mallikohtaisesti
turnDetection	string	palveluntarjoajakohtainen	Puheenvuorojen tunnistustila
audioPrompt	string		Järjestelmän lisäkehote, jota käytetään vain puheenvuoroissa
welcomeMessage	string		Puhuttu aloitusrepliikki
language	string	kielikoodi	Ensisijainen puhekieli
additionalLanguages	string	pilkuilla erotellut kielikoodit	Lisäkielet, joita puheagentti hyväksyy
maxDurationSeconds	int		Yhden äänikeskustelun ehdoton enimmäiskesto
maxDurationMessage	string		Viesti, joka näytetään enimmäiskeston saavuttamisen jälkeen

§ multilingual

Field	Type	Constraint	Description
enabled	boolean		Monikielisyystilan kytkin
mode	string	AUTODETECT tai FIXED_LIST	Miten botti valitsee vastauskielen
baseLanguage	string	kielikoodi	Kieli, jolla botin omat tekstit on kirjoitettu
languages	string	pilkuilla erotellut kielikoodit	Vierailijalle tarjottavat kielet
knowledgeLanguageMode	string	NONE, MAIN tai DYNAMIC	Miten muiden kielten tietosisältöä käsitellään
knowledgeLanguageFallback	string	kielikoodi	Kieli, jota käytetään, jos vastaavuutta ei löydy

§ advanced

Field	Type	Constraint	Description
model	string	tilin rajoitusten alainen; katso "AI text models" yllä	LLM-tunniste (esim. 5.6-LUNA)
temperature	decimal	0.0-1.0	Otantatemperatuuri (vastaa käyttöliittymän liukusäädintä)
chatContextSize	int	∈ {8000, 16000, 32000}; rajataan automaattisesti tilisi rajaan	Määritetty kontekstibudjetti sisältäen ohjeet, historian ja tietosisällön
botMessagesLimit	long	0 tai luvun 1000 kerrannainen (esim. 1000, 2000, 10000)	Kuukausittainen bottikohtaisten viesticreditsien raja (0 = ei erillistä bottirajaa; tilin budjetti pätee edelleen)
internalLocale	string	kielialuekoodi muodossa ll_CC	Widgetin käyttöliittymätekstien kielialue (eri asia kuin role.language)
productsViewEnabled	boolean		Jos tosi, näytä verkkokaupan Offer Cards -tuotekortit chatin sisällä
includeProductsInKnowledgeBase	boolean		Jos tosi, indeksoi tuotekatalogi osaksi tietopohjaa

API-rajapinnan ulkopuolelle jäävät toiminnot

Ylläpidon käyttöliittymä sisältää muutamia osioita, joita ei ole tarkoituksella tuotu saataville Management API:n tässä versiossa:

• Koulutus ja poistaminen - nämä päätepisteet eivät listaa kaikkia botteja, hallinnoi koulutusaineistoja tai poista botteja. Käytä näihin toimintoihin sovellusta.
• Flow tab - visuaalinen Conversation Flow Editor (keskusteluvirran editori) (vaiheet ja siirtymät). Ei saatavilla Management API:n kautta.
• Actions tab - hallinnoidut verkkokauppa- ja varausintegraatiot, AI Search sekä mukautetut API-funktiot. Työkalukutsut eivät ole koskaan olleet osa Management API -rajapintaa.
• Mukautettujen lomakkeiden rakennustyökalu - mukautettujen lomakkeiden luominen ja muokkaaminen ei ole saatavilla. Voit kuitenkin liittää olemassa olevan lomakkeen bottiin kenttien leadCollection.customFormId ja humanSupport.customFormId kautta.
• Mukautetut chatin avaus- ja sulkemiskuvakkeet - customLauncherIconVisible, openChatIcon, closeChatIcon. Rajapinta tarjoaa vain tärkeimmät multipart-osiot avatar ja whitelabel_logo.
• IP- ja maaluettelot - itse merkinnät ovat vain ylläpidon saatavilla. Vain tulkintatapa on tuotu saataville kentän security.countryFilterMode kautta.

Päätepisteet

POST /v1/management/bots

Luo uusi botti. Kaksi samanarvoista Content-Type-muotoa hyväksytään; valitse niistä itsellesi sopivampi.

Tapa A - pelkkä JSON (suositellaan, kun samassa pyynnössä ei tarvitse ladata avatar-kuvaa tai logoa):

• Content-Type: application/json
• Pyynnön runko on botin määrityksen JSON-rakenne (ei data-käärettä)
• Tiedostot (avatar / logo) voidaan ladata myöhemmin toisella PATCH-pyynnöllä tapaa B käyttäen

Tapa B - multipart/form-data (käytä, kun tiedostot ladataan samassa pyynnössä):

• Content-Type: multipart/form-data; boundary=...
• data JSON-osa (pakollinen, Content-Type: application/json) - botin määritys edellä kuvatussa sisäkkäisessä muodossa
• avatar-tiedosto-osa (valinnainen) - botin avatar-kuva
• whitelabel_logo-tiedosto-osa (valinnainen) - White Label -logo (sovelletaan vain, jos tilisi sisältää White Label -toiminnon)

JSONissa vain name on pakollinen; kaikki muut kentät saavat samat oletusarvot, jotka hallintapaneelin ohjattu toiminto asettaisi.

Esimerkki pyynnön rungosta

Tämä on laajin mahdollinen data-JSON - jokainen osio täytettynä. Lähetä vain ne osiot, joita tarvitset; kaikki muu saa oletusarvot.

{
  "name": "Helpdesk Bot",
  "role": {
    "rawPrompt": "You are a friendly support assistant for Acme Inc.",
    "role": "CUSTOMER_SUPPORT",
    "language": "English",
    "responseLength": "Normal",
    "websiteAddress": "https://acme.com",
    "companyDescription": "Acme sells industrial widgets."
  },
  "conversation": {
    "welcomeMessage": "Hi! How can I help today?",
    "queryRefinementEnabled": true,
    "conversationContinuityEnabled": true,
    "conversationRatingEnabled": true,
    "positiveRatingTooltip": "Helpful",
    "negativeRatingTooltip": "Not helpful",
    "suggestedQuestions": "What are your hours?\nHow do I cancel?\nWhere is my order?",
    "dynamicSuggestedFollowups": true,
    "dynamicFollowupsAutoIcons": true
  },
  "chatMemory": {
    "enabled": true,
    "summaryConversationsEnabled": true,
    "conversationSummaryPrompt": "Summarize this conversation in 3 sentences.",
    "clientSummaryPrompt": "Summarize what we know about this customer.",
    "clientSummaryPromptType": "DEFAULT",
    "conversationSummaryPromptType": "DEFAULT",
    "summariesToKnowledgeRatio": 50
  },
  "appearance": {
    "launcherColor": "#1A73E8",
    "headerColor": "#1A73E8",
    "titleColor": "#FFFFFF",
    "subtitleColor": "#FFFFFF",
    "clientMessageBubbleColor": "#000000",
    "clientMessageTextColor": "#FFFFFF",
    "responseMessageBubbleColor": "#F4F4F4",
    "responseMessageTextColor": "#000000",
    "chatSubheader": "AI support assistant",
    "senderPlaceholder": "Type a message...",
    "resetConversationTooltip": "Restart conversation",
    "chatAlignment": "right",
    "launcherBottomMargin": 20,
    "launcherSideMargin": 20,
    "displayShadow": true,
    "customCss": ".rcw-conversation-container { border-radius: 16px; }",
    "chatMessageLinkTarget": "_blank",
    "minimizedDisplayMode": "icon",
    "chatDesktopWidthPx": 400,
    "chatDesktopHeightPx": 600,
    "chatMobileSizePercent": 100,
    "messageFontSize": 14,
    "showChatbotBubblesDesktop": true,
    "showChatbotBubblesMobile": false,
    "chatbotBubblesDelaySeconds": 5,
    "welcomeScreenEnabled": false,
    "welcomeScreenQuestionsLabel": "Quick start",
    "welcomeScreenHideHumanContactForm": false,
    "welcomeScreenHideLiveChat": false,
    "headerActionsLayout": "DROPDOWN",
    "stackSuggestedQuestions": false,
    "suggestedQuestionsFontSize": 14,
    "suggestedQuestionsTextColor": "#000000",
    "suggestedQuestionsBackgroundColor": "#F4F4F4",
    "autoOpenChat": false,
    "autoOpenChatOnMobiles": false,
    "autoOpenChatDelay": false,
    "autoOpenChatDelaySeconds": 5,
    "simulateHumanTyping": true,
    "simulateHumanTypingDelay": 5,
    "footerMarkdown": "Powered by Acme"
  },
  "humanSupport": {
    "enabled": true,
    "email": "support@acme.com",
    "dialogMessage": "Leave us a message and we will get back to you.",
    "thankYouMessage": "Thanks - we received your message.",
    "emailMessageSubjectTemplate": "[Acme support] New message from {customerName}",
    "emailMessageContentTemplate": "{message}\n\n - \n{conversationTranscript}",
    "emailPlaceholder": "your@email.com",
    "messagePlaceholder": "How can we help?",
    "emailWithConversationContent": true
  },
  "leadCollection": {
    "enabled": true,
    "nameEnabled": true,
    "nameLabel": "Your name",
    "emailEnabled": true,
    "emailLabel": "Email",
    "phoneEnabled": false,
    "phoneLabel": "Phone",
    "leaveDetailsMessage": "Please leave your details and we will get in touch.",
    "thankYouMessage": "Thanks - we will be in touch shortly.",
    "requireBeforeNewConversation": false,
    "emailNotificationEnabled": true,
    "emailNotificationAddress": "leads@acme.com",
    "emailWithConversationContent": true
  },
  "liveChat": {
    "enabled": false,
    "infoMessage": "Connecting you with a human agent...",
    "startMessage": "You are now chatting with our team.",
    "endMessage": "Live chat has ended.",
    "nameLabel": "Your name",
    "emailLabel": "Email",
    "schedule": "{\"monday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"tuesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"wednesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"thursday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"friday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"saturday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"sunday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"timezone\":\"Europe/Warsaw\"}",
    "outOfHoursMessage": "We are currently offline.",
    "closeModalMessage": "End the live chat session?",
    "closeModalConfirmLabel": "Yes, end",
    "closeModalCancelLabel": "Cancel",
    "closeModalTooltipText": "End live chat",
    "operatorHasJoinedLabel": "An agent has joined.",
    "operatorDidNotJoinInTimeLabel": "No agent available right now.",
    "waitingForOperatorToJoinLabel": "Waiting for an agent...",
    "waitingForOperatorSeconds": 60,
    "redirectToHumanSupportForm": true
  },
  "consent": {
    "newConversationRequirePolicyAccept": false,
    "humanSupportRequirePolicyAccept": false,
    "leadCollectionRequirePolicyAccept": true,
    "liveChatRequirePolicyAccept": false,
    "newConversationConsentDescription": "By starting a conversation you agree to our terms.",
    "privacyPolicyConsentCheckboxLabel": "I have read and accepted the privacy policy."
  },
  "whiteLabel": {
    "hideRoboAssistLogo": false,
    "whitelabelLogoLink": "https://acme.com",
    "assignToCustomDomain": false
  },
  "security": {
    "allowedDomains": "acme.com,support.acme.com",
    "spamFilterEnabled": true,
    "talkMessagesRateLimit": 30,
    "talkMessagesRateLimitDurationSeconds": 60,
    "talkMessagesRateLimitHitMessage": "Please slow down."
  },
  "advanced": {
    "model": "5.6-LUNA",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  }
}

Validointisäännöt omine virheilmoituksineen:

• name - pakollinen, enintään 150 merkkiä
• advanced.temperature - välillä 0.0 ja 1.0
• chatMemory.summariesToKnowledgeRatio - kokonaisluku väliltä 10-90 (prosenttia, askelväli 10)
• appearance.launcherBottomMargin, appearance.launcherSideMargin - väliltä 0-500
• appearance.footerMarkdown - enintään 255 merkkiä
• humanSupport.enabled=true vaatii, että humanSupport.email on määritetty
• leadCollection.enabled=true vaatii, että vähintään toinen kentistä leadCollection.emailEnabled tai leadCollection.phoneEnabled on arvoltaan true; riippumatta siitä, kumpi kanava on käytössä, myös sen nimike sekä kentät leaveDetailsMessage ja thankYouMessage ovat pakollisia
• advanced.chatContextSize rajataan tilin tukemaan kontekstin enimmäiskokoon. Älä oleta, että muita numeerisia kenttiä rajattaisiin automaattisesti.

Kentät, joiden arvo palvelimella on null, jätetään pois JSON-rungosta - siirrossa välitetään vain kentät, joilla on muu kuin null-arvo.

Esimerkki vastausrungosta (201)

Sama rakenne kuin pyynnössä sekä lisäksi vain luku -muotoinen meta-lohko ja kertaalleen näytettävä apiKey päätasolla. Palvelin täyttää vain luku -muotoiset tiedostojen URL-osoitteet (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl), kun vastaavat multipart-osat ladattiin.

{
  "name": "Helpdesk Bot",
  "role": {
    "rawPrompt": "You are a friendly support assistant for Acme Inc.",
    "role": "CUSTOMER_SUPPORT",
    "language": "English",
    "responseLength": "Normal",
    "websiteAddress": "https://acme.com",
    "companyDescription": "Acme sells industrial widgets."
  },
  "conversation": {
    "welcomeMessage": "Hi! How can I help today?",
    "queryRefinementEnabled": true,
    "conversationContinuityEnabled": true,
    "conversationRatingEnabled": true,
    "positiveRatingTooltip": "Helpful",
    "negativeRatingTooltip": "Not helpful",
    "suggestedQuestions": "What are your hours?\nHow do I cancel?\nWhere is my order?",
    "dynamicSuggestedFollowups": true,
    "dynamicFollowupsAutoIcons": true
  },
  "chatMemory": {
    "enabled": true,
    "summaryConversationsEnabled": true,
    "conversationSummaryPrompt": "Summarize this conversation in 3 sentences.",
    "clientSummaryPrompt": "Summarize what we know about this customer.",
    "clientSummaryPromptType": "DEFAULT",
    "conversationSummaryPromptType": "DEFAULT",
    "summariesToKnowledgeRatio": 50
  },
  "appearance": {
    "launcherColor": "#1A73E8",
    "headerColor": "#1A73E8",
    "titleColor": "#FFFFFF",
    "subtitleColor": "#FFFFFF",
    "clientMessageBubbleColor": "#000000",
    "clientMessageTextColor": "#FFFFFF",
    "responseMessageBubbleColor": "#F4F4F4",
    "responseMessageTextColor": "#000000",
    "chatSubheader": "AI support assistant",
    "senderPlaceholder": "Type a message...",
    "resetConversationTooltip": "Restart conversation",
    "chatAlignment": "right",
    "launcherBottomMargin": 20,
    "launcherSideMargin": 20,
    "displayShadow": true,
    "customCss": ".rcw-conversation-container { border-radius: 16px; }",
    "chatMessageLinkTarget": "_blank",
    "minimizedDisplayMode": "icon",
    "chatDesktopWidthPx": 400,
    "chatDesktopHeightPx": 600,
    "chatMobileSizePercent": 100,
    "messageFontSize": 14,
    "showChatbotBubblesDesktop": true,
    "showChatbotBubblesMobile": false,
    "chatbotBubblesDelaySeconds": 5,
    "welcomeScreenEnabled": false,
    "welcomeScreenQuestionsLabel": "Quick start",
    "welcomeScreenHideHumanContactForm": false,
    "welcomeScreenHideLiveChat": false,
    "headerActionsLayout": "DROPDOWN",
    "stackSuggestedQuestions": false,
    "suggestedQuestionsFontSize": 14,
    "suggestedQuestionsTextColor": "#000000",
    "suggestedQuestionsBackgroundColor": "#F4F4F4",
    "autoOpenChat": false,
    "autoOpenChatOnMobiles": false,
    "autoOpenChatDelay": false,
    "autoOpenChatDelaySeconds": 5,
    "simulateHumanTyping": true,
    "simulateHumanTypingDelay": 5,
    "footerMarkdown": "Powered by Acme",
    "avatarUrl": "https://api.chatlab.com/aichat/content/avatar_a8f3b2c1_2026060110.png"
  },
  "humanSupport": {
    "enabled": true,
    "email": "support@acme.com",
    "dialogMessage": "Leave us a message and we will get back to you.",
    "thankYouMessage": "Thanks - we received your message.",
    "emailMessageSubjectTemplate": "[Acme support] New message from {customerName}",
    "emailMessageContentTemplate": "{message}\n\n - \n{conversationTranscript}",
    "emailPlaceholder": "your@email.com",
    "messagePlaceholder": "How can we help?",
    "emailWithConversationContent": true
  },
  "leadCollection": {
    "enabled": true,
    "nameEnabled": true,
    "nameLabel": "Your name",
    "emailEnabled": true,
    "emailLabel": "Email",
    "phoneEnabled": false,
    "phoneLabel": "Phone",
    "leaveDetailsMessage": "Please leave your details and we will get in touch.",
    "thankYouMessage": "Thanks - we will be in touch shortly.",
    "requireBeforeNewConversation": false,
    "emailNotificationEnabled": true,
    "emailNotificationAddress": "leads@acme.com",
    "emailWithConversationContent": true
  },
  "liveChat": {
    "enabled": false,
    "infoMessage": "Connecting you with a human agent...",
    "startMessage": "You are now chatting with our team.",
    "endMessage": "Live chat has ended.",
    "nameLabel": "Your name",
    "emailLabel": "Email",
    "schedule": "{\"monday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"tuesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"wednesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"thursday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"friday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"saturday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"sunday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"timezone\":\"Europe/Warsaw\"}",
    "outOfHoursMessage": "We are currently offline.",
    "closeModalMessage": "End the live chat session?",
    "closeModalConfirmLabel": "Yes, end",
    "closeModalCancelLabel": "Cancel",
    "closeModalTooltipText": "End live chat",
    "operatorHasJoinedLabel": "An agent has joined.",
    "operatorDidNotJoinInTimeLabel": "No agent available right now.",
    "waitingForOperatorToJoinLabel": "Waiting for an agent...",
    "waitingForOperatorSeconds": 60,
    "redirectToHumanSupportForm": true
  },
  "consent": {
    "newConversationRequirePolicyAccept": false,
    "humanSupportRequirePolicyAccept": false,
    "leadCollectionRequirePolicyAccept": true,
    "liveChatRequirePolicyAccept": false,
    "newConversationConsentDescription": "By starting a conversation you agree to our terms.",
    "privacyPolicyConsentCheckboxLabel": "I have read and accepted the privacy policy."
  },
  "whiteLabel": {
    "hideRoboAssistLogo": false,
    "whitelabelLogoLink": "https://acme.com",
    "assignToCustomDomain": false,
    "whitelabelLogoUrl": "https://api.chatlab.com/aichat/content/custom_logo_4287_2026060110.png"
  },
  "security": {
    "allowedDomains": "acme.com,support.acme.com",
    "spamFilterEnabled": true,
    "talkMessagesRateLimit": 30,
    "talkMessagesRateLimitDurationSeconds": 60,
    "talkMessagesRateLimitHitMessage": "Please slow down."
  },
  "advanced": {
    "model": "5.6-LUNA",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  },
  "meta": {
    "id": 4287,
    "createdAt": "2026-06-01T10:11:02Z",
    "updatedAt": "2026-06-01T10:11:02Z"
  },
  "apiKey": "ck_freshly_minted_bot_talk_key_here"
}

Kenttä apiKey näytetään vain luontivaiheessa - se on juuri luotu Bot Talk -avain, joka on sidottu uuteen bottiin. Selväkielinen avain näytetään vain kerran, eikä sitä voi hakea myöhemmin uudelleen API:sta; tallenna se heti omalle puolellesi.

Vastauksen Location-otsake sisältää uuden botin URL-osoitteen (/v1/management/bots/{id}).

Curl-esimerkit

Tapa A - pelkkä JSON (yksinkertaisin):

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

Tapa B - multipart avatar-kuvan kanssa:

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}

Palauttaa omistamasi botin nykyisen määrityksen.

Curl-esimerkki

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

Esimerkki vastausrungosta (200)

Sama rakenne kuin POST-vastauksessa lukuun ottamatta kertaalleen annettavaa apiKey-kenttää. meta-lohko sisältyy vastaukseen. Palauttaa virheen 404 not_found_error, jos bottia ei ole olemassa tai se ei kuulu tilillesi.

Nykyinen avatar ja White Label -logo esitetään täydellisinä vain luku -muotoisina URL-osoitteina (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) - joiden juurena on sama protokolla + isäntä + kontekstipolku, joka palveli tämän pyynnön. Nouda tiedostosisältö tekemällä GET-pyyntö suoraan näihin URL-osoitteisiin; jos haluat korvata kumman tahansa tiedoston, lataa uusi multipart-muotoisen avatar- tai whitelabel_logo-osan kautta PATCH-pyynnössä. Nämä URL-kentät ohitetaan, jos ne lähetetään pyynnön rungossa.

{
  "name": "Helpdesk Bot",
  "role": {
    "rawPrompt": "You are a friendly support assistant for Acme Inc.",
    "role": "CUSTOMER_SUPPORT",
    "language": "English",
    "responseLength": "Normal",
    "websiteAddress": "https://acme.com",
    "companyDescription": "Acme sells industrial widgets."
  },
  "conversation": {
    "welcomeMessage": "Hi! How can I help today?",
    "queryRefinementEnabled": true,
    "conversationContinuityEnabled": true,
    "conversationRatingEnabled": true,
    "positiveRatingTooltip": "Helpful",
    "negativeRatingTooltip": "Not helpful",
    "suggestedQuestions": "What are your hours?\nHow do I cancel?\nWhere is my order?",
    "dynamicSuggestedFollowups": true,
    "dynamicFollowupsAutoIcons": true
  },
  "chatMemory": {
    "enabled": true,
    "summaryConversationsEnabled": true,
    "conversationSummaryPrompt": "Summarize this conversation in 3 sentences.",
    "clientSummaryPrompt": "Summarize what we know about this customer.",
    "clientSummaryPromptType": "DEFAULT",
    "conversationSummaryPromptType": "DEFAULT",
    "summariesToKnowledgeRatio": 50
  },
  "appearance": {
    "launcherColor": "#1A73E8",
    "headerColor": "#1A73E8",
    "titleColor": "#FFFFFF",
    "subtitleColor": "#FFFFFF",
    "clientMessageBubbleColor": "#000000",
    "clientMessageTextColor": "#FFFFFF",
    "responseMessageBubbleColor": "#F4F4F4",
    "responseMessageTextColor": "#000000",
    "chatSubheader": "AI support assistant",
    "senderPlaceholder": "Type a message...",
    "resetConversationTooltip": "Restart conversation",
    "chatAlignment": "right",
    "launcherBottomMargin": 20,
    "launcherSideMargin": 20,
    "displayShadow": true,
    "customCss": ".rcw-conversation-container { border-radius: 16px; }",
    "chatMessageLinkTarget": "_blank",
    "minimizedDisplayMode": "icon",
    "chatDesktopWidthPx": 400,
    "chatDesktopHeightPx": 600,
    "chatMobileSizePercent": 100,
    "messageFontSize": 14,
    "showChatbotBubblesDesktop": true,
    "showChatbotBubblesMobile": false,
    "chatbotBubblesDelaySeconds": 5,
    "welcomeScreenEnabled": false,
    "welcomeScreenQuestionsLabel": "Quick start",
    "welcomeScreenHideHumanContactForm": false,
    "welcomeScreenHideLiveChat": false,
    "headerActionsLayout": "DROPDOWN",
    "stackSuggestedQuestions": false,
    "suggestedQuestionsFontSize": 14,
    "suggestedQuestionsTextColor": "#000000",
    "suggestedQuestionsBackgroundColor": "#F4F4F4",
    "autoOpenChat": false,
    "autoOpenChatOnMobiles": false,
    "autoOpenChatDelay": false,
    "autoOpenChatDelaySeconds": 5,
    "simulateHumanTyping": true,
    "simulateHumanTypingDelay": 5,
    "footerMarkdown": "Powered by Acme",
    "avatarUrl": "https://api.chatlab.com/aichat/content/avatar_a8f3b2c1_2026060110.png"
  },
  "humanSupport": {
    "enabled": true,
    "email": "support@acme.com",
    "dialogMessage": "Leave us a message and we will get back to you.",
    "thankYouMessage": "Thanks - we received your message.",
    "emailMessageSubjectTemplate": "[Acme support] New message from {customerName}",
    "emailMessageContentTemplate": "{message}\n\n - \n{conversationTranscript}",
    "emailPlaceholder": "your@email.com",
    "messagePlaceholder": "How can we help?",
    "emailWithConversationContent": true
  },
  "leadCollection": {
    "enabled": true,
    "nameEnabled": true,
    "nameLabel": "Your name",
    "emailEnabled": true,
    "emailLabel": "Email",
    "phoneEnabled": false,
    "phoneLabel": "Phone",
    "leaveDetailsMessage": "Please leave your details and we will get in touch.",
    "thankYouMessage": "Thanks - we will be in touch shortly.",
    "requireBeforeNewConversation": false,
    "emailNotificationEnabled": true,
    "emailNotificationAddress": "leads@acme.com",
    "emailWithConversationContent": true
  },
  "liveChat": {
    "enabled": false,
    "infoMessage": "Connecting you with a human agent...",
    "startMessage": "You are now chatting with our team.",
    "endMessage": "Live chat has ended.",
    "nameLabel": "Your name",
    "emailLabel": "Email",
    "schedule": "{\"monday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"tuesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"wednesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"thursday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"friday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"saturday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"sunday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"timezone\":\"Europe/Warsaw\"}",
    "outOfHoursMessage": "We are currently offline.",
    "closeModalMessage": "End the live chat session?",
    "closeModalConfirmLabel": "Yes, end",
    "closeModalCancelLabel": "Cancel",
    "closeModalTooltipText": "End live chat",
    "operatorHasJoinedLabel": "An agent has joined.",
    "operatorDidNotJoinInTimeLabel": "No agent available right now.",
    "waitingForOperatorToJoinLabel": "Waiting for an agent...",
    "waitingForOperatorSeconds": 60,
    "redirectToHumanSupportForm": true
  },
  "consent": {
    "newConversationRequirePolicyAccept": false,
    "humanSupportRequirePolicyAccept": false,
    "leadCollectionRequirePolicyAccept": true,
    "liveChatRequirePolicyAccept": false,
    "newConversationConsentDescription": "By starting a conversation you agree to our terms.",
    "privacyPolicyConsentCheckboxLabel": "I have read and accepted the privacy policy."
  },
  "whiteLabel": {
    "hideRoboAssistLogo": false,
    "whitelabelLogoLink": "https://acme.com",
    "assignToCustomDomain": false,
    "whitelabelLogoUrl": "https://api.chatlab.com/aichat/content/custom_logo_4287_2026060110.png"
  },
  "security": {
    "allowedDomains": "acme.com,support.acme.com",
    "spamFilterEnabled": true,
    "talkMessagesRateLimit": 30,
    "talkMessagesRateLimitDurationSeconds": 60,
    "talkMessagesRateLimitHitMessage": "Please slow down."
  },
  "advanced": {
    "model": "5.6-LUNA",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  },
  "meta": {
    "id": 4287,
    "createdAt": "2026-06-01T10:11:02Z",
    "updatedAt": "2026-06-01T11:02:19Z"
  }
}

Kloonaa botti

Pyyntörunko POST /v1/management/bots ja vastausrunko GET /v1/management/bots/{bot_id} jakavat saman rakenteen, joten kloonaus on kolmivaiheinen prosessi: tee GET lähdebottiin, poista palvelimen hallinnoimat tunnistekentät ja tee POST tulokselle.

1. Hae (GET) lähdebotti.

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

2. Poista ylimmän tason meta-lohko. meta-objekti (id, createdAt, updatedAt) on palvelimen hallinnoima ja vain luku -muodossa - sen jättäminen POST-runkoon ei aiheuta haittaa (palvelin ohittaa sen), mutta sen poistaminen tekee tarkoituksesta selkeän ja pitää hyötykuorman siistinä. Voit myös muokata name-kenttää, jotta kloonin erottaa lähteestä.

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

3. Luo klooni lähettämällä karsittu runko POST-pyynnöllä. Katso yllä olevasta POST /v1/management/bots -viitteestä koko rungon rakenne ja validointisäännöt.

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

Vastaus sisältää uuden botin meta.id-tunnisteen sekä vastaluodun apiKey-avaimen (kloonin Bot Talk -avaimen). Selkokielinen apiKey palautetaan vain tässä luontivastauksessa - kopioi se talteen ennen vastausrungon hävittämistä; sitä ei voi hakea myöhemmin.

Tämä kopioi tuetut asetukset, ei täysin koulutettua chatbotia. Nämä päätepisteet eivät kloonaa koulutussisältöä, keskusteluhistoriaa, integraatioita/toimintoja, Flow-prosessia eikä lomakemäärityksiä. Määritä ne erikseen sovelluksessa.

Muita huomioitavia asioita:

• Tiedostoja ei kloonata. Kentät appearance.avatarUrl ja whiteLabel.whitelabelLogoUrl ovat vain luku -muodossa ja osoittavat lähdebotin tiedostoihin. Jos tarvitset kloonille saman avatarin tai white-label-logon, lataa tavut lähde-URL-osoitteista ja lähetä ne multipart-muodossa avatar- / whitelabel_logo-osina - joko luonnin POST-pyynnössä (tila B) tai sitä seuraavassa PATCH-pyynnössä.
• Bot Talk -avaimia ei kloonata. Jokaisella botilla on oma Bot Talk -avaimien valikoimansa. Yksittäinen luonnin POST-pyynnön palauttama apiKey on ainoa automaattisesti luotu avain; luo tarvittaessa lisäavaimia botin API-välilehdeltä.

PATCH /v1/management/bots/{bot_id}

Päivitä yksi tai useampi kenttä omistamassasi botissa. Vain ne osiot / kentät muuttuvat, jotka ovat mukana JSONissa; kaikki pois jätetty (tai arvona null lähetetty) jätetään ennalleen. Osittaisen päivityksen periaatteita sovelletaan kenttäkohtaisesti lähetetyn osion sisällä.

Pyyntö hyväksyy kaksi vastaavaa Content-Type-tyyppiä (kuten POST):

Tila A - pelkkä JSON (suositellaan, kun päivitetään vain asetuksia):

• Content-Type: application/json
• Pyyntörunko on patch-JSON (ei data-käärettä)

Tila B - multipart/form-data (käytä tiedostoja ladattaessa):

• data-JSON-osa (valinnainen) - patch-päivitys. Lähetä vain, jos haluat muuttaa kenttiä. Jätä kokonaan pois, jos haluat ladata vain avatarin tai logon.
• avatar-tiedosto-osa (valinnainen) - korvaa avatar
• whitelabel_logo-tiedosto-osa (valinnainen) - korvaa white-label-logo (koskee vain tilejä, joihin sisältyy White Label)

Kaikki kolme osaa ovat valinnaisia PATCH-pyynnössä, mutta vähintään yhden on oltava mukana, jotta kutsulla olisi merkitystä.

Esimerkkipyyntörunko (useita osioita)

Mikä tahansa kenttä, jonka POST /v1/management/bots hyväksyy, voidaan lähettää myös täällä. Alla oleva esimerkki havainnollistaa useita osioita, ei kaikkia tuettuja kenttiä; käytännössä lähetät vain ne avaimet, joita haluat muuttaa (katso "Minimaalinen osittainen päivitys" alempana) - jokainen pois jätetty (tai arvona null lähetetty) avain jättää tallennetun arvon ennalleen.

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

Minimaalinen osittainen päivitys

Päivitä yksittäinen kenttä PATCH-pyynnöllä lähettämällä vain ne avaimet, joita haluat muuttaa - kaikki muu säilyy ennallaan.

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

Curl-esimerkit

Tila A - pelkkä JSON (yksinkertaisin):

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

Tila B - multipart (avataria / logoa korvattaessa):

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'

Tila B - korvaa vain avatar (ei kenttämuutoksia):

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

Vastausrunko (200)

Sama rakenne kuin GET /v1/management/bots/{bot_id} - botin koko konfiguraatio patchin soveltamisen jälkeen, mukaan lukien meta-lohko. Ei sisällä apiKey-kenttää. Palauttaa virheen 404 not_found_error, jos bottia ei ole olemassa tai se ei kuulu tilillesi.

Alla oleva esimerkki näyttää vastauksen sen jälkeen, kun yllä oleva Täysi pyyntörunko (useita osioita) -patch on otettu käyttöön GET-esimerkin botille - muuttuneet kentät heijastavat uusia arvoja, koskemattomat kentät säilyvät ja meta.updatedAt päivittyy.

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

Lue Management-avaimen omistavan tilin nykyinen tilauksen käyttömäärä.

Vastausrunko (200)

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

• subscriptionType on tilin nykyisen tilauksen pienin kirjaimin kirjoitettu tunniste (your-plan-id on havainnollistava paikanvaraaja). Tilaukset tulevat dynaamisesta luettelosta, joten tarkka tunnistevalikoima voi muuttua ajan myötä, kun tilauksia nimetään uudelleen tai lisätään - käsittele tätä peitettynä merkkijonona, ei kiinteänä enum-luettelona.
• messages.used / limit / remaining ovat kuluvan kalenterikuukauden viestisaldomäärät, jotka nollautuvat kuukauden ensimmäisenä päivänä, eivät tilauksen uusimispäivänä. Ne ovat saldopainotettuja, eivät pelkkiä vastausten määriä.
• bots.used / limit / remaining laskevat omistetut botit, mukaan lukien pysäytetyt botit, tilisi bottien kokonaiskiintiötä vasten.

Pyyntörajojen otsikot (Rate limit headers)

Vastaukset, jotka etenevät pyyntörajojen tarkistusvaiheeseen (eli todennus ja IP-osoitteiden sallittujen lista on läpäisty), sisältävät seuraavat otsikot:

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

• X-RateLimit-Limit - tälle kutsulle todellisuudessa sovellettu avainkohtainen yläraja (oletuksena 10 tai määrittämäsi rateLimitPerMinute, jos se on pienempi).
• X-RateLimit-Remaining - säiliössä heti tämän kutsun jälkeen jäljellä olevat poletit.
• X-RateLimit-Reset - Unix epoch -aika sekunteina, jolloin seuraava poletti tulee saataville (ei koko säiliön nollaus; säiliö täyttyy jatkuvasti). Kun säiliö on täynnä, tämä on nykyinen aika.

Vastauksissa 429 rate_limit_exceeded asetetaan myös otsikko Retry-After, joka ilmaisee kokonaisina sekunteina ajan siihen, kunnes vähintään yksi poletti vapautuu.

Todennusta edeltävät virheet (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) ja 403 ip_not_whitelisted eivät sisällä X-RateLimit-*-otsikoita - pyyntörajoitinta käytetään vasta, kun todennus ja IP-tarkistukset ovat onnistuneet.

Virhemuoto

Sama kääre kuin Bot Talk API:ssa:

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

Validointivirheet käyttävät koodia code: "invalid_parameter" ja lisäävät virheellisen kentän polun viestin alkuun, jotta virheellinen kohta on helppo havaita:

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

Virheelliset arvot enum- tai rajoitetun arvojoukon kentissä (esim. chatMemory.clientSummaryPromptType = "BOGUS") sisältävät kentän polun, hylätyn arvon sekä sallittujen arvojen luettelon:

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

Liittyvät aiheet

Keskustelupäätepisteet ja SSE-suoratoisto kuvataan ohjeessa Bot Talk API.