Management API

Visión general de la Management API

La Management API está pensada para tareas de gestión interna que no implican el envío de mensajes de chat:

• crear un bot mediante programación con POST /v1/management/bots
• consultar un bot específico de tu propiedad con GET /v1/management/bots/{bot_id}
• actualizar un bot específico con PATCH /v1/management/bots/{bot_id}
• consultar el uso de la suscripción con GET /v1/usage

Las claves de gestión están vinculadas a tu cuenta, no a ningún bot en particular. Se mantienen deliberadamente separadas de las claves de Bot Talk para que una clave de chat comprometida no pueda modificar tus bots ni leer tus datos de facturación.

URL base

https://api.chatlab.com/aichat

Todos los endpoints de este artículo son relativos a esta URL base.

Primeros pasos

1. Abre la aplicación de administración y ve a Account Settings > Management API (Ajustes de la cuenta > Management API).
2. Haz clic en Create Management Key (Crear clave de gestión), asígnale un nombre, define opcionalmente una lista blanca de IP y un límite de peticiones, y luego confirma.
3. Selecciona únicamente los permisos que necesita tu integración y copia la clave completa desde la ventana modal de confirmación. El texto sin formato solo se muestra una vez.
4. Guárdala en tu servidor, no en código del navegador ni en un repositorio público. Realiza una petición de solo lectura como GET /v1/usage con el permiso usage para verificar el acceso.
5. Revoca las claves no utilizadas o comprometidas desde la página de la Management API.

Una clave tiene un formato similar a mk_abcdefghijklmnopqrstuvwxyz012345. El prefijo mk_ la distingue de las claves de Bot Talk (ck_).

Autenticación

Authorization: Bearer mk_abcdefghijklmnopqrstuvwxyz012345

