Центр допомоги
Chat API

Management API

Останнє оновлення:

Огляд Management API

Management API призначений для внутрішніх операцій бек-офісу, які не пов'язані з надсиланням повідомлень у чат:

  • створення бота програмним шляхом за допомогою POST /v1/management/bots
  • отримання даних конкретного вашого бота за допомогою GET /v1/management/bots/{bot_id}
  • оновлення конкретного бота за допомогою PATCH /v1/management/bots/{bot_id}
  • перегляд використання підписки за допомогою GET /v1/usage

Ключі керування прив'язані до вашого облікового запису, а не до конкретного бота. Вони навмисно відокремлені від ключів Bot Talk, щоб скомпрометований ключ чату не міг змінити ваших ботів або прочитати ваші платіжні дані.

Базова URL-адреса

https://api.chatlab.com/aichat

Усі кінцеві точки в цій статті наведені відносно цієї базової URL-адреси.

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

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

Ключ виглядає як 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 запитів на хвилину на ключ (алгоритм маркерного кошика: місткість 10, плавне поповнення приблизно на 1 маркер кожні 6 секунд). Ліміт можна зменшити під час створення: вкажіть менше значення rateLimitPerMinute, і максимальний ліміт знизиться разом зі швидкістю поповнення.

Дозволи

