Помощен център
Chat API

Management API

Последна актуализация:

Преглед на Management API

Management API е предназначен за административни задачи от бек офиса, които не включват изпращане на съобщения в чата:

  • създаване на бот програмно с POST /v1/management/bots
  • извличане на конкретен бот, който притежавате, с GET /v1/management/bots/{bot_id}
  • обновяване на конкретен бот с PATCH /v1/management/bots/{bot_id}
  • извличане на данните за потреблението на абонамента с GET /v1/usage

Ключовете за управление (Management keys) са обвързани с Вашия профил, а не с конкретен бот. Те умишлено се пазят отделно от ключовете за Bot Talk, така че компрометиран ключ за чат да не може да променя ботовете Ви или да чете данни за фактурирането.

Базов URL (Base URL)

https://api.chatlab.com/aichat

Всички крайни точки (endpoints) в тази статия са относителни спрямо този базов URL адрес.

Първи стъпки

  1. Отворете административния панел и отидете на Account Settings > Management API (Настройки на профила > Management API).
  2. Кликнете върху Create Management Key (Създаване на ключ за управление), дайте му име, по желание задайте бял списък с IP адреси и лимит на заявките, след което потвърдете.
  3. Копирайте целия ключ от прозореца за успешно завършване. Неговият чист текст се показва само веднъж.

Ключът изглежда по следния начин: mk_abcdefghijklmnopqrstuvwxyz012345. Префиксът mk_ го отличава от ключовете за Bot Talk (ck_).

Удостоверяване (Authentication)

Authorization: Bearer mk_abcdefghijklmnopqrstuvwxyz012345