Si envías una clave mk_ a /v1/chat (o a cualquier otro endpoint de Bot Talk), recibirás un error 403 key_type_not_allowed. Si envías una clave ck_ a /v1/management/*, recibirás el mismo error.

Límites

• Máximo de 5 claves activas de la Management API por usuario
• Máximo de 10 peticiones por minuto por clave (token bucket, capacidad de 10, recarga progresiva de ~1 token cada 6 segundos). Se puede configurar a la baja en el momento de la creación: define un valor inferior en rateLimitPerMinute y el límite máximo bajará, escalando la tasa de recarga en consecuencia.

Permisos

Cada clave de gestión incluye cualquier subconjunto de los tres permisos siguientes. Debe seleccionarse al menos uno en el momento de la creación; de lo contrario, la petición se rechazará con un error 400 invalid_request_error. Llamar a un endpoint con una clave que no disponga del permiso requerido devuelve un error 403 insufficient_permissions.

• bot_read - requerido para GET /v1/management/bots/{bot_id}
• bot_management - requerido para POST /v1/management/bots y PATCH /v1/management/bots/{bot_id}
• usage - requerido para GET /v1/usage

Estructura del cuerpo: secciones anidadas que reflejan las pestañas del panel de administración

POST y PATCH admiten un cuerpo JSON agrupado en 13 secciones. Cada sección se corresponde con una subpestaña de la barra lateral de ajustes del bot en el panel de administración, de modo que las claves JSON y las pestañas visibles coinciden: si cambias consent.humanSupportRequirePolicyAccept a través de la API, verás cambiar el mismo interruptor en la pestaña Consent & Privacy (Consentimiento y privacidad) de la aplicación de administración.

• role - rol del bot, prompt en bruto, longitud de la respuesta, idioma, contexto del sitio web o de la empresa (pestaña Role & Behavior [Rol y comportamiento])
• conversation - mensaje de bienvenida, ajuste de consultas, continuidad de la conversación, interruptor de valoración + mensajes de ayuda (tooltips), contenido de preguntas sugeridas + seguimiento dinámico (pestaña Chat Conversation [Conversación de chat])
• chatMemory - interruptor de memoria del chat, prompts de resumen, asignación de contexto (pestaña Summaries & Memory [Resúmenes y memoria])
• appearance - colores, textos, dimensiones, CSS personalizado, pantalla de bienvenida, estilo de las preguntas sugeridas, comportamiento de apertura automática, simulación de escritura humana, markdown del pie de página (pestaña Appearance [Apariencia])
• humanSupport - formulario de contacto humano (pestaña Human Contact Form [Formulario de contacto humano])
• leadCollection - formulario de captación de leads (pestaña Lead Collection [Captación de leads])
• liveChat - derivación a chat en vivo (pestaña Live Chat [Chat en vivo])
• consent - los cuatro interruptores de consentimiento de la política de privacidad junto con el texto de la pantalla de consentimiento (pestaña Consent & Privacy [Consentimiento y privacidad])
• whiteLabel - ocultar logotipo, enlace del logotipo personalizado, alojamiento en dominio personalizado (pestaña Whitelabel [Marca blanca])
• security - dominios permitidos, filtro de spam, límites de frecuencia de conversación (pestaña Security [Seguridad])
• voice - entrada de voz y conversaciones por voz: modelo, voz, idiomas, prompt, límite de duración (pestaña Voice Conversation [Conversación por voz])
• multilingual - modo multilingüe, idioma base, idiomas ofrecidos, gestión del idioma de la base de conocimiento (pestaña Languages [Idiomas])
• advanced - modelo LLM, temperatura, tamaño de contexto, límite de mensajes del bot, configuración regional interna, Offer Cards (pestaña Model & Advanced [Modelo y avanzado])

De las opciones editables, solo name se encuentra en el nivel superior, ya que identifica al bot en lugar de pertenecer a una pestaña concreta.

La barra lateral de ajustes del bot cuenta actualmente con 16 subpestañas, y 13 de ellas se corresponden con las secciones anteriores. Las tres subpestañas que no tienen sección correspondiente son Flow (Flujo), Actions (Acciones) y Forms (Formularios) - las tres detalladas más abajo en "Fuera del alcance de la API". Las 13 que sí se corresponden son Appearance, Chat Conversation, Role & Behavior, Human Contact Form, Lead Collection, Live Chat, Whitelabel, Consent & Privacy, Security, Model & Advanced, Summaries & Memory, Voice Conversation y Languages.

El cuerpo de la petición y el de la respuesta comparten la misma estructura. La respuesta añade dos elementos adicionales:

• meta - solo lectura: identificador del bot y marcas de tiempo. Elimínalo para transformar una respuesta GET en un cuerpo POST válido.
• apiKey - presente únicamente en la creación - la clave de Bot Talk API recién generada para el nuevo bot.

Dos campos dentro de esta estructura compartida son de solo lectura - se devuelven en la respuesta y se ignoran si intentas enviarlos en POST/PATCH:

• appearance.avatarUrl - URL pública completa de la imagen del avatar del bot (p. ej., https://api.chatlab.com/aichat/content/avatar_xyz.png). Haz una petición GET directa para descargar los bytes. Para cambiarlo, sube un nuevo archivo mediante la parte multipart avatar (consulta PATCH).
• whiteLabel.whitelabelLogoUrl - URL pública completa del logotipo de cabecera de marca blanca. Mismo funcionamiento que avatarUrl. Para cambiarlo, sube un nuevo archivo mediante la parte multipart whitelabel_logo (consulta PATCH).

Ambas URL utilizan el esquema + host + ruta de contexto de la petición actual, por lo que en un dominio personalizado de White Label se devuelven vinculadas a dicho dominio (p. ej., https://api.acme.com/aichat/content/...).

Envía null en una sección para omitirla en un PATCH; envía null en un campo dentro de una sección para omitir únicamente ese campo. Un valor null a nivel de campo nunca borra un valor guardado - solo significa "no modificar".

Rol y construcción del prompt

El prompt de sistema que el LLM recibe en la práctica se genera de dos formas posibles según el valor de role.role. Saber en qué rama te encuentras te indicará qué campos se tienen en cuenta y cuáles se guardan pero se ignoran.

Rama A - role.role es CUSTOMER_SUPPORT, SALES o LEAD_COLLECTION_AGENT (basada en plantillas)

El backend genera el prompt a partir de una plantilla integrada e ignora role.rawPrompt por completo (el valor sigue guardado en el bot, simplemente no se utiliza). La plantilla incluye:

• role.role - etiqueta del rol (p. ej., "Customer Support") e instrucciones específicas del rol añadidas automáticamente
• name - nombre del bot, insertado en la frase inicial
• role.language - "Auto Detect" configura el bot para adaptarse al idioma del usuario; cualquier otro valor (p. ej., "English", "Polish") se convierte en "Output in {language}, unless user uses another language"
• role.responseLength - se asigna a un recuento aproximado de palabras: Concise ≈ 50 palabras, Normal ≈ 100, Detailed ≈ 200
• role.websiteAddress - opcional; si no está en blanco, se añade como "for the users of the website {url}"
• role.companyDescription - opcional; si no está en blanco, se antepone como un párrafo adicional antes de las instrucciones del rol

Esta es la opción recomendada para la mayoría de los bots: obtienes de serie un comportamiento ajustado al rol y directrices de seguridad.

Rama B - role.role es CUSTOM (prompt proporcionado por el usuario)

El backend utiliza role.rawPrompt como prompt de rol y añade la directriz fija de longitud de respuesta de la plataforma. Esto es independiente de role.responseLength: el ajuste opcional Concise/Normal/Detailed no se inserta para un rol CUSTOM. Del mismo modo, language, websiteAddress y companyDescription se guardan pero no se inyectan en este prompt de rol. Incluye en rawPrompt cualquier directriz de idioma, objetivo de longitud de respuesta o contexto de empresa que consideres oportuno. También se pueden proporcionar instrucciones de ejecución adicionales y contexto recuperado, por lo que rawPrompt no constituye la totalidad de la entrada del modelo. No se añaden las instrucciones de tono de los roles predefinidos, pero elegir CUSTOM no elimina todas las instrucciones de la plataforma.

Utiliza CUSTOM solo cuando el prompt basado en plantillas no se adapte a tu caso de uso (p. ej., si necesitas una personalidad muy específica de tu sector, tus propias restricciones de seguridad o un formato de salida no estándar).

Campos de tipo enumeración / conjunto cerrado

Los campos de tipo enum y los restringidos rechazan valores no válidos con un error 400 invalid_parameter. Otros campos son cadenas de texto simples, incluso cuando la interfaz ofrece una lista fija. Utiliza la grafía indicada en la documentación y valida tu contenido en lugar de asumir que cualquier cadena no admitida será rechazada.

• role.role - CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM
• role.responseLength - Concise, Normal, Detailed
• role.language - nombre completo del idioma en inglés tal como aparece en el menú desplegable de administración, p. ej., Auto Detect, English, Polish, Spanish, German, French, Italian, Portuguese, Dutch, Russian, Chinese (Simplified), Japanese, Arabic, Hindi y unos ~80 más. El valor se guarda de forma literal y se sustituye en la plantilla del prompt, por lo que los códigos ISO de dos letras (en, pl) y otros valores fuera de la lista no son rechazados por la API, pero generan una instrucción incoherente como "Output in en, unless...". Por defecto es Auto Detect si se omite en la creación.
• advanced.model - consulta la sección "Modelos de texto de IA" a continuación. Se trata de una cadena de texto, no de un enum validado en el esquema de la petición; utiliza un valor admitido y no un nombre de modelo arbitrario.
• advanced.chatContextSize - utiliza 8000, 16000 o 32000, coincidiendo con la interfaz. Los valores superiores al máximo de la cuenta se ajustan a dicho límite de forma automática; el DTO no restringe este conjunto de tres valores.
• chatMemory.clientSummaryPromptType - DEFAULT, CUSTOM
• chatMemory.conversationSummaryPromptType - DEFAULT, CUSTOM
• appearance.chatAlignment - left, right
• appearance.minimizedDisplayMode - icon, minified, pill
• appearance.chatMessageLinkTarget - _blank, _self
• leadCollection.requireBeforeNewConversation - interruptor booleano. true obliga al usuario a rellenar el formulario de contacto antes de iniciar una conversación; false permite que la IA decida cuándo mostrar el formulario (valor predeterminado).

Campos estructurados y rangos

Campos que parecen cadenas o números simples pero que en realidad cuentan con estructuras específicas, rangos o particularidades del panel de administración que conviene conocer.

• advanced.temperature - el rango admitido es de 0.0 a 1.0, coincidiendo con el control deslizante del panel de administración. Los valores fuera de este rango se rechazan con un error 400 invalid_parameter.

• chatMemory.summariesToKnowledgeRatio - porcentaje entero, 10-90; la interfaz utiliza incrementos de 10, pero la API acepta enteros a lo largo de todo el rango. Valor predeterminado 50. Con la memoria activada y un contexto superior a 8k, distribuye el presupuesto de conocimiento y memoria tras la reserva de prompt y conversación reciente, no el contexto total del modelo. Con 8k, este ajuste no asigna presupuesto para resúmenes.

• liveChat.schedule - JSON codificado como una cadena de texto, no un objeto JSON anidado en la transmisión. El servidor almacena la cadena tal cual; la interfaz de administración la procesa en el cliente al cargar el editor de horarios. Una vez interpretada, la cadena consta de una entrada por día de la semana más una clave timezone:

  • cada clave de día de la semana (monday-sunday) se asigna a {enabled: boolean, from: "H:MM", to: "H:MM"} en formato de 24 horas
  • timezone es un nombre de zona IANA (p. ej., "Europe/Warsaw", "America/New_York")

  Ejemplo de valor (ten en cuenta las comillas exteriores y las comillas interiores escapadas: es un único campo de texto, no un objeto anidado):

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

  Fuera del horario indicado, se muestra liveChat.outOfHoursMessage al visitante y se desactiva la derivación al chat en vivo. La validación de la estructura interna solo se ejecuta en el navegador dentro de la interfaz de administración - la API aceptará cualquier JSON mal formado o clave no reconocida como una simple cadena de texto, y provocará un error de visualización cuando un usuario abra el bot más adelante en el panel. Valida la estructura por tu cuenta antes de enviarla.

• conversation.positiveRatingTooltip / conversation.negativeRatingTooltip - textos breves que se muestran en los botones de valoración con 👍 / 👎 cuando conversation.conversationRatingEnabled=true. El texto predeterminado es "I like the response" / "I don't like the response". Visible para los usuarios finales.

• whiteLabel.hideRoboAssistLogo - función de White Label, sujeta a los límites de tu cuenta. Oculta el texto "Powered by ChatLab" del pie de página. Si tu cuenta no incluye marca blanca, el valor se guarda pero se ignora y el pie de página se mostrará siempre.

• whiteLabel.whitelabelLogoLink - función de White Label, sujeta a los límites de tu cuenta. URL de destino al hacer clic en el logotipo personalizado cuando hideRoboAssistLogo=true y se ha subido un archivo de logotipo personalizado a través del elemento multipart whitelabel_logo.

• appearance.simulateHumanTypingDelay - segundos (no milisegundos), número entero de 0-200. Pausa entre mensajes sucesivos del bot cuando simulateHumanTyping=true. Valor predeterminado 5.

• appearance.autoOpenChatDelaySeconds - segundos, número entero. Tiempo de espera antes de que el widget se abra automáticamente cuando autoOpenChat=true y autoOpenChatDelay=true.

• advanced.internalLocale - código de región e idioma IETF en formato ll_CC (con guion bajo, NO ll-CC con guion medio). Los valores admitidos pertenecen a una lista fija de ~95 configuraciones regionales: 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 y muchas más. Enviar únicamente un código de dos letras ("en") o en formato BCP-47 ("en-US") no está permitido. Valor predeterminado en_US. Esta es la configuración regional utilizada para el formato de fechas y números en la interfaz del widget, a diferencia de role.language (el idioma de conversación que usa el bot).

• security.talkMessagesRateLimit / security.talkMessagesRateLimitDurationSeconds - números enteros (enviar como números JSON, p. ej., 30, no "30"). Define el límite de mensajes en 0 para desactivar este límite por sesión. Al activarlo, proporciona una duración positiva. El backend aplica un límite de N mensajes por sesión en el intervalo de segundos configurado antes de mostrar security.talkMessagesRateLimitHitMessage al visitante.

• advanced.botMessagesLimit - número entero (número JSON, p. ej., 1000). 0 significa que no hay un límite adicional por bot, aplicándose únicamente el saldo de créditos de la cuenta; de lo contrario, debe ser un múltiplo de 1000 (1000, 2000, 10000, ...). Los valores como 100 o 1500 se rechazan con un error 400 invalid_parameter. Este es un límite mensual de créditos para el bot, no un límite de mensajes por conversación. El conversor de datos no ajusta este valor al límite global de la cuenta; el saldo de la cuenta seguirá restringiendo el consumo real.

Modelos de texto de IA (advanced.model)

Utiliza el identificador exacto devuelto en advanced.model al consultar un bot configurado con el modelo deseado en Settings > Model & Advanced (Ajustes > Modelo y avanzado). El valor predeterminado actual al crear un bot es 5.6-LUNA. Los identificadores distinguen entre mayúsculas y minúsculas y no coinciden con los nombres visibles; por ejemplo, 5.6-LUNA se muestra como GPT 5.6-luna.

El catálogo de modelos se actualiza con el tiempo. No asumas que una cadena de texto arbitraria o el ID de modelo público de un proveedor son compatibles solo porque el esquema de la petición acepte una cadena de texto. Consulta la configuración guardada y prueba el chatbot resultante antes de publicarlo.

Referencia de campos (esquema completo de solicitud)

Las secciones y campos admitidos, con sus tipos y restricciones importantes. Semántica de PATCH: cualquier campo omitido (o enviado como null) deja intacto el valor guardado. Se utiliza la misma estructura para la respuesta (salvo el contenido binario multipart; más el bloque de solo lectura meta en cada respuesta y apiKey únicamente en la respuesta de creación).

Nivel superior

Campo	Tipo	Restricción	Descripción
name	string	máx. 150, obligatorio al crear	Nombre visible del bot
role	object		Consulta § role
conversation	object		Consulta § conversation
chatMemory	object		Consulta § chatMemory
appearance	object		Consulta § appearance
humanSupport	object		Consulta § humanSupport
leadCollection	object		Consulta § leadCollection
liveChat	object		Consulta § liveChat
consent	object		Consulta § consent
whiteLabel	object		Consulta § whiteLabel
security	object		Consulta § security
advanced	object		Consulta § advanced

Adiciones exclusivas de la respuesta:

• meta: { id, createdAt, updatedAt } - solo lectura.
• apiKey - string, presente únicamente en la respuesta de POST /v1/management/bots - la clave de Bot Talk recién generada para el nuevo bot, devuelta exactamente una vez.

§ role

Campo	Tipo	Restricción	Descripción
role	string (enum)	CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM	Ajuste predefinido del rol; selecciona la plantilla de prompt (consulta "Construcción del rol y del prompt")
language	string	nombre completo del idioma en inglés (English, Polish, ...) o Auto Detect	Idioma principal introducido en la plantilla de prompt
responseLength	string	∈ {Concise, Normal, Detailed}	Nivel de detalle deseado en la respuesta de la IA
websiteAddress	string		Sitio web utilizado como contexto para el prompt
companyDescription	string		Descripción de la empresa utilizada como contexto para el prompt
rawPrompt	string		Prompt de sistema personalizado - se utiliza textualmente solo cuando role=CUSTOM

§ conversation

Campo	Tipo	Restricción	Descripción
welcomeMessage	string		Primer mensaje mostrado al visitante al abrir el chat
queryRefinementEnabled	boolean		Si es true, afina la pregunta del visitante antes de la recuperación RAG
conversationContinuityEnabled	boolean		Si es true, los visitantes recurrentes reanudan su última conversación
conversationRatingEnabled	boolean		Si es true, muestra los controles de valoración de la conversación con pulgar arriba/abajo
positiveRatingTooltip	string		Mensaje emergente en el botón de valoración positiva
negativeRatingTooltip	string		Mensaje emergente en el botón de valoración negativa
suggestedQuestions	string		Preguntas sugeridas para iniciar la conversación, separadas por saltos de línea
dynamicSuggestedFollowups	boolean		Si es true, la IA propone sugerencias de seguimiento tras cada respuesta
positiveRatingMessage	string		Mensaje mostrado tras recibir una valoración positiva
negativeRatingMessage	string		Mensaje mostrado tras recibir una valoración negativa
hideSuggestedQuestionsAfterFirstUse	boolean		Oculta las sugerencias estáticas tras el primer uso
dynamicFollowupsAutoIcons	boolean		Si es true, la IA selecciona automáticamente iconos emoji para los seguimientos dinámicos

§ chatMemory

Campo	Tipo	Restricción	Descripción
enabled	boolean		Interruptor principal de la función de memoria de chat
summaryConversationsEnabled	boolean		Guarda resúmenes individuales por conversación
conversationSummaryPrompt	string		Prompt personalizado utilizado para resumir cada conversación
conversationSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Indica si se utiliza el prompt de resumen predeterminado o uno personalizado
clientSummaryPrompt	string		Prompt personalizado utilizado para resumir al cliente a través de múltiples conversaciones
clientSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Prompt de perfil de cliente predeterminado frente a personalizado
summariesToKnowledgeRatio	int	10-90 (paso de la interfaz: 10)	% del límite disponible de conocimiento/memoria asignado a resúmenes en contextos superiores a 8k

§ appearance

Campo	Tipo	Restricción	Descripción
launcherLabelLine1	string	máx. 60	Primera línea de texto del activador
launcherLabelLine2	string	máx. 60	Segunda línea de texto del activador
launcherTextColor	string		Color del texto del activador
launcherDismissEnabled	boolean		Permite descartar o cerrar el activador
widgetFontFamily	string	inter, system, nunito, lato, montserrat, poppins, source-serif, jetbrains-mono	Familia tipográfica del widget
chatDrawerEnabled	boolean		Activa la presentación tipo panel lateral (drawer)
launcherColor	string (hex)		Color de fondo del activador (icono de chat)
headerColor	string (hex)		Color de fondo del encabezado del chat
titleColor	string (hex)		Color del título del encabezado del chat
subtitleColor	string (hex)		Color del subtítulo del encabezado del chat
clientMessageBubbleColor	string (hex)		Color del bocadillo de mensaje del visitante
clientMessageTextColor	string (hex)		Color del texto del mensaje del visitante
responseMessageBubbleColor	string (hex)		Color del bocadillo de respuesta del bot
responseMessageTextColor	string (hex)		Color del texto de la respuesta del bot
chatSubheader	string		Línea descriptiva mostrada debajo del título del chat
senderPlaceholder	string		Texto de marcador de posición en el campo de entrada de mensajes
resetConversationTooltip	string		Mensaje emergente en el botón de "reiniciar conversación"
chatAlignment	string (enum)	∈ {left, right}	Lado de la pantalla en el que se ancla el chat
launcherBottomMargin	int	0-500	Distancia del activador respecto al borde inferior (px)
launcherSideMargin	int	0-500	Distancia del activador respecto al borde lateral (px)
displayShadow	boolean		Sombra paralela debajo del widget
customCss	string		CSS sin procesar inyectado en el iframe del widget
chatMessageLinkTarget	string (enum)	∈ {_blank, _self}	Cómo se abren los enlaces dentro de los mensajes del bot
minimizedDisplayMode	string (enum)	∈ {icon, minified, pill}	Estado minimizado: icono activador, barra de envío compacta o pastilla (pill)
chatDesktopWidthPx	int		Anchura del widget en escritorio
chatDesktopHeightPx	int		Altura del widget en escritorio
chatMobileSizePercent	int		Tamaño del widget en móvil como % del viewport
messageFontSize	int		Tamaño de fuente del texto del mensaje (px)
showChatbotBubblesDesktop	boolean		Muestra los globos flotantes de vista previa en escritorio
showChatbotBubblesMobile	boolean		Muestra los globos flotantes de vista previa en móvil
chatbotBubblesDelaySeconds	int		Retardo antes de que aparezcan los globos de vista previa (segundos)
launcherIconFullSize	boolean		Muestra el icono personalizado del activador de borde a borde en lugar de con sangría
welcomeScreenEnabled	boolean		Muestra la pantalla de bienvenida en lugar de abrir directamente el chat
welcomeScreenQuestionsLabel	string		Etiqueta situada sobre las preguntas sugeridas en la pantalla de bienvenida
welcomeScreenHideHumanContactForm	boolean		Oculta la acción del formulario de contacto humano en el encabezado mientras se muestra la pantalla de bienvenida. Vuelve a aparecer tras el primer mensaje del visitante. En bots creados antes del 2026-09-02 el valor predeterminado es true
welcomeScreenHideLiveChat	boolean		Oculta la acción de chat en vivo en el encabezado mientras se muestra la pantalla de bienvenida. Vuelve a aparecer tras el primer mensaje del visitante. En bots creados antes del 2026-09-02 el valor predeterminado es true
headerActionsLayout	string	ICONS o DROPDOWN	Cómo se ofrecen el chat en vivo y el formulario de contacto humano en el encabezado del chat: ICONS (un icono independiente para cada uno) o DROPDOWN (agrupados en el menú del encabezado). En bots creados antes del 2026-09-02 el valor predeterminado es ICONS
stackSuggestedQuestions	boolean		Apila las preguntas sugeridas verticalmente (frente a situarlas lado a lado)
suggestedQuestionsFontSize	int		Tamaño de fuente de las fichas de preguntas sugeridas (px)
suggestedQuestionsTextColor	string (hex)		Color del texto de las fichas de preguntas sugeridas
suggestedQuestionsBackgroundColor	string (hex)		Color de fondo de las fichas de preguntas sugeridas
autoOpenChat	boolean		Abre automáticamente el chat en escritorio
autoOpenChatOnMobiles	boolean		Abre automáticamente el chat en móvil
autoOpenChatDelay	boolean		Aplica un retardo antes de abrir automáticamente el chat
autoOpenChatDelaySeconds	int		Retardo para la apertura automática (segundos)
simulateHumanTyping	boolean		Divide la respuesta del bot en varios bocadillos con animación de escritura
simulateHumanTypingDelay	int	0-200	Retardo entre los mensajes en bocadillo (segundos)
footerMarkdown	string	máx. 255	Markdown personalizado que se muestra debajo del chat
avatarUrl	string	solo lectura	URL pública completa del avatar; para cambiarlo, súbelo a través de la parte multipart avatar

Multipart en POST/PATCH: avatar (parte de archivo). Los cuerpos de GET / respuesta omiten el contenido del archivo; solo viaja la URL por la red.

§ humanSupport

Campo	Tipo	Restricción	Descripción
enabled	boolean		Interruptor del flujo de Human Support (asistencia humana)
email	string	obligatorio (creación estricta) cuando enabled=true	Dirección que recibe los correos de asistencia humana
dialogMessage	string		Mensaje motivador mostrado encima del formulario
thankYouMessage	string		Mensaje de confirmación mostrado tras el envío
emailMessageSubjectTemplate	string		Plantilla de asunto para el correo electrónico enviado al agente
emailMessageContentTemplate	string		Plantilla de contenido para el correo electrónico enviado al agente
emailPlaceholder	string		Marcador de posición en el campo de entrada del correo electrónico
messagePlaceholder	string		Marcador de posición en el área de texto del mensaje
emailWithConversationContent	boolean		Si es true, incluye la transcripción de la conversación en el cuerpo del correo
customFormId	long	id de un formulario personalizado existente	Sustituye el formulario de contacto integrado por uno personalizado. Al crear, omitirlo utiliza el formulario integrado; en PATCH, null mantiene la selección actual sin cambios
customFormMapping	string	cadena codificada en JSON	Asocia los campos del formulario personalizado con los campos del correo de asistencia humana

requirePolicyAccept se encuentra en consent.humanSupportRequirePolicyAccept, no aquí.

§ leadCollection

Campo	Tipo	Restricción	Descripción
enabled	boolean		Interruptor del formulario de captación de leads
nameEnabled	boolean		Recopilar nombre
nameLabel	string		Etiqueta en el campo del nombre
emailEnabled	boolean		Recopilar correo electrónico
emailLabel	string	obligatorio (creación estricta) cuando enabled=true Y emailEnabled=true	Etiqueta en el campo del correo electrónico
phoneEnabled	boolean		Recopilar teléfono
phoneLabel	string	obligatorio (creación estricta) cuando enabled=true Y phoneEnabled=true	Etiqueta en el campo del teléfono
leaveDetailsMessage	string	obligatorio (creación estricta) cuando enabled=true	Mensaje que invita al visitante a dejar sus datos
thankYouMessage	string	obligatorio (creación estricta) cuando enabled=true	Mensaje de confirmación mostrado tras el envío
requireBeforeNewConversation	boolean		Si es true, debe enviarse el formulario antes de iniciar el chat; si es false, la IA decide cuándo mostrar el formulario
emailNotificationEnabled	boolean		Envía un correo al propietario cada vez que se recopila un lead
emailNotificationAddress	string		Destinatario de la notificación (por defecto es el correo de la cuenta)
emailWithConversationContent	boolean		Si es true, incluye la transcripción de la conversación en la notificación

| customFormId | long | id de un formulario personalizado existente | Sustituye el formulario de leads integrado por uno personalizado. Al crear, omitirlo utiliza el formulario integrado; en PATCH, null mantiene la selección actual sin cambios | | customFormMapping | string | cadena codificada en JSON | Asocia los campos del formulario personalizado con nombre / correo electrónico / teléfono |

Regla de creación estricta entre campos: enabled=true requiere al menos uno de emailEnabled o phoneEnabled. requirePolicyAccept se encuentra en consent.leadCollectionRequirePolicyAccept, no aquí.

§ liveChat

Campo	Tipo	Restricción	Descripción
enabled	boolean		Interruptor de la función Live Chat
infoMessage	string		Mensaje explicativo previo a la transferencia
startMessage	string		Mensaje mostrado cuando comienza la sesión en vivo
endMessage	string		Mensaje mostrado cuando finaliza la sesión en vivo
nameLabel	string		Etiqueta en el campo del nombre en el formulario previo a Live Chat
emailLabel	string		Etiqueta en el campo del correo electrónico en el formulario previo a Live Chat
schedule	string	cadena codificada en JSON (interruptores de días de la semana + from/to + timezone)	Horario operativo de Live Chat - consulta "Campos estructurados y rangos" para ver la estructura exacta
outOfHoursMessage	string		Mensaje mostrado cuando el horario indica que no hay atención
closeModalMessage	string		Título de la ventana modal "¿cerrar chat en vivo?"
closeModalConfirmLabel	string		Etiqueta del botón de confirmación en la ventana de cierre
closeModalCancelLabel	string		Etiqueta del botón de cancelación en la ventana de cierre
closeModalTooltipText	string		Mensaje emergente en el botón de cerrar chat
operatorHasJoinedLabel	string		Etiqueta mostrada cuando un agente se une
operatorDidNotJoinInTimeLabel	string		Etiqueta mostrada cuando ningún agente se une dentro del tiempo límite
waitingForOperatorToJoinLabel	string		Etiqueta mostrada mientras se espera a un agente
waitingForOperatorSeconds	int		Tiempo límite de espera para que un agente atienda (segundos)
redirectToHumanSupportForm	boolean		Si es true, redirige al formulario de Human Support cuando ningún agente atiende
requireAdminOnline	boolean		Requiere que haya un agente disponible según la configuración de presencia
presenceMode	string		Modo de presencia; utiliza el valor de un bot configurado en la interfaz
hideHumanSupportWhenLiveChatAvailable	boolean		Oculta el formulario de contacto cuando el chat en vivo está disponible
missedEmailEnabled	boolean	por defecto true	Envía un correo al propietario del bot cuando una solicitud de chat en vivo no fue atendida. En bots antiguos queda sin definir, lo que se interpreta como activado

requirePolicyAccept se encuentra en consent.liveChatRequirePolicyAccept, no aquí.

§ consent

Campo	Tipo	Restricción	Descripción
newConversationRequirePolicyAccept	boolean		Requiere la aceptación de la política de privacidad antes de iniciar una nueva conversación
humanSupportRequirePolicyAccept	boolean		Requiere la aceptación de la política de privacidad antes de enviar el formulario de asistencia humana
leadCollectionRequirePolicyAccept	boolean		Requiere la aceptación de la política de privacidad antes de enviar el formulario de captación de leads
liveChatRequirePolicyAccept	boolean		Requiere la aceptación de la política de privacidad antes de iniciar una sesión de chat en vivo
newConversationConsentDescription	string		Texto introductorio para la pantalla de consentimiento al inicio de la conversación
privacyPolicyConsentCheckboxLabel	string		Etiqueta junto a la casilla de verificación de consentimiento (suele contener un enlace a la política de privacidad)

§ whiteLabel

Campo	Tipo	Restricción	Descripción
hideRoboAssistLogo	boolean	funcionalidad de white-label; sujeta a los límites de la cuenta	Oculta el logotipo predeterminado de ChatLab en el pie de página
whitelabelLogoLink	string	funcionalidad de white-label; sujeta a los límites de la cuenta	URL a la que enlaza el logotipo personalizado del pie de página
assignToCustomDomain	boolean	sujeto a la función CUSTOM_DOMAIN	Aloja el chat en el dominio personalizado configurado
whitelabelLogoUrl	string	solo lectura	URL pública completa del logotipo de white-label; para cambiarlo, súbelo a través de la parte multipart whitelabel_logo

Multipart en POST/PATCH: whitelabel_logo (parte de archivo). Los cuerpos de GET / respuesta omiten el contenido del archivo; solo viaja la URL por la red.

§ security

Campo	Tipo	Restricción	Descripción
allowedDomains	string		Lista de dominios separados por comas autorizados para incrustar el widget (vacío = sin lista blanca)
spamFilterEnabled	boolean		Activa el filtro de spam por bot en los mensajes entrantes
countryFilterMode	string	BLACKLIST o WHITELIST	Cómo se interpretan las listas de países. Las listas en sí quedan restringidas solo a administradores
talkMessagesRateLimit	int	>= 0; 0 lo desactiva	Límite máximo de mensajes de usuario permitidos en la ventana de limitación de tasa
talkMessagesRateLimitDurationSeconds	int	>= 0	Duración de la ventana de limitación de tasa (segundos)
talkMessagesRateLimitHitMessage	string		Mensaje mostrado al visitante cuando se alcanza el límite de tasa

§ voice

Campo	Tipo	Restricción	Descripción
inputEnabled	boolean		Permite al visitante dictar mensajes (voz a texto)
conversationEnabled	boolean	requiere la función de voz en el plan	Activa conversaciones de voz completas
voiceId	string	identificador de voz específico del proveedor (p. ej. alloy)	Qué voz sintética habla
model	string	p. ej. GPT-REALTIME-MINI, GEMINI-LIVE, ELEVENLABS-*	Modelo de voz. Se factura por minuto, las tarifas varían según el modelo
turnDetection	string	específico del proveedor	Modo de detección de turnos de palabra
audioPrompt	string		Prompt de sistema adicional utilizado solo para turnos de voz
welcomeMessage	string		Frase inicial hablada
language	string	código de idioma	Idioma de voz principal
additionalLanguages	string	códigos de idioma separados por comas	Idiomas adicionales que acepta el agente de voz
maxDurationSeconds	int		Límite estricto de duración de una conversación de voz individual
maxDurationMessage	string		Mensaje mostrado cuando se alcanza el límite máximo

§ multilingual

Campo	Tipo	Restricción	Descripción
enabled	boolean		Interruptor del modo multilingüe
mode	string	AUTODETECT o FIXED_LIST	Cómo selecciona el bot el idioma de respuesta
baseLanguage	string	código de idioma	Idioma en el que están redactados los textos propios del bot
languages	string	códigos de idioma separados por comas	Idiomas ofrecidos al visitante
knowledgeLanguageMode	string	NONE, MAIN o DYNAMIC	Cómo se procesa el conocimiento en otros idiomas
knowledgeLanguageFallback	string	código de idioma	Idioma utilizado cuando no se encuentra ninguna coincidencia

§ advanced

Campo	Tipo	Restricción	Descripción
model	string	sujeto a los límites de la cuenta; consulta "Modelos de texto de IA" más arriba	Identificador del LLM (p. ej. 5.6-LUNA)
temperature	decimal	0.0-1.0	Temperatura de muestreo (coincide con el control deslizante de la interfaz)
chatContextSize	int	∈ {8000, 16000, 32000}; ajustado automáticamente al límite de tu cuenta	Límite de contexto configurado, incluyendo instrucciones, historial y base de conocimiento
botMessagesLimit	long	0 o múltiplo de 1000 (p. ej. 1000, 2000, 10000)	Límite mensual de créditos de mensajes del bot (0 = sin límite adicional en el bot; el límite de la cuenta sigue aplicándose)
internalLocale	string	código de configuración regional en formato ll_CC	Configuración regional para las etiquetas de la interfaz del widget (diferente de role.language)
productsViewEnabled	boolean		Si es true, muestra las Offer Cards de e-commerce dentro del chat
includeProductsInKnowledgeBase	boolean		Si es true, indexa el catálogo de productos como parte de la base de conocimiento

Fuera del alcance de la API

La interfaz de administración presenta algunas áreas que deliberadamente no están expuestas en esta versión de la Management API:

• Entrenamiento y eliminación: estos endpoints no permiten listar todos los bots, gestionar conjuntos de datos de entrenamiento ni eliminar bots. Utiliza la aplicación para esos flujos de trabajo.
• Pestaña Flow (flujo): el editor visual de Conversation Flow (etapas y transiciones). No está expuesto a través de la Management API.
• Pestaña Actions (acciones): integraciones gestionadas de e-commerce y reservas, AI Search y funciones personalizadas de la API. El uso de herramientas (tool calling) nunca ha formado parte de la Management API.
• El propio generador de formularios personalizados: no está expuesta la creación ni la edición de formularios personalizados. Sin embargo, puedes vincular un formulario existente a un bot mediante leadCollection.customFormId y humanSupport.customFormId.
• Iconos personalizados para abrir / cerrar el chat: customLauncherIconVisible, openChatIcon, closeChatIcon. La API solo expone las partes multipart principales avatar y whitelabel_logo.
• Listas de IP y países: las entradas en sí son exclusivas para administradores. Solo está expuesto el modo de interpretación, mediante security.countryFilterMode.

Endpoints

POST /v1/management/bots

Crea un nuevo bot. Se aceptan dos Content-Types equivalentes; elige el que te resulte más cómodo.

Modo A - JSON sin formato (recomendado si no necesitas subir un avatar o logotipo en la misma solicitud):

• Content-Type: application/json
• El cuerpo de la solicitud es el JSON de configuración del bot (sin el contenedor data)
• Los archivos (avatar o logotipo) se pueden subir más tarde mediante un segundo PATCH usando el modo B

Modo B - multipart/form-data (utilízalo cuando subas archivos en la misma solicitud):

• Content-Type: multipart/form-data; boundary=...
• Parte JSON data (obligatoria, Content-Type: application/json): configuración del bot en la estructura anidada descrita anteriormente
• Parte de archivo avatar (opcional): imagen de avatar del bot
• Parte de archivo whitelabel_logo (opcional): logotipo de marca blanca (aplica solo si tu cuenta incluye White Label)

Solo name es obligatorio en el JSON; todos los demás campos adoptan el mismo valor predeterminado que establecería el asistente de la interfaz de administración.

Ejemplo de cuerpo de solicitud

Este es el JSON data máximo: con cada sección completada. Envía solo las secciones que te interesen; todo lo demás tomará los valores predeterminados.

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

Reglas de validación con sus propios mensajes de error:

• name: obligatorio, máx. 150 caracteres
• advanced.temperature: entre 0.0 y 1.0
• chatMemory.summariesToKnowledgeRatio: entero entre 10 y 90 (porcentaje, intervalos de 10)
• appearance.launcherBottomMargin, appearance.launcherSideMargin: entre 0 y 500
• appearance.footerMarkdown: máx. 255 caracteres
• humanSupport.enabled=true requiere que humanSupport.email esté definido
• leadCollection.enabled=true requiere que al menos uno entre leadCollection.emailEnabled o leadCollection.phoneEnabled esté en true; cualquier canal activado también requiere su etiqueta, además de leaveDetailsMessage y thankYouMessage
• advanced.chatContextSize se ajusta automáticamente al tamaño máximo de contexto admitido por la cuenta. No asumas que otros campos numéricos se ajustan de manera automática.

Los campos cuyo valor sea null en el servidor se omiten del cuerpo JSON; la transmisión solo traslada campos con valores no nulos.

Ejemplo de cuerpo de respuesta (201)

La misma estructura que la solicitud, más el bloque de solo lectura meta y la clave de un solo uso apiKey en el nivel superior. Las URL de archivos de solo lectura (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) las completa el servidor cuando se han subido las partes multipart correspondientes.

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

El campo apiKey aparece únicamente al crear; es la clave recién generada de Bot Talk vinculada al nuevo bot. El texto sin formato se muestra una sola vez y no se puede recuperar después a través de la API; guárdala inmediatamente de tu lado.

El encabezado de respuesta Location contiene la URL del nuevo bot (/v1/management/bots/{id}).

Ejemplos de curl

Modo A - JSON sin formato (el más sencillo):

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

Modo B - multipart con avatar:

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}

Devuelve la configuración actual de un bot que te pertenece.

Ejemplo de curl

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

Ejemplo de cuerpo de respuesta (200)

La misma estructura que la respuesta de POST, sin la apiKey de un solo uso. Se incluye el bloque meta. Devuelve 404 not_found_error si el bot no existe o no pertenece a tu cuenta.

El avatar y el logotipo de marca blanca actuales se proporcionan como URL completas de solo lectura (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl), basadas en el mismo esquema + host + ruta de contexto que atendió esta solicitud. Obtén los bytes realizando una solicitud GET directa a esas URL; para reemplazar cualquiera de los archivos, sube uno nuevo mediante la parte multipart avatar o whitelabel_logo en PATCH. Estos campos de URL se ignoran si se envían en el cuerpo de una solicitud.

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

Clonar un bot

El cuerpo de la solicitud de POST /v1/management/bots y el cuerpo de la respuesta de GET /v1/management/bots/{bot_id} comparten la misma estructura, por lo que la clonación es un proceso de tres pasos: hacer GET del bot de origen, eliminar los campos de identidad gestionados por el servidor y hacer POST del resultado.

1. Haz GET del bot de origen.

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

2. Elimina el bloque superior meta. El objeto meta (id, createdAt, updatedAt) está gestionado por el servidor y es de solo lectura - dejarlo en el cuerpo del POST no causa ningún problema (el servidor lo ignora), pero quitarlo hace que la intención sea explícita y mantiene la carga útil limpia. De forma opcional, edita name para que el clon se distinga del origen.

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

3. Haz POST del cuerpo depurado para crear el clon. Consulta la referencia de POST /v1/management/bots anterior para conocer la estructura completa del cuerpo y las reglas de validación.

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

La respuesta contiene el meta.id del nuevo bot junto con una apiKey recién generada (la clave de Bot Talk para el clon). El texto en claro de apiKey se devuelve únicamente en esta respuesta de creación - cópiala antes de descartar el cuerpo de la respuesta; no se puede recuperar más tarde.

Esto copia la configuración admitida, no un chatbot totalmente entrenado. El contenido de entrenamiento, el historial de conversaciones, las integraciones/acciones, Flow y las definiciones de formularios no se clonan mediante estos endpoints. Configúralos por separado en la aplicación.

Advertencias adicionales:

• Los archivos no se clonan. appearance.avatarUrl y whiteLabel.whitelabelLogoUrl son de solo lectura y apuntan a los archivos del bot de origen. Si necesitas el mismo avatar o logotipo de white-label en el clon, descarga los bytes desde las URL de origen y súbelos como partes multipart avatar / whitelabel_logo, ya sea en el POST de creación (Modo B) o en un PATCH posterior.
• Las claves de Bot Talk no se clonan. Cada bot tiene su propio conjunto de claves de Bot Talk. La única apiKey devuelta por el POST de creación es la única que se genera automáticamente; crea claves adicionales desde la pestaña API (API) del bot si es necesario.

PATCH /v1/management/bots/{bot_id}

Actualiza uno o varios campos de un bot que te pertenezca. Solo se modifican las secciones / campos presentes en el JSON; todo lo omitido (o enviado como null) se deja sin cambios. Se aplican semánticas de actualización parcial por campo dentro de una sección enviada.

Se aceptan dos valores equivalentes de Content-Type (igual que en POST):

Modo A - JSON sin formato (recomendado cuando solo se actualizan ajustes):

• Content-Type: application/json
• El cuerpo de la solicitud es el JSON del patch (sin contenedor data)

Modo B - multipart/form-data (utilízalo al subir archivos):

• Parte JSON data (opcional) - el patch. Envíala solo si quieres cambiar campos. Omítela por completo si solo quieres subir un avatar o logotipo.
• Parte de archivo avatar (opcional) - reemplaza el avatar
• Parte de archivo whitelabel_logo (opcional) - reemplaza el logotipo de white-label (se aplica solo si tu cuenta incluye White Label)

Las tres partes son opcionales en PATCH, pero al menos una debe estar presente para que la llamada tenga efecto.

Ejemplo de cuerpo de solicitud (varias secciones)

Cualquier campo aceptado por POST /v1/management/bots también se puede enviar aquí. El siguiente ejemplo ilustra varias secciones, no todos los campos admitidos; en la práctica solo envías las claves que deseas cambiar (consulta "Actualización parcial mínima" más abajo) - cada clave omitida (o enviada como null) deja intacto el valor persistido.

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

Actualización parcial mínima

Haz PATCH de un solo campo enviando exactamente las claves que quieres cambiar; todo lo demás se conserva.

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

Ejemplos con Curl

Modo A - JSON sin formato (el más sencillo):

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

Modo B - multipart (al sustituir el avatar / logotipo):

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'

Modo B - sustituir solo el avatar (sin cambios en los campos):

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

Cuerpo de la respuesta (200)

Misma estructura que GET /v1/management/bots/{bot_id}: la configuración completa del bot tras aplicar el patch, incluido el bloque meta. Sin campo apiKey. Devuelve 404 not_found_error si el bot no existe o no pertenece a tu cuenta.

El siguiente ejemplo muestra la respuesta tras aplicar el patch del Cuerpo de solicitud completo (varias secciones) anterior al bot del ejemplo GET: los campos modificados reflejan los nuevos valores, los campos intactos se conservan y meta.updatedAt avanza.

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

Consulta el uso actual de la suscripción para la cuenta propietaria de la clave Management.

Cuerpo de la respuesta (200)

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

• subscriptionType es un identificador en minúsculas del plan actual de la cuenta (your-plan-id es un marcador de posición ilustrativo). Los planes provienen de un catálogo dinámico, por lo que el conjunto exacto de identificadores puede cambiar con el tiempo a medida que se renombran o añaden planes; trátalo como una cadena opaca, no como un enum fijo.
• messages.used / limit / remaining corresponden a los créditos de mensajes del mes natural actual, que se restablecen el primer día del mes, no el día de renovación de la suscripción. Están ponderados por créditos, no por recuentos brutos de respuestas.
• bots.used / limit / remaining contabilizan los bots en propiedad, incluidos los bots en pausa, respecto al límite total de bots de tu cuenta.

Encabezados de límite de velocidad

Las respuestas que llegan a la fase de límite de velocidad (es decir, tras superar la autenticación y la lista blanca de IP) incluyen:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1715430000

• X-RateLimit-Limit - el límite por clave aplicado efectivamente a esta llamada (10 por defecto, o tu valor configurado en rateLimitPerMinute si es menor).
• X-RateLimit-Remaining - tokens restantes en el depósito justo después de esta llamada.
• X-RateLimit-Reset - segundos epoch de Unix en los que el siguiente token estará disponible (no es un reinicio completo del depósito; el depósito se rellena de forma continua). Cuando el depósito está lleno, corresponde a la hora actual.

En las respuestas 429 rate_limit_exceeded, también se incluye Retry-After, expresado en segundos completos hasta que se libere al menos un token.

Los errores previos a la autenticación (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) y 403 ip_not_whitelisted no incluyen los encabezados X-RateLimit-* - el limitador solo se consulta tras superar con éxito la autenticación y las comprobaciones de IP.

Formato de error

La misma estructura que Bot Talk API:

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

Los errores de validación utilizan code: "invalid_parameter" y anteponen la ruta del campo con error al mensaje para que resulte fácil localizar la sección afectada:

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

Los valores no válidos para campos de tipo enum / conjunto cerrado (por ejemplo, chatMemory.clientSummaryPromptType = "BOGUS") incluyen la ruta del campo, el valor rechazado y la lista de valores permitidos:

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

Relacionado

Para consultar los endpoints de conversación y la transmisión SSE, consulta Bot Talk API.