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 (Създаване на ключ за Management), въведете име, по желание задайте списък с разрешени IP адреси (IP whitelist) и лимит на заявките (rate limit), след което потвърдете.
3. Изберете само правата, от които Вашата интеграция се нуждае, и копирайте пълния ключ от прозореца за успех. Неговият чист текст се показва само веднъж.
4. Съхранявайте го на Вашия сървър, а не в браузърен код или в публично хранилище. Направете заявка само за четене, като например GET /v1/usage с право usage, за да потвърдите достъпа.
5. Анулирайте неизползваните или компрометирани ключове от страницата Management API.

Ключът изглежда така: 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 - персонализирана роля на бота, суров prompt, дължина на отговора, език, контекст за уебсайт / компания (раздел Role & Behavior)
• conversation - съобщение за добре дошли, прецизиране на заявките, непрекъснатост на разговора, превключвател за оценяване + подсказки (tooltips), съдържание за предложени въпроси + динамични последващи въпроси (раздел 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 - гласово въвеждане и гласови разговори: модел, глас, езици, prompt, лимит за продължителност (раздел Voice Conversation)
• multilingual - многоезичен режим, базов език, предлагани езици, управление на езика на базата знания (раздел Languages)
• advanced - LLM модел, температура, размер на контекста, лимит на съобщенията от бота, вътрешен локал, Offer Cards (раздел Model & Advanced)

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

Страничната лента Настройки на бота (Bot Settings) в момента има 16 подраздела, като 13 от тях съответстват на разделите по-горе. Трите подраздела без съответстващ раздел са Flow, Actions и Forms - и трите са разгледани в раздел „Извън обхвата на API“ по-долу. 13-те, които съответстват, са 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 адрес на whitelabel логото в хедъра. Същият модел като при avatarUrl. За да го промените, качете нов файл чрез multipart частта whitelabel_logo (вижте PATCH).

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

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

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

Системният prompt, който 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 (prompt, предоставен от извикващия)

Бекендът използва role.rawPrompt като prompt за ролята и добавя фиксираните насоки на платформата за дължината на отговора. Това е отделно от role.responseLength: незадължителната настройка Concise/Normal/Detailed не се вмъква при роля CUSTOM. По същия начин, language, websiteAddress и companyDescription се съхраняват, но не се вмъкват в този prompt за роля. Включете желания език, целева дължина на отговора или фирмен контекст директно в rawPrompt. Могат да бъдат подадени и допълнителни инструкции по време на изпълнение, както и извлечен контекст, така че rawPrompt не представлява целия входящ текст за модела. Инструкциите за тона на предварително дефинираната роля не се добавят, но изборът на CUSTOM не премахва всички системни инструкции на платформата.

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

Изброими / затворени полета (Enum)

Изброимите и ограничените полета отхвърлят невалидни стойности с 400 invalid_parameter. Другите полета са обикновени низове, дори когато потребителският интерфейс предлага фиксиран списък. Използвайте документираното изписване и валидирайте Вашите данни, вместо да предполагате, че всеки неподдържан низ ще бъде отхвърлен.

• 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 други. Стойността се съхранява дословно и се замества в шаблона за prompt, така че двубуквените ISO кодове (en, pl) и други стойности извън списъка не се отхвърлят от API, но генерират неразбираема инструкция от рода на „Output in en, unless...“. По подразбиране е Auto Detect, ако бъде пропуснато при създаване.
• advanced.model - вижте „AI текстови модели“ по-долу. Това е низ, а не валидиран enum в схемата на заявката; използвайте поддържана стойност, а не произволно име на модел.
• advanced.chatContextSize - използвайте 8000, 16000 или 32000, съответстващи на потребителския интерфейс. Стойности над максимума на акаунта се ограничават автоматично; DTO не налага този набор от три стойности.
• chatMemory.clientSummaryPromptType - DEFAULT, CUSTOM
• chatMemory.conversationSummaryPromptType - DEFAULT, CUSTOM
• appearance.chatAlignment - left, right
• appearance.minimizedDisplayMode - icon, minified, pill
• appearance.chatMessageLinkTarget - _blank, _self
• leadCollection.requireBeforeNewConversation - булев превключвател. true задължава потребителя да попълни формуляра за лийдове, преди да започне разговор; false позволява на изкуствения интелект сам да прецени кога да покаже формуляра (по подразбиране).

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

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

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

• chatMemory.summariesToKnowledgeRatio - целочислен процент, 10-90; интерфейсът използва стъпки от 10, но API приема цели числа в целия диапазон. По подразбиране е 50. При активирана памет и контекст, по-голям от 8k, то разделя бюджета за знания и памет след заделеното пространство за промпта и скорошния разговор, а не целия контекст на модела. При 8k чрез тази настройка не се заделя бюджет за обобщения.

• 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 - кратки текстове, показвани до контролите за оценяване на разговора с 👍 / 👎, когато 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, за да деактивирате това ограничение на база сесия. Когато го активирате, посочете положителна продължителност. Бекендът прилага N съобщения на сесия за период от време в секунди, преди да покаже security.talkMessagesRateLimitHitMessage на посетителя.

• advanced.botMessagesLimit - цяло число (JSON число, напр. 1000). 0 означава, че няма допълнителен лимит за конкретния бот, докато лимитът на кредитите за акаунта все още е в сила; в противен случай стойността трябва да бъде кратна на 1000 (1000, 2000, 10000, ...). Стойности като 100 или 1500 се отхвърлят с 400 invalid_parameter. Това представлява месечен лимит на кредитите за бота, а не брой съобщения за един разговор. Преобразувателят (mapper) не ограничава тази стойност спрямо бюджета на акаунта; общият бюджет на акаунта продължава да ограничава реалното потребление.

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

Използвайте точния идентификатор на модела, върнат в advanced.model, когато извличате бот, конфигуриран с желания от Вас модел в Settings > Model & Advanced (Настройки > Модел и разширени). Текущата стойност по подразбиране при създаване е 5.6-LUNA. Идентификаторите са чувствителни към регистъра на буквите и се различават от екранните имена; например 5.6-LUNA се визуализира като GPT 5.6-luna.

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

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

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

Главно ниво

Поле	Тип	Ограничение	Описание
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 API за новия бот, връщан точно веднъж.

§ role

Поле	Тип	Ограничение	Описание
role	string (enum)	CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM	Предварително зададена персона; избира шаблона на системните инструкции (вижте "Изграждане на ролята и промпта")
language	string	пълно английско име на езика (English, Polish, ...) или Auto Detect	Основен език, подаван в шаблона на системните инструкции
responseLength	string	∈ {Concise, Normal, Detailed}	Желано ниво на подробност на отговорите от изкуствения интелект
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, изкуственият интелект предлага последващи въпроси след всеки отговор
positiveRatingMessage	string		Съобщение, показвано след положителна обратна връзка
negativeRatingMessage	string		Съобщение, показвано след отрицателна обратна връзка
hideSuggestedQuestionsAfterFirstUse	boolean		Скриване на статичните предложения след употреба
dynamicFollowupsAutoIcons	boolean		Ако е true, изкуственият интелект избира автоматично емоджи икони за динамичните последващи въпроси

§ chatMemory

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

§ appearance

Поле	Тип	Ограничение	Описание
launcherLabelLine1	string	макс. 60	Първи ред на текста в бутона за отваряне (launcher)
launcherLabelLine2	string	макс. 60	Втори ред на текста в бутона за отваряне (launcher)
launcherTextColor	string		Цвят на текста в бутона за отваряне
launcherDismissEnabled	boolean		Позволяване на затварянето на бутона за отваряне
widgetFontFamily	string	inter, system, nunito, lato, montserrat, poppins, source-serif, jetbrains-mono	Семейство шрифтове на уиджета
chatDrawerEnabled	boolean		Активиране на страничен панел (drawer презентация)
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		Текст при задържане (tooltip) върху бутона за нулиране на разговора
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, pill}	Минимизирано състояние: икона за отваряне, компактна лента за изпращане или бутон тип хапче
chatDesktopWidthPx	int		Ширина на уиджета на настолни устройства
chatDesktopHeightPx	int		Височина на уиджета на настолни устройства
chatMobileSizePercent	int		Размер на уиджета на мобилни устройства като % от екрана
messageFontSize	int		Размер на шрифта на текста на съобщенията (px)
showChatbotBubblesDesktop	boolean		Показване на плаващи приканващи балончета на настолни устройства
showChatbotBubblesMobile	boolean		Показване на плаващи приканващи балончета на мобилни устройства
chatbotBubblesDelaySeconds	int		Забавяне преди появата на приканващите балончета (секунди)
launcherIconFullSize	boolean		Изобразяване на персонализираната икона за отваряне от край до край (без отстъп)
welcomeScreenEnabled	boolean		Показване на начален екран (Welcome Screen) вместо директно преминаване към чата
welcomeScreenQuestionsLabel	string		Етикет над предложените въпроси на началния екран
welcomeScreenHideHumanContactForm	boolean		Скриване на действието за форма за контакт в заглавната лента, докато се показва началният екран. Появява се отново след първото съобщение на посетителя. За ботове, създадени преди 2026-09-02, стойността по подразбиране е true
welcomeScreenHideLiveChat	boolean		Скриване на действието за чат на живо в заглавната лента, докато се показва началният екран. Появява се отново след първото съобщение на посетителя. За ботове, създадени преди 2026-09-02, стойността по подразбиране е true
headerActionsLayout	string	ICONS или DROPDOWN	Как се предлагат чатът на живо и формата за контакт в заглавната лента на чата: ICONS (отделна икона за всяко) или DROPDOWN (групирани в менюто на заглавната лента). За ботове, създадени преди 2026-09-02, стойността по подразбиране е 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 текст в долния колонтитул под чата
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 на съществуващ персонализиран формуляр	Замяна на вградения формуляр за контакт с персонализиран формуляр. При създаване, ако се пропусне, се използва вграденият формуляр; при PATCH, 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, изкуственият интелект решава кога да го покаже
emailNotificationEnabled	boolean		Изпращане на имейл до собственика при всеки събран лийд
emailNotificationAddress	string		Получател на известията (по подразбиране е имейлът на акаунта)
emailWithConversationContent	boolean		Ако е true, включва преписа на разговора в известието

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

