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 секций. Каждая секция соответствует подвкладке в боковом меню настроек бота в панели управления, поэтому ключи 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, температура, размер контекста, лимит сообщений бота, внутренний языковой стандарт (locale), Offer Cards (вкладка Model & Advanced (Модель и расширенные настройки))

Среди доступных для записи настроек только name находится на верхнем уровне, поскольку этот параметр идентифицирует самого бота, а не относится к какой-то конкретной вкладке.

Боковое меню настроек бота сейчас содержит 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 и поля с фиксированным набором значений

Поля-перечисления и поля с ограниченным набором значений отклоняют некорректные данные с ошибкой 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 - см. подраздел "Текстовые модели ИИ" ниже. Это поле является строкой, а не валидируемым 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. Это ежемесячный лимит кредитов бота, а не количество сообщений на один диалог. Маппер не ограничивает это значение рамками тарифа аккаунта, но фактический объем использования всегда ограничен общим бюджетом аккаунта.

Текстовые модели ИИ (advanced.model)

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

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

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

Поддерживаемые разделы и поля с указанием их типов и ключевых ограничений. Семантика PATCH: любое пропущенное поле (или переданное со значением null) оставляет сохраненное значение без изменений. Такая же структура используется и в ответе (за вычетом составного бинарного содержимого; плюс блок 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	Предустановка персонажа; выбирает шаблон промпта (см. "Роль и построение промпта")
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 (шаг в UI 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		Скрывать кнопку чата с оператором в шапке, пока отображается 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		Плейсхолдер в поле ввода email
messagePlaceholder	string		Плейсхолдер в текстовом поле сообщения
emailWithConversationContent	boolean		Если true, включать стенограмму разговора в тело письма
customFormId	long	id существующей настраиваемой формы	Заменить встроенную контактную форму на собственную. При создании отсутствие поля использует стандартную форму; при PATCH значение null оставляет текущий выбор без изменений
customFormMapping	string	строка в формате JSON	Сопоставляет поля настраиваемой формы с полями письма оператору

Параметр requirePolicyAccept находится в consent.humanSupportRequirePolicyAccept, а не здесь.

§ leadCollection

Поле	Тип	Ограничение	Описание
enabled	boolean		Переключатель формы сбора лидов
nameEnabled	boolean		Запрашивать имя
nameLabel	string		Надпись поля ввода имени
emailEnabled	boolean		Запрашивать 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		Отправлять email владельцу каждый раз при сборе лида
emailNotificationAddress	string		Получатель уведомлений (по умолчанию email учетной записи)
emailWithConversationContent	boolean		Если true, включать стенограмму разговора в уведомление

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

Перекрестное правило строгой валидации при создании: при enabled=true требуется включить хотя бы одно из полей - emailEnabled или phoneEnabled. Параметр requirePolicyAccept находится в consent.leadCollectionRequirePolicyAccept, а не здесь.

§ liveChat

Поле	Тип	Ограничение	Описание
enabled	boolean		Переключатель функции Live Chat
infoMessage	string		Пояснительное сообщение перед передачей диалога
startMessage	string		Сообщение, отображаемое в начале сеанса с оператором
endMessage	string		Сообщение, отображаемое после завершения сеанса с оператором
nameLabel	string		Надпись поля ввода имени в предварительной форме чата с оператором
emailLabel	string		Надпись поля ввода email в предварительной форме чата с оператором
schedule	string	строка в формате JSON (переключатели дней недели + from/to + timezone)	График работы чата с оператором - точный формат см. в разделе "Структурированные поля и диапазоны"
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, если оператор не ответил
requireAdminOnline	boolean		Требовать присутствия доступного оператора согласно настройкам статуса
presenceMode	string		Режим присутствия; используйте значение бота, настроенного в интерфейсе
hideHumanSupportWhenLiveChatAvailable	boolean		Скрывать контактную форму, когда доступен чат с оператором
missedEmailEnabled	boolean	по умолчанию true	Отправлять владельцу бота email при пропущенном запросе в 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	зависит от лимитов аккаунта; см. раздел "Текстовые модели ИИ" выше	Идентификатор 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) электронной коммерции прямо в чате
includeProductsInKnowledgeBase	boolean		Если true, индексировать каталог товаров в составе базы знаний

Не входит в область действия API

Интерфейс панели управления содержит ряд разделов, которые намеренно не включены в текущую версию Management API:

• Обучение и удаление - данные эндпоинты не позволяют получать список всех ботов, управлять наборами данных для обучения или удалять ботов. Для этих задач используйте панель управления.
• Вкладка Flow (Сценарии) - визуальный редактор сценариев диалога Conversation Flow (этапы и переходы). Недоступен через Management API.
• Вкладка Actions (Действия) - готовые интеграции для электронной коммерции и бронирования, функция AI Search и пользовательские функции API. Вызов инструментов никогда не являлся частью 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-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; для каждого включенного канала связи обязательно наличие метки (label), а также полей leaveDetailsMessage и thankYouMessage
• Параметр advanced.chatContextSize автоматически ограничивается максимальным размером контекста, доступным для вашего аккаунта. Не считайте, что другие числовые поля ограничиваются автоматически.

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

Пример тела ответа (201)

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

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

Поле apiKey возвращается только при создании - это только что сгенерированный ключ Bot Talk API, привязанный к новому боту. Значение в виде открытого текста отображается один раз и не может быть получено через API повторно; сразу же сохраните его на своей стороне.

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

Примеры cURL

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

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

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

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

GET /v1/management/bots/{bot_id}

Возвращает текущую конфигурацию принадлежащего вам бота.

Пример cURL

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

Пример тела ответа (200)

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

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

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

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

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

1. Выполните GET-запрос к исходному боту.

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

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

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

3. Отправьте очищенное тело через POST-запрос, чтобы создать клон. Полную структуру тела и правила валидации см. выше в описании POST /v1/management/bots.

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

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

При этом копируются поддерживаемые настройки, а не полностью обученный чат-бот. Обучающие материалы, история разговоров, интеграции/действия, Flow и определения форм данными эндпоинтами не клонируются. Настройте их отдельно в приложении.

Дополнительные нюансы:

• Файлы не клонируются. Поля appearance.avatarUrl и whiteLabel.whitelabelLogoUrl доступны только для чтения и указывают на файлы исходного бота. Если вам нужен тот же аватар или логотип White Label на клоне, скачайте байты по исходным URL-адресам и загрузите их как части multipart-запроса avatar / whitelabel_logo - либо при создании через POST (режим B), либо последующим PATCH-запросом.
• Ключи Bot Talk не клонируются. У каждого бота есть собственный пул ключей Bot Talk. Единственный ключ apiKey, возвращаемый при создании через POST, генерируется автоматически; при необходимости создайте дополнительные ключи на вкладке API (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 приведен в качестве примера). Планы формируются из динамического каталога, поэтому точный набор идентификаторов со временем может меняться по мере переименования или добавления планов - обрабатывайте это значение как произвольную строку, а не как фиксированное перечисление.
• 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.