Management API

Prezentare generală a Management API

Management API este destinat activităților de back-office care nu implică trimiterea de mesaje de chat:

• creați un bot în mod programatic cu POST /v1/management/bots
• citiți datele unui bot specific pe care îl dețineți cu GET /v1/management/bots/{bot_id}
• actualizați un bot specific cu PATCH /v1/management/bots/{bot_id}
• citiți consumul aferent abonamentului cu GET /v1/usage

Cheile Management sunt asociate contului dumneavoastră, nu unui bot anume. Acestea sunt separate în mod deliberat de cheile Bot Talk, astfel încât o cheie de chat compromisă să nu poată modifica roboții dumneavoastră și nici să nu poată citi datele de facturare.

Base URL

https://api.chatlab.com/aichat

Toate endpointurile din acest articol sunt relative la acest Base URL.

Primii pași

1. Deschideți aplicația de administrare și mergeți la Account Settings > Management API (Setări cont > Management API).
2. Faceți clic pe Create Management Key (Creează cheie Management), denumiți-o, opțional setați lista albă de adrese IP (IP whitelist) și limita de frecvență a cererilor (rate limit), apoi trimiteți formularul.
3. Selectați doar permisiunile de care are nevoie integrarea dumneavoastră și copiați cheia completă din fereastra modală de confirmare. Textul în clar este afișat o singură dată.
4. Salvați-o pe serverul dumneavoastră, nu în codul care rulează în browser și nici într-un depozit de cod public. Efectuați o cerere de tip read-only, cum ar fi GET /v1/usage cu permisiunea usage, pentru a verifica accesul.
5. Revocați cheile neutilizate sau compromise direct din pagina Management API.

O cheie arată sub forma mk_abcdefghijklmnopqrstuvwxyz012345. Prefixul mk_ o diferențiază de cheile Bot Talk (ck_).

Autentificare

Authorization: Bearer mk_abcdefghijklmnopqrstuvwxyz012345