Правило от тип create-strict между полетата: enabled=true изисква поне едно от emailEnabled или phoneEnabled. requirePolicyAccept се намира в consent.leadCollectionRequirePolicyAccept, а не тук.

§ liveChat

Поле	Тип	Ограничение	Описание
enabled	boolean		Превключвател за функцията Live Chat
infoMessage	string		Разяснително съобщение преди прехвърляне към оператор
startMessage	string		Съобщение, показвано при започване на сесията на живо
endMessage	string		Съобщение, показвано при приключване на сесията на живо
nameLabel	string		Етикет на полето за име в предварителния формуляр за Live Chat
emailLabel	string		Етикет на полето за имейл в предварителния формуляр за Live Chat
schedule	string	JSON-кодиран низ (превключватели за дни от седмицата + from/to + timezone)	Работен график за Live Chat - вижте "Структурирани полета и диапазони" за точната структура
outOfHoursMessage	string		Съобщение, показвано когато според графика не сте на линия
closeModalMessage	string		Заглавие на модалния прозорец "close live chat?" (затваряне на чата на живо)
closeModalConfirmLabel	string		Етикет на бутона за потвърждение в модалния прозорец за затваряне
closeModalCancelLabel	string		Етикет на бутона за отказ в модалния прозорец за затваряне
closeModalTooltipText	string		Текст при задържане върху бутона за затваряне на чата
operatorHasJoinedLabel	string		Текст, показван при присъединяване на оператор
operatorDidNotJoinInTimeLabel	string		Текст, показван когато никой оператор не се присъедини в рамките на времето за изчакване
waitingForOperatorToJoinLabel	string		Текст, показван по време на изчакване на оператор
waitingForOperatorSeconds	int		Време за изчакване оператор да поеме чата (секунди)
redirectToHumanSupportForm	boolean		Ако е true, пренасочва към формуляра за Human Support, когато никой оператор не поеме чата
requireAdminOnline	boolean		Изискване за наличен оператор съгласно настройките за присъствие
presenceMode	string		Режим на присъствие; използвайте стойността от бот, конфигуриран през потребителския интерфейс
hideHumanSupportWhenLiveChatAvailable	boolean		Скриване на формата за контакт, когато е наличен чат на живо
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 по подразбиране в долния колонтитул
whitelabelLogoLink	string	функционалност White Label; зависи от лимитите на акаунта	URL адрес, към който води персонализираното лого в долния колонтитул
assignToCustomDomain	boolean	ограничено от функцията CUSTOM_DOMAIN	Хостване на чата на конфигурирания персонализиран домейн
whitelabelLogoUrl	string	само за четене	Пълен публичен URL адрес на логото за White Label; за промяна качете файл чрез 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	специфичен за доставчика voice id (напр. alloy)	Кой синтетичен глас говори
model	string	напр. GPT-REALTIME-MINI, GEMINI-LIVE, ELEVENLABS-*	Гласов модел. Таксува се на минута, цените се различават според модела
turnDetection	string	специфично за доставчика	Режим на редуване на репликите (turn-taking)
audioPrompt	string		Допълнителни системни инструкции, използвани само при гласовите реплики
welcomeMessage	string		Изговорена начална фраза
language	string	езиков код	Основен гласов език
additionalLanguages	string	езикови кодове, разделени със запетая	Допълнителни езици, които гласовият агент приема
maxDurationSeconds	int		Твърд лимит за продължителност на единичен гласов разговор
maxDurationMessage	string		Съобщение, показвано при достигане на лимита