Изпращането на ключ mk_ към /v1/chat (или всяка друга крайна точка на Bot Talk) връща 403 key_type_not_allowed. Изпращането на ключ ck_ към /v1/management/* връща същата грешка.

Лимити

  • Максимум 5 активни ключа за Management API на потребител
  • Максимум 10 заявки в минута за всеки ключ (алгоритъм token bucket с капацитет 10 и плавно възстановяване с ~1 токен на всеки 6 секунди). Възможност за конфигуриране надолу при създаване - ако зададете по-ниска стойност за rateLimitPerMinute, таванът пада, а темпът на възстановяване се мащабира съответно.

Разрешения (Permissions)

Всеки ключ за управление съдържа произволно подмножество от трите разрешения по-долу. Поне едно от тях трябва да бъде избрано при създаването, в противен случай заявката се отхвърля с 400 invalid_request_error. Извикването на крайна точка с ключ, на който му липсва необходимото разрешение, връща 403 insufficient_permissions.

  • bot_read - изисква се за GET /v1/management/bots/{bot_id}
  • bot_management - изисква се за POST /v1/management/bots и PATCH /v1/management/bots/{bot_id}
  • usage - изисква се за GET /v1/usage

Структура на тялото: вложени секции, отразяващи разделите в административния интерфейс

POST и PATCH приемат JSON тяло, групирано в 13 секции. Всяка секция съответства на подраздел в страничната лента с настройки на бота (Bot Settings) в административното приложение, така че JSON ключовете и видимите раздели съвпадат: ако промените consent.humanSupportRequirePolicyAccept чрез API, ще видите как същият превключвател се сменя в раздела Consent & Privacy (Съгласие и поверителност) в панела.

  • role - персона на бота, суров промпт, дължина на отговора, език, контекст на уебсайта / компанията (раздел Role & Behavior)
  • conversation - приветствено съобщение, прецизиране на заявките, непрекъснатост на разговора, превключвател за оценка + подсказки, съдържание на предложените въпроси + динамични последващи въпроси (раздел Chat Conversation)
  • chatMemory - превключвател на паметта на чата, промптове за обобщения, заделяне на контекст (раздел Summaries & Memory)
  • appearance - цветове, текстове, размери, персонализиран CSS, начален екран, стилизиране на предложените въпроси, поведение на автоматично отваряне, симулация на писане от човек, markdown за футъра (раздел Appearance)
  • humanSupport - форма за връзка с човек (раздел Human Contact Form)
  • leadCollection - форма за събиране на лийдове (раздел Lead Collection)
  • liveChat - прехвърляне към чат на живо (раздел Live Chat)
  • consent - четирите превключвателя за съгласие с политиката за поверителност плюс текста на екрана за съгласие (раздел Consent & Privacy)
  • whiteLabel - скриване на логото, връзка към персонализирано лого, хостинг на собствен домейн (раздел Whitelabel)
  • security - разрешени домейни, филтър за спам, лимити на съобщенията (раздел Security)
  • voice - гласово въвеждане и гласови разговори: модел, глас, езици, промпт, ограничение на продължителността (раздел Voice Conversation)
  • multilingual - многоезичен режим, базов език, предлагани езици, обработка на езика на базата знания (раздел Languages)
  • advanced - LLM модел, температура, размер на контекста, лимит на съобщенията от бота, вътрешна локализация, Offer Cards (раздел Model & Advanced)

Единствено name се намира на най-високо ниво, тъй като идентифицира бота, вместо да принадлежи към конкретен раздел.

Страничната лента Bot Settings в момента съдържа 15 подраздела, като 13 от тях съответстват на секциите по-горе. Двата подраздела без съответстваща секция са Flow и Actions - и двата са описани в частта "Извън обхвата на API" по-долу. Тринадесетте, които имат съответствие, са Appearance, Chat Conversation, Role & Behavior, Human Contact Form, Lead Collection, Live Chat, Whitelabel, Consent & Privacy, Security, Model & Advanced, Summaries & Memory, Voice Conversation и Languages.

Тялото на заявката и тялото на отговора споделят еднаква структура. Отговорът добавя две допълнителни полета:

  • meta - само за четене: ID на бота и времеви отпечатъци. Премахнете го, за да превърнете GET отговор във валидно POST тяло.
  • apiKey - присъства само при създаване - новогенерираният ключ за Bot Talk API за новия бот.

Две полета в споделената структура са само за четене - връщат се в отговора и се игнорират, ако се опитате да ги изпратите при POST/PATCH:

  • appearance.avatarUrl - пълен публичен URL адрес на изображението за аватар на бота (напр. https://api.chatlab.com/aichat/content/avatar_xyz.png). Изпратете GET заявка директно към него, за да изтеглите байтовете. За да го промените, качете нов файл чрез multipart частта avatar (вижте PATCH).
  • whiteLabel.whitelabelLogoUrl - пълен публичен URL адрес на логото в заглавната част при White Label. Работи по същия начин като avatarUrl. За да го промените, качете нов файл чрез multipart частта whitelabel_logo (вижте PATCH).

И двата URL адреса използват схемата + хоста + пътя на текущата заявка, така че при персонализиран White Label домейн те се връщат с корен в този домейн (напр. https://api.acme.com/aichat/content/...).

Изпратете null за цяла секция, за да я пропуснете при PATCH; изпратете null за поле в дадена секция, за да пропуснете само това поле. Стойност null на ниво поле никога не изчиства запазена стойност - тя означава единствено "не променяй".

Изграждане на роля и промпт

Системният промпт, който LLM всъщност получава, се изгражда по един от два начина в зависимост от role.role. Познаването на използвания подход Ви показва кои полета имат значение и кои се записват, но се игнорират.

Вариант A - role.role е CUSTOMER_SUPPORT, SALES или LEAD_COLLECTION_AGENT (базиран на шаблон)

Бекендът сглобява промпта от вграден шаблон и напълно игнорира role.rawPrompt (стойността все пак се запазва за бота, но не се използва). Шаблонът включва:

  • role.role - етикет на ролята (напр. "Customer Support") и автоматично добавени специфични инструкции за нея
  • name - име на бота, вмъкнато в първото изречение
  • role.language - "Auto Detect" настройва бота да следва езика на потребителя; всяка друга стойност (напр. "English", "Polish") се превръща в "Output in {language}, unless user uses another language"
  • role.responseLength - съответства на целеви брой думи: Concise ≈ 50 думи, Normal ≈ 100, Detailed ≈ 200
  • role.websiteAddress - по избор; когато не е празно, се добавя като "for the users of the website {url}"
  • role.companyDescription - по избор; когато не е празно, се добавя като предхождащ параграф преди инструкциите за ролята

Това е препоръчителният вариант за повечето ботове - получавате оптимизирано за конкретната роля поведение и предпазни механизми без допълнителни настройки.

Вариант B - role.role е CUSTOM (промпт, предоставен от потребителя)

Бекендът използва role.rawPrompt директно и изцяло като системен промпт. Полетата responseLength, language, websiteAddress, companyDescription се записват, но не се вмъкват в промпта - ако искате някое от тях да влияе върху поведението на бота, трябва сами да го включите в текста на Вашия rawPrompt. Специфичните за дадена роля предпазни мерки и указания за тон също не се добавят; Вие контролирате целия промпт.

Използвайте CUSTOM само когато шаблонният промпт не отговаря на Вашия случай (напр. нуждаете се от персона за силно специфичен отрасъл, собствени ограничения за сигурност или нестандартен изходен формат).

Полета от изброим тип (enum / фиксиран набор)

Няколко полета приемат само фиксиран набор от низови стойности. Изпращането на стойност извън списъка се отхвърля с 400 validation_failed и пътя до полето в error.param. Стойностите зависят от регистъра на буквите (case-sensitive).

  • role.role - CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM
  • role.responseLength - Concise, Normal, Detailed
  • role.language - пълното английско име на езика от падащото меню в панела, напр. Auto Detect, English, Polish, Spanish, German, French, Italian, Portuguese, Dutch, Russian, Chinese (Simplified), Japanese, Arabic, Hindi и около 80 други. Стойността се записва буквално и се замества в шаблона на промпта, така че двубуквените ISO кодове (en, pl) и други стойности извън списъка не се отхвърлят от API, но генерират некоректна инструкция като "Output in en, unless...". По подразбиране е Auto Detect, ако се пропусне при създаване.
  • advanced.model - вижте "AI текстови модели" по-долу; достъпният списък зависи от лимитите на профила Ви и всяка стойност, която Вашият профил не може да използва, връща 400 invalid_parameter
  • advanced.chatContextSize - 8000, 16000, 32000. Зависи от лимитите на Вашия профил; по-високите стойности се ограничават автоматично без съобщение
  • chatMemory.clientSummaryPromptType - DEFAULT, CUSTOM
  • chatMemory.conversationSummaryPromptType - DEFAULT, CUSTOM
  • appearance.chatAlignment - left, right
  • appearance.minimizedDisplayMode - icon, minified
  • appearance.chatMessageLinkTarget - _blank, _self
  • leadCollection.requireBeforeNewConversation - булев превключвател. true задължава потребителя да попълни формата за лийдове преди започване на разговор; false позволява на AI да прецени кога да покаже формата (по подразбиране).

Структурирани полета и диапазони

Полета, които изглеждат като обикновени низове или числа, но всъщност имат специфична структура, диапазони или особености в административния панел, които е важно да знаете.

  • advanced.temperature - допустимият диапазон е от 0.0 до 1.0, съответстващ на плъзгача в административния интерфейс. Стойности извън този диапазон се отхвърлят с 400 validation_failed.

  • chatMemory.summariesToKnowledgeRatio - цяло число в проценти, 10-90 със стъпка 10. Контролира колко от контекста на чата да бъде запазен за хронологичните обобщения на клиента спрямо останалата част (база знания, текущ разговор, инструкции). По подразбиране е 50. Стойности извън диапазона 10-90 се отхвърлят с 400 validation_failed. Прилага се само когато chatMemory.enabled=true И chatMemory.summaryConversationsEnabled=true.

  • liveChat.schedule - JSON, кодиран като низ, а не вложен JSON обект при преноса на данни. Сървърът съхранява суровия низ директно; административният панел го парсва от страната на клиента, когато зарежда редактора на графика. След като се парсне, низът има структура от по един запис за всеки ден от седмицата плюс ключ timezone:

    • всеки ключ за ден от седмицата (monday-sunday) сочи към {enabled: boolean, from: "H:MM", to: "H:MM"} в 24-часов формат
    • timezone е име на IANA часова зона (напр. "Europe/Warsaw", "America/New_York")

    Примерна стойност (обърнете внимание на външните кавички и екранираните вътрешни кавички - това е едно низово поле, а не вложен обект):

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

    Извън посочените часове на посетителя се показва liveChat.outOfHoursMessage, а прехвърлянето към чат на живо се спира. Валидацията на вътрешната структура се изпълнява само от страната на клиента в административния интерфейс - невалиден JSON или неразпознати ключове се приемат от API като обикновен низ и ще предизвикат грешка при рендиране, когато потребител отвори бота по-късно в панела. Валидирайте структурата от Ваша страна, преди да я изпратите.

  • conversation.positiveRatingTooltip / conversation.negativeRatingTooltip - кратки етикети, показвани върху бутоните 👍 / 👎 до всеки отговор на AI, когато conversation.conversationRatingEnabled=true. Текстът по подразбиране е "I like the response" / "I don't like the response". Видими са за крайните потребители.

  • whiteLabel.hideRoboAssistLogo - функционалност на White Label, подчинена на ограниченията на Вашия акаунт. Скрива реда "Powered by ChatLab" във футъра. Ако акаунтът Ви не включва опцията White Label, стойността се запазва, но се игнорира и футърът се показва винаги.

  • whiteLabel.whitelabelLogoLink - функционалност на White Label, подчинена на ограниченията на Вашия акаунт. Целеви URL адрес при клик върху персонализираното лого, когато hideRoboAssistLogo=true и е качен файл за лого чрез multipart частта whitelabel_logo.

  • appearance.simulateHumanTypingDelay - секунди (не милисекунди), цяло число 0-200. Пауза между последователните балончета на бота, когато simulateHumanTyping=true. По подразбиране е 5.

  • appearance.autoOpenChatDelaySeconds - секунди, цяло число. Забавяне преди уиджетът да се отвори автоматично, когато autoOpenChat=true и autoOpenChatDelay=true.

  • advanced.internalLocale - код за локал и регион по IETF във формат ll_CC (долна черта, а НЕ ll-CC с тире). Допустимите стойности идват от фиксиран списък от около 95 локализации: 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 и много други. Изпращането само на двубуквен код ("en") или BCP-47 ("en-US") не е част от разрешения списък. По подразбиране е en_US. Това е локализацията, използвана за форматиране на дати и числа в интерфейса на уиджета, и се различава от role.language (езика на изходящите съобщения на бота).

  • security.talkMessagesRateLimit / security.talkMessagesRateLimitDurationSeconds - цели числа (изпращат се като JSON числа, напр. 30, а не "30"). Стойност 0 деактивира лимита на съобщения за IP адрес. При ненулева стойност уиджетът налага ограничение от N съобщения за посочения брой секунди, преди да покаже security.talkMessagesRateLimitHitMessage на посетителя.

  • advanced.botMessagesLimit - цяло число (JSON число, напр. 1000). Стойност 0 означава "без ограничение"; в противен случай трябва да бъде кратно на 1000 (1000, 2000, 10000...). Стойности като 100 или 1500 се отхвърлят с 400 validation_failed. В допълнение стойността се ограничава тихо до лимита на Вашия акаунт.

AI текстови модели (advanced.model)

Изпратете точната стойност за API (колоната вляво с обратни кавички). Името за показване в административния интерфейс е посочено в скоби. Ограниченията на Вашия акаунт определят кое подмножество е достъпно; изпращането на модел, който профилът Ви не може да използва, връща 400 invalid_parameter. Стойността по подразбиране за нови ботове е 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)

Справочник на полетата (пълна схема на заявката)

Всяко поле в мрежовия трафик, заедно с неговия тип, ограничение и едноредово описание. Семантика на PATCH: всяко пропуснато поле (или изпратено като null) оставя запазената стойност непроменена. Същата структура се използва и за отговора (без многокомпонентното двоично съдържание; плюс блока само за четене meta при всеки отговор и apiKey единствено при отговора за създаване).

Най-горно ниво (Top level)

Поле Тип Ограничение Описание
name string макс. 150, задължително при създаване Екранно име на бота
role object Вижте § role
conversation object Вижте § conversation
chatMemory object Вижте § chatMemory
appearance object Вижте § appearance
humanSupport object Вижте § humanSupport
leadCollection object Вижте § leadCollection
liveChat object Вижте § liveChat
consent object Вижте § consent
whiteLabel object Вижте § whiteLabel
security object Вижте § security
advanced object Вижте § advanced

Допълнения само в отговора:

  • meta: { id, createdAt, updatedAt } - само за четене.
  • apiKey - string, присъства само в отговора на POST /v1/management/bots - новосъздаденият Bot Talk ключ за новия бот, върнат точно веднъж.

§ role

Поле Тип Ограничение Описание
role string (enum) CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM Предварително зададена персона; избира шаблона на системните инструкции (вижте "Роля и изграждане на промпт")
language string пълно английско име на езика (English, Polish, ...) или Auto Detect Основен език, подаден към шаблона на промпта
responseLength string ∈ {Concise, Normal, Detailed} Желана детайлност на отговора от AI
websiteAddress string Уебсайт, използван за контекст на промпта
companyDescription string Описание на компанията, използвано за контекст на промпта
rawPrompt string Персонализиран системен промпт - използва се буквално само при role=CUSTOM

§ conversation

Поле Тип Ограничение Описание
welcomeMessage string Първо съобщение, показано на посетителя при отваряне
queryRefinementEnabled boolean Ако е true, въпросът на посетителя се прецизира преди RAG извличането
conversationContinuityEnabled boolean Ако е true, завръщащите се посетители продължават последния си разговор
conversationRatingEnabled boolean Ако е true, показва бутони с палец нагоре/надолу за оценка на съобщенията на бота
positiveRatingTooltip string Подсказка (tooltip) на бутона за положителна оценка
negativeRatingTooltip string Подсказка (tooltip) на бутона за отрицателна оценка
suggestedQuestions string Предложени въпроси / начални фрази за разговор, разделени с нов ред
dynamicSuggestedFollowups boolean Ако е true, AI предлага последващи въпроси след всеки отговор
dynamicFollowupsAutoIcons boolean Ако е true, AI автоматично избира емоджи икони за динамичните последващи въпроси

§ chatMemory

Поле Тип Ограничение Описание
enabled boolean Главен превключвател за функцията за памет на чата
summaryConversationsEnabled boolean Запазване на обобщения за всеки разговор
conversationSummaryPrompt string Персонализиран промпт, използван за обобщаване на всеки разговор
conversationSummaryPromptType string (enum) ∈ {DEFAULT, CUSTOM} Дали да се използва стандартният, или персонализираният промпт за обобщение
clientSummaryPrompt string Персонализиран промпт, използван за обобщаване на профила на клиента през различните разговори
clientSummaryPromptType string (enum) ∈ {DEFAULT, CUSTOM} Стандартен спрямо персонализиран промпт за профила на клиента
summariesToKnowledgeRatio int 10-90, стъпка 10 Процент от контекстния прозорец на чата, заделен за обобщения спрямо RAG базата със знания

§ appearance

Поле Тип Ограничение Описание
launcherColor string (hex) Фонов цвят на бутона за стартиране (иконата на чата)
headerColor string (hex) Фонов цвят на заглавната лента на чата
titleColor string (hex) Цвят на заглавието в горната част на чата
subtitleColor string (hex) Цвят на подзаглавието в горната част на чата
clientMessageBubbleColor string (hex) Цвят на балончето със съобщение от посетителя
clientMessageTextColor string (hex) Цвят на текста в съобщението от посетителя
responseMessageBubbleColor string (hex) Цвят на балончето с отговор от бота
responseMessageTextColor string (hex) Цвят на текста в отговора от бота
chatSubheader string Допълнително мото/подзаглавие, показано под заглавието на чата
senderPlaceholder string Заместващ текст (placeholder) в полето за въвеждане на съобщение
resetConversationTooltip string Подсказка на бутона за "нулиране на разговора"
chatAlignment string (enum) ∈ {left, right} Към коя страна на екрана да бъде фиксиран чатът
launcherBottomMargin int 0-500 Разстояние на бутона за стартиране от долния край (px)
launcherSideMargin int 0-500 Разстояние на бутона за стартиране от страничния край (px)
displayShadow boolean Падаща сянка под уиджета
customCss string Директен CSS, вграден в iframe на уиджета
chatMessageLinkTarget string (enum) ∈ {_blank, _self} Начин на отваряне на връзките вътре в съобщенията на бота
minimizedDisplayMode string (enum) ∈ {icon, minified} Минимизирано състояние: икона за отваряне или компактна лента за въвеждане
chatDesktopWidthPx int Ширина на уиджета за десктоп
chatDesktopHeightPx int Височина на уиджета за десктоп
chatMobileSizePercent int Размер на мобилния уиджет като процент от видимата област (viewport)
messageFontSize int Размер на шрифта на текста на съобщенията (px)
showChatbotBubblesDesktop boolean Показване на плаващи закачливи балончета на десктоп
showChatbotBubblesMobile boolean Показване на плаващи закачливи балончета на мобилни устройства
chatbotBubblesDelaySeconds int Забавяне преди появата на закачливите балончета (секунди)
launcherIconFullSize boolean Изчертаване на персонализираната икона за стартиране от край до край, вместо с отстъп
welcomeScreenEnabled boolean Показване на Welcome Screen (начален екран) вместо директно преминаване към чата
welcomeScreenQuestionsLabel string Етикет над предложените въпроси на началния екран
welcomeScreenHideHumanContactForm boolean Скриване на действието за форма за връзка с човек в заглавната лента, докато се показва Welcome Screen. То се появява отново след първото съобщение на посетителя. За ботове, създадени преди 02.09.2026 г., стойността по подразбиране е true
welcomeScreenHideLiveChat boolean Скриване на действието за чат на живо в заглавната лента, докато се показва Welcome Screen. То се появява отново след първото съобщение на посетителя. За ботове, създадени преди 02.09.2026 г., стойността по подразбиране е true
headerActionsLayout string DROPDOWN Как се предлагат чатът на живо и формата за връзка с човек в заглавната лента на чата: ICONS (всяко с отделна икона) или DROPDOWN (групирани в падащо меню). За ботове, създадени преди 02.09.2026 г., стойността по подразбиране е ICONS
stackSuggestedQuestions boolean Вертикално подреждане на предложените въпроси (вместо един до друг)
suggestedQuestionsFontSize int Размер на шрифта на бутоните за предложени въпроси (px)
suggestedQuestionsTextColor string (hex) Цвят на текста на бутоните за предложени въпроси
suggestedQuestionsBackgroundColor string (hex) Фонов цвят на бутоните за предложени въпроси
autoOpenChat boolean Автоматично отваряне на чата на десктоп
autoOpenChatOnMobiles boolean Автоматично отваряне на чата на мобилни устройства
autoOpenChatDelay boolean Използване на забавяне преди автоматичното отваряне
autoOpenChatDelaySeconds int Време за забавяне на автоматичното отваряне (секунди)
simulateHumanTyping boolean Разделяне на отговора на бота на отделни балончета с анимация на писане
simulateHumanTypingDelay int 0-200 Забавяне между отделните съобщения (секунди)
footerMarkdown string макс. 255 Персонализиран Markdown текст в долната част (footer), показан под чата
avatarUrl string само за четене Пълен публичен URL адрес на аватара; за да го промените, качете файл чрез multipart частта avatar

Multipart данни при POST/PATCH: avatar (файлова част). Телата на GET / отговорите пропускат съдържанието на файла - в мрежовия трафик се предава само URL адресът.

§ humanSupport

Поле Тип Ограничение Описание
enabled boolean Превключвател за процеса за връзка с човек (Human Support)
email string задължително (create-strict), когато enabled=true Имейл адрес, който получава съобщенията за поддръжка от човек
dialogMessage string Подканващо съобщение, показано над формата
thankYouMessage string Потвърждение, показано след изпращане
emailMessageSubjectTemplate string Шаблон за тема на имейла, изпращан до агента
emailMessageContentTemplate string Шаблон за съдържанието на имейла, изпращан до агента
emailPlaceholder string Заместващ текст в полето за въвеждане на имейл
messagePlaceholder string Заместващ текст в полето за съобщение
emailWithConversationContent boolean Ако е true, включва стенограмата на разговора в тялото на имейла
customFormId long id на съществуваща персонализирана форма Заменя вградената форма за контакт с персонализирана форма. Стойност null запазва вградената форма
customFormMapping string JSON-кодиран низ Съпоставя полетата на персонализираната форма с полетата на имейла за връзка с човек

Настройката requirePolicyAccept се намира в consent.humanSupportRequirePolicyAccept, а не тук.

§ leadCollection

Поле Тип Ограничение Описание
enabled boolean Превключвател за формата за събиране на лийдове
nameEnabled boolean Събиране на име
nameLabel string Етикет на полето за име
emailEnabled boolean Събиране на имейл
emailLabel string задължително (create-strict), когато enabled=true И emailEnabled=true Етикет на полето за имейл
phoneEnabled boolean Събиране на телефон
phoneLabel string задължително (create-strict), когато enabled=true И phoneEnabled=true Етикет на полето за телефон
leaveDetailsMessage string задължително (create-strict), когато enabled=true Съобщение, подканващо посетителя да остави своите данни
thankYouMessage string задължително (create-strict), когато enabled=true Потвърждение, показано след изпращане
requireBeforeNewConversation boolean Ако е true, формата трябва да бъде попълнена преди началото на чата; ако е false, AI решава кога да покаже формата
emailNotificationEnabled boolean Изпращане на имейл до собственика при всеки събран лийд
emailNotificationAddress string Получател на известието (по подразбиране е имейлът на акаунта)
emailWithConversationContent boolean Ако е true, включва стенограмата на разговора в известието

Кръстосано правило при създаване (create-strict): enabled=true изисква поне едно от полетата emailEnabled или phoneEnabled да бъде активно. Настройката requirePolicyAccept се намира в consent.leadCollectionRequirePolicyAccept, а не тук.

| customFormId | long | id на съществуваща персонализирана форма | Заменя вградената форма за лийдове с персонализирана форма. Стойност null запазва вградената форма | | customFormMapping | string | JSON-кодиран низ | Съпоставя полетата на персонализираната форма с name / email / phone |

§ liveChat

Поле Тип Ограничение Описание
enabled boolean Превключвател за функцията Live Chat
infoMessage string Разяснително съобщение преди прехвърляне към оператор
startMessage string Съобщение, показано при започване на сесията на живо
endMessage string Съобщение, показано при приключване на сесията на живо
nameLabel string Етикет на полето за име в предварителната форма за чат на живо
emailLabel string Етикет на полето за имейл в предварителната форма за чат на живо
schedule string JSON-кодиран низ (превключватели за дни от седмицата + from/to + timezone) Работен график за чат на живо - вижте "Структурирани полета и диапазони" за точната структура
outOfHoursMessage string Съобщение, показвано извън работното време според графика
closeModalMessage string Заглавие на модалния прозорец "затваряне на чата на живо?"
closeModalConfirmLabel string Етикет на бутона за потвърждение в модалния прозорец за затваряне
closeModalCancelLabel string Етикет на бутона за отказ в модалния прозорец за затваряне
closeModalTooltipText string Подсказка към бутона за прекратяване на чата
operatorHasJoinedLabel string Текст, показван при включване на оператор
operatorDidNotJoinInTimeLabel string Текст, показван когато оператор не се включи в рамките на зададеното време
waitingForOperatorToJoinLabel string Текст, показван по време на изчакване на оператор
waitingForOperatorSeconds int Време за изчакване на оператор да поеме чата (секунди)
redirectToHumanSupportForm boolean Ако е true, пренасочва към формата за Human Support, когато никой оператор не отговори
missedEmailEnabled boolean по подразбиране true Изпращане на имейл до собственика на бота при пропуснат чат на живо. При по-стари ботове остава незададено, което се третира като активно

Настройката requirePolicyAccept се намира в consent.liveChatRequirePolicyAccept, а не тук.

§ consent

Поле Тип Ограничение Описание
newConversationRequirePolicyAccept boolean Изискване на съгласие с политиката за поверителност преди започване на нов разговор
humanSupportRequirePolicyAccept boolean Изискване на съгласие с политиката за поверителност преди изпращане на формата за връзка с човек
leadCollectionRequirePolicyAccept boolean Изискване на съгласие с политиката за поверителност преди изпращане на формата за лийдове
liveChatRequirePolicyAccept boolean Изискване на съгласие с политиката за поверителност преди започване на сесия за чат на живо
newConversationConsentDescription string Въвеждащ текст на екрана за съгласие при стартиране на разговор
privacyPolicyConsentCheckboxLabel string Етикет до полето за съгласие (обикновено съдържа връзка към политиката за поверителност)

§ whiteLabel

Поле Тип Ограничение Описание
hideRoboAssistLogo boolean възможност на White Label; предмет на лимити на акаунта Скриване на стандартното лого на ChatLab в долната част (footer)
whitelabelLogoLink string white-label възможност; предмет на лимити на акаунта URL адрес, към който води персонализираното лого в долната част
assignToCustomDomain boolean ограничено от функцията CUSTOM_DOMAIN Хостване на чата на конфигурирания персонализиран домейн
whitelabelLogoUrl string само за четене Пълен публичен URL адрес на whitelabel логото; за да го промените, качете файл чрез multipart частта whitelabel_logo

Multipart данни при POST/PATCH: whitelabel_logo (файлова част). Телата на GET / отговорите пропускат съдържанието на файла - в мрежовия трафик се предава само URL адресът.

§ security

Поле Тип Ограничение Описание
allowedDomains string Списък с домейни, разделени със запетая, с право да вграждат уиджета (празно = без списък с разрешени)
spamFilterEnabled boolean Активиране на спам филтъра за входящи съобщения за съответния бот
countryFilterMode string BLACKLIST или WHITELIST Как да се тълкуват списъците с държави. Самите списъци остават достъпни само за администратори
talkMessagesRateLimit int >= 0; 0 деактивира Максимален брой потребителски съобщения в рамките на прозореца за ограничаване на честотата
talkMessagesRateLimitDurationSeconds int >= 0 Продължителност на прозореца за ограничаване на честотата (секунди)
talkMessagesRateLimitHitMessage string Съобщение, показвано на посетителя при достигане на лимита на честотата

§ voice

Поле Тип Ограничение Описание
inputEnabled boolean Позволява на посетителя да диктува съобщения (говор към текст)
conversationEnabled boolean изисква гласовата функция да е налична в плана Активиране на пълноценни гласови разговори
voiceId string специфичен гласов идентификатор според доставчика (напр. alloy) Кой синтетичен глас говори
model string напр. GPT-REALTIME-MINI, GEMINI-LIVE, ELEVENLABS-* Гласов модел. Таксува се на минута, цените варират според модела
turnDetection string според доставчика Режим на разпознаване на ред за говорене
audioPrompt string Допълнителен системен промпт, използван само за гласовите реплики
welcomeMessage string Изговорена начална реплика
language string код на език Основен гласов език
additionalLanguages string кодове на езици, разделени със запетая Допълнителни езици, които гласовият асистент приема
maxDurationSeconds int Твърд лимит за продължителност на единичен гласов разговор
maxDurationMessage string Съобщение, показвано при достигане на лимита за продължителност

§ multilingual

Поле Тип Ограничение Описание
enabled boolean Превключвател за многоезичен режим
mode string AUTODETECT или фиксиран списък Как ботът избира езика на отговора
baseLanguage string код на език Езикът, на който са написани основните текстове на бота
languages string кодове на езици, разделени със запетая Езици, предлагани на посетителя
knowledgeLanguageMode string Как се обработват материалите от базата със знания на други езици
knowledgeLanguageFallback string код на език Резервен език, използван при липса на съвпадение

§ advanced

Поле Тип Ограничение Описание
model string зависи от лимитите на акаунта; вижте "AI текстови модели" по-горе Идентификатор на LLM (напр. 5-MINI)
temperature decimal 0.0-1.0 Температура на семплиране (съответства на плъзгача в интерфейса)
chatContextSize int ∈ {8000, 16000, 32000}; автоматично се ограничава до лимита на Вашия акаунт Токен прозорец за историята на чата
botMessagesLimit long 0 или число, кратно на 1000 (напр. 1000, 2000, 10000) Максимален брой отговори на бота за един разговор (0 = без лимит)
internalLocale string код на локал във формат ll_CC Локал за системните текстове на уиджета (различен от role.language)
productsViewEnabled boolean Ако е true, визуализира картите с продукти (Offer Cards) за електронна търговия вътре в чата
includeProductsInKnowledgeBase boolean Ако е true, индексира продуктовия каталог като част от базата със знания

Извън обхвата на API

Административният потребителски интерфейс съдържа няколко секции, които нарочно не са достъпни в тази версия на Management API:

  • Раздел Flow (Поток) - визуалният редактор на разговорния поток (Flow Editor - стъпки и преходи). Не е достъпен през Management API.
  • Раздел Actions (Действия) - управлявани интеграции за електронна търговия / резервации, AI Search и персонализирани API функции. Извикването на външни инструменти (tool calling) никога не е било част от Management API.
  • Самият конструктор на персонализирани форми - създаването и редактирането на потребителски форми не е достъпно. Можете обаче да прикачите съществуваща форма към бот чрез leadCollection.customFormId и humanSupport.customFormId.
  • Персонализирани икони за отваряне / затваряне на чата - customLauncherIconVisible, openChatIcon, closeChatIcon. API предоставя достъп само до основните multipart части за avatar и whitelabel_logo.
  • Списъци с IP адреси и държави - самите записи са достъпни единствено за администратори. През API е достъпен само режимът на филтриране чрез security.countryFilterMode.

Крайни точки (Endpoints)

POST /v1/management/bots

Създаване на нов бот. Приемат се два еквивалентни типа съдържание (Content-Type); изберете този, който е по-удобен за Вас.

Режим A - чист JSON (препоръчва се, когато не е необходимо да качвате аватар / лого в същата заявка):

  • Content-Type: application/json
  • Тялото на заявката е конфигурационният JSON на бота (без обвивка data)
  • Файловете (аватар / лого) могат да бъдат качени по-късно чрез втори PATCH, използвайки режим B

Режим B - multipart/form-data (използвайте при качване на файлове в същата заявка):

  • Content-Type: multipart/form-data; boundary=...
  • data JSON част (задължителна, Content-Type: application/json) - конфигурация на бота във вложената структура, описана по-горе
  • avatar файлова част (незадължителна) - изображение за аватар на бота
  • whitelabel_logo файлова част (незадължителна) - white-label лого (приложимо само ако акаунтът Ви включва White Label)

В JSON формата се изисква единствено name; всяко друго поле приема същата стойност по подразбиране, която би задал съветникът в администраторския панел.

Пълно тяло на заявката

Това е максималният data JSON - с попълнени всички секции. Изпращайте само секциите, които са Ви необходими; всичко останало приема стойности по подразбиране.

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

Правила за валидация със собствени съобщения за грешка:

  • name - задължително, максимум 150 знака
  • advanced.temperature - между 0.0 и 1.0
  • chatMemory.summariesToKnowledgeRatio - цяло число между 10 и 90 (процент, стъпка 10)
  • appearance.launcherBottomMargin, appearance.launcherSideMargin - между 0 и 500
  • appearance.footerMarkdown - максимум 255 знака
  • humanSupport.enabled=true изисква да бъде зададен humanSupport.email
  • leadCollection.enabled=true изисква поне едно от полетата leadCollection.emailEnabled или leadCollection.phoneEnabled да бъде true; съответният активен канал изисква също своя етикет, както и leaveDetailsMessage и thankYouMessage
  • Полетата с лимити (advanced.chatContextSize, advanced.botMessagesLimit и др.) автоматично се ограничават до лимитите на Вашия акаунт

Полетата, чиято стойност на сървъра е null, се пропускат от JSON тялото - мрежовият трафик пренася само полета със стойности, различни от null.

Пълно тяло на отговора (201)

Същата структура като на заявката, плюс блока само за четене meta и еднократния apiKey на най-горно ниво. URL адресите за четене на файлове (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) се попълват от сървъра, когато съответните multipart части са били качени.

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

Полето apiKey се появява само при създаване - това е току-що генерираният ключ за Bot Talk API, свързан с новия бот. Чистият текст се показва еднократно и не може да бъде извлечен по-късно през API; запазете го незабавно от Ваша страна.

Заглавната част Location в отговора съдържа URL адреса на новия бот (/v1/management/bots/{id}).

Примери с Curl

Режим A - чист JSON (най-прост):

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

Режим B - multipart с аватар:

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}

Връща текущата конфигурация на бот, който притежавате.

Пример с Curl

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

Пълно тяло на отговора (200)

Същата структура като отговора на POST, без еднократния apiKey. Блокът meta е включен. Връща 404 not_found_error, ако ботът не съществува или не принадлежи на Вашия акаунт.

Текущият аватар и white-label логото са представени като пълни URL адреси само за четене (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) - базирани на същата схема + хост + път на контекста, обслужили тази заявка. Извлечете съдържанието чрез директна GET заявка към тези URL адреси; за да замените който и да е от файловете, качете нов чрез multipart частта avatar / whitelabel_logo при PATCH. Тези URL полета се игнорират, ако бъдат изпратени в тялото на заявката.

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

Клониране на бот

Тялото на заявката при POST /v1/management/bots и тялото на отговора при GET /v1/management/bots/{bot_id} споделят една и съща структура, така че клонирането е процес в три стъпки: извличане чрез GET на изходния бот, премахване на управляваните от сървъра полета за идентификация и изпращане чрез POST на резултата.

1. Извлечете изходния бот чрез GET.

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

2. Премахнете блока meta от най-високо ниво. Обектът meta (id, createdAt, updatedAt) се управлява от сървъра и е само за четене - оставянето му в тялото на POST заявката не пречи (сървърът го игнорира), но премахването му прави намерението ясно и поддържа данните изчистени. По избор редактирайте name, така че клонингът да се различава от оригинала.

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

3. Изпратете изчистеното тяло чрез POST, за да създадете клонинга. Вижте справочника за POST /v1/management/bots по-горе за пълната структура на тялото и правилата за валидация.

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

Отговорът съдържа meta.id на новия бот плюс новосъздаден apiKey (ключът за Bot Talk API за клонинга). Текстовата стойност на apiKey се връща само в този отговор при създаване - копирайте я, преди да затворите тялото на отговора; тя не може да бъде извлечена по-късно.

Две важни уточнения:

  • Файловете не се клонират. appearance.avatarUrl и whiteLabel.whitelabelLogoUrl са само за четене и сочат към файловете на изходния бот. Ако се нуждаете от същия аватар или White Label лого при клонинга, изтеглете байтовете от изходните URL адреси и ги качете като multipart части avatar / whitelabel_logo - или при създаващата POST заявка (Режим B), или чрез последваща PATCH заявка.
  • Ключовете за Bot Talk API не се клонират. Всеки бот разполага със собствен набор от ключове за Bot Talk API. Единственият apiKey, върнат от създаващата POST заявка, е единственият, генериран автоматично; създайте допълнителни ключове от таба API на бота, ако е необходимо.

PATCH /v1/management/bots/{bot_id}

Актуализирайте едно или повече полета на бот, който притежавате. Променят се само секциите / полетата, присъстващи в JSON обекта; всичко пропуснато (или изпратено като null) остава непроменено. Прилага се семантика за частична актуализация за всяко поле в изпратената секция.

Приемат се два еквивалентни Content-Type типа (същите като при POST):

Режим A - чист JSON (препоръчва се, когато актуализирате само настройки):

  • Content-Type: application/json
  • Тялото на заявката е JSON съдържанието на кръпката (без обвивка data)

Режим B - multipart/form-data (използва се при качване на файлове):

  • JSON част data (по избор) - съдържанието на актуализацията. Изпратете само ако искате да промените полета. Пропуснете изцяло, ако искате само да качите аватар или лого.
  • файлова част avatar (по избор) - замяна на аватара
  • файлова част whitelabel_logo (по избор) - замяна на логото за White Label (прилага се само ако Вашият акаунт включва опцията White Label)

И трите части са по избор при PATCH, но поне една трябва да присъства, за да има смисъл извикването.

Пълно тяло на заявката (максимален обхват)

Всяко поле, прието от POST /v1/management/bots, може да бъде изпратено и тук. Примерът по-долу показва пълния обхват; на практика изпращате само ключовете, които искате да промените (вижте "Минимална частична актуализация" по-долу) - всеки пропуснат ключ (или изпратен като null) оставя запазената стойност недокосната.

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

Минимална частична актуализация

Приложете PATCH само за едно поле, като изпратите точно ключовете, които искате да промените - всичко останало се запазва.

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

Примери с Curl

Режим A - чист JSON (най-простият вариант):

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

Режим B - multipart (при замяна на аватар / лого):

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'

Режим B - замяна само на аватара (без промени по полетата):

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

Тяло на отговора (200)

Същата структура като при GET /v1/management/bots/{bot_id} - пълната конфигурация на бота след прилагането на кръпката, включително блока meta. Без поле apiKey. Връща 404 not_found_error, ако ботът не съществува или не принадлежи на Вашия акаунт.

Примерът по-долу показва отговора след прилагане на актуализацията от Пълно тяло на заявката (максимален обхват) по-горе върху бота от примера за GET - променените полета отразяват новите стойности, непроменените полета са запазени, а meta.updatedAt се актуализира.

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

Прегледайте текущото потребление на абонамента за акаунта, който притежава ключа за Management API.

Тяло на отговора (200)

{
  "subscriptionType": "standard",
  "messages": {"used": 4123, "limit": 11000, "remaining": 6877},
  "bots": {"used": 3, "limit": 5, "remaining": 2}
}
  • subscriptionType е изписан с малки букви идентификатор на текущия план на акаунта (напр. standard в примера). Плановете идват от динамичен каталог, така че точният набор от идентификатори може да се променя с течение на времето при преименуване или добавяне на планове - третирайте това като непрозрачен низ, а не като фиксирано изброяване.
  • messages.used / limit / remaining представляват кредитите за съобщения за текущия отчетен период.
  • bots.used / limit / remaining отчитат броя на активните ботове спрямо лимита за ботове на Вашия акаунт.

Заглавки за лимит на заявките (Rate limit headers)

Отговорите, които достигат до етапа на ограничаване на честотата на заявките (т.е. автентикацията и списъкът с разрешени IP адреси са преминали успешно), включват:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1715430000
  • X-RateLimit-Limit - лимитът за конкретния ключ, реално приложен към това извикване (по подразбиране 10, или конфигурираната от Вас стойност за rateLimitPerMinute, ако е по-ниска).
  • X-RateLimit-Remaining - оставащи токени в пула непосредствено след това извикване.
  • X-RateLimit-Reset - секунди по Unix епоха, в които следващият токен става наличен (не цялостно нулиране на пула; пулът се запълва непрекъснато). Когато пулът е пълен, това показва текущото време.

При отговори 429 rate_limit_exceeded се задава и заглавката Retry-After, изразена в цели секунди до освобождаването на поне един токен.

Грешките преди автентикация (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) и 403 ip_not_whitelisted не съдържат заглавките X-RateLimit-* - ограничителят се проверява само след успешна автентикация и проверка на IP адреса.

Формат на грешките

Същата структура (envelope) като при Bot Talk API:

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

Грешките при валидация използват code: "invalid_parameter" и добавят пътя на проблемното поле в началото на съобщението, за да бъде проблемната секция лесна за откриване:

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

Невалидните стойности за изброими полета (enum / closed-set, напр. chatMemory.clientSummaryPromptType = "BOGUS") включват пътя на полето, отхвърлената стойност и списъка с позволени стойности:

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

Свързани теми

За крайни точки за разговори и SSE поточно предаване вижте Bot Talk API.

Търсене във всички статииПопитайте асистента