Trimiterea unei chei mk_ către /v1/chat (sau către orice alt endpoint Bot Talk) returnează eroarea 403 key_type_not_allowed. Trimiterea unei chei ck_ către /v1/management/* returnează aceeași eroare.

Limite

• Maximum 5 chei Management API active per utilizator
• Maximum 10 cereri pe minut per cheie (token bucket, capacitate 10, reumplere lină la un ritm de ~1 token la fiecare 6 secunde). Poate fi configurată în jos la momentul creării - setați o valoare mai mică pentru rateLimitPerMinute, iar plafonul va scădea, ritmul de reumplere scalându-se proporțional.

Permisiuni

Fiecare cheie Management include orice subset al celor trei permisiuni de mai jos. Cel puțin una trebuie selectată în momentul creării; în caz contrar, cererea este respinsă cu 400 invalid_request_error. Apelarea unui endpoint cu o cheie care nu dispune de permisiunea necesară returnează 403 insufficient_permissions.

• bot_read - necesară pentru GET /v1/management/bots/{bot_id}
• bot_management - necesară pentru POST /v1/management/bots și PATCH /v1/management/bots/{bot_id}
• usage - necesară pentru GET /v1/usage

Structura corpului cererii: secțiuni imbricate care reflectă filele din interfața de administrare

POST și PATCH acceptă un corp JSON grupat în 13 secțiuni. Fiecare secțiune corespunde unei subfile din bara laterală Bot Settings (Setări bot) din aplicația de administrare, astfel încât cheile JSON și filele vizibile se aliniază perfect: dacă modificați consent.humanSupportRequirePolicyAccept prin API, veți vedea comutatorul respectiv schimbându-și starea în fila Consent & Privacy (Consimțământ și confidențialitate) din aplicația de administrare.

• role - persona botului, promptul brut, lungimea răspunsului, limba, contextul site-ului web / al companiei (fila Role & Behavior [Rol și comportament])
• conversation - mesajul de întâmpinare, rafinarea interogărilor, continuitatea conversației, comutatorul de evaluare + tooltipurile, conținutul întrebărilor sugerate + întrebările dinamice de continuare (fila Chat Conversation [Conversație pe chat])
• chatMemory - comutatorul pentru memoria conversației, prompturile de rezumare, alocarea contextului (fila Summaries & Memory [Rezumate și memorie])
• appearance - culori, texte, dimensiuni, CSS personalizat, ecranul de întâmpinare, stilul întrebărilor sugerate, comportamentul de deschidere automată, simularea tastării umane, markdown pentru subsol (fila Appearance [Aspect])
• humanSupport - formularul de contact uman (fila Human Contact Form [Formular de contact uman])
• leadCollection - formularul de captare a leadurilor (fila Lead Collection [Colectare de leaduri])
• liveChat - transferul către Live Chat (fila Live Chat)
• consent - toate cele patru comutatoare de consimțământ pentru politica de confidențialitate, plus textul ecranului de consimțământ (fila Consent & Privacy)
• whiteLabel - ascunderea logo-ului, linkul personalizat pentru logo, găzduirea pe domeniu personalizat (fila Whitelabel)
• security - domenii permise, filtru anti-spam, limite de frecvență pentru conversație (fila Security [Securitate])
• voice - intrare vocală și conversații vocale: model, voce, limbi, prompt, plafon de durată (fila Voice Conversation [Conversație vocală])
• multilingual - modul multilingv, limba de bază, limbile oferite, gestionarea limbii bazei de cunoștințe (fila Languages [Limbi])
• advanced - modelul LLM, temperatura, dimensiunea contextului, limita de mesaje ale botului, setările regionale interne, Offer Cards (fila Model & Advanced [Model și avansat])

Dintre setările care pot fi scrise, doar name se află la nivelul rădăcină, deoarece acesta identifică botul și nu aparține unei singure file.

Bara laterală Bot Settings conține în prezent 16 subfile, iar 13 dintre ele corespund secțiunilor de mai sus. Cele trei subfile care nu au o secțiune corespondentă sunt Flow, Actions și Forms - toate trei fiind acoperite mai jos în secțiunea „În afara ariei API-ului”. Cele 13 care corespund sunt Appearance, Chat Conversation, Role & Behavior, Human Contact Form, Lead Collection, Live Chat, Whitelabel, Consent & Privacy, Security, Model & Advanced, Summaries & Memory, Voice Conversation și Languages.

Corpul cererii și corpul răspunsului au aceeași structură. Răspunsul adaugă două elemente suplimentare:

• meta - de tip read-only: id-ul botului și marcajele temporale. Eliminați-l pentru a transforma un răspuns GET într-un corp POST valid.
• apiKey - prezent doar la creare - cheia Bot Talk API nou generată pentru noul bot.

Două câmpuri din cadrul structurii comune sunt read-only - returnate în răspuns, dar ignorate dacă încercați să le trimiteți prin POST/PATCH:

• appearance.avatarUrl - URL-ul public complet al imaginii de avatar a botului (de exemplu https://api.chatlab.com/aichat/content/avatar_xyz.png). Efectuați o cerere GET direct către acesta pentru a descărca fișierul. Pentru a-l modifica, încărcați un fișier nou prin intermediul părții multipart avatar (consultați PATCH).
• whiteLabel.whitelabelLogoUrl - URL-ul public complet al logo-ului din antet pentru white-label. Același principiu ca la avatarUrl. Pentru a-l modifica, încărcați un fișier nou prin intermediul părții multipart whitelabel_logo (consultați PATCH).

Ambele URL-uri utilizează schema + gazda + calea de context ale cererii curente, astfel încât pe un domeniu personalizat de tip white-label acestea sunt returnate având ca rădăcină domeniul respectiv (de exemplu https://api.acme.com/aichat/content/...).

Trimiteți null pentru o secțiune pentru a o omite la PATCH; trimiteți null pentru un câmp dintr-o secțiune pentru a omite acel câmp individual. Valoarea null la nivel de câmp nu șterge niciodată o valoare stocată - înseamnă doar „nu modifica”.

Rolul și construirea promptului

Promptul de sistem pe care îl primește efectiv modelul LLM este construit într-unul din două moduri, în funcție de role.role. Faptul de a ști pe ce ramură vă aflați vă indică ce câmpuri contează și care sunt stocate, dar ignorate.

Ramura A - role.role este CUSTOMER_SUPPORT, SALES sau LEAD_COLLECTION_AGENT (bazat pe șabloane)

Backendul asamblează promptul dintr-un șablon integrat și ignoră complet role.rawPrompt (valoarea rămâne stocată pentru bot, dar nu este utilizată). Șablonul include:

• role.role - eticheta rolului (de exemplu „Customer Support”) și instrucțiuni specifice rolului adăugate automat
• name - numele botului, inserat în propoziția introductivă
• role.language - "Auto Detect" setează botul să urmeze limba utilizatorului; orice altă valoare (de exemplu "English", "Polish") devine „Output in {language}, unless user uses another language”
• role.responseLength - mapat la un număr țintă de cuvinte: Concise ≈ 50 de cuvinte, Normal ≈ 100, Detailed ≈ 200
• role.websiteAddress - opțional; dacă nu este gol, se adaugă ca „for the users of the website {url}”
• role.companyDescription - opțional; dacă nu este gol, se adaugă la început ca un paragraf suplimentar înainte de instrucțiunile rolului

Aceasta este ramura recomandată pentru majoritatea roboților - beneficiați în mod direct de un comportament optimizat pentru rolul respectiv și de măsuri de siguranță predefinite.

Ramura B - role.role este CUSTOM (prompt furnizat de apelant)

Backendul folosește role.rawPrompt ca prompt de rol și adaugă ghidul fix al platformei privind lungimea răspunsului. Aceasta este separată de role.responseLength: setarea opțională Concise/Normal/Detailed nu este injectată pentru un rol CUSTOM. În mod similar, language, websiteAddress și companyDescription sunt stocate, dar nu sunt injectate în acest prompt de rol. Includeți dumneavoastră în rawPrompt orice cerințe legate de limbă, lungimea țintă a răspunsului sau contextul companiei. De asemenea, pot fi furnizate instrucțiuni suplimentare de execuție și context extras, astfel încât rawPrompt nu reprezintă întreaga intrare a modelului. Instrucțiunile de ton ale rolului predefinit nu sunt adăugate, însă selectarea rolului CUSTOM nu elimină toate instrucțiunile platformei.

Utilizați CUSTOM numai atunci când promptul bazat pe șabloane nu se potrivește cazului dumneavoastră de utilizare (de exemplu, aveți nevoie de o persona foarte specifică unui anumit domeniu, de propriile constrângeri de siguranță sau de un format de ieșire nestandard).

Câmpuri de tip enum / set închis

Câmpurile de tip enum și cele cu valori restricționate resping valorile nevalide cu 400 invalid_parameter. Alte câmpuri sunt șiruri simple de text, chiar și acolo unde interfața oferă o listă fixă. Folosiți scrierea documentată și validați datele trimise în loc să presupuneți că orice șir neacceptat va fi respins.

• role.role - CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM
• role.responseLength - Concise, Normal, Detailed
• role.language - denumirea completă în limba engleză a limbii din meniul derulant al panoului de administrare, de exemplu Auto Detect, English, Polish, Spanish, German, French, Italian, Portuguese, Dutch, Russian, Chinese (Simplified), Japanese, Arabic, Hindi și alte aproximativ 80 de limbi. Valoarea este stocată ca atare și introdusă în șablonul de prompt; prin urmare, codurile ISO din două litere (en, pl) și alte valori din afara listei nu sunt respinse de API, dar generează o instrucțiune incorectă precum „Output in en, unless...”. Când este omis la creare, valoarea implicită este Auto Detect.
• advanced.model - consultați „Modele de text AI” de mai jos. Acesta este un șir de caractere, nu un enum validat în schema cererii; utilizați o valoare acceptată, nu un nume arbitrar de model.
• advanced.chatContextSize - utilizați 8000, 16000 sau 32000, conform interfeței de utilizare. Valorile peste limita maximă a contului sunt ajustate automat în mod silențios; DTO-ul nu impune în mod strict acest set de trei valori.
• chatMemory.clientSummaryPromptType - DEFAULT, CUSTOM
• chatMemory.conversationSummaryPromptType - DEFAULT, CUSTOM
• appearance.chatAlignment - left, right
• appearance.minimizedDisplayMode - icon, minified, pill
• appearance.chatMessageLinkTarget - _blank, _self
• leadCollection.requireBeforeNewConversation - comutator boolean. true obligă utilizatorul să completeze formularul de leaduri înainte de a începe o conversație; false permite sistemului AI să decidă când să afișeze formularul (implicit).

Câmpuri structurate și intervale

Câmpuri care par a fi șiruri simple sau numere, dar care au în realitate structuri specifice, intervale sau particularități în interfața de administrare care merită cunoscute.

• advanced.temperature - intervalul acceptat este de la 0.0 la 1.0, corespunzând glisorului din interfața de administrare. Valorile din afara acestui interval sunt respinse cu 400 invalid_parameter.

• chatMemory.summariesToKnowledgeRatio - procent întreg, 10-90; interfața folosește pași de 10, dar API-ul acceptă numere întregi pe tot intervalul. Valoarea implicită este 50. Când memoria este activată și contextul este mai mare de 8k, această setare împarte bugetul alocat bazei de cunoștințe și memoriei după scăderea rezervei pentru prompt și conversația recentă, nu întregul context al modelului. La 8k nu este alocat niciun buget pentru rezumate prin această setare.

• liveChat.schedule - JSON codat ca șir de caractere, nu un obiect JSON imbricat în payloadul efectiv. Serverul stochează șirul brut exact așa cum este trimis; interfața de administrare îl parsează pe partea de client la randarea editorului de program. Odată parsat, șirul este structurat cu câte o intrare pentru fiecare zi a săptămânii plus o cheie timezone:

  • fiecare cheie corespunzătoare unei zile a săptămânii (monday-sunday) indică spre {enabled: boolean, from: "H:MM", to: "H:MM"} în format de 24 de ore
  • timezone este o denumire de zonă IANA (de exemplu "Europe/Warsaw", "America/New_York")

  Exemplu de valoare (observați ghilimelele exterioare și ghilimelele interioare mascate prin escape - este un singur câmp de tip șir, nu un obiect imbricat):

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

  În afara orelor specificate, vizitatorului i se afișează liveChat.outOfHoursMessage, iar transferul către chatul live este dezactivat. Validarea structurii interne se execută doar pe partea de client în interfața de administrare - un JSON formatat incorect sau cheile nerecunoscute sunt acceptate de API ca un simplu șir și vor genera o eroare de randare atunci când o persoană va deschide ulterior botul în panoul de administrare. Validați structura la nivelul dumneavoastră înainte de a trimite datele.

• conversation.positiveRatingTooltip / conversation.negativeRatingTooltip - etichete scurte afișate pe controalele de evaluare 👍 / 👎 ale conversației atunci când conversation.conversationRatingEnabled=true. Textul implicit este „I like the response” / „I don't like the response”. Este vizibil pentru utilizatorii finali.

• whiteLabel.hideRoboAssistLogo - funcție White Label, în limita abonamentului dumneavoastră. Ascunde linia de subsol „Powered by ChatLab”. Dacă abonamentul dumneavoastră nu include funcția de white-label, valoarea este stocată, dar ignorată, iar subsolul este randat întotdeauna.

• whiteLabel.whitelabelLogoLink - funcție White Label, în limita abonamentului dumneavoastră. URL-ul destinație la clic pentru logo-ul personalizat atunci când hideRoboAssistLogo=true și a fost încărcat un fișier de logo personalizat prin partea multipart whitelabel_logo.

• appearance.simulateHumanTypingDelay - secunde (nu milisecunde), număr întreg 0-200. Pauza dintre mesajele succesive ale botului atunci când simulateHumanTyping=true. Valoarea implicită este 5.

• appearance.autoOpenChatDelaySeconds - secunde, număr întreg. Întârzierea înainte ca widgetul să se deschidă automat atunci când autoOpenChat=true și autoOpenChatDelay=true.

• advanced.internalLocale - cod regional de limbă IETF în formatul ll_CC (cu liniuță de subliniere, NU ll-CC cu cratimă). Valorile acceptate provin dintr-o listă fixă de aproximativ 95 de configurări regionale: 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 și multe altele. Trimiterea exclusivă a unui cod din două litere ("en") sau BCP-47 ("en-US") nu este permisă. Valoarea implicită este en_US. Aceasta este configurarea regională utilizată pentru formatarea datelor și a numerelor în elementele de interfață ale widgetului, fiind distinctă de role.language (limba de răspuns conversațional a botului).

• security.talkMessagesRateLimit / security.talkMessagesRateLimitDurationSeconds - numere întregi (trimise ca valori numerice JSON, de exemplu 30, nu "30"). Setați limita de mesaje la 0 pentru a dezactiva această limită bazată pe sesiune. Când o activați, furnizați o durată pozitivă. Backendul impune N mesaje per sesiune pentru durata în secunde specificată înainte de a afișa security.talkMessagesRateLimitHitMessage vizitatorului.

• advanced.botMessagesLimit - număr întreg (valoare numerică JSON, de exemplu 1000). 0 înseamnă că nu există un plafon suplimentar per bot, continuând să se aplice bugetul de credite al contului; în caz contrar, trebuie să fie un multiplu de 1000 (1000, 2000, 10000, ...). Valorile precum 100 sau 1500 sunt respinse cu 400 invalid_parameter. Acesta reprezintă un plafon lunar de credite al botului, nu un număr de mesaje per conversație. Componenta de mapare nu ajustează această valoare la bugetul contului; bugetul contului limitează în continuare utilizarea efectivă.

Modele de text AI (advanced.model)

Utilizați identificatorul exact de model returnat în advanced.model la citirea unui bot configurat cu modelul dorit în Settings > Model & Advanced (Setări > Model și avansat). Valoarea implicită actuală la creare este 5.6-LUNA. Identificatorii sunt sensibili la majuscule și minuscule și diferă de denumirile afișate; de exemplu, 5.6-LUNA este afișat ca GPT 5.6-luna.

Catalogul de modele se modifică în timp. Nu deduceți că un șir oarecare sau un ID public de model al unui furnizor este acceptat doar pentru că schema cererii acceptă un șir de caractere. Citiți configurația salvată și testați chatbotul rezultat înainte de a-l publica.

Referință câmpuri (schema completă a cererii)

Secțiunile și câmpurile acceptate, împreună cu tipurile lor și constrângerile importante. Semantica PATCH: orice câmp omis (sau trimis ca null) lasă valoarea stocată neschimbată. Aceeași structură este utilizată pentru răspuns (fără conținutul binar multipart; plus blocul needitabil meta la fiecare răspuns și apiKey doar la răspunsul de creare).

Nivel superior

Câmp	Tip	Constrângere	Descriere
name	string	max 150, obligatoriu la creare	Numele afișat al botului
role	object		Consultați § role
conversation	object		Consultați § conversation
chatMemory	object		Consultați § chatMemory
appearance	object		Consultați § appearance
humanSupport	object		Consultați § humanSupport
leadCollection	object		Consultați § leadCollection
liveChat	object		Consultați § liveChat
consent	object		Consultați § consent
whiteLabel	object		Consultați § whiteLabel
security	object		Consultați § security
advanced	object		Consultați § advanced

Adăugiri prezente doar în răspuns:

• meta: { id, createdAt, updatedAt } - doar pentru citire.
• apiKey - string, prezent doar în răspunsul la POST /v1/management/bots - cheia Bot Talk nou generată pentru noul bot, returnată o singură dată.

§ role

Câmp	Tip	Constrângere	Descriere
role	string (enum)	CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM	Profil prestabilit; selectează șablonul de prompt (consultați „Role and prompt construction”)
language	string	numele complet al limbii în engleză (English, Polish, ...) sau Auto Detect	Limba principală transmisă în șablonul de prompt
responseLength	string	∈ {Concise, Normal, Detailed}	Lungimea dorită a răspunsurilor AI
websiteAddress	string		Site-ul web utilizat pentru contextul promptului
companyDescription	string		Descrierea companiei utilizată pentru contextul promptului
rawPrompt	string		Prompt de sistem personalizat - utilizat ca atare doar când role=CUSTOM

§ conversation

Câmp	Tip	Constrângere	Descriere
welcomeMessage	string		Primul mesaj afișat vizitatorului la deschidere
queryRefinementEnabled	boolean		Dacă este true, reformulează întrebarea vizitatorului înainte de căutarea RAG
conversationContinuityEnabled	boolean		Dacă este true, vizitatorii care revin își reiau ultima conversație
conversationRatingEnabled	boolean		Dacă este true, afișează controalele de evaluare a conversației cu degetul în sus/jos
positiveRatingTooltip	string		Text explicativ la trecerea cursorului peste butonul de evaluare pozitivă
negativeRatingTooltip	string		Text explicativ la trecerea cursorului peste butonul de evaluare negativă
suggestedQuestions	string		Întrebări sugerate / formule de început al conversației, separate prin linie nouă
dynamicSuggestedFollowups	boolean		Dacă este true, AI propune sugestii de continuare după fiecare răspuns
positiveRatingMessage	string		Mesaj afișat după feedbackul pozitiv
negativeRatingMessage	string		Mesaj afișat după feedbackul negativ
hideSuggestedQuestionsAfterFirstUse	boolean		Ascunde sugestiile statice după utilizare
dynamicFollowupsAutoIcons	boolean		Dacă este true, AI alege automat pictograme emoji pentru sugestiile dinamice de continuare

§ chatMemory

Câmp	Tip	Constrângere	Descriere
enabled	boolean		Comutator principal pentru funcția de memorie a chatului
summaryConversationsEnabled	boolean		Păstrează rezumatele fiecărei conversații
conversationSummaryPrompt	string		Prompt personalizat utilizat pentru a rezuma fiecare conversație
conversationSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Indică dacă se utilizează promptul de rezumat prestabilit sau cel personalizat
clientSummaryPrompt	string		Prompt personalizat utilizat pentru a rezuma profilul clientului de-a lungul conversațiilor
clientSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Prompt prestabilit vs personalizat pentru profilul clientului
summariesToKnowledgeRatio	int	10-90 (pas în UI 10)	Procentul din bugetul de cunoștințe/memorie alocat rezumatelor la contexte de peste 8k

§ appearance

Câmp	Tip	Constrângere	Descriere
launcherLabelLine1	string	max 60	Prima linie de text a butonului de lansare
launcherLabelLine2	string	max 60	A doua linie de text a butonului de lansare
launcherTextColor	string		Culoarea textului de pe butonul de lansare
launcherDismissEnabled	boolean		Permite închiderea butonului de lansare
widgetFontFamily	string	inter, system, nunito, lato, montserrat, poppins, source-serif, jetbrains-mono	Familia de fonturi a widgetului
chatDrawerEnabled	boolean		Activează afișarea de tip panou lateral (drawer)
launcherColor	string (hex)		Culoarea de fundal a butonului de lansare (pictograma de chat)
headerColor	string (hex)		Culoarea de fundal a antetului de chat
titleColor	string (hex)		Culoarea titlului din antetul de chat
subtitleColor	string (hex)		Culoarea subtitlului din antetul de chat
clientMessageBubbleColor	string (hex)		Culoarea bulei mesajului vizitatorului
clientMessageTextColor	string (hex)		Culoarea textului din mesajul vizitatorului
responseMessageBubbleColor	string (hex)		Culoarea bulei răspunsului botului
responseMessageTextColor	string (hex)		Culoarea textului din răspunsul botului
chatSubheader	string		Slogan afișat sub titlul chatului
senderPlaceholder	string		Text substituent (placeholder) în câmpul de introducere a mesajului
resetConversationTooltip	string		Text explicativ la trecerea cursorului peste butonul „reset conversation” (resetează conversația)
chatAlignment	string (enum)	∈ {left, right}	Pe ce parte a ecranului se ancorează chatul
launcherBottomMargin	int	0-500	Distanța butonului de lansare față de marginea de jos (px)
launcherSideMargin	int	0-500	Distanța butonului de lansare față de marginea laterală (px)
displayShadow	boolean		Umbră sub widget
customCss	string		CSS brut injectat în iframe-ul widgetului
chatMessageLinkTarget	string (enum)	∈ {_blank, _self}	Modul în care se deschid linkurile din mesajele botului
minimizedDisplayMode	string (enum)	∈ {icon, minified, pill}	Starea minimizată: pictogramă de lansare, bară compactă de trimitere sau pastilă
chatDesktopWidthPx	int		Lățimea widgetului pe desktop
chatDesktopHeightPx	int		Înălțimea widgetului pe desktop
chatMobileSizePercent	int		Dimensiunea widgetului pe mobil ca procent din viewport
messageFontSize	int		Dimensiunea fontului pentru textul mesajelor (px)
showChatbotBubblesDesktop	boolean		Afișează bulele plutitoare de atragere a atenției pe desktop
showChatbotBubblesMobile	boolean		Afișează bulele plutitoare de atragere a atenției pe mobil
chatbotBubblesDelaySeconds	int		Întârzierea înainte de apariția bulelor de atragere a atenției (secunde)
launcherIconFullSize	boolean		Afișează pictograma personalizată a butonului de lansare din margine în margine în loc de inserată la interior
welcomeScreenEnabled	boolean		Afișează ecranul Welcome Screen în loc de a intra direct în chat
welcomeScreenQuestionsLabel	string		Etichetă deasupra întrebărilor sugerate pe ecranul de bun venit
welcomeScreenHideHumanContactForm	boolean		Ascunde acțiunea formularului de contact uman din antet în timp ce este afișat ecranul Welcome Screen. Aceasta reapare după primul mesaj al vizitatorului. Pentru boții creați înainte de 2026-09-02, valoarea implicită este true
welcomeScreenHideLiveChat	boolean		Ascunde acțiunea de Live Chat din antet în timp ce este afișat ecranul Welcome Screen. Aceasta reapare după primul mesaj al vizitatorului. Pentru boții creați înainte de 2026-09-02, valoarea implicită este true
headerActionsLayout	string	ICONS sau DROPDOWN	Modul în care sunt oferite Live Chat și formularul de contact uman în antetul chatului: ICONS (câte o pictogramă separată pentru fiecare) sau DROPDOWN (grupate în meniul din antet). Pentru boții creați înainte de 2026-09-02, valoarea implicită este ICONS
stackSuggestedQuestions	boolean		Aranjează întrebările sugerate pe verticală (față de una lângă alta)
suggestedQuestionsFontSize	int		Dimensiunea fontului pentru butoanele de tip pastilă cu întrebări sugerate (px)
suggestedQuestionsTextColor	string (hex)		Culoarea textului de pe pastila cu întrebare sugerată
suggestedQuestionsBackgroundColor	string (hex)		Culoarea de fundal a pastilei cu întrebare sugerată
autoOpenChat	boolean		Deschide automat chatul pe desktop
autoOpenChatOnMobiles	boolean		Deschide automat chatul pe mobil
autoOpenChatDelay	boolean		Utilizează o întârziere înainte de deschiderea automată
autoOpenChatDelaySeconds	int		Întârzierea deschiderii automate (secunde)
simulateHumanTyping	boolean		Împarte răspunsul botului în bule cu animație de tastare
simulateHumanTypingDelay	int	0-200	Întârzierea dintre mesajele din bule (secunde)
footerMarkdown	string	max 255	Markdown personalizat afișat în subsolul chatului
avatarUrl	string	read-only	URL public complet calificat al avatarului; pentru a-l modifica, încărcați prin partea multipart avatar

Multipart pe POST/PATCH: avatar (parte de fișier). Corpurile răspunsurilor GET / omit conținutul fișierului - prin rețea circulă doar URL-ul.

§ humanSupport

Câmp	Tip	Constrângere	Descriere
enabled	boolean		Comutator pentru fluxul Human Support
email	string	obligatoriu (la creare strictă) când enabled=true	Adresa care primește e-mailurile pentru asistență umană
dialogMessage	string		Mesaj de încurajare afișat deasupra formularului
thankYouMessage	string		Confirmare afișată după trimitere
emailMessageSubjectTemplate	string		Șablonul de subiect pentru e-mailul trimis către agent
emailMessageContentTemplate	string		Șablonul de conținut pentru e-mailul trimis către agent
emailPlaceholder	string		Text substituent pe câmpul de introducere a e-mailului
messagePlaceholder	string		Text substituent pe zona de text pentru mesaj
emailWithConversationContent	boolean		Dacă este true, include transcrierea conversației în corpul e-mailului
customFormId	long	id-ul unui formular personalizat existent	Înlocuiește formularul de contact integrat cu un formular personalizat. La creare, omiterea folosește formularul integrat; la PATCH, null lasă selecția curentă neschimbată
customFormMapping	string	șir codificat JSON	Mapează câmpurile formularului personalizat pe câmpurile e-mailului de asistență umană

requirePolicyAccept se află pe consent.humanSupportRequirePolicyAccept, nu aici.

§ leadCollection

Câmp	Tip	Constrângere	Descriere
enabled	boolean		Comutator pentru formularul de colectare clienți potențiali
nameEnabled	boolean		Colectează numele
nameLabel	string		Etichetă pe câmpul de introducere a numelui
emailEnabled	boolean		Colectează adresa de e-mail
emailLabel	string	obligatoriu (la creare strictă) când enabled=true ȘI emailEnabled=true	Etichetă pe câmpul de introducere a e-mailului
phoneEnabled	boolean		Colectează numărul de telefon
phoneLabel	string	obligatoriu (la creare strictă) când enabled=true ȘI phoneEnabled=true	Etichetă pe câmpul de introducere a telefonului
leaveDetailsMessage	string	obligatoriu (la creare strictă) când enabled=true	Mesaj prin care vizitatorul este încurajat să își lase datele de contact
thankYouMessage	string	obligatoriu (la creare strictă) când enabled=true	Confirmare afișată după trimitere
requireBeforeNewConversation	boolean		Dacă este true, formularul trebuie trimis înainte de a începe chatul; dacă este false, AI decide când să afișeze formularul
emailNotificationEnabled	boolean		Trimite un e-mail proprietarului de fiecare dată când este colectat un lead
emailNotificationAddress	string		Destinatarul notificării (implicit este adresa de e-mail a contului)
emailWithConversationContent	boolean		Dacă este true, include transcrierea conversației în notificare

| customFormId | long | id-ul unui formular personalizat existent | Înlocuiește formularul integrat de leaduri cu un formular personalizat. La creare, omiterea folosește formularul integrat; la PATCH, null lasă selecția curentă neschimbată | | customFormMapping | string | șir codificat JSON | Mapează câmpurile formularului personalizat pe nume / e-mail / telefon |

Regulă strictă de creare între câmpuri: enabled=true necesită cel puțin una dintre opțiunile emailEnabled sau phoneEnabled. requirePolicyAccept se află pe consent.leadCollectionRequirePolicyAccept, nu aici.

§ liveChat

Câmp	Tip	Constrângere	Descriere
enabled	boolean		Comutator pentru funcția Live Chat
infoMessage	string		Mesaj explicativ înainte de preluare
startMessage	string		Mesaj afișat când începe sesiunea live
endMessage	string		Mesaj afișat când se încheie sesiunea live
nameLabel	string		Etichetă pe câmpul de introducere a numelui în preformularul de live chat
emailLabel	string		Etichetă pe câmpul de introducere a e-mailului în preformularul de live chat
schedule	string	șir codificat JSON (comutatoare pe zile + from/to + timezone)	Programul de funcționare pentru chatul în direct - consultați „Structured fields and ranges” pentru formatul exact
outOfHoursMessage	string		Mesaj afișat atunci când programul indică faptul că suntem în afara orelor de lucru
closeModalMessage	string		Titlul ferestrei modale „close live chat?” (închideți chatul live?)
closeModalConfirmLabel	string		Eticheta butonului de confirmare pe fereastra modală de închidere
closeModalCancelLabel	string		Eticheta butonului de anulare pe fereastra modală de închidere
closeModalTooltipText	string		Text explicativ la trecerea cursorului peste butonul de închidere a chatului
operatorHasJoinedLabel	string		Etichetă afișată atunci când un operator se alătură conversației
operatorDidNotJoinInTimeLabel	string		Etichetă afișată atunci când niciun operator nu se alătură în intervalul de timp stabilit
waitingForOperatorToJoinLabel	string		Etichetă afișată în timp ce se așteaptă conectarea unui operator
waitingForOperatorSeconds	int		Timpul de expirare pentru preluarea conversației de către un operator (secunde)
redirectToHumanSupportForm	boolean		Dacă este true, redirecționează către formularul Human Support atunci când niciun operator nu preia conversația
requireAdminOnline	boolean		Necesită un operator disponibil în conformitate cu setările de prezență
presenceMode	string		Mod de prezență; utilizați valoarea de la un bot configurat în interfață
hideHumanSupportWhenLiveChatAvailable	boolean		Ascunde formularul de contact atunci când chatul live este disponibil
missedEmailEnabled	boolean	implicit true	Trimite un e-mail proprietarului botului atunci când o solicitare de live chat a rămas fără răspuns. Lăsat neconfigurat pe boții vechi, ceea ce este interpretat ca activat

requirePolicyAccept se află pe consent.liveChatRequirePolicyAccept, nu aici.

§ consent

Câmp	Tip	Constrângere	Descriere
newConversationRequirePolicyAccept	boolean		Solicită acordul pentru politica de confidențialitate înainte de începerea unei conversații noi
humanSupportRequirePolicyAccept	boolean		Solicită acordul pentru politica de confidențialitate înainte de trimiterea formularului de asistență umană
leadCollectionRequirePolicyAccept	boolean		Solicită acordul pentru politica de confidențialitate înainte de trimiterea formularului de colectare a clienților potențiali
liveChatRequirePolicyAccept	boolean		Solicită acordul pentru politica de confidențialitate înainte de începerea unei sesiuni de chat live
newConversationConsentDescription	string		Text introductiv pentru ecranul de acord la începutul conversației
privacyPolicyConsentCheckboxLabel	string		Etichetă lângă caseta de selectare a acordului (conține de obicei un link către politica de confidențialitate)

§ whiteLabel

Câmp	Tip	Constrângere	Descriere
hideRoboAssistLogo	boolean	capacitate white-label; supusă limitărilor contului	Ascunde sigla implicită ChatLab din subsol
whitelabelLogoLink	string	capacitate white-label; supusă limitărilor contului	URL-ul către care trimite sigla personalizată din subsol
assignToCustomDomain	boolean	condiționat de funcția CUSTOM_DOMAIN	Găzduiește chatul pe domeniul personalizat configurat
whitelabelLogoUrl	string	read-only	URL public complet calificat al siglei White Label; pentru a o modifica, încărcați prin partea multipart whitelabel_logo

Multipart pe POST/PATCH: whitelabel_logo (parte de fișier). Corpurile răspunsurilor GET / omit conținutul fișierului - prin rețea circulă doar URL-ul.

§ security

Câmp	Tip	Constrângere	Descriere
allowedDomains	string		Listă separată prin virgulă a domeniilor autorizate să integreze widgetul (gol = fără listă de permisiuni)
spamFilterEnabled	boolean		Activează filtrul antispam individual al botului pentru mesajele primite
countryFilterMode	string	BLACKLIST sau WHITELIST	Modul în care sunt interpretate listele de țări. Listele propriu-zise rămân accesibile doar administratorilor
talkMessagesRateLimit	int	>= 0; 0 dezactivează	Numărul maxim de mesaje de la utilizator permise în fereastra limitei de frecvență
talkMessagesRateLimitDurationSeconds	int	>= 0	Durata ferestrei limitei de frecvență (secunde)
talkMessagesRateLimitHitMessage	string		Mesaj afișat vizitatorului la atingerea limitei de frecvență

§ voice

Câmp	Tip	Constrângere	Descriere
inputEnabled	boolean		Permite vizitatorului să dicteze mesaje (speech to text)
conversationEnabled	boolean	necesită funcția de voce inclusă în plan	Activează conversațiile vocale complete
voiceId	string	id vocal specific furnizorului (de exemplu alloy)	Vocea sintetică utilizată
model	string	de exemplu GPT-REALTIME-MINI, GEMINI-LIVE, ELEVENLABS-*	Modelul vocal. Facturat pe minut, tarifele diferă în funcție de model
turnDetection	string	specific furnizorului	Modul de detectare a alternanței replicilor (turn-taking)
audioPrompt	string		Prompt suplimentar de sistem utilizat doar pentru intervențiile vocale
welcomeMessage	string		Fraza de deschidere rostită
language	string	cod de limbă	Limba principală a vocii
additionalLanguages	string	coduri de limbă separate prin virgulă	Limbi suplimentare pe care agentul vocal le acceptă
maxDurationSeconds	int		Limită fixă maximă pentru o singură conversație vocală
maxDurationMessage	string		Mesaj afișat la atingerea limitei maxime

§ multilingual

Câmp	Tip	Constrângere	Descriere
enabled	boolean		Comutator pentru modul multilingv
mode	string	AUTODETECT sau FIXED_LIST	Modul în care botul alege limba de răspuns
baseLanguage	string	cod de limbă	Limba în care sunt redactate textele proprii ale botului
languages	string	coduri de limbă separate prin virgulă	Limbile puse la dispoziția vizitatorului
knowledgeLanguageMode	string	NONE, MAIN sau DYNAMIC	Modul în care sunt tratate informațiile din baza de cunoștințe în alte limbi
knowledgeLanguageFallback	string	cod de limbă	Limba de rezervă utilizată atunci când nu este găsită nicio potrivire

§ advanced

Câmp	Tip	Constrângere	Descriere
model	string	supus limitărilor contului; consultați „AI text models” de mai sus	Identificatorul LLM (de exemplu 5.6-LUNA)
temperature	decimal	0.0-1.0	Temperatura de eșantionare (corespunde cursorului din interfață)
chatContextSize	int	∈ {8000, 16000, 32000}; limitat automat la limita contului dumneavoastră	Bugetul de context configurat, incluzând instrucțiunile, istoricul și cunoștințele
botMessagesLimit	long	0 sau multiplu de 1000 (de exemplu 1000, 2000, 10000)	Limita lunară de credite pentru mesajele botului (0 = fără limită suplimentară pe bot; se aplică în continuare bugetul contului)
internalLocale	string	cod de configurare regională în format ll_CC	Limba pentru etichetele interfeței widgetului (distinctă de role.language)
productsViewEnabled	boolean		Dacă este true, afișează Offer Cards pentru e-commerce în interiorul chatului
includeProductsInKnowledgeBase	boolean		Dacă este true, indexează catalogul de produse ca parte a bazei de cunoștințe

În afara ariei API-ului

Interfața de administrare prezintă câteva secțiuni care nu sunt expuse intenționat în această versiune a Management API:

• Antrenare și ștergere - aceste puncte finale nu listează toți boții, nu gestionează seturile de date pentru antrenare și nu șterg boți. Utilizați aplicația pentru aceste fluxuri de lucru.
• Fila Flow - editorul vizual Conversation Flow (stadii și tranziții). Nu este expus prin Management API.
• Fila Actions - integrări gestionate de e-commerce / rezervări, AI Search și funcții API personalizate. Apelarea de instrumente (tool calling) nu a făcut niciodată parte din Management API.
• Constructorul de formulare personalizate în sine - crearea și editarea formularelor personalizate nu sunt expuse. Puteți, totuși, să atașați un formular existent la un bot prin leadCollection.customFormId și humanSupport.customFormId.
• Pictograme personalizate de deschidere / închidere a chatului - customLauncherIconVisible, openChatIcon, closeChatIcon. API-ul expune doar părțile multipart principale avatar și whitelabel_logo.
• Listele de IP-uri și țări - înregistrările propriu-zise sunt accesibile doar administratorilor. Este expus doar modul de interpretare, prin security.countryFilterMode.

Puncte finale

POST /v1/management/bots

Creați un bot nou. Sunt acceptate două antete Content-Type echivalente; alegeți-l pe cel mai convenabil.

Modul A - JSON simplu (recomandat atunci când nu este nevoie să încărcați un avatar / logo în aceeași cerere):

• Content-Type: application/json
• Corpul cererii este JSON-ul de configurare a botului (fără wrapper data)
• Fișierele (avatar / logo) pot fi încărcate ulterior printr-un al doilea PATCH folosind modul B

Modul B - multipart/form-data (utilizați la încărcarea fișierelor în aceeași cerere):

• Content-Type: multipart/form-data; boundary=...
• Partea JSON data (obligatorie, Content-Type: application/json) - configurarea botului în structura imbricată descrisă mai sus
• Partea de fișier avatar (opțională) - imaginea avatarului botului
• Partea de fișier whitelabel_logo (opțională) - logo White Label (se aplică doar dacă contul dumneavoastră include white-labelling)

Doar name este obligatoriu în JSON; toate celelalte câmpuri revin la aceeași valoare implicită pe care ar fi setat-o expertul din interfața de administrare.

Exemplu de corp al cererii

Acesta este JSON-ul maximal data - fiecare secțiune fiind completată. Trimiteți doar secțiunile care vă interesează; toate celelalte preiau valori implicite.

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

Reguli de validare cu propriile mesaje de eroare:

• name - obligatoriu, maximum 150 de caractere
• advanced.temperature - între 0.0 și 1.0
• chatMemory.summariesToKnowledgeRatio - număr întreg între 10 și 90 (procente, pas 10)
• appearance.launcherBottomMargin, appearance.launcherSideMargin - între 0 și 500
• appearance.footerMarkdown - maximum 255 de caractere
• humanSupport.enabled=true necesită setarea humanSupport.email
• leadCollection.enabled=true necesită ca cel puțin unul dintre leadCollection.emailEnabled sau leadCollection.phoneEnabled să fie setat la true; canalul activat necesită, de asemenea, eticheta sa, plus leaveDetailsMessage și thankYouMessage
• advanced.chatContextSize este limitat la dimensiunea maximă de context acceptată de cont. Nu presupuneți că celelalte câmpuri numerice sunt limitate automat.

Câmpurile a căror valoare este null pe server sunt omise din corpul JSON - transmisia conține doar câmpuri cu valori non-null.

Exemplu de corp al răspunsului (201)

Aceeași formă ca a cererii, plus blocul doar pentru citire meta și cheia de unică folosință apiKey la nivelul rădăcină. URL-urile doar pentru citire ale fișierelor (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) sunt completate de server atunci când părțile multipart corespunzătoare au fost încărcate.

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

Câmpul apiKey apare doar la creare - este cheia Bot Talk nou generată, asociată noului bot. Textul în clar este afișat o singură dată și nu poate fi recuperat ulterior din API; salvați-l imediat de partea dumneavoastră.

Antetul de răspuns Location conține URL-ul noului bot (/v1/management/bots/{id}).

Exemple curl

Modul A - JSON simplu (cel mai direct):

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

Modul B - multipart cu avatar:

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}

Returnează configurația curentă a unui bot pe care îl dețineți.

Exemplu curl

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

Exemplu de corp al răspunsului (200)

Aceeași formă ca a răspunsului la POST, minus apiKey de unică folosință. Blocul meta este inclus. Returnează 404 not_found_error dacă botul nu există sau nu aparține contului dumneavoastră.

Avatarul și logoul White Label actuale sunt afișate ca URL-uri complete, doar pentru citire (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) - având ca rădăcină aceeași schemă + gazdă + cale de context care a deservit această cerere. Preluați octeții trimițând cereri GET direct la aceste URL-uri; pentru a înlocui oricare dintre fișiere, încărcați unul nou prin partea multipart avatar / whitelabel_logo la apelul PATCH. Aceste câmpuri de tip URL sunt ignorate dacă sunt trimise în corpul cererii.

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

Clonarea unui bot

Corpul cererii (request body) pentru POST /v1/management/bots și corpul răspunsului (response body) pentru GET /v1/management/bots/{bot_id} au aceeași structură, astfel încât clonarea este un proces în trei pași: trimiteți o cerere GET pentru sursă, eliminați câmpurile de identitate gestionate de server și trimiteți rezultatul printr-o cerere POST.

1. Trimiteți o cerere GET pentru botul sursă.

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

2. Eliminați blocul meta de la nivelul superior. Obiectul meta (id, createdAt, updatedAt) este gestionat de server și este de tip read-only - lăsarea acestuia în corpul cererii POST nu produce erori (serverul îl ignoră), dar eliminarea lui face intenția explicită și păstrează datele trimise curate. Opțional, editați name astfel încât clona să se distingă de sursă.

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

3. Trimiteți corpul curățat printr-o cerere POST pentru a crea clona. Consultați secțiunea de referință POST /v1/management/bots de mai sus pentru structura completă a corpului cererii și regulile de validare.

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

Răspunsul conține noul meta.id al botului, plus o cheie apiKey nou generată (cheia Bot Talk pentru clonă). Valoarea text în clar a apiKey este returnată doar în acest răspuns de creare - copiați-o înainte de a închide corpul răspunsului; aceasta nu va mai putea fi recuperată ulterior.

Această acțiune copiază setările acceptate, nu un chatbot complet antrenat. Conținutul de antrenare, istoricul conversațiilor, integrările/acțiunile, Flow și definițiile formularelor nu sunt clonate de aceste endpointuri. Configurați-le separat în aplicație.

Mențiuni suplimentare:

• Fișierele nu sunt clonate. Câmpurile appearance.avatarUrl și whiteLabel.whitelabelLogoUrl sunt de tip read-only și indică spre fișierele botului sursă. Dacă aveți nevoie de același avatar sau logo White Label pe clonă, descărcați fișierele de la URL-urile sursă și încărcați-le ca părți multipart avatar / whitelabel_logo - fie la cererea POST de creare (Modul B), fie printr-o cerere PATCH ulterioară.
• Cheile Bot Talk nu sunt clonate. Fiecare bot are propriul set de chei Bot Talk. Singura cheie apiKey returnată de cererea POST de creare este singura generată automat; creați chei suplimentare din fila API (API tab) a botului, dacă este necesar.

PATCH /v1/management/bots/{bot_id}

Actualizați unul sau mai multe câmpuri pentru un bot pe care îl dețineți. Doar secțiunile / câmpurile prezente în JSON sunt modificate; tot ceea ce este omis (sau trimis ca null) rămâne neschimbat. Se aplică o actualizare parțială pentru fiecare câmp dintr-o secțiune trimisă.

Sunt acceptate două valori echivalente pentru Content-Type (la fel ca la POST):

Modul A - JSON simplu (recomandat atunci când actualizați doar setări):

• Content-Type: application/json
• Corpul cererii este direct JSON-ul de modificare (fără containerul data)

Modul B - multipart/form-data (utilizați-l la încărcarea fișierelor):

• Partea JSON data (opțională) - modificările. Trimiteți-o doar dacă doriți să schimbați câmpuri. Omiteți-o complet dacă doriți doar să încărcați un avatar sau un logo.
• Partea de fișier avatar (opțională) - înlocuiește avatarul
• Partea de fișier whitelabel_logo (opțională) - înlocuiește sigla White Label (se aplică doar dacă contul dumneavoastră include funcția White Label)

Toate cele trei părți sunt opționale la PATCH, dar cel puțin una trebuie să fie prezentă pentru ca apelul să aibă sens.

Exemplu de corp al cererii (mai multe secțiuni)

Orice câmp acceptat de POST /v1/management/bots poate fi trimis și aici. Exemplul de mai jos ilustrează mai multe secțiuni, nu fiecare câmp acceptat; în practică trimiteți doar cheile pe care doriți să le modificați (consultați secțiunea „Actualizare parțială minimă” de mai jos) - fiecare cheie omisă (sau trimisă ca null) lasă valoarea salvată neatinsă.

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

Actualizare parțială minimă

Aplicați PATCH unui singur câmp trimițând exact cheile pe care doriți să le modificați - toate celelalte valori sunt păstrate.

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

Exemple curl

Modul A - JSON simplu (cel mai simplu):

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

Modul B - multipart (la înlocuirea avatarului / logo-ului):

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'

Modul B - înlocuirea doar a avatarului (fără modificări de câmpuri):

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

Corpul răspunsului (200)

Aceeași structură ca la GET /v1/management/bots/{bot_id} - configurația completă a botului după aplicarea modificărilor, inclusiv blocul meta. Fără câmpul apiKey. Returnează 404 not_found_error dacă botul nu există sau nu aparține contului dumneavoastră.

Exemplul de mai jos arată răspunsul după aplicarea modificării din Exemplu de corp al cererii (mai multe secțiuni) de mai sus pentru botul din exemplul GET - câmpurile modificate reflectă noile valori, câmpurile neatinse sunt păstrate, iar meta.updatedAt se actualizează.

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

Afișează consumul curent al abonamentului pentru contul care deține cheia Management.

Corpul răspunsului (200)

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

• subscriptionType este un identificator cu litere mici al planului curent al contului (your-plan-id este un substituent demonstrativ). Planurile provin dintr-un catalog dinamic, astfel încât setul exact de identificatori se poate modifica în timp pe măsură ce planurile sunt redenumite sau adăugate - tratați această valoare ca pe un șir de caractere opac, nu ca pe o enumerare fixă.
• messages.used / limit / remaining reprezintă creditele de mesaje pentru luna calendaristică curentă, care se resetează în prima zi a lunii, nu în ziua reînnoirii abonamentului. Acestea sunt ponderate în funcție de credite, nefiind o simplă numărătoare a răspunsurilor brute.
• bots.used / limit / remaining contorizează boții deținuți, inclusiv boții puși pe pauză, raportați la limita totală de boți a contului dumneavoastră.

Antete pentru limitarea ratei (rate limit headers)

Răspunsurile care ajung în etapa de limitare a ratei (adică autentificarea și lista albă de adrese IP au fost validate cu succes) includ:

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

• X-RateLimit-Limit - limita per cheie aplicată efectiv acestui apel (implicit 10, sau valoarea configurată de dumneavoastră în rateLimitPerMinute dacă este mai mică).
• X-RateLimit-Remaining - tokenurile rămase în recipient (bucket) imediat după acest apel.
• X-RateLimit-Reset - secunde Unix epoch la care următorul token devine disponibil (nu reprezintă o resetare completă a recipientului; recipientul se reumple continuu). Când recipientul este plin, aceasta reprezintă ora curentă.

La răspunsurile 429 rate_limit_exceeded, este setat și antetul Retry-After, exprimat în secunde întregi până când se eliberează cel puțin un token.

Erorile pre-autentificare (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) și 403 ip_not_whitelisted nu conțin antetele X-RateLimit-* - limitatorul este consultat doar după ce verificările de autentificare și IP reușesc.

Formatul erorilor

Același format de înveliș (envelope) ca în Bot Talk API:

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

Erorile de validare folosesc code: "invalid_parameter" și adaugă calea câmpului nevalid la începutul mesajului, astfel încât secțiunea cu erori să fie ușor de identificat:

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

Valorile nevalide pentru câmpurile de tip enum / set închis (de exemplu, chatMemory.clientSummaryPromptType = "BOGUS") includ calea câmpului, valoarea respinsă și lista valorilor permise:

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

Resurse conexe

Pentru endpointurile de conversație și streaming SSE, consultați Bot Talk API.