§ multilingual

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

§ advanced

Поле	Тип	Ограничение	Описание
model	string	предмет на лимитите на акаунта; вижте "AI текстови модели" по-горе	Идентификатор на големия езиков модел (напр. 5.6-LUNA)
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 - управлявани интеграции за e-commerce / резервации, AI Search и персонализирани API функции. Извикването на външни инструменти (tool calling) никога не е било част от Management API.
• Същинският конструктор на персонализирани формуляри - създаването и редактирането на персонализирани формуляри не е достъпно. Можете обаче да прикачите съществуващ формуляр към бот чрез leadCollection.customFormId и humanSupport.customFormId.
• Персонализирани икони за отваряне / затваряне на чата - customLauncherIconVisible, openChatIcon, closeChatIcon. API предоставя достъп само до основните multipart части avatar и whitelabel_logo.
• Списъци с IP адреси и държави - самите записи са достъпни само за администратори. Достъпен е единствено режимът на тълкуване чрез security.countryFilterMode.

Ендпойнти

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.6-LUNA",
    "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 се ограничава до максималния размер на контекста, поддържан от акаунта. Не приемайте, че останалите числови полета се ограничават автоматично.

Полетата, чиято стойност на сървъра е 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.6-LUNA",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  },
  "meta": {
    "id": 4287,
    "createdAt": "2026-06-01T10:11:02Z",
    "updatedAt": "2026-06-01T10:11:02Z"
  },
  "apiKey": "ck_freshly_minted_bot_talk_key_here"
}

