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 прив'язані до вашого акаунта, а не до конкретного бота. Вони навмисно відокремлені від ключів Bot Talk, щоб у разі компрометації ключа чату зловмисники не могли змінювати ваших ботів або переглядати платіжні дані.

Базовий URL

https://api.chatlab.com/aichat

Усі кінцеві точки в цій статті наведено відносно цього базового URL.

Початок роботи

1. Відкрийте панель керування та перейдіть у Account Settings > Management API (Налаштування акаунта > Management API).
2. Натисніть Create Management Key (Створити ключ Management), укажіть його назву, за потреби налаштуйте білий список IP-адрес і ліміт запитів, після чого підтвердьте дію.
3. Виберіть лише ті дозволи, які потрібні вашій інтеграції, і скопіюйте повний ключ із модального вікна успішного створення. Відкритий текст показується лише один раз.
4. Збережіть його на своєму сервері, а не в коді браузера чи публічному репозиторії. Зробіть запит лише для читання, як-от GET /v1/usage із дозволом usage, щоб перевірити доступ.
5. Відкликайте невикористовувані або скомпрометовані ключі на сторінці Management API.

Ключ має вигляд mk_abcdefghijklmnopqrstuvwxyz012345. Префікс mk_ відрізняє його від ключів Bot Talk (ck_).

Автентифікація

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, і максимальне обмеження знизиться, а швидкість поповнення пропорційно зміниться.

Дозволи

