Ohjekeskus
Chat API

Management API

Viimeksi päivitetty:

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 tietyn omistamasi botin tiedot kutsulla GET /v1/management/bots/{bot_id}
  • päivitä tietty botti 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 tarkoituksella erillään Bot Talk -avaimista, jotta vaarantunut chat-avain ei voi muokata bottejasi tai lukea laskutustietojasi.

Perus-URL (Base URL)

https://api.chatlab.com/aichat

Kaikki tämän artikkelin päätepisteet ovat suhteessa tähän perus-URL-osoitteeseen.

Aloittaminen

  1. Avaa hallintasovellus ja siirry kohtaan Account Settings > Management API (Tilin asetukset > Management API).
  2. Napsauta Create Management Key (Luo Management-avain), anna sille nimi, määritä halutessasi IP-sallittujen luettelo ja pyyntörajoitus (rate limit) ja vahvista.
  3. Kopioi koko avain onnistumisikkunasta. Selväkielinen avain näytetään vain kerran.

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

Todennus

Authorization: Bearer mk_abcdefghijklmnopqrstuvwxyz012345

Jos lähetät mk_-avaimen päätepisteeseen /v1/chat (tai mihin tahansa muuhun Bot Talk -päätepisteeseen), vastauksena on 403 key_type_not_allowed. Vastaavasti ck_-avaimen lähettäminen päätepisteeseen /v1/management/* palauttaa saman virheen.

Rajoitukset

  • Enintään 5 aktiivista Management API -avainta käyttäjää kohden
  • Enintään 10 pyyntöä minuutissa avainta kohden (token bucket, kapasiteetti 10, tasainen täyttö noin 1 poletti 6 sekunnin välein). Voidaan määrittää pienemmäksi luontivaiheessa - aseta matalampi rateLimitPerMinute, jolloin yläraja laskee ja täyttönopeus skaalautuu sen mukaan.

Käyttöoikeudet

Jokainen Management-avain sisältää minkä tahansa osajoukon alla olevista kolmesta käyttöoikeudesta. Vähintään yksi on valittava luontivaiheessa; muuten pyyntö hylätään virheellä 400 invalid_request_error. Päätepisteen kutsuminen avaimella, jolta puuttuu vaadittu 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

Rungon rakenne: sisäkkäiset osiot, jotka vastaavat hallintapaneelin välilehtiä

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

  • role - botin persoona, raaka kehote, vastauksen pituus, kieli, verkkosivuston/yrityksen konteksti (Role & Behavior -välilehti)
  • conversation - tervetuloviesti, kyselyn tarkennus, keskustelun jatkuvuus, arviointivalitsin + työkaluvihjeet, ehdotettujen kysymysten sisältö + dynaamiset jatkokysymykset (Chat Conversation -välilehti)
  • chatMemory - keskustelumuistin valitsin, yhteenvetokehotteet, kontekstin kohdentaminen (Summaries & Memory -välilehti)
  • appearance - värit, tekstit, mitat, mukautettu CSS, aloitusnäkymä, ehdotettujen kysymysten tyyli, automaattisen avaamisen toiminta, kirjoitussimulaatio, alatunnisteen markdown (Appearance -välilehti)
  • humanSupport - yhteydenottolomake ihmiselle (Human Contact Form -välilehti)
  • leadCollection - liidien keruulomake (Lead Collection -välilehti)
  • liveChat - siirto asiakaspalvelijalle (Live Chat -välilehti)
  • consent - kaikki neljä tietosuojaselosteen suostumusvalitsinta sekä suostumusnäkymän teksti (Consent & Privacy -välilehti)
  • whiteLabel - logon piilotus, mukautetun logon linkki, mukautetun verkkotunnuksen ylläpito (Whitelabel -välilehti)
  • security - sallitut verkkotunnukset, roskapostisuodatin, keskustelujen pyyntörajoitukset (Security -välilehti)
  • voice - äänisyöte ja äänikeskustelut: malli, ääni, kielet, kehote, 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, kontekstin koko, bottiviestien raja, sisäinen lokaali, Offer Cards (Model & Advanced -välilehti)

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ä 15 alavälilehteä, ja niistä 13 vastaa yllä olevia osioita. Kaksi alavälilehteä, joilla ei ole vastaavaa osiota, ovat Flow ja Actions - molemmat käsitellään jäljempänä kohdassa "API:n soveltamisalan ulkopuolella". Ne 13, jotka vastaavat osioita, ovat Appearance, Chat Conversation, Role & Behavior, Human Contact Form, Lead Collection, Live Chat, Whitelabel, Consent & Privacy, Security, Model & Advanced, Summaries & Memory, Voice Conversation ja Languages.

Pyyntörungolla ja vastausrungolla on sama rakenne. Vastaus sisältää kaksi lisäkenttää:

  • meta - vain luku: botin tunniste ja aikaleimat. Poista tämä, jos haluat muuntaa GET-vastauksen kelvolliseksi POST-rungoksi.
  • apiKey - mukana vain luonnin yhteydessä - juuri luotu Bot Talk API -avain uudelle botille.

Kaksi jaetun rakenteen sisällä olevaa kenttää ovat vain luku -kenttiä - ne palautetaan vastauksessa, mutta 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 tavut. Voit muuttaa sitä lataamalla uuden tiedoston moniosaisen avatar-osan kautta (katso PATCH).
  • whiteLabel.whitelabelLogoUrl - White Label -ylätunnisteen logon täydellinen julkinen URL-osoite. Sama toimintaperiaate kuin kentässä avatarUrl. Voit muuttaa sitä lataamalla uuden tiedoston moniosaisen whitelabel_logo-osan kautta (katso PATCH).

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

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

Rooli ja kehotteen muodostaminen

Järjestelmäkehote, jonka LLM todellisuudessa vastaanottaa, rakennetaan jommallakummalla tavalla riippuen arvosta role.role. Kun tiedät kummassa haarassa olet, tiedät mitkä kentät ovat merkityksellisiä ja mitkä tallennetaan mutta jätetään huomiotta.

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

Taustajärjestelmä kokoaa kehotteen valmiista mallipohjasta ja jättää kentän role.rawPrompt kokonaan huomiotta (arvo tallennetaan silti botille, sitä ei vain käytetä). Mallipohja yhdistää seuraavat tiedot:

  • role.role - roolin nimike (esim. "Customer Support") ja automaattisesti lisättävät roolikohtaiset ohjeet
  • name - botin nimi, joka lisätään aloituslauseeseen
  • role.language - "Auto Detect" asettaa botin seuraamaan käyttäjän kieltä; mikä tahansa muu arvo (esim. "English", "Polish") muuntuu 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 määritetty, lisätään muodossa "for the users of the website {url}"
  • role.companyDescription - valinnainen; jos määritetty, lisätään lisäkappaleena ennen rooliohjeita

Tämä on suositeltu haara useimmille boteille - saat rooliin sovitetun toiminnan ja suojakaiteet ilman lisävaivaa.

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

Taustajärjestelmä käyttää kenttää role.rawPrompt sellaisenaan koko järjestelmäkehotteena. Kentät responseLength, language, websiteAddress ja companyDescription tallennetaan, mutta niitä ei lisätä kehotteeseen - jos haluat jonkin niistä heijastuvan botin toimintaan, sinun on sisällytettävä ne itse rawPrompt-tekstiin. Roolikohtaisia suojakaiteita tai sävyohjeita ei myöskään lisätä; hallitset koko kehotetta itse.

Käytä tilaa CUSTOM vain silloin, kun mallipohjainen kehote ei sovi käyttötapaukseesi (tarvitset esimerkiksi hyvin toimialakohtaisen persoonan, omat turvallisuusrajoitteet tai poikkeavan tulostemuodon).

Enum- / kiinteät arvokentät

Useat kentät hyväksyvät vain kiinteän joukon merkkijonoarvoja. Minkä tahansa luettelon ulkopuolisen arvon lähettäminen hylätään virheellä 400 validation_failed, ja kentän polku ilmoitetaan parametrissa error.param. Arvoissa kirjainkoko on merkitsevä (case-sensitive).

  • 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 kehotemalliin, joten kaksimerkkisiä ISO-koodeja (en, pl) tai muita luettelon ulkopuolisia arvoja ei hylätä API:ssa, mutta ne tuottavat virheellisen ohjeen, kuten "Output in en, unless...". Oletusarvo on Auto Detect, jos kenttä jätetään pois luotaessa.
  • advanced.model - katso alla oleva kohta "AI-tekstimallit"; valittavissa oleva joukko riippuu tilisi rajoituksista, ja mikä tahansa arvo, jota tilisi ei voi käyttää, palauttaa virheen 400 invalid_parameter
  • advanced.chatContextSize - 8000, 16000, 32000. Tilisi rajoitusten alainen; suuremmat arvot rajataan automaattisesti sallittuun enimmäismäärään
  • chatMemory.clientSummaryPromptType - DEFAULT, CUSTOM
  • chatMemory.conversationSummaryPromptType - DEFAULT, CUSTOM
  • appearance.chatAlignment - left, right
  • appearance.minimizedDisplayMode - icon, minified
  • appearance.chatMessageLinkTarget - _blank, _self
  • leadCollection.requireBeforeNewConversation - boolean-valitsin. 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 tietty rakenne, arvoalue tai hallintapaneeliin liittyviä huomioitavia erityispiirteitä.

  • advanced.temperature - hyväksytty arvoalue on 0.0-1.0, mikä vastaa hallintapaneelin liukusäädintä. Tämän alueen ulkopuolella olevat arvot hylätään virheellä 400 validation_failed.

  • chatMemory.summariesToKnowledgeRatio - kokonaislukumuotoinen prosentti, 10-90 10:n välein. Määrittää, kuinka suuri osa keskustelukontekstista varataan asiakkaan aiemmille yhteenvedoille suhteessa muuhun osaan (tietopohja, nykyinen keskustelu, ohjeet). Oletusarvo on 50. Arvoalueen 10-90 ulkopuolella olevat arvot hylätään virheellä 400 validation_failed. Pätevä vain, kun chatMemory.enabled=true JA chatMemory.summaryConversationsEnabled=true.

  • liveChat.schedule - merkkijonoksi koodattu JSON, ei sisäkkäinen JSON-objekti verkkoliikenteessä. Palvelin tallentaa raakamerkkijonon sellaisenaan; hallintasovelluksen käyttöliittymä jäsentää sen asiakaspäässä aikataulueditoria muodostaessaan. Jäsennettynä merkkijonon rakenne sisältää yhden tietueen viikonpäivää kohden sekä timezone-avaimen:

    • kukin viikonpäivä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 siirto live chatiin estetään. Sisäisen rakenteen validointi suoritetaan vain asiakaspuolella hallintapaneelin käyttöliittymässä - virheellinen JSON tai tuntemattomat avaimet hyväksytään API:ssa pelkkänä merkkijonona, ja ne ilmenevät renderöintivirheenä vasta, kun joku avaa botin myöhemmin hallintapaneelissa. Validoi rakenne omassa järjestelmässäsi ennen lähettämistä.

  • conversation.positiveRatingTooltip / conversation.negativeRatingTooltip - lyhyet tekstit, jotka näkyvät kunkin tekoälyvastauksen vieressä olevissa 👍 / 👎 -painikkeissa, 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, joka riippuu tilisi rajoituksista. Piilottaa alatunnisteen "Powered by ChatLab" -tekstin. Jos tilisi ei sisällä White Label -ominaisuuksia, arvo tallennetaan mutta jätetään huomiotta, ja alatunniste näytetään aina.

  • whiteLabel.whitelabelLogoLink - White Label -ominaisuus, joka riippuu tilisi rajoituksista. Mukautetun logon napsautuksen kohde-URL, kun hideRoboAssistLogo=true ja mukautettu logotiedosto on ladattu moniosaisen whitelabel_logo-osan kautta.

  • appearance.simulateHumanTypingDelay - sekunteina (ei millisekunteina), kokonaisluku 0-200. Viive peräkkäisten bottikuplien välillä, kun simulateHumanTyping=true. Oletusarvo on 5.

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

  • advanced.internalLocale - IETF-lokaali- ja aluekoodi muodossa ll_CC (alaviiva, EI ll-CC yhdysmerkillä). Hyväksytyt arvot tulevat noin 95 lokaalin kiinteästä luettelosta: 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 kaksimerkkisen koodin ("en") tai BCP-47-muodon ("en-US") lähettäminen ei sisälly sallittujen luetteloon. 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 keskustelun tulostuskieli).

  • security.talkMessagesRateLimit / security.talkMessagesRateLimitDurationSeconds - kokonaislukuja (lähetetään JSON-numeroina, esim. 30, ei "30"). Arvo 0 poistaa IP-kohtaisen rajoituksen käytöstä. Kun arvo on muu kuin nolla, widget rajoittaa viestien määrän N viestiin määritetyn sekuntimäärän aikana ennen kuin vierailijalle näytetään teksti security.talkMessagesRateLimitHitMessage.

  • advanced.botMessagesLimit - kokonaisluku (JSON-numero, esim. 1000). Arvo 0 tarkoittaa "ei rajoitusta"; muuten arvon on oltava 1000:n kerrannainen (1000, 2000, 10000, ...). Arvot kuten 100 tai 1500 hylätään virheellä 400 validation_failed. Tämän lisäksi arvo rajataan automaattisesti tilisi enimmäisrajaan.

AI-tekstimallit (advanced.model)

Lähetä tarkka API-arvo (vasen koodimerkitty sarake). Näyttönimi hallintapaneelissa on sulkeissa. Tilisi rajoitukset määrittävät, mikä osajoukko on valittavissa; sellaisen mallin lähettäminen, jota tilisi ei voi käyttää, palauttaa virheen 400 invalid_parameter. Uusien bottien oletusarvo 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)

Kenttäviite (koko pyyntöskema)

Kaikki verkon yli kulkevat kentät tyyppeineen, rajoitteineen ja yksirivisine kuvauksineen. PATCH-semantiikka: minkä tahansa kentän jättäminen pois (tai lähettäminen arvona null) jättää tallennetun arvon ennalleen. Samaa rakennetta käytetään vastauksessa (pois lukien moniosainen binaarisisältö; lisäksi mukana on vain luku -muotoinen meta-lohko jokaisessa vastauksessa ja apiKey ainoastaan 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, mukana vain pyynnön 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 Roolipersoonan esiasetus; valitsee prompt-pohjan (katso "Role and prompt construction")
language string kielen koko englanninkielinen nimi (English, Polish, ...) tai Auto Detect Prompt-pohjaan syötettävä ensisijainen kieli
responseLength string ∈ {Concise, Normal, Detailed} Tekoälyn vastauksen toivottu pituus
websiteAddress string Promptin kontekstina käytettävä verkkosivusto
companyDescription string Promptin kontekstina käytettävä yrityksen kuvaus
rawPrompt string Mukautettu järjestelmäprompti - käytetään sellaisenaan vain, kun role=CUSTOM

§ conversation

Field Type Constraint Description
welcomeMessage string Ensimmäinen viesti, joka näytetään vierailijalle chatin avautuessa
queryRefinementEnabled boolean Jos tosi, tarkenna vierailijan kysymystä ennen RAG-hakua
conversationContinuityEnabled boolean Jos tosi, palaavat vierailijat jatkavat edellistä keskusteluaan
conversationRatingEnabled boolean Jos tosi, näytä peukku ylös / peukku alas -arvostelu botin viesteissä
positiveRatingTooltip string Työkaluvihje positiivisen arvostelun painikkeessa
negativeRatingTooltip string Työkaluvihje negatiivisen arvostelun painikkeessa
suggestedQuestions string Rivinvaihdoilla erotellut kysymysehdotukset / keskustelunavaukset
dynamicSuggestedFollowups boolean Jos tosi, tekoäly ehdottaa jatkokysymyksiä jokaisen vastauksen jälkeen
dynamicFollowupsAutoIcons boolean Jos tosi, tekoäly valitsee emojikuvakkeet dynaamisille jatkoehdotuksille automaattisesti

§ chatMemory

Field Type Constraint Description
enabled boolean Chat-muistitoiminnon pääkytkin
summaryConversationsEnabled boolean Tallenna keskustelukohtaiset yhteenvedot
conversationSummaryPrompt string Mukautettu prompti kunkin keskustelun tiivistämiseen
conversationSummaryPromptType string (enum) ∈ {DEFAULT, CUSTOM} Käytetäänkö oletusarvoista vai mukautettua yhteenvetopromptia
clientSummaryPrompt string Mukautettu prompti asiakasprofiilin tiivistämiseen eri keskustelujen pohjalta
clientSummaryPromptType string (enum) ∈ {DEFAULT, CUSTOM} Oletusarvoinen vs mukautettu asiakasprofiiliprompti
summariesToKnowledgeRatio int 10-90, askel 10 Chatin konteksti-ikkunan prosenttiosuus, joka varataan yhteenvedoille verrattuna RAG-tietopohjaan

§ appearance

Field Type Constraint Description
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 alaotsikkoväri
clientMessageBubbleColor string (hex) Vierailijan viestikuplan väri
clientMessageTextColor string (hex) Vierailijan viestin tekstivä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 keskustelun nollauspainikkeessa
chatAlignment string (enum) ∈ {left, right} Kummalle näytön puolelle chat kiinnitetään
launcherBottomMargin int 0-500 Avauspainikkeen etäisyys alareunasta (px)
launcherSideMargin int 0-500 Avauspainikkeen etäisyys sivureunasta (px)
displayShadow boolean Putoava varjo widgetin alla
customCss string Widgetin iframe-kehykseen lisättävä mukautettu CSS
chatMessageLinkTarget string (enum) ∈ {_blank, _self} Miten botin viestien sisällä olevat linkit avautuvat
minimizedDisplayMode string (enum) ∈ {icon, minified} Pienennetty tila: avauskuvake tai kompakti syöttöpalkki
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äversiossa
showChatbotBubblesMobile boolean Näytä leijuvat herätekuplat mobiiliversiossa
chatbotBubblesDelaySeconds int Viive ennen herätekuplien ilmestymistä (sekuntia)
launcherIconFullSize boolean Näytä mukautettu avauskuvake reunaan asti upotuksen sijaan
welcomeScreenEnabled boolean Näytä Welcome Screen suoraan chattiin siirtymisen sijaan
welcomeScreenQuestionsLabel string Tervetulonäytön kysymysehdotusten yläpuolella oleva teksti
welcomeScreenHideHumanContactForm boolean Piilota ylätunnisteen yhteydenottolomaketoiminto 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 ylätunnisteen live chat -toiminto 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 DROPDOWN Miten Live Chat ja ihmisen 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 Pinoa kysymysehdotukset päällekkäin (vierekkäin asettelun sijaan)
suggestedQuestionsFontSize int Kysymysehdotuspainikkeiden fonttikoko (px)
suggestedQuestionsTextColor string (hex) Kysymysehdotuspainikkeen tekstiväri
suggestedQuestionsBackgroundColor string (hex) Kysymysehdotuspainikkeen taustaväri
autoOpenChat boolean Avaa chat automaattisesti työpöydällä
autoOpenChatOnMobiles boolean Avaa chat automaattisesti mobiilissa
autoOpenChatDelay boolean Käytä viivettä ennen automaattista avaamista
autoOpenChatDelaySeconds int Automaattisen avaamisen viive (sekuntia)
simulateHumanTyping boolean Jaa botin vastaus kupliin kirjoitusanimaatiolla
simulateHumanTypingDelay int 0-200 Viestikuplien välinen viive (sekuntia)
footerMarkdown string max 255 Chatin alla näytettävä mukautettu alatunnisteen markdown-teksti
avatarUrl string vain luku Profiilikuvan täydellinen julkinen URL-osoite; voit vaihtaa sen lataamalla tiedoston moniosaisen avatar-osan kautta

Moniosainen lähetys POST-/PATCH-pyynnöissä: avatar (tiedosto-osa). GET-pyynnöt ja vastausrungot eivät sisällä tiedoston sisältöä - ainoastaan URL-osoite välitetään verkon yli.

§ humanSupport

Field Type Constraint Description
enabled boolean Human Support -työnkulun kytkin
email string pakollinen (create-strict), kun enabled=true Osoite, johon asiakaspalvelupyynnöt lähetetään sähköpostitse
dialogMessage string Lomakkeen yläpuolella näytettävä kannustava viesti
thankYouMessage string Lähettämisen jälkeen näytettävä vahvistusviesti
emailMessageSubjectTemplate string Asiakaspalvelijalle lähetettävän sähköpostin aihemallipohja
emailMessageContentTemplate string Asiakaspalvelijalle lähetettävän sähköpostin viestirungon mallipohja
emailPlaceholder string Sähköpostikentän paikkamerkkiteksti
messagePlaceholder string Viestialueen paikkamerkkiteksti
emailWithConversationContent boolean Jos tosi, liitä keskusteluhistoria sähköpostiviestin runkoon
customFormId long olemassa olevan mukautetun lomakkeen id Korvaa sisäänrakennettu yhteydenottolomake mukautetulla lomakkeella. null säilyttää sisäänrakennetun lomakkeen
customFormMapping string JSON-koodattu merkkijono Määrittää mukautetun lomakkeen kentät asiakastuen sähköpostikenttiin

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

§ 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 chatin alkamista; jos false, tekoäly päättää, milloin lomake näytetään
emailNotificationEnabled boolean Lähetä sähköposti omistajalle aina, kun uusi liidi kerätään
emailNotificationAddress string Ilmoituksen vastaanottaja (oletuksena tilin sähköpostiosoite)
emailWithConversationContent boolean Jos tosi, liitä keskusteluhistoria ilmoitukseen

Kenttien välinen create-strict-sääntö: enabled=true edellyttää, että vähintään toinen kentistä emailEnabled tai phoneEnabled on käytössä. requirePolicyAccept sijaitsee kohdassa consent.leadCollectionRequirePolicyAccept, ei tässä.

| customFormId | long | olemassa olevan mukautetun lomakkeen id | Korvaa sisäänrakennettu liidilomake mukautetulla lomakkeella. null säilyttää sisäänrakennetun lomakkeen | | customFormMapping | string | JSON-koodattu merkkijono | Määrittää mukautetun lomakkeen kentät nimen, sähköpostin ja puhelinnumeron arvoihin |

§ liveChat

Field Type Constraint Description
enabled boolean Live Chat -toiminnon 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äkytkimet + from/to + timezone) Live Chatin aukioloaikataulu - katso tarkka rakenne kohdasta "Structured fields and ranges"
outOfHoursMessage string Viesti, joka näytetään, kun palvelu on aikataulun mukaan suljettu
closeModalMessage string "Suljetaanko Live Chat?" -vahvistusikkunan otsikko
closeModalConfirmLabel string Vahvista-painikkeen teksti sulkemisikkunassa
closeModalCancelLabel string Peruuta-painikkeen teksti sulkemisikkunassa
closeModalTooltipText string Työkaluvihje chatin sulkemispainikkeessa
operatorHasJoinedLabel string Teksti, joka näytetään, kun asiakaspalvelija liittyy keskusteluun
operatorDidNotJoinInTimeLabel string Teksti, joka näytetään, kun asiakaspalvelija ei liity aikarajan kuluessa
waitingForOperatorToJoinLabel string Teksti, joka näytetään asiakaspalvelijaa odotettaessa
waitingForOperatorSeconds int Asiakaspalvelijan vastausaikaraja (sekuntia)
redirectToHumanSupportForm boolean Jos tosi, ohjaa ihmistuen lomakkeeseen, kun asiakaspalvelija ei vastaa
missedEmailEnabled boolean oletus true Lähetä sähköposti botin omistajalle, kun Live Chat -pyyntöön ei vastattu. Vanhoissa boteissa määrittelemätön arvo tulkitaan käytössä olevaksi

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

§ consent

Field Type Constraint Description
newConversationRequirePolicyAccept boolean Vaadi tietosuojaselosteen hyväksyminen ennen uuden keskustelun aloittamista
humanSupportRequirePolicyAccept boolean Vaadi tietosuojaselosteen hyväksyminen ennen ihmistuen lomakkeen lähettämistä
leadCollectionRequirePolicyAccept boolean Vaadi tietosuojaselosteen hyväksyminen ennen liidilomakkeen lähettämistä
liveChatRequirePolicyAccept boolean Vaadi tietosuojaselosteen hyväksyminen 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; tilikohtaisten rajoitusten alainen Piilota oletusarvoinen ChatLab-logo alatunnisteesta
whitelabelLogoLink string White Label -ominaisuus; tilikohtaisten rajoitusten alainen URL-osoite, johon alatunnisteen mukautettu logo linkittää
assignToCustomDomain boolean vaatii CUSTOM_DOMAIN-ominaisuuden Isännöi chattia määritetyssä omassa verkkotunnuksessa
whitelabelLogoUrl string vain luku White Label -logon täydellinen julkinen URL-osoite; voit vaihtaa sen lataamalla tiedoston moniosaisen whitelabel_logo-osan kautta

Moniosainen lähetys POST-/PATCH-pyynnöissä: whitelabel_logo (tiedosto-osa). GET-pyynnöt ja vastausrungot eivät sisällä tiedoston sisältöä - ainoastaan URL-osoite välitetään verkon yli.

§ security

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

§ voice

Field Type Constraint Description
inputEnabled boolean Salli vierailijan sanelevan viestejä (puheesta tekstiksi)
conversationEnabled boolean vaatii äänitoiminnon tilauksessa Ota käyttöön täydet äänikeskustelut
voiceId string palveluntarjoajakohtainen äänen tunniste (esim. alloy) Millä synteettisellä äänellä puhutaan
model string esim. GPT-REALTIME-MINI, GEMINI-LIVE, ELEVENLABS-* Äänimalli. Laskutetaan minuuttikohtaisesti, hinnat vaihtelevat malleittain
turnDetection string palveluntarjoajakohtainen Puheenvuorojen tunnistustila
audioPrompt string Ylimääräinen järjestelmäprompti, jota käytetään vain puheenvuoroissa
welcomeMessage string Ääneen lausuttu aloitusrepliikki
language string kielikoodi Ensisijainen puhekieli
additionalLanguages string pilkuin erotellut kielikoodit Lisäkielet, joita puheagentti tukee
maxDurationSeconds int Yksittäisen äänikeskustelun ehdoton enimmäiskesto
maxDurationMessage string Viesti, joka näytetään, kun enimmäiskesto saavutetaan

§ multilingual

Field Type Constraint Description
enabled boolean Monikielisyystilan kytkin
mode string AUTODETECT tai kiinteän luettelon tila Miten botti valitsee vastauskielen
baseLanguage string kielikoodi Kieli, jolla botin oma teksti on laadittu
languages string pilkuin erotellut kielikoodit Vierailijalle tarjottavat kielet
knowledgeLanguageMode string Miten muunkieliseen tietopohjaan suhtaudutaan
knowledgeLanguageFallback string kielikoodi Kieli, jota käytetään, kun vastaavuutta ei löydy

§ advanced

Field Type Constraint Description
model string tilikohtaisten rajojen alainen; katso "AI text models" edeltä LLM-tunniste (esim. 5-MINI)
temperature decimal 0.0-1.0 Otantaterävyys / temperature (vastaa käyttöliittymän liukusäädintä)
chatContextSize int ∈ {8000, 16000, 32000}; rajataan hiljaisesti tilisi rajoituksen mukaan Keskusteluhistorian token-ikkuna
botMessagesLimit long 0 tai 1000:n kerrannainen (esim. 1000, 2000, 10000) Botin vastausten enimmäismäärä keskustelua kohden (0 = ei rajoitusta)
internalLocale string kieliasetuskoodi muodossa ll_CC Widgetin käyttöliittymätekstien kieli (eri kuin role.language)
productsViewEnabled boolean Jos tosi, näytä verkkokaupan Offer Cards chatin sisällä
includeProductsInKnowledgeBase boolean Jos tosi, indeksoi tuotekatalogi osaksi tietopohjaa

API-rajapinnan ulkopuolella

Ylläpitorajapinnassa on muutamia alueita, joita ei ole tarkoituksella tuotu esiin tässä Management API -versiossa:

  • Flow-välilehti (Flow tab) - visuaalinen Flow Editor (vaiheet ja siirtymät). Ei saatavilla Management API:n kautta.
  • Actions-välilehti (Actions tab) - hallinnoidut verkkokauppa- ja varausintegraatiot, AI Search sekä mukautetut API-funktiot. Työkalukutsut eivät ole koskaan olleet osa Management API:a.
  • Mukautettujen lomakkeiden rakennustyökalu itsessään - 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. API tukee vain tärkeimpiä moniosaisia osia avatar ja whitelabel_logo.
  • IP- ja maaluettelot - itse merkinnät ovat vain pääkäyttäjien saatavilla. Vain tulkintatila on käytettävissä kentän security.countryFilterMode kautta.

Päätepisteet

POST /v1/management/bots

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

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

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

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

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

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

Koko pyynnön runko

Tämä on laajin mahdollinen data-JSON, jossa kaikki osiot on täytetty. 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-MINI",
    "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älillä 10 ja 90 (prosenttia, askelväli 10)
  • appearance.launcherBottomMargin, appearance.launcherSideMargin - välillä 0 ja 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 tosi (true); kumpi tahansa kanava onkaan päällä, se vaatii myös nimikkeensä sekä kentät leaveDetailsMessage ja thankYouMessage
  • Rajatut kentät (advanced.chatContextSize, advanced.botMessagesLimit jne.) rajataan hiljaisesti tilisi rajoitusten mukaisiksi

Kentät, joiden arvo palvelimella on null, jätetään pois JSON-rungosta - tiedonsiirrossa välitetään vain kentät, joilla on ei-tyhjä arvo.

Koko vastausrunko (201)

Sama rakenne kuin pyynnössä, lisättynä vain luku -muotoisella meta-lohkolla ja kerran näytettävällä apiKey-arvolla 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-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"
}

Kenttä apiKey näytetään vain luonnin yhteydessä - se on uuteen bottiin sidottu, juuri luotu Bot Talk -avain. Selkokielinen arvo näytetään vain kerran, eikä sitä voi hakea myöhemmin API:sta; tallenna se heti omaan järjestelmääsi.

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 profiilikuvalla:

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 nykyiset määritykset.

Curl-esimerkki

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

Koko vastausrunko (200)

Sama rakenne kuin POST-pyynnön vastauksessa ilman kerran näytettävää apiKey-kenttää. meta-lohko sisältyy vastaukseen. Palauttaa virheen 404 not_found_error, jos bottia ei ole olemassa tai se ei kuulu tilillesi.

Nykyinen profiilikuva ja White Label -logo esitetään täydellisinä vain luku -muotoisina URL-osoitteina (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) - niiden juurena on sama protokolla + isäntä + kontekstipolku, joka palveli tämän pyynnön. Nouda tavut tekemällä GET-pyyntö suoraan näihin osoitteisiin; kummankin tiedoston korvaamiseksi lataa uusi tiedosto PATCH-pyynnön multipart-osassa avatar / whitelabel_logo. Nämä URL-kentät jätetään huomiotta, 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-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"
  }
}

Kloonaa botti

Pyyntörunko metodille POST /v1/management/bots ja vastausrunko metodille GET /v1/management/bots/{bot_id} noudattavat samaa rakennetta, joten kloonaus on kolmivaiheinen prosessi: tee GET-pyyntö lähdebottiin, poista palvelimen hallinnoimat tunnistekentät ja lähetä tulos POST-pyynnöllä.

1. Hae lähdebotti GET-pyynnöllä.

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 -muotoinen - sen jättäminen POST-pyynnön runkoon ei aiheuta haittaa (palvelin jättää sen huomiotta), mutta sen poistaminen tekee tarkoituksesta selkeän ja pitää hyötykuorman siistinä. Voit myös halutessasi muokata name-kenttää, jotta klooni erottuu lähteestä.

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

3. Lähetä karsittu runko POST-pyynnöllä kloonin luomiseksi. Katso täydellinen rungon rakenne ja validointisäännöt ylempää kohdasta 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

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

Kaksi huomionarvoista asiaa:

  • Tiedostoja ei kloonata. Kentät appearance.avatarUrl ja whiteLabel.whitelabelLogoUrl ovat vain luku -muotoisia ja viittaavat lähdebotin tiedostoihin. Jos tarvitset kloonille saman profiilikuvan tai White Label -logon, lataa tavut lähdeosoitteista ja lähetä ne multipart-muodossa kentissä avatar / whitelabel_logo - joko luontikutsun POST-pyynnössä (tapa B) tai myöhemmässä PATCH-pyynnössä.
  • Bot Talk -avaimia ei kloonata. Jokaisella botilla on oma Bot Talk -avainten varantonsa. Luontikutsun POST-pyynnön palauttama yksittäinen apiKey on ainoa, joka luodaan automaattisesti; luo lisäavaimia tarvittaessa botin API (API) -välilehdeltä.

PATCH /v1/management/bots/{bot_id}

Päivitä vähintään yksi kenttä omistamassasi botissa. Vain ne osiot ja kentät, jotka ovat mukana JSON-objektissa, muuttuvat; kaikki pois jätetyt (tai arvona null lähetetyt) pidetään ennallaan. Osittaisten päivitysten periaatetta sovelletaan kenttäkohtaisesti lähetetyssä osiossa.

Pyyntö hyväksyy kaksi samanarvoista Content-Type-otsaketta (kuten POST):

Tapa A - pelkkä JSON (suositus, kun päivitetään vain asetuksia):

  • Content-Type: application/json
  • Pyyntörunko on korjaustiedot sisältävä JSON (ilman data-käärettä)

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

  • data-JSON-osa (valinnainen) - päivitystiedot. Lähetä vain, jos haluat muuttaa kenttiä. Jätä kokonaan pois, jos haluat vain ladata profiilikuvan tai logon.
  • avatar-tiedosto-osa (valinnainen) - korvaa profiilikuvan
  • whitelabel_logo-tiedosto-osa (valinnainen) - korvaa White Label -logon (käytettävissä vain, jos tilaukseesi kuuluu White Label)

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

Täysi pyyntörunko (kattavin rakenne)

Kaikki kentät, jotka POST /v1/management/bots hyväksyy, voidaan lähettää myös täällä. Alla oleva esimerkki esittelee täyden rakenteen; käytännössä lähetät vain ne avaimet, joita haluat muuttaa (katso alempana "Minimaalinen osittainen päivitys") - 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

Tee PATCH-päivitys yhteen kenttään lähettämällä vain ne avaimet, jotka haluat muuttaa - kaikki muu säilytetään.

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

Curl-esimerkit

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

Tapa B - multipart (profiilikuvaa tai logoa vaihdettaessa):

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'

Tapa B - pelkän profiilikuvan vaihtaminen (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 kutsussa GET /v1/management/bots/{bot_id} - botin täysi konfiguraatio päivityksen soveltamisen jälkeen, mukaan lukien meta-lohko. Ei 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ä kuvattu Täysi pyyntörunko (kattavin rakenne) -päivitys on kohdistettu GET-esimerkin bottiin - 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": "standard",
  "messages": {"used": 4123, "limit": 11000, "remaining": 6877},
  "bots": {"used": 3, "limit": 5, "remaining": 2}
}
  • subscriptionType on pienillä kirjaimilla kirjoitettu tunniste tilin nykyiselle tilaukselle (esim. standard esimerkissä). Tilaukset tulevat dynaamisesta luettelosta, joten tarkka tunnistevalikoima voi muuttua ajan kuluessa pakettien uudelleennimeämisen tai uusien lisäysten myötä - käsittele tätä peitettynä merkkijonona (opaque string), ei kiinteänä luettelointityyppinä (enum).
  • messages.used / limit / remaining ovat nykyisen laskutuskauden viesticreditit.
  • bots.used / limit / remaining laskevat aktiiviset botit suhteessa tilisi bottirajoitukseen.

Pyyntörajoitusten otsikot (Rate limit headers)

Vastaukset, jotka etenevät pyyntörajoitusvaiheeseen asti (eli tunnistautuminen 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ähän kutsuun sovellettu avainkohtainen enimmäismäärä (oletuksena 10 tai määrittämäsi rateLimitPerMinute, jos se on pienempi).
  • X-RateLimit-Remaining - kiintiössä (bucket) jäljellä olevat poletit heti tämän kutsun jälkeen.
  • X-RateLimit-Reset - Unix epoch -sekunnit, jolloin seuraava poletti tulee saataville (kyseessä ei ole koko kiintiön nollaus; kiintiö täyttyy jatkuvasti). Kun kiintiö on täysi, tämä arvo on nykyinen aika.

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

Ennen tunnistautumista tapahtuvat 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örajoitusta tarkastellaan vasta sen jälkeen, kun tunnistautuminen ja IP-tarkistukset ovat onnistuneet.

Virhemuoto

Sama rakenne 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 virheen aiheuttaneen kenttä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"
  }
}

Enum-muotoisten tai suljetun arvojoukon kenttien virheelliset arvot (esim. chatMemory.clientSummaryPromptType = "BOGUS") sisältävät kenttä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

Keskustelujen päätepisteet ja SSE-suoratoisto löytyvät artikkelista Bot Talk API.

Hae kaikista artikkeleistaKysy agentilta