Полето 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.6-LUNA",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  },
  "meta": {
    "id": 4287,
    "createdAt": "2026-06-01T10:11:02Z",
    "updatedAt": "2026-06-01T11:02:19Z"
  }
}

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

Тялото на заявката на 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 за клонинга). Текстът на apiKey се връща само при този отговор за създаване - копирайте го, преди да затворите тялото на отговора; той не може да бъде извлечен по-късно.

Това копира поддържаните настройки, а не напълно обучен чатбот. Съдържанието за обучение, историята на разговорите, интеграциите/действията, Flow и дефинициите на формуляри не се клонират от тези крайни точки. Конфигурирайте ги отделно в приложението.

Допълнителни предупреждения:

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

PATCH /v1/management/bots/{bot_id}

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

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

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

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

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

• JSON част data (незадължителна) - patch заявката. Изпращайте само ако искате да промените полета. Пропуснете изцяло, ако искате само да качите аватар или лого.
• Файлова част 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, ако ботът не съществува или не принадлежи на Вашия акаунт.

Примерът по-долу показва отговора след прилагане на корекцията от Full request body (multiple sections) (Пълно тяло на заявката с множество секции) по-горе към бота от примера за 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 ключа.

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

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

• subscriptionType е идентификатор с малки букви на текущия план на акаунта (your-plan-id е примерна заместваща стойност). Плановете идват от динамичен каталог, така че точният набор от идентификатори може да се променя с времето при преименуване или добавяне на планове - третирайте това като непрозрачен низ, а не като фиксирано изброяване (enum).
• 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.