Кожен ключ Management містить довільний набір із трьох наведених нижче дозволів. Принаймні один із них потрібно вибрати під час створення, інакше запит буде відхилено з помилкою 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 (вкладка Live Chat)
• consent - усі чотири перемикачі згоди з політикою конфіденційності плюс текст екрана згоди (вкладка Consent & Privacy)
• whiteLabel - приховування логотипа, посилання власного логотипа, хостинг на власному домені (вкладка Whitelabel)
• security - дозволені домени, спам-фільтр, ліміти частоти розмов (вкладка Security)
• voice - голосове введення та голосові розмови: модель, голос, мови, промпт, обмеження тривалості (вкладка 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 - лише для читання: ідентифікатор бота та позначки часу. Видаліть цей блок, щоб перетворити відповідь GET на коректне тіло для POST.
• apiKey - присутній лише під час створення - щойно згенерований ключ Bot Talk API для нового бота.

Два поля у спільній структурі доступні лише для читання: вони повертаються у відповіді, але ігноруються, якщо ви спробуєте передати їх у POST/PATCH:

• appearance.avatarUrl - повний публічний URL зображення аватара бота (наприклад, https://api.chatlab.com/aichat/content/avatar_xyz.png). Виконайте прямий запит GET, щоб завантажити його байти. Щоб змінити аватар, завантажте новий файл через частину avatar у запиті multipart (див. PATCH).
• whiteLabel.whitelabelLogoUrl - повний публічний URL логотипа верхнього колонтитула White Label. Схожий принцип, як і для avatarUrl. Щоб змінити його, завантажте новий файл через частину whitelabel_logo у запиті multipart (див. 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 як промпт ролі та додає фіксовані системні рекомендації щодо довжини відповіді. Це не залежить від параметра role.responseLength: необов'язкове налаштування Concise/Normal/Detailed для ролі CUSTOM не підставляється. Так само параметри language, websiteAddress і companyDescription зберігаються, але не додаються до цього промпту ролі. Указуйте бажану мову, цільову довжину відповіді чи контекст компанії безпосередньо в rawPrompt. Додаткові інструкції під час виконання та отриманий контекст також можуть передаватися, тому rawPrompt не є єдиним вхідним текстом для моделі. Інструкції щодо тону попередньо визначеної ролі не додаються, проте вибір значення CUSTOM не видаляє абсолютно всі системні інструкції платформи.

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

Поля enum та поля з фіксованим набором значень

Поля типу 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 інших. Значення зберігається дослівно та підставляється в шаблон промпту, тому дволітерні коди 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. Це щомісячне обмеження кредитів для бота, а не кількість повідомлень у межах однієї розмови. Обробник не обмежує це значення рамками балансу акаунта; фактичне використання все одно регулюється лімітом акаунта.

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

Використовуйте точний ідентифікатор моделі, який повертається в advanced.model під час читання конфігурації бота, налаштованого з потрібною моделлю в розділі Settings > Model & Advanced (Налаштування > Модель і додаткові параметри). Наразі типовим значенням під час створення є 5.6-LUNA. Ідентифікатори чутливі до регістру та відрізняються від відображуваних назв; наприклад, ідентифікатор 5.6-LUNA відображається в інтерфейсі як GPT 5.6-luna.

Каталог моделей із часом змінюється. Не вважайте, що будь-який довільний рядок або публічний ідентифікатор моделі від провайдера підтримується лише тому, що схема запиту приймає рядковий тип даних. Зчитуйте збережену конфігурацію та тестуйте створеного чатбота перед його запуском.

Довідник полів (повна схема запиту)

Підтримувані розділи та поля з їхніми типами й важливими обмеженнями. Семантика 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 для нового бота, повертається рівно один раз.

§ role

Поле	Тип	Обмеження	Опис
role	string (enum)	CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM	Шаблон ролі; вибирає шаблон промпту (див. "Role and prompt construction")
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		Підказка на кнопці позитивної оцінки
negativeRatingTooltip	string		Підказка на кнопці негативної оцінки
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	Перший рядок тексту лаунчера
launcherLabelLine2	string	макс. 60	Другий рядок тексту лаунчера
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		Текст-підказка в полі введення повідомлення
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, 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		Приховувати кнопку форми зв'язку з оператором у шапці, поки відображається Welcome Screen. Вона знову з'явиться після першого повідомлення відвідувача. Для ботів, створених до 2026-09-02, типовим значенням є true
welcomeScreenHideLiveChat	boolean		Приховувати кнопку Live Chat у шапці, поки відображається Welcome Screen. Вона знову з'явиться після першого повідомлення відвідувача. Для ботів, створених до 2026-09-02, типовим значенням є true
headerActionsLayout	string	ICONS або DROPDOWN	Спосіб відображення Live Chat і форми зв'язку з людиною в шапці чату: 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	обов'язкове (суворе створення), якщо enabled=true	Адреса, яка отримує електронні листи підтримки
dialogMessage	string		Заохочувальне повідомлення над формою
thankYouMessage	string		Підтвердження, яке показується після надсилання
emailMessageSubjectTemplate	string		Шаблон теми електронного листа, що надсилається агенту
emailMessageContentTemplate	string		Шаблон тексту електронного листа, що надсилається агенту
emailPlaceholder	string		Текст-підказка в полі введення електронної пошти
messagePlaceholder	string		Текст-підказка в полі введення повідомлення
emailWithConversationContent	boolean		Якщо true, додавати розшифровку розмови до тексту листа
customFormId	long	ідентифікатор наявної власної форми	Замінити вбудовану контактну форму власною. Під час створення пропуск поля активує вбудовану форму; у запиті PATCH значення null зберігає поточний вибір
customFormMapping	string	рядок у форматі JSON	Зіставляє поля власної форми з полями електронного листа підтримки

Поле requirePolicyAccept розташоване в consent.humanSupportRequirePolicyAccept, а не тут.

§ leadCollection

Поле	Тип	Обмеження	Опис
enabled	boolean		Перемикач форми збору лідів
nameEnabled	boolean		Збирати ім'я
nameLabel	string		Підпис поля імені
emailEnabled	boolean		Збирати адресу електронної пошти
emailLabel	string	обов'язкове (суворе створення), якщо enabled=true ТА emailEnabled=true	Підпис поля електронної пошти
phoneEnabled	boolean		Збирати номер телефону
phoneLabel	string	обов'язкове (суворе створення), якщо enabled=true ТА phoneEnabled=true	Підпис поля номера телефону
leaveDetailsMessage	string	обов'язкове (суворе створення), якщо enabled=true	Повідомлення із пропозицією залишити контактні дані
thankYouMessage	string	обов'язкове (суворе створення), якщо enabled=true	Підтвердження, яке показується після надсилання
requireBeforeNewConversation	boolean		Якщо true, форму потрібно заповнити до початку чату; якщо false, ШІ сам вирішує, коли показувати форму
emailNotificationEnabled	boolean		Надсилати електронного листа власнику щоразу під час отримання ліда
emailNotificationAddress	string		Отримувач сповіщень (за замовчуванням адреса облікового запису)
emailWithConversationContent	boolean		Якщо true, додавати розшифровку розмови до сповіщення

| customFormId | long | ідентифікатор наявної власної форми | Замінити вбудовану лід-форму власною формою. Під час створення пропуск поля активує вбудовану форму; у запиті PATCH значення null зберігає поточний вибір | | customFormMapping | string | рядок у форматі JSON | Зіставляє поля власної форми з полями імені / пошти / телефону |

Міжпольове правило суворого створення: якщо enabled=true, потрібно ввімкнути хоча б одне з полів: emailEnabled або phoneEnabled. Поле requirePolicyAccept розташоване в consent.leadCollectionRequirePolicyAccept, а не тут.

§ liveChat

Поле	Тип	Обмеження	Опис
enabled	boolean		Перемикач функції Live Chat
infoMessage	string		Пояснювальне повідомлення перед перемиканням на оператора
startMessage	string		Повідомлення на початку сеансу з оператором
endMessage	string		Повідомлення наприкінці сеансу з оператором
nameLabel	string		Підпис поля імені в попередній формі чату наживо
emailLabel	string		Підпис поля пошти в попередній формі чату наживо
schedule	string	рядок у форматі JSON (перемикачі днів тижня + from/to + timezone)	Графік роботи Live Chat - точну структуру див. у розділі "Structured fields and ranges"
outOfHoursMessage	string		Повідомлення, яке показується в неробочий час згідно з графіком
closeModalMessage	string		Заголовок модального вікна "закрити чат наживо?"
closeModalConfirmLabel	string		Текст кнопки підтвердження в модальному вікні закриття
closeModalCancelLabel	string		Текст кнопки скасування в модальному вікні закриття
closeModalTooltipText	string		Підказка для кнопки закриття чату
operatorHasJoinedLabel	string		Повідомлення про підключення оператора
operatorDidNotJoinInTimeLabel	string		Повідомлення, якщо оператор не приєднався вчасно
waitingForOperatorToJoinLabel	string		Повідомлення під час очікування оператора
waitingForOperatorSeconds	int		Час очікування на відповідь оператора (секунди)
redirectToHumanSupportForm	boolean		Якщо true, перенаправляти на форму підтримки людиною, коли оператор не відповідає
requireAdminOnline	boolean		Вимагати присутності оператора в мережі відповідно до налаштувань статусу
presenceMode	string		Режим присутності; використовуйте значення бота, налаштованого через інтерфейс
hideHumanSupportWhenLiveChatAvailable	boolean		Приховувати контактну форму, коли доступний Live Chat
missedEmailEnabled	boolean	типово true	Сповіщати власника бота електронною поштою про пропущений запит Live Chat. Не встановлено для застарілих ботів, що трактується як увімкнено

Поле 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	ідентифікатор голосу постачальника (наприклад, 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 або FIXED_LIST	Як бот визначає мову відповіді
baseLanguage	string	код мови	Мова, якою складено власний текст бота
languages	string	коди мов через кому	Мови, які пропонуються відвідувачу
knowledgeLanguageMode	string	NONE, MAIN або DYNAMIC	Як обробляються знання іншими мовами
knowledgeLanguageFallback	string	код мови	Мова за замовчуванням, якщо збігів не знайдено

§ advanced

Поле	Тип	Обмеження	Опис
model	string	регулюється лімітами облікового запису; див. "AI text models" вище	Ідентифікатор LLM (наприклад, 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 для e-commerce всередині чату
includeProductsInKnowledgeBase	boolean		Якщо true, індексувати каталог товарів як частину бази знань

Поза межами API

Панель керування містить кілька розділів, які навмисно не представлені в цій версії Management API:

• Навчання та видалення - ці кінцеві точки не призначені для перегляду списку всіх ботів, керування наборами даних для навчання чи видалення ботів. Для цих завдань використовуйте застосунок.
• Вкладка Flow (Сценарій) - візуальний редактор сценаріїв розмови Flow Editor (стадії та переходи). Недоступний через Management API.
• Вкладка Actions (Дії) - керовані інтеграції для e-commerce / бронювання, AI Search та власні функції API. Виклик інструментів ніколи не був частиною Management API.
• Конструктор власних форм - створення та редагування власних форм через API недоступне. Проте ви можете прикріпити наявну форму до бота за допомогою leadCollection.customFormId та humanSupport.customFormId.
• Власні іконки відкриття / закриття чату - customLauncherIconVisible, openChatIcon, closeChatIcon. API надає доступ лише до основних multipart-частин avatar та whitelabel_logo.
• Списки IP-адрес і країн - самі записи доступні лише адміністратору. Через 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=...
• JSON-частина data (обов'язкова, Content-Type: application/json) - конфігурація бота у вкладеному форматі, описаному вище
• Файлова частина avatar (необов'язкова) - зображення аватара бота
• Файлова частина whitelabel_logo (необов'язкова) - логотип White Label (застосовується, лише якщо ваш акаунт включає White Label)

У JSON обов'язковим є лише поле name; усі інші поля повертаються до тих самих значень за замовчуванням, які встановив би майстер в інтерфейсі адміністратора.

Приклад тіла запиту

Це максимальний JSON data - із заповненням усіх розділів. Надсилайте лише ті розділи, які вам потрібні; усе інше отримає значення за замовчуванням.

{
  "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 - через мережу передаються лише поля з ненульовими значеннями.

Приклад тіла відповіді (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) - із коренем за тією самою схемою + хостом + контекстним шляхом, які обслуговували цей запит. Отримуйте байти безпосередньо за цими URL за допомогою GET-запиту; щоб замінити будь-який із цих файлів, завантажте новий через 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-об'єктом змін (без обгортки 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.

Тіло відповіді (200)

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

• subscriptionType - це ідентифікатор поточного тарифного плану облікового запису, записаний малими літерами (your-plan-id наведено для прикладу). Плани підтягуються з динамічного каталогу, тому точний набір ідентифікаторів може змінюватися з часом у разі перейменування або додавання планів - сприймайте це значення як непрозорий рядок (opaque string), а не як фіксований enum.
• messages.used / limit / remaining - це кредити повідомлень на поточний календарний місяць, які скидаються першого числа місяця, а не в день поновлення підписки. Вони зважені за системою кредитів, а не є простим підрахунком кількості відповідей.
• bots.used / limit / remaining підраховують наявних ботів, включно з призупиненими, з урахуванням загального ліміту ботів для вашого облікового запису.

Заголовки rate limit

Відповіді, які доходять до етапу перевірки лімітів швидкості (тобто аутентифікація та білий список 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 epoch, коли стане доступним наступний токен (це не повне скидання кошика; кошик поповнюється безперервно). Коли кошик повний, це поточний час.

У відповідях 429 rate_limit_exceeded також встановлюється заголовок Retry-After, виражений у цілих секундах, доки не звільниться принаймні один токен.

Помилки до аутентифікації (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) і 403 ip_not_whitelisted не містять заголовків X-RateLimit-* - перевірка лімітів виконується лише після успішної аутентифікації та перевірки IP.

Формат помилок

Така ж оболонка, як і в 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"
  }
}

Некоректні значення для перелічуваних типів або полів із фіксованим набором значень (наприклад, 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.