Centru de ajutor
Chat API

Management API

Ultima actualizare:

Prezentare generală a Management API

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

  • crearea programatică a unui bot prin POST /v1/management/bots
  • citirea datelor unui bot specific pe care îl dețineți prin GET /v1/management/bots/{bot_id}
  • actualizarea unui bot specific prin PATCH /v1/management/bots/{bot_id}
  • citirea datelor privind utilizarea abonamentului prin 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 să nu poată citi datele de facturare.

URL de bază

https://api.chatlab.com/aichat

Toate endpointurile din acest articol sunt relative la acest URL de bază.

Noțiuni introductive

  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 (Creare cheie Management), introduceți un nume, opțional configurați lista de permisiuni IP (IP whitelist) și limita de viteză (rate limit), apoi trimiteți formularul.
  3. Copiați cheia completă din fereastra modală de confirmare. Textul necriptat este afișat o singură dată.

O cheie arată sub forma mk_abcdefghijklmnopqrstuvwxyz012345. Prefixul mk_ o deosebește de cheile Bot Talk (ck_).

Autentificare

Authorization: Bearer mk_abcdefghijklmnopqrstuvwxyz012345

Trimiterea unei chei mk_ către /v1/chat (sau 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 (algoritm token bucket, capacitate 10, reumplere lină la ~1 token la fiecare 6 secunde). Se poate configura o valoare mai mică în momentul creării - dacă setați o valoare mai redusă pentru rateLimitPerMinute, limita scade, iar viteza de reumplere se scalează corespunzător.

Permisiuni

Fiecare cheie Management deține orice subset din următoarele trei permisiuni. Cel puțin una trebuie selectată la crearea cheii; în caz contrar, cererea este respinsă cu eroarea 400 invalid_request_error. Apelarea unui endpoint cu o cheie care nu deține 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: secțiuni imbricate care reflectă filele din interfața de administrare

Metodele 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 se aliniază cu filele vizibile: dacă schimbați consent.humanSupportRequirePolicyAccept prin API, veți vedea cum același comutator se modifică în fila Consent & Privacy (Consimțământ și confidențialitate) din aplicația de administrare.

  • role - profilul botului (persona), promptul brut, lungimea răspunsului, limba, contextul site-ului web / al companiei (fila Role & Behavior [Rol și comportament])
  • conversation - mesajul de întâmpinare, rafinarea întrebărilor, continuitatea conversației, comutatorul pentru evaluare + sfaturile подсказка (tooltips), conținutul întrebărilor sugerate + întrebări suplimentare dinamice (fila Chat Conversation [Conversație pe chat])
  • chatMemory - comutatorul pentru memoria chatului, prompturile de rezumat, 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 colectare a leadurilor (fila Lead Collection [Colectare leaduri])
  • liveChat - transferul către chatul live (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 [Consimțământ și confidențialitate])
  • whiteLabel - ascunderea logoului, linkul personalizat pentru logo, găzduirea pe domeniu personalizat (fila Whitelabel)
  • security - domenii permise, filtru antispam, limite de viteză pentru conversație (fila Security [Securitate])
  • voice - introducerea vocală și conversațiile vocale: model, voce, limbi, prompt, durata maximă (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 mesajelor botului, configurarea regională internă, Offer Cards (fila Model & Advanced [Model și avansat])

Doar name se află la nivelul superior, deoarece acesta identifică botul și nu aparține unei file anume.

Bara laterală Bot Settings conține în prezent 15 subfile, iar 13 dintre ele corespund secțiunilor de mai sus. Cele două subfile care nu au o secțiune corespondentă sunt Flow și Actions - ambele fiind prezentate mai jos la secțiunea „În afara ariei API-ului”. Cele 13 care au corespondență 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 utilizează aceeași structură. Răspunsul adaugă două elemente suplimentare:

  • meta - doar pentru citire (read-only): ID-ul botului și marcajele temporale. Eliminați acest obiect pentru a transforma un răspuns GET într-un corp POST valid.
  • apiKey - prezent doar la creare - cheia Bot Talk API nou generată pentru botul respectiv.

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

  • appearance.avatarUrl - adresa URL publică completă a imaginii de avatar a botului (de exemplu https://api.chatlab.com/aichat/content/avatar_xyz.png). Apelați direct prin GET pentru a descărca fișierul. Pentru a-l schimba, încărcați un fișier nou prin intermediul părții multipart avatar (consultați PATCH).
  • whiteLabel.whitelabelLogoUrl - adresa URL publică completă a logoului din antetul white-label. Urmează același principiu ca avatarUrl. Pentru a-l schimba, încărcați un fișier nou prin intermediul părții multipart whitelabel_logo (consultați PATCH).

Ambele adrese URL utilizează schema + gazda + calea de context ale cererii curente, astfel încât, în cazul unui domeniu personalizat white-label, acestea sunt afișate având rădăcina pe domeniul respectiv (de exemplu https://api.acme.com/aichat/content/...).

Trimiteți valoarea null pentru o secțiune dacă doriți să o omiteți la un apel PATCH; trimiteți null pentru un câmp individual dintr-o secțiune pentru a omite doar acel câmp. Un null la nivel de câmp nu șterge niciodată o valoare salvată - semnifică doar comanda „nu modifica”.

Rolul și construirea promptului

Promptul de sistem pe care îl primește LLM-ul este generat într-unul din două moduri, în funcție de role.role. Înțelegerea ramurii pe care vă aflați vă ajută să știți ce câmpuri sunt luate în considerare și care sunt stocate, dar ignorate.

Ramura A - role.role este CUSTOMER_SUPPORT, SALES sau LEAD_COLLECTION_AGENT (pe bază de șablon)

Backend-ul generează promptul dintr-un șablon integrat și ignoră complet câmpul role.rawPrompt (valoarea rămâne stocată pe bot, dar nu este utilizată). Șablonul include:

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

Aceasta este ramura recomandată pentru majoritatea roboților - beneficiați automat de comportamente optimizate pentru rol și de mecanisme de siguranță integrate.

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

Backend-ul utilizează role.rawPrompt exact așa cum a fost transmis ca întreg prompt de sistem. Câmpurile responseLength, language, websiteAddress, companyDescription sunt stocate, dar nu sunt inserate în prompt - dacă doriți ca oricare dintre acestea să influențeze comportamentul botului, trebuie să le includeți manual în textul din rawPrompt. Instrucțiunile privind tonul și mecanismele de siguranță specifice rolurilor nu sunt adăugate; dumneavoastră controlați întregul prompt.

Folosiți CUSTOM numai atunci când promptul bazat pe șablon nu corespunde cazului dumneavoastră de utilizare (de exemplu dacă aveți nevoie de o identitate foarte specifică unui domeniu, de propriile restricții de siguranță sau de un format de ieșire non-standard).

Câmpuri de tip enum / valori fixe

Mai multe câmpuri acceptă doar un set fix de valori de tip șir de caractere. Trimiterea oricărei valori din afara listei este respinsă cu eroarea 400 validation_failed, iar calea câmpului este indicată în error.param. Valorile sunt sensibile la majuscule și minuscule (case-sensitive).

  • 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 drop-down de administrare, de exemplu Auto Detect, English, Polish, Spanish, German, French, Italian, Portuguese, Dutch, Russian, Chinese (Simplified), Japanese, Arabic, Hindi și aproximativ alte 80. Valoarea este stocată identic ș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 vor genera o instrucțiune incorectă precum „Output in en, unless...”. Dacă este omis la creare, valoarea implicită este Auto Detect.
  • advanced.model - consultați secțiunea „Modele de text AI” de mai jos; setul disponibil depinde de limitele contului dumneavoastră, iar trimiterea oricărei valori pe care contul dumneavoastră nu o poate utiliza returnează 400 invalid_parameter
  • advanced.chatContextSize - 8000, 16000, 32000. Valori supuse limitelor contului dumneavoastră; valorile mai mari sunt limitate automat fără avertisment
  • chatMemory.clientSummaryPromptType - DEFAULT, CUSTOM
  • chatMemory.conversationSummaryPromptType - DEFAULT, CUSTOM
  • appearance.chatAlignment - left, right
  • appearance.minimizedDisplayMode - icon, minified
  • appearance.chatMessageLinkTarget - _blank, _self
  • leadCollection.requireBeforeNewConversation - comutator boolean. Valoarea true obligă utilizatorul să completeze formularul de lead înainte de a iniția o conversație; false permite AI-ului să decidă când să afișeze formularul (implicit).

Câmpuri structurate și intervale de valori

Câmpuri care par a fi simple șiruri de caractere sau numere, dar care au structuri specifice, intervale sau particularități în interfața de administrare pe care este util să le cunoașteți.

  • advanced.temperature - intervalul acceptat este între 0.0 și 1.0, corespunzând glisorului din interfața de administrare. Valorile din afara acestui interval sunt respinse cu eroarea 400 validation_failed.

  • chatMemory.summariesToKnowledgeRatio - procent întreg, între 10 și 90, cu pas de 10. Controlează procentul din contextul de chat rezervat pentru rezumatele istorice ale clientului în comparație cu restul elementelor (bază de cunoștințe, conversația curentă, instrucțiuni). Valoarea implicită este 50. Valorile din afara intervalului 10-90 sunt respinse cu eroarea 400 validation_failed. Se aplică doar dacă chatMemory.enabled=true ȘI chatMemory.summaryConversationsEnabled=true.

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

    • fiecare cheie corespunzătoare unei zile (monday-sunday) trimite către {enabled: boolean, from: "H:MM", to: "H:MM"} în format de 24 de ore
    • timezone reprezintă un nume de fus orar IANA (de exemplu "Europe/Warsaw", "America/New_York")

    Exemplu de valoare (observați ghilimelele exterioare și ghilimelele interioare mascate - este un singur câmp de tip șir de caractere, 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ă textul din liveChat.outOfHoursMessage, iar opțiunea de transfer către chatul live este blocată. Validarea structurii interne se execută doar pe partea de client în interfața de administrare - un JSON incorect formatat sau cheile nerecunoscute sunt acceptate de API pur și simplu ca șir de caractere și vor genera o eroare de randare atunci când un utilizator uman va deschide ulterior botul în panoul de administrare. Validați structura local înainte de a o trimite.

  • conversation.positiveRatingTooltip / conversation.negativeRatingTooltip - etichete scurte afișate pe butoanele 👍 / 👎 de lângă fiecare răspuns AI 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, supusă limitelor contului dumneavoastră. Ascunde linia de subsol „Powered by ChatLab”. Dacă contul dumneavoastră nu include funcția white-label, valoarea este stocată, dar ignorată, iar subsolul se afișează întotdeauna.

  • whiteLabel.whitelabelLogoLink - funcție white-label, supusă limitelor contului dumneavoastră. URL-ul destinație la clic pentru logoul personalizat 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 între 0 și 200. Pauza dintre mesajele succesive ale botului când simulateHumanTyping=true. Valoarea implicită este 5.

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

  • advanced.internalLocale - codul de regiune/limbă IETF în formatul ll_CC (cu linie de subliniere, NU ll-CC cu cratimă). Valorile acceptate fac parte 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 a unui cod 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 grafice ale widgetului, distinctă de role.language (limba de redactare a răspunsurilor conversaționale ale botului).

  • security.talkMessagesRateLimit / security.talkMessagesRateLimitDurationSeconds - numere întregi (trimise ca valori numerice JSON, de exemplu 30, nu ca "30"). Valoarea 0 dezactivează limita de mesaje per IP. Când valoarea este diferită de zero, widgetul impune limita de N mesaje pe durata specificată în secunde înainte de a afișa vizitatorului mesajul security.talkMessagesRateLimitHitMessage.

  • advanced.botMessagesLimit - număr întreg (valoare numerică JSON, de exemplu 1000). Valoarea 0 înseamnă „fără limită”; în caz contrar, trebuie să fie un multiplu de 1000 (1000, 2000, 10000...). Valorile precum 100 sau 1500 sunt respinse cu eroarea 400 validation_failed. Ulterior, valoarea este plafonată automat conform limitei stabilite pe contul dumneavoastră.

Modele de text AI (advanced.model)

Trimiteți valoarea exactă utilizată de API (coloana din stânga marcată cu apostrof invers). Numele afișat în interfața de administrare este menționat în paranteze. Limitele contului dumneavoastră dictează ce opțiuni pot fi selectate; dacă trimiteți un model pe care contul dumneavoastră nu îl poate folosi, se va returna eroarea 400 invalid_parameter. Valoarea implicită pentru roboții noi este 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)

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

Fiecare câmp transmis prin rețea, alături de tipul său, restricții și o scurtă descriere. Semantică PATCH: orice câmp omis (sau trimis ca null) lasă neatinsă valoarea stocată. Aceeași structură este utilizată și pentru răspuns (fără conținutul binar multipart; plus blocul needitabil meta prezent în fiecare răspuns și apiKey prezent doar în răspunsul de creare).

Nivel superior

Câmp Tip Restricție 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

Elemente adăugate exclusiv în răspuns:

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

§ role

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

§ conversation

Câmp Tip Restricție Descriere
welcomeMessage string Primul mesaj afișat vizitatorului la deschidere
queryRefinementEnabled boolean Dacă este true, rafinează întrebarea vizitatorului înainte de preluarea prin RAG
conversationContinuityEnabled boolean Dacă este true, vizitatorii care revin își reiau ultima conversație
conversationRatingEnabled boolean Dacă este true, afișează evaluarea cu degetul în sus/jos la mesajele botului
positiveRatingTooltip string Tooltip pe butonul de evaluare pozitivă
negativeRatingTooltip string Tooltip pe butonul de evaluare negativă
suggestedQuestions string Întrebări sugerate / formule de deschidere a conversației, separate prin linii noi
dynamicSuggestedFollowups boolean Dacă este true, AI propune sugestii de continuare după fiecare răspuns
dynamicFollowupsAutoIcons boolean Dacă este true, AI alege automat pictograme emoji pentru sugestiile dinamice

§ chatMemory

Câmp Tip Restricție 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 rezumare implicit sau cel personalizat
clientSummaryPrompt string Prompt personalizat utilizat pentru a rezuma profilul clientului de-a lungul conversațiilor
clientSummaryPromptType string (enum) ∈ {DEFAULT, CUSTOM} Prompt implicit vs personalizat pentru profilul clientului
summariesToKnowledgeRatio int 10-90, pas de 10 Procentul din fereastra de context a chatului alocat rezumatelor comparativ cu baza de cunoștințe RAG

§ appearance

Câmp Tip Restricție Descriere
launcherColor string (hex) Culoarea de fundal a lansatorului (pictograma de chat)
headerColor string (hex) Culoarea de fundal a antetului chatului
titleColor string (hex) Culoarea titlului din antetul chatului
subtitleColor string (hex) Culoarea subtitlului din antetul chatului
clientMessageBubbleColor string (hex) Culoarea bulei de mesaj a vizitatorului
clientMessageTextColor string (hex) Culoarea textului mesajului vizitatorului
responseMessageBubbleColor string (hex) Culoarea bulei de răspuns a botului
responseMessageTextColor string (hex) Culoarea textului de răspuns al botului
chatSubheader string Text secundar afișat sub titlul chatului
senderPlaceholder string Text substituent (placeholder) în câmpul de introducere a mesajului
resetConversationTooltip string Tooltip pe butonul „reset conversation”
chatAlignment string (enum) ∈ {left, right} Pe ce parte a ecranului este fixat chatul
launcherBottomMargin int 0-500 Distanța lansatorului față de marginea de jos (px)
launcherSideMargin int 0-500 Distanța lansatorului față de marginea laterală (px)
displayShadow boolean Umbră exterioară sub widget
customCss string CSS brut injectat în cadrul iframe al widgetului
chatMessageLinkTarget string (enum) ∈ {_blank, _self} Modul în care se deschid linkurile din mesajele botului
minimizedDisplayMode string (enum) ∈ {icon, minified} Stare minimizată: pictogramă de lansare sau bară compactă de trimitere
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 Randează pictograma personalizată de lansare pe întreaga suprafață în loc de format încadrat
welcomeScreenEnabled boolean Afișează ecranul de bun venit (Welcome Screen) în loc de acces direct la chat
welcomeScreenQuestionsLabel string Etichetă afișată deasupra întrebărilor sugerate pe ecranul de bun venit
welcomeScreenHideHumanContactForm boolean Ascunde acțiunea formularului de contact uman din antet cât timp este afișat 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 cât timp este afișat 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 DROPDOWN Modul în care live chatul și formularul de contact uman sunt prezentate în antetul chatului: ICONS (câte o pictogramă separată pentru fiecare) sau DROPDOWN (grupate în meniul antetului). Pentru boții creați înainte de 2026-09-02, valoarea implicită este ICONS
stackSuggestedQuestions boolean Aranjează vertical întrebările sugerate (în loc de dispunere alăturată)
suggestedQuestionsFontSize int Dimensiunea fontului pentru butoanele de întrebări sugerate (px)
suggestedQuestionsTextColor string (hex) Culoarea textului pentru butoanele de întrebări sugerate
suggestedQuestionsBackgroundColor string (hex) Culoarea de fundal a butoanelor de întrebări sugerate
autoOpenChat boolean Deschide automat chatul pe desktop
autoOpenChatOnMobiles boolean Deschide automat chatul pe mobil
autoOpenChatDelay boolean Folosește 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 bulele de mesaje (secunde)
footerMarkdown string max 255 Formatare Markdown personalizată afișată în subsolul chatului
avatarUrl string read-only URL public complet al avatarului; pentru a-l schimba, încărcați prin componenta multipart avatar

Multipart la POST/PATCH: avatar (fișier). Corpurile de răspuns la GET omit conținutul fișierului - prin rețea este transmis doar URL-ul.

§ humanSupport

Câmp Tip Restricție Descriere
enabled boolean Comutator pentru fluxul de asistență umană
email string obligatoriu (la creare strictă) când enabled=true Adresa care primește e-mailurile de asistență umană
dialogMessage string Mesaj de încurajare afișat deasupra formularului
thankYouMessage string Confirmare afișată după trimitere
emailMessageSubjectTemplate string Șablon pentru subiectul e-mailului trimis agentului
emailMessageContentTemplate string Șablon pentru corpul e-mailului trimis agentului
emailPlaceholder string Placeholder în câmpul de e-mail
messagePlaceholder string Placeholder în zona de introducere a mesajului
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. null păstrează formularul integrat
customFormMapping string șir codificat JSON Asociază câmpurile formularului personalizat cu câmpurile de e-mail pentru asistență umană

requirePolicyAccept se află în consent.humanSupportRequirePolicyAccept, nu aici.

§ leadCollection

Câmp Tip Restricție Descriere
enabled boolean Comutator pentru formularul de colectare de lead-uri
nameEnabled boolean Colectează numele
nameLabel string Etichetă pe câmpul pentru nume
emailEnabled boolean Colectează e-mailul
emailLabel string obligatoriu (la creare strictă) când enabled=true ȘI emailEnabled=true Etichetă pe câmpul pentru e-mail
phoneEnabled boolean Colectează telefonul
phoneLabel string obligatoriu (la creare strictă) când enabled=true ȘI phoneEnabled=true Etichetă pe câmpul pentru telefon
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 începerea chatului; 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 adresa de e-mail a contului)
emailWithConversationContent boolean Dacă este true, include transcrierea conversației în notificare

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

| customFormId | long | ID-ul unui formular personalizat existent | Înlocuiește formularul integrat de lead-uri cu un formular personalizat. null păstrează formularul integrat | | customFormMapping | string | șir codificat JSON | Asociază câmpurile formularului personalizat cu name / email / phone |

§ liveChat

Câmp Tip Restricție Descriere
enabled boolean Comutator pentru funcția Live Chat
infoMessage string Mesaj explicativ înainte de preluare
startMessage string Mesaj afișat la începerea sesiunii live
endMessage string Mesaj afișat la încheierea sesiunii live
nameLabel string Etichetă pe câmpul de nume din pre-formularul de live chat
emailLabel string Etichetă pe câmpul de e-mail din pre-formularul de live chat
schedule string șir codificat JSON (comutatoare pentru zilele săptămânii + from/to + timezone) Programul de funcționare pentru live chat - consultați „Câmpuri structurate și intervale” pentru structura exactă
outOfHoursMessage string Mesaj afișat în afara orelor de program conform orarului
closeModalMessage string Titlul ferestrei modale „închideți sesiunea de live chat?”
closeModalConfirmLabel string Eticheta butonului de confirmare din fereastra modală de închidere
closeModalCancelLabel string Eticheta butonului de anulare din fereastra modală de închidere
closeModalTooltipText string Tooltip pe elementul de închidere a chatului
operatorHasJoinedLabel string Etichetă afișată atunci când se alătură un operator
operatorDidNotJoinInTimeLabel string Etichetă afișată dacă niciun operator nu se alătură în intervalul de expirare
waitingForOperatorToJoinLabel string Etichetă afișată în timpul așteptării unui operator
waitingForOperatorSeconds int Timp de expirare pentru preluarea 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
missedEmailEnabled boolean implicit true Trimite un e-mail proprietarului botului atunci când o cerere de live chat a rămas fără răspuns. Rămâne nesetat pe boții vechi, fiind interpretat ca activat

requirePolicyAccept se află în consent.liveChatRequirePolicyAccept, nu aici.

§ consent

Câmp Tip Restricție Descriere
newConversationRequirePolicyAccept boolean Solicită acceptarea politicii de confidențialitate înainte de începerea unei conversații noi
humanSupportRequirePolicyAccept boolean Solicită acceptarea politicii de confidențialitate înainte de trimiterea formularului de asistență umană
leadCollectionRequirePolicyAccept boolean Solicită acceptarea politicii de confidențialitate înainte de trimiterea formularului de colectare de lead-uri
liveChatRequirePolicyAccept boolean Solicită acceptarea politicii de confidențialitate înainte de începerea unei sesiuni de live chat
newConversationConsentDescription string Text introductiv pentru ecranul de consimțământ la începutul conversației
privacyPolicyConsentCheckboxLabel string Etichetă lângă caseta de bifare pentru consimțământ (conține de obicei un link către politica de confidențialitate)

§ whiteLabel

Câmp Tip Restricție Descriere
hideRoboAssistLogo boolean funcționalitate White Label; supusă limitelor contului Ascunde sigla implicită ChatLab din subsol
whitelabelLogoLink string funcționalitate White Label; supusă limitelor contului URL 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 al siglei white label; pentru a-l schimba, încărcați prin componenta multipart whitelabel_logo

Multipart la POST/PATCH: whitelabel_logo (fișier). Corpurile de răspuns la GET omit conținutul fișierului - prin rețea este transmis doar URL-ul.

§ security

Câmp Tip Restricție Descriere
allowedDomains string Listă separată prin virgulă a domeniilor autorizate să integreze widgetul (gol = fără listă albă)
spamFilterEnabled boolean Activează filtrul anti-spam pentru fiecare bot pe 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 permise de la utilizator în intervalul de limitare
talkMessagesRateLimitDurationSeconds int >= 0 Durata intervalului de limitare a ratei (secunde)
talkMessagesRateLimitHitMessage string Mesaj afișat vizitatorului la atingerea limitei de mesaje

§ voice

Câmp Tip Restricție Descriere
inputEnabled boolean Permite vizitatorului să dicteze mesaje (speech to text)
conversationEnabled boolean necesită funcția vocală inclusă în abonament Activează conversațiile vocale complete
voiceId string ID de voce specific furnizorului (de ex. alloy) Ce voce sintetică va vorbi
model string de ex. GPT-REALTIME-MINI, GEMINI-LIVE, ELEVENLABS-* Model vocal. Facturat pe minut, tarifele diferă în funcție de model
turnDetection string specific furnizorului Modul de detectare a rândului la replică
audioPrompt string Prompt suplimentar de sistem utilizat exclusiv pentru intervențiile vocale
welcomeMessage string Mesajul introductiv rostit
language string cod de limbă Limba principală pentru voce
additionalLanguages string coduri de limbă separate prin virgulă Limbi suplimentare acceptate de agentul vocal
maxDurationSeconds int Limită strictă a duratei unei singure conversații vocale
maxDurationMessage string Mesaj afișat la atingerea limitei de durată

§ multilingual

Câmp Tip Restricție Descriere
enabled boolean Comutator pentru modul multilingv
mode string AUTODETECT sau un mod cu listă fixă 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 Cum sunt tratate cunoștințele din alte limbi
knowledgeLanguageFallback string cod de limbă Limba de rezervă utilizată când nu se găsește nicio potrivire

§ advanced

Câmp Tip Restricție Descriere
model string supus limitelor contului; consultați „Modele de text AI” de mai sus Identificator LLM (de ex. 5-MINI)
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ă Fereastra de tokenuri pentru istoricul conversației
botMessagesLimit long 0 sau multiplu de 1000 (de ex. 1000, 2000, 10000) Numărul maxim de răspunsuri ale botului pe conversație (0 = fără limită)
internalLocale string cod de localizare în format ll_CC Localizarea 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 de acoperire a API-ului

Interfața de administrare include câteva secțiuni care în mod deliberat nu sunt expuse în această versiune a Management API:

  • Fila Flow (Flux) - editorul vizual Conversation Flow (stadii și tranziții). Nu este expus prin Management API.
  • Fila Actions (Acțiuni) - integrările gestionate de e-commerce / rezervări, AI Search și funcțiile API personalizate. Apelarea instrumentelor nu a făcut niciodată parte din Management API.
  • Generatorul propriu-zis de formulare personalizate - crearea și editarea formularelor personalizate nu sunt expuse. Puteți, totuși, să atașați un formular existent la un bot prin intermediul leadCollection.customFormId și humanSupport.customFormId.
  • Pictogramele personalizate de deschidere / închidere a chatului - customLauncherIconVisible, openChatIcon, closeChatIcon. API-ul expune doar componentele multipart principale avatar și whitelabel_logo.
  • Listele de IP-uri și țări - intrările propriu-zise sunt rezervate exclusiv administratorilor. Este expus doar modul de interpretare, prin security.countryFilterMode.

Puncte finale

POST /v1/management/bots

Creați un bot nou. Sunt acceptate două tipuri echivalente de Content-Type; 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 direct JSON-ul de configurare a botului (fără wrapper data)
  • Fișierele (avatar / logo) pot fi încărcate ulterior printr-un al doilea apel PATCH folosind modul B

Modul B - multipart/form-data (folosiți-l când încărcați fișiere î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 avatar a botului
  • Partea de fișier whitelabel_logo (opțională) - logo-ul white-label (se aplică numai dacă contul dumneavoastră include funcția White Label)

În JSON este obligatoriu doar câmpul name; toate celelalte câmpuri revin la aceleași valori implicite pe care le-ar seta asistentul configurator din interfața de administrare.

Corpul complet 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-MINI",
    "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 de 10)
  • appearance.launcherBottomMargin, appearance.launcherSideMargin - între 0 și 500
  • appearance.footerMarkdown - maximum 255 de caractere
  • humanSupport.enabled=true necesită setarea câmpului humanSupport.email
  • leadCollection.enabled=true necesită ca cel puțin unul dintre câmpurile leadCollection.emailEnabled sau leadCollection.phoneEnabled să fie setat pe true; canalul activat necesită, de asemenea, eticheta corespunzătoare, plus valorile leaveDetailsMessage și thankYouMessage
  • Câmpurile plafonate (advanced.chatContextSize, advanced.botMessagesLimit etc.) sunt limitate automat la limitele contului dumneavoastră

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

Corpul complet al răspunsului (201)

Aceeași formă ca a cererii, plus blocul read-only meta și cheia de unică afișare apiKey la nivelul principal. URL-urile de fișiere read-only (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) sunt completate de server atunci când au fost încărcate părțile multipart corespunzătoare.

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

Câmpul apiKey apare doar la creare - este cheia Bot Talk nou generată, asociată noului bot. Textul simplu este afișat o singură dată și nu mai poate fi recuperat ulterior prin 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 simplu):

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 actuală 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_..."

Corpul complet al răspunsului (200)

Aceeași formă ca răspunsul POST, fără câmpul de unică afișare apiKey. Blocul meta este inclus. Returnează 404 not_found_error dacă botul nu există sau nu aparține contului dumneavoastră.

Avatarul curent și logo-ul white-label sunt expuse ca URL-uri complete read-only (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) - având ca rădăcină aceeași schemă + gazdă + cale de context care a servit cererea. Preluarea octeților se face prin apeluri GET directe la respectivele URL-uri; pentru a înlocui oricare dintre fișiere, încărcați un fișier nou prin partea multipart avatar / whitelabel_logo din PATCH. Aceste câmpuri URL sunt ignorate dacă sunt trimise în corpul unei cereri.

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

Clonarea unui bot

Corpul cererii pentru POST /v1/management/bots și corpul răspunsului 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 către botul sursă, eliminați câmpurile de identitate gestionate de server, apoi trimiteți rezultatul printr-o cerere POST.

1. Efectuați GET pe botul sursă.

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

2. Eliminați blocul de nivel superior meta. Obiectul meta (id, createdAt, updatedAt) este gestionat de server și este doar pentru citire - lăsarea lui în corpul cererii POST nu produce erori (serverul îl ignoră), dar eliminarea lui face intenția explicită și păstrează sarcina utilă curată. Opțional, editați câmpul 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 prin POST corpul curățat pentru a crea clona. Consultați documentația de referință pentru POST /v1/management/bots de mai sus pentru structura completă a corpului ș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 un apiKey nou generat (cheia Bot Talk pentru clonă). Cheia apiKey în text clar este returnată doar în acest răspuns de creare - copiați-o înainte de a închide corpul răspunsului; aceasta nu mai poate fi recuperată ulterior.

Două avertismente:

  • Fișierele nu sunt clonate. Câmpurile appearance.avatarUrl și whiteLabel.whitelabelLogoUrl sunt doar pentru citire și indică 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 adresele URL sursă și încărcați-le ca părți multipart avatar / whitelabel_logo - fie la cererea POST de creare (Modul B), fie printr-un apel PATCH ulterior.
  • Cheile Bot Talk nu sunt clonate. Fiecare bot are propriul grup 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 ale unui bot pe care îl dețineți. Sunt modificate doar secțiunile / câmpurile prezente în JSON; tot ce este omis (sau trimis ca null) rămâne neschimbat. Se aplică semantica de actualizare parțială pentru fiecare câmp dintr-o secțiune trimisă.

Sunt acceptate două tipuri de conținut (Content-Type) echivalente (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 actualizare (fără înveliș data)

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

  • Partea JSON data (opțional) - actualizarea propriu-zisă. Trimiteți doar dacă doriți să modificați câmpuri. Omiteți 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 logoul 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ă fie valid.

Corp complet al cererii (suprafață maximală)

Orice câmp acceptat de POST /v1/management/bots poate fi trimis și aici. Exemplul de mai jos reprezintă suprafața completă; în practică trimiteți doar cheile pe care doriți să le modificați (consultați secțiunea "Actualizare parțială minimală" de mai jos) - fiecare cheie omisă (sau trimisă ca null) lasă valoarea salvată neschimbată.

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

Actualizați prin PATCH un singur câmp trimițând exact cheile pe care doriți să le modificați - restul datelor sunt păstrate.

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

Exemple de comenzi curl

Modul A - JSON simplu (cel mai ușor):

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 / logoului):

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 exclusivă 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 actualizării parțiale, inclusiv blocul meta. Nu conține câmpul apiKey. Returnează 404 not_found_error dacă botul nu există sau nu aparține contului dumneavoastră.

Exemplul de mai jos ilustrează răspunsul primit după aplicarea actualizării din secțiunea Corp complet al cererii (suprafață maximală) de mai sus asupra botului 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ă utilizarea curentă a abonamentului pentru contul care deține cheia Management.

Corpul răspunsului (200)

{
  "subscriptionType": "standard",
  "messages": {"used": 4123, "limit": 11000, "remaining": 6877},
  "bots": {"used": 3, "limit": 5, "remaining": 2}
}
  • subscriptionType este identificatorul scris cu minuscule al planului curent asociat contului (de exemplu standard în acest exemplu). 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ă numărul de credite de mesaje pentru perioada de facturare curentă.
  • bots.used / limit / remaining contorizează boții activi raportați la limita de boți a contului dumneavoastră.

Anteturi de limitare a ratei (rate limit headers)

Răspunsurile care ajung în etapa de limitare a ratei (adică au trecut de autentificare și de lista albă de IP-uri) includ:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1715430000
  • X-RateLimit-Limit - limita per cheie aplicată efectiv acestui apel (10 în mod implicit sau valoarea configurată de dumneavoastră în rateLimitPerMinute, dacă este mai mică).
  • X-RateLimit-Remaining - numărul de tokenuri rămase în bucket imediat după acest apel.
  • X-RateLimit-Reset - timpul Unix epoch în secunde la care devine disponibil următorul token (nu o resetare completă a bucketului; bucketul se reumple continuu). Când bucketul este plin, acesta 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 prealabile autentificării (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) și 403 ip_not_whitelisted nu conțin anteturile X-RateLimit-* - limitatorul este consultat numai după ce verificările de autentificare și IP reușesc.

Formatul erorilor

Același format de bază ca la 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 cu probleme la începutul mesajului, astfel încât secțiunea invalidă 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 streamingul SSE, consultați Bot Talk API.

Căutați în toate articoleleÎntrebați agentul