Кожен ключ керування містить будь-який піднабір із трьох наведених нижче дозволів. Під час створення необхідно вибрати щонайменше один із них; інакше запит буде відхилено з помилкою 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 наразі містить 15 вкладок, і 13 із них відповідають розділам вище. Дві вкладки, які не мають відповідного розділу, - це Flow та Actions (обидві описані нижче в розділі "Поза межами 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-запит за цією адресою, щоб завантажити байти. Щоб змінити його, завантажте новий файл через multipart-частину avatar (див. PATCH).
  • whiteLabel.whitelabelLogoUrl - повна публічна URL-адреса логотипа у заголовку для White Label. Працює так само, як avatarUrl. Щоб змінити його, завантажте новий файл через multipart-частину whitelabel_logo (див. PATCH).

Обидві URL-адреси використовують схему + хост + контекстний шлях поточного запиту, тому на кастомному домені White Label вони повертаються з прив'язкою до цього домену (наприклад, https://api.acme.com/aichat/content/...).

Передайте null для розділу, щоб пропустити його під час PATCH; передайте null для поля всередині розділу, щоб пропустити це окреме поле. Значення null на рівні поля ніколи не видаляє збережене значення - воно лише вказує "не змінювати".

Роль та формування промпту

Системний промпт, який фактично отримує LLM, формується одним із двох способів залежно від значення role.role. Розуміння поточної гілки допоможе з'ясувати, які поля мають значення, а які зберігаються, але ігноруються.

Гілка A - role.role має значення CUSTOMER_SUPPORT, SALES або LEAD_COLLECTION_AGENT (на основі шаблону)

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

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

Ця гілка рекомендована для більшості ботів: ви отримуєте оптимізовану під роль поведінку та готові правила безпеки без додаткових зусиль.

Гілка B - role.role має значення CUSTOM (промпт надається користувачем)

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

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

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

Деякі поля приймають лише фіксований набір рядкових значень. Передача будь-чого поза цим списком відхиляється з помилкою 400 validation_failed, а шлях до поля повертається в error.param. Значення чутливі до регістру.

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

Структуровані поля та діапазони значень

Поля, які виглядають як прості рядки або числа, але насправді мають специфічні формати, діапазони або нюанси в панелі адміністратора, про які варто знати.

  • advanced.temperature - допустимий діапазон від 0.0 до 1.0, що відповідає повзунку в панелі керування. Значення поза цим діапазоном відхиляються з помилкою 400 validation_failed.

  • chatMemory.summariesToKnowledgeRatio - ціле число у відсотках, від 10 до 90 з кроком 10. Визначає, яку частку контексту чату зарезервовано для підсумків історії клієнта порівняно з рештою даних (база знань, поточна розмова, інструкції). За замовчуванням 50. Значення поза діапазоном 10-90 відхиляються з помилкою 400 validation_failed. Застосовується, лише якщо chatMemory.enabled=true ТА chatMemory.summaryConversationsEnabled=true.

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

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

    Приклад значення (зверніть увагу на зовнішні лапки та екрановані внутрішні лапки - це єдине рядкове поле, а не вкладений об'єкт):

    "{\"monday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"tuesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"wednesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"thursday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"friday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"saturday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"sunday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"timezone\":\"Europe/Warsaw\"}"

    Поза зазначеними годинами відвідувачу показується повідомлення liveChat.outOfHoursMessage, а переведення діалогу на людину вимикається. Перевірка внутрішньої структури виконується лише на боці клієнта в панелі адміністратора: некоректний JSON або невідомі ключі приймаються API просто як рядок і спричинять помилку відображення, коли оператор пізніше відкриє бота в панелі керування. Перевіряйте структуру самостійно перед надсиланням.

  • conversation.positiveRatingTooltip / conversation.negativeRatingTooltip - короткі підказки для кнопок 👍 / 👎 поруч із кожною відповіддю AI, коли conversation.conversationRatingEnabled=true. Текст за замовчуванням: "I like the response" / "I don't like the response". Їх бачать кінцеві користувачі.

  • whiteLabel.hideRoboAssistLogo - функція White Label, яка залежить від лімітів вашого облікового запису. Приховує рядок "Powered by ChatLab" у нижньому колонтитулі. Якщо ваш обліковий запис не підтримує White Label, значення зберігається, але ігнорується, а футер відображається завжди.

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

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

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

  • advanced.internalLocale - код локалі та регіону IETF у форматі ll_CC (через підкреслення, а НЕ ll-CC через дефіс). Допустимі значення беруться з фіксованого списку з близько 95 локалей: en_US, pl_PL, de_DE, fr_FR, es_ES, it_IT, pt_PT, nl_NL, ru_RU, zh_CN, zh_TW, ja_JP, ko_KR, ar_SA, hi_IN, tr_TR, cs_CZ, da_DK, fi_FI, sv_SE, no_NO, el_GR, he_IL та багатьох інших. Передача лише дволітерного коду ("en") або коду BCP-47 ("en-US") неприпустима. За замовчуванням en_US. Ця локаль використовується для форматування дат/чисел в інтерфейсі віджета на відміну від role.language (мови, якою бот веде розмову).

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

  • advanced.botMessagesLimit - ціле число (числове значення JSON, наприклад 1000). 0 означає "без обмежень"; в інших випадках значення має бути кратним 1000 (1000, 2000, 10000...). Такі значення, як 100 або 1500, відхиляються з помилкою 400 validation_failed. Додатково значення автоматично обмежується лімітом вашого облікового запису.

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

Надсилайте точне значення API (стовпець ліворуч у зворотних лапках). Відображувана назва в панелі керування наведена в дужках. Доступний набір моделей визначається лімітами вашого облікового запису; надсилання моделі, яку ваш акаунт не може використовувати, повертає 400 invalid_parameter. Значенням за замовчуванням для нових ботів є 5-MINI.

  • 4-O-MINI (GPT 4-o mini)
  • 4-O (GPT 4-o)
  • 4.1-MINI (GPT 4.1-mini)
  • 4.1 (GPT 4.1)
  • 5-MINI (GPT 5-mini)
  • 5 (GPT 5)
  • 5.1 (GPT 5.1)
  • 5.4-MINI (GPT 5.4-mini)
  • 5.4 (GPT 5.4)
  • 5.5 (GPT 5.5)
  • GEMINI 2.5 PRO (Gemini 2.5 Pro)
  • GEMINI 3 Flash (Gemini 3 Flash)
  • GEMINI 3.5 Flash (Gemini 3.5 Flash)
  • GEMINI 3.7 Flash (Gemini 3.7 Flash)
  • GEMINI 3.8 Flash (Gemini 3.8 Flash)
  • GEMINI 3.1 Flash-Lite (Gemini 3.1 Flash-Lite)
  • GEMINI 3 PRO (Gemini 3 Pro)

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

Кожне поле, що передається мережею, із зазначенням його типу, обмежень і однорядкового опису. Семантика PATCH: будь-яке пропущене поле (або надіслане як null) залишає збережене значення без змін. Така ж структура використовується і для відповіді (за винятком двійкового вмісту 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, штучний інтелект пропонує варіанти наступних запитань після кожної відповіді
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 Частка вікна контексту чату (у %), виділена під збережені підсумки у порівнянні з базою знань RAG

§ appearance

Поле Тип Обмеження Опис
launcherColor string (hex) Колір фону кнопки запуску (іконки чату)
headerColor string (hex) Колір фону шапки чату
titleColor string (hex) Колір заголовка в шапці чату
subtitleColor string (hex) Колір підзаголовка в шапці чату
clientMessageBubbleColor string (hex) Колір бульбашки повідомлення відвідувача
clientMessageTextColor string (hex) Колір тексту повідомлення відвідувача
responseMessageBubbleColor string (hex) Колір бульбашки відповіді бота
responseMessageTextColor string (hex) Колір тексту відповіді бота
chatSubheader string Додатковий текст, що відображається під заголовком чату
senderPlaceholder string Текст-заповнювач у полі введення повідомлення
resetConversationTooltip string Підказка на кнопці «скинути розмову»
chatAlignment string (enum) ∈ {left, right} Сторона екрана, до якої прив'язаний чат
launcherBottomMargin int 0-500 Відступ кнопки запуску від нижнього краю (px)
launcherSideMargin int 0-500 Відступ кнопки запуску від бічного краю (px)
displayShadow boolean Тінь під віджетом
customCss string Користувацький CSS, що додається в iframe віджета
chatMessageLinkTarget string (enum) ∈ {_blank, _self} Спосіб відкриття посилань усередині повідомлень бота
minimizedDisplayMode string (enum) ∈ {icon, minified} Згорнутий стан: іконка запуску або компактна смуга введення
chatDesktopWidthPx int Ширина віджета на комп'ютерах
chatDesktopHeightPx int Висота віджета на комп'ютерах
chatMobileSizePercent int Розмір мобільного віджета у % від області перегляду
messageFontSize int Розмір шрифту тексту повідомлень (px)
showChatbotBubblesDesktop boolean Показувати спливаючі підказки над віджетом на комп'ютерах
showChatbotBubblesMobile boolean Показувати спливаючі підказки над віджетом на мобільних
chatbotBubblesDelaySeconds int Затримка перед появою підказок над віджетом (у секундах)
launcherIconFullSize boolean Відображати власну іконку кнопки запуску на всю площу без внутрішніх відступів
welcomeScreenEnabled boolean Показувати екран привітання (Welcome Screen) замість миттєвого переходу до чату
welcomeScreenQuestionsLabel string Підпис над рекомендованими запитаннями на екрані привітання
welcomeScreenHideHumanContactForm boolean Приховувати дію форми зв'язку з людиною в шапці, поки відображається Welcome Screen. Вона знову з'являється після першого повідомлення відвідувача. Для ботів, створених до 02.09.2026, стандартне значення true
welcomeScreenHideLiveChat boolean Приховувати кнопку Live Chat у шапці, поки відображається Welcome Screen. Вона знову з'являється після першого повідомлення відвідувача. Для ботів, створених до 02.09.2026, стандартне значення true
headerActionsLayout string DROPDOWN Спосіб відображення живого чату та форми зв'язку з людиною в шапці: ICONS (окремі іконки) або DROPDOWN (згруповані в меню шапки). Для ботів, створених до 02.09.2026, стандартне значення ICONS
stackSuggestedQuestions boolean Розміщувати запропоновані запитання вертикально (а не поруч)
suggestedQuestionsFontSize int Розмір шрифту блоків із запропонованими запитаннями (px)
suggestedQuestionsTextColor string (hex) Колір тексту в блоках запропонованих запитань
suggestedQuestionsBackgroundColor string (hex) Колір фону в блоках запропонованих запитань
autoOpenChat boolean Автоматично відкривати чат на комп'ютерах
autoOpenChatOnMobiles boolean Автоматично відкривати чат на мобільних
autoOpenChatDelay boolean Застосовувати затримку перед автоматичним відкриттям
autoOpenChatDelaySeconds int Час затримки автопереходу (у секундах)
simulateHumanTyping boolean Розбивати відповідь бота на окремі бульбашки з анімацією введення тексту
simulateHumanTypingDelay int 0-200 Затримка між повідомленнями (у секундах)
footerMarkdown string макс. 255 Користувацька розмітка markdown, що показується в нижньому колонтитулі під чатом
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 Текст-заповнювач у полі введення email
messagePlaceholder string Текст-заповнювач у полі введення повідомлення
emailWithConversationContent boolean Якщо true, додавати історію розмови до тіла електронного листа
customFormId long ідентифікатор наявної власної форми Замінити вбудовану форму зв'язку на власну форму. Значення null зберігає вбудовану форму
customFormMapping string рядок у форматі JSON Зіставляє поля власної форми з полями листа підтримки

Параметр requirePolicyAccept міститься в consent.humanSupportRequirePolicyAccept, а не тут.

§ leadCollection

Поле Тип Обмеження Опис
enabled boolean Перемикач форми збору лідів
nameEnabled boolean Збирати ім'я
nameLabel string Підпис біля поля введення імені
emailEnabled boolean Збирати email
emailLabel string обов'язкове (суворий режим створення), якщо enabled=true ТА emailEnabled=true Підпис біля поля введення email
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, додавати історію розмови до тексту сповіщення

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

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

§ liveChat

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

Параметр requirePolicyAccept міститься в consent.liveChatRequirePolicyAccept, а не тут.

§ consent

Поле Тип Обмеження Опис
newConversationRequirePolicyAccept boolean Вимагати згоду з політикою конфіденційності перед початком нової розмови
humanSupportRequirePolicyAccept boolean Вимагати згоду з політикою конфіденційності перед надсиланням форми підтримки
leadCollectionRequirePolicyAccept boolean Вимагати згоду з політикою конфіденційності перед надсиланням форми збору лідів
liveChatRequirePolicyAccept boolean Вимагати згоду з політикою конфіденційності перед початком сесії Live Chat
newConversationConsentDescription string Вступний текст на екрані згоди на початку розмови
privacyPolicyConsentCheckboxLabel string Текст біля прапорця згоди (зазвичай містить посилання на політику конфіденційності)

§ whiteLabel

Поле Тип Обмеження Опис
hideRoboAssistLogo boolean можливість White Label; регулюється лімітами облікового запису Приховати стандартний логотип ChatLab у нижньому колонтитулі
whitelabelLogoLink string white-label capability; subject to account limits 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 або режим з фіксованим списком Спосіб вибору мови відповіді бота
baseLanguage string код мови Мова, якою створено основні тексти бота
languages string коди мов через кому Мови, доступні для відвідувача
knowledgeLanguageMode string Принцип роботи з матеріалами бази знань іншими мовами
knowledgeLanguageFallback string код мови Мова за замовчуванням, якщо відповідність не знайдено

§ advanced

Поле Тип Обмеження Опис
model string регулюється лімітами облікового запису; див. «AI text models» вище Ідентифікатор LLM (наприклад, 5-MINI)
temperature decimal 0.0-1.0 Температура вибірки (відповідає повзунку в інтерфейсі)
chatContextSize int ∈ {8000, 16000, 32000}; автоматично обмежується лімітом вашого облікового запису Вікно токенів для збереження історії чату
botMessagesLimit long 0 або кратне 1000 (наприклад, 1000, 2000, 10000) Максимум відповідей бота за розмову (0 = без обмежень)
internalLocale string код локалі у форматі ll_CC Локаль для системних підписів інтерфейсу віджета (не залежить від role.language)
productsViewEnabled boolean Якщо true, відображати картки пропозицій (Offer Cards) для e-commerce всередині чату
includeProductsInKnowledgeBase boolean Якщо true, індексувати каталог товарів як частину бази знань

Поза межами Management API

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

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

У 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-MINI",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  }
}

Правила валідації зі своїми повідомленнями про помилки:

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

Поля, значення яких на сервері дорівнює null, пропускаються в тілі JSON - через мережу передаються лише поля з ненульовими значеннями.

Повне тіло відповіді (201)

Така сама структура, як і в запиті, плюс блок тільки для читання meta та одноразовий ключ apiKey на верхньому рівні. URL-адреси файлів лише для читання (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) заповнюються сервером після завантаження відповідних частин multipart.

{
  "name": "Helpdesk Bot",
  "role": {
    "rawPrompt": "You are a friendly support assistant for Acme Inc.",
    "role": "CUSTOMER_SUPPORT",
    "language": "English",
    "responseLength": "Normal",
    "websiteAddress": "https://acme.com",
    "companyDescription": "Acme sells industrial widgets."
  },
  "conversation": {
    "welcomeMessage": "Hi! How can I help today?",
    "queryRefinementEnabled": true,
    "conversationContinuityEnabled": true,
    "conversationRatingEnabled": true,
    "positiveRatingTooltip": "Helpful",
    "negativeRatingTooltip": "Not helpful",
    "suggestedQuestions": "What are your hours?\nHow do I cancel?\nWhere is my order?",
    "dynamicSuggestedFollowups": true,
    "dynamicFollowupsAutoIcons": true
  },
  "chatMemory": {
    "enabled": true,
    "summaryConversationsEnabled": true,
    "conversationSummaryPrompt": "Summarize this conversation in 3 sentences.",
    "clientSummaryPrompt": "Summarize what we know about this customer.",
    "clientSummaryPromptType": "DEFAULT",
    "conversationSummaryPromptType": "DEFAULT",
    "summariesToKnowledgeRatio": 50
  },
  "appearance": {
    "launcherColor": "#1A73E8",
    "headerColor": "#1A73E8",
    "titleColor": "#FFFFFF",
    "subtitleColor": "#FFFFFF",
    "clientMessageBubbleColor": "#000000",
    "clientMessageTextColor": "#FFFFFF",
    "responseMessageBubbleColor": "#F4F4F4",
    "responseMessageTextColor": "#000000",
    "chatSubheader": "AI support assistant",
    "senderPlaceholder": "Type a message...",
    "resetConversationTooltip": "Restart conversation",
    "chatAlignment": "right",
    "launcherBottomMargin": 20,
    "launcherSideMargin": 20,
    "displayShadow": true,
    "customCss": ".rcw-conversation-container { border-radius: 16px; }",
    "chatMessageLinkTarget": "_blank",
    "minimizedDisplayMode": "icon",
    "chatDesktopWidthPx": 400,
    "chatDesktopHeightPx": 600,
    "chatMobileSizePercent": 100,
    "messageFontSize": 14,
    "showChatbotBubblesDesktop": true,
    "showChatbotBubblesMobile": false,
    "chatbotBubblesDelaySeconds": 5,
    "welcomeScreenEnabled": false,
    "welcomeScreenQuestionsLabel": "Quick start",
    "welcomeScreenHideHumanContactForm": false,
    "welcomeScreenHideLiveChat": false,
    "headerActionsLayout": "DROPDOWN",
    "stackSuggestedQuestions": false,
    "suggestedQuestionsFontSize": 14,
    "suggestedQuestionsTextColor": "#000000",
    "suggestedQuestionsBackgroundColor": "#F4F4F4",
    "autoOpenChat": false,
    "autoOpenChatOnMobiles": false,
    "autoOpenChatDelay": false,
    "autoOpenChatDelaySeconds": 5,
    "simulateHumanTyping": true,
    "simulateHumanTypingDelay": 5,
    "footerMarkdown": "Powered by Acme",
    "avatarUrl": "https://api.chatlab.com/aichat/content/avatar_a8f3b2c1_2026060110.png"
  },
  "humanSupport": {
    "enabled": true,
    "email": "support@acme.com",
    "dialogMessage": "Leave us a message and we will get back to you.",
    "thankYouMessage": "Thanks - we received your message.",
    "emailMessageSubjectTemplate": "[Acme support] New message from {customerName}",
    "emailMessageContentTemplate": "{message}\n\n - \n{conversationTranscript}",
    "emailPlaceholder": "your@email.com",
    "messagePlaceholder": "How can we help?",
    "emailWithConversationContent": true
  },
  "leadCollection": {
    "enabled": true,
    "nameEnabled": true,
    "nameLabel": "Your name",
    "emailEnabled": true,
    "emailLabel": "Email",
    "phoneEnabled": false,
    "phoneLabel": "Phone",
    "leaveDetailsMessage": "Please leave your details and we will get in touch.",
    "thankYouMessage": "Thanks - we will be in touch shortly.",
    "requireBeforeNewConversation": false,
    "emailNotificationEnabled": true,
    "emailNotificationAddress": "leads@acme.com",
    "emailWithConversationContent": true
  },
  "liveChat": {
    "enabled": false,
    "infoMessage": "Connecting you with a human agent...",
    "startMessage": "You are now chatting with our team.",
    "endMessage": "Live chat has ended.",
    "nameLabel": "Your name",
    "emailLabel": "Email",
    "schedule": "{\"monday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"tuesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"wednesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"thursday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"friday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"saturday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"sunday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"timezone\":\"Europe/Warsaw\"}",
    "outOfHoursMessage": "We are currently offline.",
    "closeModalMessage": "End the live chat session?",
    "closeModalConfirmLabel": "Yes, end",
    "closeModalCancelLabel": "Cancel",
    "closeModalTooltipText": "End live chat",
    "operatorHasJoinedLabel": "An agent has joined.",
    "operatorDidNotJoinInTimeLabel": "No agent available right now.",
    "waitingForOperatorToJoinLabel": "Waiting for an agent...",
    "waitingForOperatorSeconds": 60,
    "redirectToHumanSupportForm": true
  },
  "consent": {
    "newConversationRequirePolicyAccept": false,
    "humanSupportRequirePolicyAccept": false,
    "leadCollectionRequirePolicyAccept": true,
    "liveChatRequirePolicyAccept": false,
    "newConversationConsentDescription": "By starting a conversation you agree to our terms.",
    "privacyPolicyConsentCheckboxLabel": "I have read and accepted the privacy policy."
  },
  "whiteLabel": {
    "hideRoboAssistLogo": false,
    "whitelabelLogoLink": "https://acme.com",
    "assignToCustomDomain": false,
    "whitelabelLogoUrl": "https://api.chatlab.com/aichat/content/custom_logo_4287_2026060110.png"
  },
  "security": {
    "allowedDomains": "acme.com,support.acme.com",
    "spamFilterEnabled": true,
    "talkMessagesRateLimit": 30,
    "talkMessagesRateLimitDurationSeconds": 60,
    "talkMessagesRateLimitHitMessage": "Please slow down."
  },
  "advanced": {
    "model": "5-MINI",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  },
  "meta": {
    "id": 4287,
    "createdAt": "2026-06-01T10:11:02Z",
    "updatedAt": "2026-06-01T10:11:02Z"
  },
  "apiKey": "ck_freshly_minted_bot_talk_key_here"
}

Поле apiKey з'являється лише під час створення - це щойно згенерований ключ Bot Talk, прив'язаний до нового бота. Відкритий текст показується один раз і надалі його не можна отримати через API; негайно збережіть його на своїй стороні.

Заголовок відповіді Location містить URL-адресу нового бота (/v1/management/bots/{id}).

Приклади з Curl

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

curl -X POST https://api.chatlab.com/aichat/v1/management/bots \
  -H "Authorization: Bearer mk_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Helpdesk Bot","conversation":{"welcomeMessage":"Hi!"}}'

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

curl -X POST https://api.chatlab.com/aichat/v1/management/bots \
  -H "Authorization: Bearer mk_..." \
  -F 'data={"name":"Helpdesk Bot","conversation":{"welcomeMessage":"Hi!"}};type=application/json' \
  -F 'avatar=@./avatar.png'

GET /v1/management/bots/{bot_id}

Повертає поточну конфігурацію бота, яким ви володієте.

Приклад із Curl

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

Повне тіло відповіді (200)

Така сама структура, як і у відповіді на POST, без одноразового ключа apiKey. Блок meta додається. Повертає 404 not_found_error, якщо бот не існує або не належить вашому акаунту.

Поточний аватар і логотип White Label надаються у вигляді повних URL-адрес лише для читання (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) - на основі тих самих схеми, хосту та шляху контексту, які обробляли цей запит. Щоб отримати байти, надішліть GET-запит безпосередньо на ці URL-адреси; щоб замінити будь-який із цих файлів, завантажте новий файл через відповідну multipart-частину avatar / whitelabel_logo за допомогою PATCH. Ці поля з URL-адресами ігноруються, якщо передаються в тілі запиту.

{
  "name": "Helpdesk Bot",
  "role": {
    "rawPrompt": "You are a friendly support assistant for Acme Inc.",
    "role": "CUSTOMER_SUPPORT",
    "language": "English",
    "responseLength": "Normal",
    "websiteAddress": "https://acme.com",
    "companyDescription": "Acme sells industrial widgets."
  },
  "conversation": {
    "welcomeMessage": "Hi! How can I help today?",
    "queryRefinementEnabled": true,
    "conversationContinuityEnabled": true,
    "conversationRatingEnabled": true,
    "positiveRatingTooltip": "Helpful",
    "negativeRatingTooltip": "Not helpful",
    "suggestedQuestions": "What are your hours?\nHow do I cancel?\nWhere is my order?",
    "dynamicSuggestedFollowups": true,
    "dynamicFollowupsAutoIcons": true
  },
  "chatMemory": {
    "enabled": true,
    "summaryConversationsEnabled": true,
    "conversationSummaryPrompt": "Summarize this conversation in 3 sentences.",
    "clientSummaryPrompt": "Summarize what we know about this customer.",
    "clientSummaryPromptType": "DEFAULT",
    "conversationSummaryPromptType": "DEFAULT",
    "summariesToKnowledgeRatio": 50
  },
  "appearance": {
    "launcherColor": "#1A73E8",
    "headerColor": "#1A73E8",
    "titleColor": "#FFFFFF",
    "subtitleColor": "#FFFFFF",
    "clientMessageBubbleColor": "#000000",
    "clientMessageTextColor": "#FFFFFF",
    "responseMessageBubbleColor": "#F4F4F4",
    "responseMessageTextColor": "#000000",
    "chatSubheader": "AI support assistant",
    "senderPlaceholder": "Type a message...",
    "resetConversationTooltip": "Restart conversation",
    "chatAlignment": "right",
    "launcherBottomMargin": 20,
    "launcherSideMargin": 20,
    "displayShadow": true,
    "customCss": ".rcw-conversation-container { border-radius: 16px; }",
    "chatMessageLinkTarget": "_blank",
    "minimizedDisplayMode": "icon",
    "chatDesktopWidthPx": 400,
    "chatDesktopHeightPx": 600,
    "chatMobileSizePercent": 100,
    "messageFontSize": 14,
    "showChatbotBubblesDesktop": true,
    "showChatbotBubblesMobile": false,
    "chatbotBubblesDelaySeconds": 5,
    "welcomeScreenEnabled": false,
    "welcomeScreenQuestionsLabel": "Quick start",
    "welcomeScreenHideHumanContactForm": false,
    "welcomeScreenHideLiveChat": false,
    "headerActionsLayout": "DROPDOWN",
    "stackSuggestedQuestions": false,
    "suggestedQuestionsFontSize": 14,
    "suggestedQuestionsTextColor": "#000000",
    "suggestedQuestionsBackgroundColor": "#F4F4F4",
    "autoOpenChat": false,
    "autoOpenChatOnMobiles": false,
    "autoOpenChatDelay": false,
    "autoOpenChatDelaySeconds": 5,
    "simulateHumanTyping": true,
    "simulateHumanTypingDelay": 5,
    "footerMarkdown": "Powered by Acme",
    "avatarUrl": "https://api.chatlab.com/aichat/content/avatar_a8f3b2c1_2026060110.png"
  },
  "humanSupport": {
    "enabled": true,
    "email": "support@acme.com",
    "dialogMessage": "Leave us a message and we will get back to you.",
    "thankYouMessage": "Thanks - we received your message.",
    "emailMessageSubjectTemplate": "[Acme support] New message from {customerName}",
    "emailMessageContentTemplate": "{message}\n\n - \n{conversationTranscript}",
    "emailPlaceholder": "your@email.com",
    "messagePlaceholder": "How can we help?",
    "emailWithConversationContent": true
  },
  "leadCollection": {
    "enabled": true,
    "nameEnabled": true,
    "nameLabel": "Your name",
    "emailEnabled": true,
    "emailLabel": "Email",
    "phoneEnabled": false,
    "phoneLabel": "Phone",
    "leaveDetailsMessage": "Please leave your details and we will get in touch.",
    "thankYouMessage": "Thanks - we will be in touch shortly.",
    "requireBeforeNewConversation": false,
    "emailNotificationEnabled": true,
    "emailNotificationAddress": "leads@acme.com",
    "emailWithConversationContent": true
  },
  "liveChat": {
    "enabled": false,
    "infoMessage": "Connecting you with a human agent...",
    "startMessage": "You are now chatting with our team.",
    "endMessage": "Live chat has ended.",
    "nameLabel": "Your name",
    "emailLabel": "Email",
    "schedule": "{\"monday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"tuesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"wednesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"thursday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"friday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"saturday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"sunday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"timezone\":\"Europe/Warsaw\"}",
    "outOfHoursMessage": "We are currently offline.",
    "closeModalMessage": "End the live chat session?",
    "closeModalConfirmLabel": "Yes, end",
    "closeModalCancelLabel": "Cancel",
    "closeModalTooltipText": "End live chat",
    "operatorHasJoinedLabel": "An agent has joined.",
    "operatorDidNotJoinInTimeLabel": "No agent available right now.",
    "waitingForOperatorToJoinLabel": "Waiting for an agent...",
    "waitingForOperatorSeconds": 60,
    "redirectToHumanSupportForm": true
  },
  "consent": {
    "newConversationRequirePolicyAccept": false,
    "humanSupportRequirePolicyAccept": false,
    "leadCollectionRequirePolicyAccept": true,
    "liveChatRequirePolicyAccept": false,
    "newConversationConsentDescription": "By starting a conversation you agree to our terms.",
    "privacyPolicyConsentCheckboxLabel": "I have read and accepted the privacy policy."
  },
  "whiteLabel": {
    "hideRoboAssistLogo": false,
    "whitelabelLogoLink": "https://acme.com",
    "assignToCustomDomain": false,
    "whitelabelLogoUrl": "https://api.chatlab.com/aichat/content/custom_logo_4287_2026060110.png"
  },
  "security": {
    "allowedDomains": "acme.com,support.acme.com",
    "spamFilterEnabled": true,
    "talkMessagesRateLimit": 30,
    "talkMessagesRateLimitDurationSeconds": 60,
    "talkMessagesRateLimitHitMessage": "Please slow down."
  },
  "advanced": {
    "model": "5-MINI",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  },
  "meta": {
    "id": 4287,
    "createdAt": "2026-06-01T10:11:02Z",
    "updatedAt": "2026-06-01T11:02:19Z"
  }
}

Клонування бота

Тіло запиту POST /v1/management/bots і тіло відповіді GET /v1/management/bots/{bot_id} мають однакову структуру, тому клонування складається з трьох кроків: отримати вихідного бота (GET), видалити ідентифікаційні поля, якими керує сервер, і надіслати результат (POST).

1. Отримайте вихідного бота за допомогою GET.

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

2. Видаліть блок meta верхнього рівня. Об'єкт meta (id, createdAt, updatedAt) керований сервером і доступний лише для читання - якщо залишити його в тілі POST-запиту, нічого страшного не станеться (сервер його проігнорує), але видалення робить намір чітким і зберігає корисне навантаження чистим. За бажанням змініть name, щоб клон можна було відрізнити від оригіналу.

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

3. Надішліть очищене тіло через POST, щоб створити клон. Повну структуру тіла та правила валідації дивіться вище в довідці до POST /v1/management/bots.

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

Відповідь містить meta.id нового бота, а також щойно згенерований apiKey (ключ Bot Talk для клона). Відкритий текст apiKey повертається лише в цій відповіді на створення - скопіюйте його, перш ніж закрити тіло відповіді; пізніше отримати його буде неможливо.

Два важливих застереження:

  • Файли не клонуються. Поля 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 API.

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

{
  "subscriptionType": "standard",
  "messages": {"used": 4123, "limit": 11000, "remaining": 6877},
  "bots": {"used": 3, "limit": 5, "remaining": 2}
}
  • subscriptionType - це ідентифікатор поточного плану облікового запису в нижньому регістрі (наприклад, standard у прикладі). Плани походять із динамічного каталогу, тому точний набір ідентифікаторів може змінюватися з часом у міру перейменування або додавання планів - ставтеся до цього значення як до довільного рядка, а не як до фіксованого списку переліку (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 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"
  }
}

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

Шукати серед усіх статейЗапитати агента