Centro de ayuda
Chat API

Management API

Última actualización:

Información general sobre la Management API

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

  • crear un bot de forma programática 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 un 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 el panel de administración y ve a Account Settings > Management API (Configuración 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 tasa (rate limit), y luego envía el formulario.
  3. Copia la clave completa desde la ventana modal de confirmación. El texto sin formato solo se muestra una vez.

Una clave tiene el formato 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 solicitudes por minuto por clave (cubo de tokens, capacidad de 10, reposición gradual de ~1 token cada 6 segundos). Se puede configurar a un nivel inferior al momento de la creación: define un valor de rateLimitPerMinute más bajo y el tope disminuirá, escalando la tasa de reposición proporcionalmente.

Permisos

Cada clave de gestión admite cualquier subconjunto de los tres permisos siguientes. Se debe seleccionar al menos uno al momento de crearla; de lo contrario, la solicitud se rechazará con el error 400 invalid_request_error. Llamar a un endpoint con una clave que carezca del permiso requerido devuelve un error 403 insufficient_permissions.

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

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

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

  • role: perfil del bot, prompt sin procesar, longitud de respuesta, idioma, contexto del sitio web/empresa (pestaña Role & Behavior)
  • conversation: mensaje de bienvenida, refinamiento de consultas, continuidad de la conversación, interruptor de valoración + mensajes emergentes (tooltips), contenido de preguntas sugeridas + seguimiento dinámico (pestaña Chat Conversation)
  • chatMemory: interruptor de memoria del chat, prompts de resumen, asignación de contexto (pestaña Summaries & Memory)
  • appearance: colores, textos, dimensiones, CSS personalizado, pantalla de bienvenida, estilo de preguntas sugeridas, comportamiento de apertura automática, simulación de escritura humana, markdown del pie de página (pestaña Appearance)
  • humanSupport: formulario de contacto humano (pestaña Human Contact Form)
  • leadCollection: formulario de captación de clientes potenciales (pestaña Lead Collection)
  • liveChat: transferencia a chat en vivo (pestaña Live Chat)
  • consent: los cuatro interruptores de consentimiento de la política de privacidad junto con los textos de la pantalla de consentimiento (pestaña Consent & Privacy)
  • whiteLabel: ocultar logotipo, enlace personalizado del logotipo, alojamiento en dominio personalizado (pestaña Whitelabel)
  • security: dominios permitidos, filtro de spam, límites de tasa de conversación (pestaña Security)
  • voice: entrada de voz y conversaciones por voz: modelo, voz, idiomas, prompt, límite de duración (pestaña Voice Conversation)
  • multilingual: modo multilingüe, idioma base, idiomas ofrecidos, gestión del idioma del contenido (pestaña Languages)
  • advanced: modelo LLM, temperatura, tamaño de contexto, límite de mensajes del bot, configuración regional interna, Offer Cards (pestaña Model & Advanced)

Solo name se sitúa en el nivel superior, ya que identifica al bot en lugar de pertenecer a una pestaña en particular.

La barra lateral de configuración del bot incluye actualmente 15 subpestañas, y 13 de ellas corresponden a las secciones indicadas arriba. Las dos subpestañas que no cuentan con una sección equivalente son Flow y Actions, ambas descritas más adelante en la sección "Fuera del alcance de la API". Las 13 que sí tienen correspondencia 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 solicitud y el de la respuesta comparten la misma estructura. La respuesta añade dos elementos adicionales:

  • meta: de solo lectura: ID 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 la Bot Talk API recién generada para el nuevo bot.

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

  • appearance.avatarUrl: URL pública completa de la imagen de avatar del bot (por ejemplo, https://api.chatlab.com/aichat/content/avatar_xyz.png). Realiza una solicitud GET directa para descargar los bytes. Para modificarla, sube un nuevo archivo a través de la parte multiparte avatar (consulta PATCH).
  • whiteLabel.whitelabelLogoUrl: URL pública completa del logotipo de encabezado de marca blanca. Sigue el mismo patrón que avatarUrl. Para modificarla, sube un nuevo archivo a través de la parte multiparte whitelabel_logo (consulta PATCH).

Ambas URL utilizan el esquema, host y ruta de contexto de la solicitud actual; por lo tanto, en un dominio personalizado de marca blanca se devolverán vinculadas a la raíz de dicho dominio (por ejemplo, https://api.acme.com/aichat/content/...).

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

Configuración del rol y construcción del prompt

El prompt del sistema que realmente recibe el LLM se construye de dos maneras distintas según el valor de role.role. Saber en qué caso te encuentras te indicará qué campos se aplican y cuáles se almacenan pero se ignoran.

Caso A: role.role es CUSTOMER_SUPPORT, SALES o LEAD_COLLECTION_AGENT (basado en plantilla)

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

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

Este es el método recomendado para la mayoría de los bots: obtienes un comportamiento ajustado al rol y medidas de seguridad integradas sin esfuerzo adicional.

Caso B: role.role es CUSTOM (prompt proporcionado por el usuario)

El backend utiliza role.rawPrompt de forma literal como prompt completo del sistema. Los campos responseLength, language, websiteAddress y companyDescription se guardan pero no se insertan en el prompt; si deseas que alguno influya en el comportamiento del bot, debes incluirlo manualmente dentro del texto de tu rawPrompt. Tampoco se añaden instrucciones de tono ni restricciones de seguridad automáticas del rol; tú defines el prompt por completo.

Utiliza CUSTOM únicamente si el prompt generado mediante plantilla no se adapta a tu caso de uso (por ejemplo, si requieres una personalidad muy específica de un sector, tus propias medidas de seguridad o un formato de salida no estándar).

Campos de enumeración o conjunto cerrado

Diversos campos admiten únicamente un conjunto fijo de valores de cadena. Enviar un valor fuera de esta lista provocará el rechazo con un error 400 validation_failed y la ruta del campo en error.param. Los valores distinguen entre mayúsculas y minúsculas.

  • 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 del panel de administración; por ejemplo, Auto Detect, English, Polish, Spanish, German, French, Italian, Portuguese, Dutch, Russian, Chinese (Simplified), Japanese, Arabic, Hindi, entre otros ~80. El valor se guarda de forma literal y se inserta 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 errónea como "Output in en, unless...". El valor por defecto al crear el bot es Auto Detect si se omite.
  • advanced.model: consulta la sección "Modelos de texto de IA" más abajo; el conjunto disponible depende de los límites de tu cuenta, y cualquier valor no admitido devolverá un error 400 invalid_parameter
  • advanced.chatContextSize: 8000, 16000, 32000. Sujeto a los límites de tu cuenta; los valores que los superen se reducirán automáticamente al máximo permitido
  • chatMemory.clientSummaryPromptType: DEFAULT, CUSTOM
  • chatMemory.conversationSummaryPromptType: DEFAULT, CUSTOM
  • appearance.chatAlignment: left, right
  • appearance.minimizedDisplayMode: icon, minified
  • appearance.chatMessageLinkTarget: _blank, _self
  • leadCollection.requireBeforeNewConversation: selector booleano. true obliga al usuario a completar el formulario de captación antes de iniciar una conversación; false permite que la IA determine el momento adecuado para mostrar el formulario (por defecto).

Campos estructurados y rangos

Campos que parecen cadenas o números simples, pero que en realidad presentan formatos particulares, rangos o particularidades del panel de administración que conviene conocer.

  • advanced.temperature: el rango permitido 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 400 validation_failed.

  • chatMemory.summariesToKnowledgeRatio: porcentaje entero de 10-90 en pasos de 10. Determina qué proporción del contexto del chat se reserva para los resúmenes históricos del usuario frente al resto (base de conocimientos, conversación en curso, instrucciones). Valor por defecto: 50. Los valores fuera del rango 10-90 se rechazan con 400 validation_failed. Solo se aplica si chatMemory.enabled=true Y chatMemory.summaryConversationsEnabled=true.

  • liveChat.schedule: JSON codificado como una cadena de texto, no un objeto JSON anidado en el envío. El servidor guarda la cadena tal cual; el panel de administración la analiza en el cliente al procesar el editor de horarios. Una vez interpretada, la cadena consta de una entrada por cada día de la semana más una clave timezone:

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

    Ejemplo de valor (observa las comillas exteriores y las comillas interiores escapadas; se trata de un único campo de texto, no de 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 especificado, se muestra liveChat.outOfHoursMessage al visitante y se desactiva la transferencia al chat en vivo. La validación interna de este formato solo se realiza en el panel de administración del lado del cliente: la API aceptará como simple texto cualquier JSON con errores o claves desconocidas, lo que generará un fallo visual cuando un usuario acceda más tarde al bot en el panel. Comprueba la estructura por tu cuenta antes de enviarla.

  • conversation.positiveRatingTooltip / conversation.negativeRatingTooltip: etiquetas breves mostradas en los botones de 👍 / 👎 junto a cada respuesta de la IA cuando conversation.conversationRatingEnabled=true. El texto por defecto es "I like the response" / "I don't like the response". Visibles 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 la opción de marca blanca, el valor se almacena pero se ignora, mostrando siempre el pie de página.

  • 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 logotipo personalizado mediante la sección multiparte whitelabel_logo.

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

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

  • advanced.internalLocale: código de región e idioma según el formato IETF ll_CC (con guion bajo, NO ll-CC con guion). Los valores válidos corresponden a una lista cerrada 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, entre muchas otras. Enviar únicamente un código de dos letras ("en") o en formato BCP-47 ("en-US") no está admitido. Valor por defecto: en_US. Esta configuración regional determina el formato de fechas y números en la interfaz del widget, independientemente de role.language (el idioma en el que responde el bot).

  • security.talkMessagesRateLimit / security.talkMessagesRateLimitDurationSeconds: números enteros (enviar como números JSON, por ejemplo 30, no "30"). 0 desactiva el límite de tasa por dirección IP. Cuando es distinto de cero, el widget restringe el número de mensajes permitidos dentro del intervalo en segundos antes de mostrar al visitante el mensaje configurado en security.talkMessagesRateLimitHitMessage.

  • advanced.botMessagesLimit: número entero (número JSON, por ejemplo 1000). 0 equivale a "sin límite"; en cualquier otro caso debe ser un múltiplo de 1000 (1000, 2000, 10000, ...). Valores como 100 o 1500 se rechazan con 400 validation_failed. Además, el valor se ajustará automáticamente si excede el límite asignado a tu cuenta.

Modelos de texto de IA (advanced.model)

Envía el valor exacto de la API (columna izquierda entre comillas invertidas). El nombre mostrado en el panel de administración se indica entre paréntesis. Los límites de tu cuenta determinan cuáles están disponibles; si envías un modelo no habilitado para tu cuenta, recibirás un error 400 invalid_parameter. El modelo predeterminado para bots nuevos es 5-MINI.

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

Referencia de campos (esquema completo de la solicitud)

Cada campo enviado en la red, con su tipo, restricción y descripción en una línea. Semántica de PATCH: cualquier campo omitido (o enviado como null) deja intacto el valor guardado. Se utiliza la misma estructura para la respuesta (menos el contenido binario multipart; más el bloque meta de solo lectura en cada respuesta y apiKey únicamente en la respuesta de creación).

Nivel superior

Field Type Constraint Description
name string max 150, required on create 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 solo en la respuesta:

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

§ role

Field Type Constraint Description
role string (enum) CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM Ajuste predefinido del rol; selecciona la plantilla de prompt (consulta "Role and prompt construction")
language string full English language name (English, Polish, ...) or 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 para el contexto del prompt
companyDescription string Descripción de la empresa utilizada para el contexto del prompt
rawPrompt string Prompt del sistema personalizado - se utiliza literalmente solo cuando role=CUSTOM

§ conversation

Field Type Constraint Description
welcomeMessage string Primer mensaje mostrado al visitante al abrir el chat
queryRefinementEnabled boolean Si es true, perfecciona la pregunta del visitante antes de la recuperación RAG
conversationContinuityEnabled boolean Si es true, los visitantes que regresan reanudan su última conversación
conversationRatingEnabled boolean Si es true, muestra la calificación con pulgares arriba/abajo en los mensajes del bot
positiveRatingTooltip string Información sobre herramientas en el botón de calificación positiva
negativeRatingTooltip string Información sobre herramientas en el botón de calificación negativa
suggestedQuestions string Preguntas sugeridas separadas por saltos de línea / iniciadores de conversación
dynamicSuggestedFollowups boolean Si es true, la IA propone sugerencias de seguimiento después de cada respuesta
dynamicFollowupsAutoIcons boolean Si es true, la IA selecciona automáticamente iconos de emoji para los seguimientos dinámicos

§ chatMemory

Field Type Constraint Description
enabled boolean Interruptor principal para la función de memoria de chat
summaryConversationsEnabled boolean Guardar resúmenes por conversación
conversationSummaryPrompt string Prompt personalizado utilizado para resumir cada conversación
conversationSummaryPromptType string (enum) ∈ {DEFAULT, CUSTOM} Indica si se debe utilizar el prompt de resumen predeterminado o personalizado
clientSummaryPrompt string Prompt personalizado utilizado para resumir al cliente a lo largo de las conversaciones
clientSummaryPromptType string (enum) ∈ {DEFAULT, CUSTOM} Prompt de perfil de cliente predeterminado frente a personalizado
summariesToKnowledgeRatio int 10-90, step 10 % de la ventana de contexto del chat asignado a resúmenes frente al conocimiento RAG

§ appearance

Field Type Constraint Description
launcherColor string (hex) Color de fondo del lanzador (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 de la burbuja del mensaje del visitante
clientMessageTextColor string (hex) Color del texto del mensaje del visitante
responseMessageBubbleColor string (hex) Color de la burbuja de respuesta del bot
responseMessageTextColor string (hex) Color del texto de respuesta del bot
chatSubheader string Lema mostrado debajo del título del chat
senderPlaceholder string Texto de marcador de posición en el campo de entrada del mensaje
resetConversationTooltip string Información sobre herramientas en el botón "reset conversation" (reiniciar conversación)
chatAlignment string (enum) ∈ {left, right} En qué lado de la pantalla se ancla el chat
launcherBottomMargin int 0-500 Distancia del lanzador desde el borde inferior (px)
launcherSideMargin int 0-500 Distancia del lanzador desde el borde lateral (px)
displayShadow boolean Sombra paralela debajo del widget
customCss string CSS en bruto 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} Estado minimizado: icono de lanzador o barra de envío compacta
chatDesktopWidthPx int Ancho del widget en escritorio
chatDesktopHeightPx int Altura del widget en escritorio
chatMobileSizePercent int Tamaño del widget en móviles como % de la ventana gráfica
messageFontSize int Tamaño de fuente del texto del mensaje (px)
showChatbotBubblesDesktop boolean Mostrar las burbujas flotantes de llamada de atención en escritorio
showChatbotBubblesMobile boolean Mostrar las burbujas flotantes de llamada de atención en móviles
chatbotBubblesDelaySeconds int Retraso antes de que aparezcan las burbujas flotantes (segundos)
launcherIconFullSize boolean Renderizar el icono del lanzador personalizado de borde a borde en lugar de insertado
welcomeScreenEnabled boolean Mostrar la pantalla de bienvenida en lugar de ir directamente al chat
welcomeScreenQuestionsLabel string Etiqueta sobre las preguntas sugeridas en la pantalla de bienvenida
welcomeScreenHideHumanContactForm boolean Ocultar la acción del formulario de contacto humano en el encabezado mientras se muestra la pantalla de bienvenida. Reaparece después del primer mensaje del visitante. Los bots creados antes del 2026-09-02 tienen el valor predeterminado true
welcomeScreenHideLiveChat boolean Ocultar la acción de Live Chat en el encabezado mientras se muestra la pantalla de bienvenida. Reaparece después del primer mensaje del visitante. Los bots creados antes del 2026-09-02 tienen el valor predeterminado true
headerActionsLayout string DROPDOWN Cómo se ofrecen el chat en vivo y el formulario de contacto humano en el encabezado del chat: ICONS (un icono separado para cada uno) o DROPDOWN (agrupados en el menú del encabezado). Los bots creados antes del 2026-09-02 tienen el valor predeterminado ICONS
stackSuggestedQuestions boolean Apilar las preguntas sugeridas verticalmente (frente a lado a lado)
suggestedQuestionsFontSize int Tamaño de fuente de las etiquetas de preguntas sugeridas (px)
suggestedQuestionsTextColor string (hex) Color del texto de las etiquetas de preguntas sugeridas
suggestedQuestionsBackgroundColor string (hex) Color de fondo de las etiquetas de preguntas sugeridas
autoOpenChat boolean Abrir automáticamente el chat en escritorio
autoOpenChatOnMobiles boolean Abrir automáticamente el chat en móviles
autoOpenChatDelay boolean Usar un retraso antes de la apertura automática
autoOpenChatDelaySeconds int Retraso de la apertura automática (segundos)
simulateHumanTyping boolean Dividir la respuesta del bot en burbujas con animación de escritura
simulateHumanTypingDelay int 0-200 Retraso entre los mensajes en burbuja (segundos)
footerMarkdown string max 255 Markdown personalizado en el pie de página que se muestra debajo del chat
avatarUrl string read-only URL pública completa del avatar; para cambiarla, súbela a través de la parte multipart avatar

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

§ humanSupport

Field Type Constraint Description
enabled boolean Interruptor del flujo de asistencia humana
email string required (create-strict) when enabled=true Dirección que recibe los correos de asistencia humana
dialogMessage string Mensaje motivador mostrado sobre el formulario
thankYouMessage string Confirmación mostrada después del envío
emailMessageSubjectTemplate string Plantilla de asunto para el correo electrónico enviado al agente
emailMessageContentTemplate string Plantilla de cuerpo para el correo electrónico enviado al agente
emailPlaceholder string Marcador de posición en el campo de 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 of an existing custom form Reemplaza el formulario de contacto integrado por un formulario personalizado. null conserva el formulario integrado
customFormMapping string JSON-encoded string Asigna los campos del formulario personalizado a los campos de correo de asistencia humana

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

§ leadCollection

Field Type Constraint Description
enabled boolean Interruptor del formulario de clientes potenciales
nameEnabled boolean Recopilar nombre
nameLabel string Etiqueta en el campo del nombre
emailEnabled boolean Recopilar correo electrónico
emailLabel string required (create-strict) when enabled=true AND emailEnabled=true Etiqueta en el campo del correo electrónico
phoneEnabled boolean Recopilar teléfono
phoneLabel string required (create-strict) when enabled=true AND phoneEnabled=true Etiqueta en el campo del teléfono
leaveDetailsMessage string required (create-strict) when enabled=true Mensaje que anima al visitante a dejar sus datos
thankYouMessage string required (create-strict) when enabled=true Confirmación mostrada después del envío
requireBeforeNewConversation boolean Si es true, el formulario debe enviarse antes de iniciar el chat; si es false, la IA decide cuándo mostrar el formulario
emailNotificationEnabled boolean Enviar un correo al propietario cada vez que se recopila un cliente potencial
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

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

| customFormId | long | id of an existing custom form | Reemplaza el formulario de captación de clientes potenciales integrado por un formulario personalizado. null conserva el formulario integrado | | customFormMapping | string | JSON-encoded string | Asigna los campos del formulario personalizado a nombre / correo electrónico / teléfono |

§ liveChat

Field Type Constraint Description
enabled boolean Interruptor de la función Live Chat
infoMessage string Mensaje explicativo antes de 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 JSON-encoded string (weekday toggles + from/to + timezone) Horario de atención del chat en vivo - consulta "Structured fields and ranges" para conocer el formato exacto
outOfHoursMessage string Mensaje mostrado cuando el horario indica que estamos fuera de servicio
closeModalMessage string Título del modal "¿cerrar chat en vivo?"
closeModalConfirmLabel string Etiqueta del botón de confirmación en el modal de cierre
closeModalCancelLabel string Etiqueta del botón de cancelación en el modal de cierre
closeModalTooltipText string Información sobre herramientas en el elemento para cerrar el chat
operatorHasJoinedLabel string Etiqueta mostrada cuando un operador se une
operatorDidNotJoinInTimeLabel string Etiqueta mostrada cuando ningún operador se une dentro del tiempo de espera
waitingForOperatorToJoinLabel string Etiqueta mostrada mientras se espera a un operador
waitingForOperatorSeconds int Tiempo de espera para que un operador responda (segundos)
redirectToHumanSupportForm boolean Si es true, redirige al formulario de asistencia humana cuando ningún operador responde
missedEmailEnabled boolean default true Envía un correo al propietario del bot cuando una solicitud de chat en vivo no fue atendida. No se define en bots antiguos, lo cual se interpreta como habilitado

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

§ consent

Field Type Constraint Description
newConversationRequirePolicyAccept boolean Requerir el consentimiento de la política de privacidad antes de iniciar una nueva conversación
humanSupportRequirePolicyAccept boolean Requerir el consentimiento de la política de privacidad antes de enviar el formulario de asistencia humana
leadCollectionRequirePolicyAccept boolean Requerir el consentimiento de la política de privacidad antes de enviar el formulario de captación de clientes potenciales
liveChatRequirePolicyAccept boolean Requerir el consentimiento 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 consentimiento (normalmente contiene un enlace a la política de privacidad)

§ whiteLabel

Field Type Constraint Description
hideRoboAssistLogo boolean white-label capability; subject to account limits Ocultar el logotipo predeterminado de ChatLab en el pie de página
whitelabelLogoLink string white-label capability; subject to account limits URL a la que enlaza el logotipo personalizado del pie de página
assignToCustomDomain boolean gated by CUSTOM_DOMAIN feature Alojar el chat en el dominio personalizado configurado
whitelabelLogoUrl string read-only 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 respuesta GET omiten el contenido del archivo; solo la URL se envía por la red.

§ security

Field Type Constraint Description
allowedDomains string Lista separada por comas de dominios autorizados para insertar el widget (vacío = sin lista blanca)
spamFilterEnabled boolean Habilitar el filtro de spam por bot en los mensajes entrantes
countryFilterMode string BLACKLIST or WHITELIST Cómo se interpretan las listas de países. Las listas en sí quedan restringidas solo para administradores
talkMessagesRateLimit int >= 0; 0 disables Cantidad máxima de mensajes de usuario permitidos en la ventana de límite de frecuencia
talkMessagesRateLimitDurationSeconds int >= 0 Duración de la ventana de límite de frecuencia (segundos)
talkMessagesRateLimitHitMessage string Mensaje mostrado al visitante cuando se alcanza el límite de frecuencia

§ voice

Field Type Constraint Description
inputEnabled boolean Permitir al visitante dictar mensajes (voz a texto)
conversationEnabled boolean requires the voice feature on the plan Habilitar conversaciones completas por voz
voiceId string provider-specific voice id (e.g. alloy) Qué voz sintética habla
model string e.g. GPT-REALTIME-MINI, GEMINI-LIVE, ELEVENLABS-* Modelo de voz. Se factura por minuto, las tarifas varían según el modelo
turnDetection string provider-specific Modo de alternancia de turnos
audioPrompt string Prompt del sistema adicional utilizado únicamente para los turnos de voz
welcomeMessage string Frase de apertura hablada
language string language code Idioma de voz principal
additionalLanguages string comma-separated language codes Idiomas adicionales que admite el agente de voz
maxDurationSeconds int Límite máximo para una sola conversación de voz
maxDurationMessage string Mensaje mostrado cuando se alcanza el límite

§ multilingual

Field Type Constraint Description
enabled boolean Interruptor del modo multilingüe
mode string AUTODETECT or a fixed-list mode Cómo elige el bot el idioma de respuesta
baseLanguage string language code Idioma en el que está redactado el texto propio del bot
languages string comma-separated language codes Idiomas ofrecidos al visitante
knowledgeLanguageMode string Cómo se trata el conocimiento en otros idiomas
knowledgeLanguageFallback string language code Idioma utilizado cuando no se encuentra ninguna coincidencia

§ advanced

Field Type Constraint Description
model string subject to account limits; see "AI text models" above Identificador de LLM (por ejemplo, 5-MINI)
temperature decimal 0.0-1.0 Temperatura de muestreo (coincide con el control deslizante de la interfaz)
chatContextSize int ∈ {8000, 16000, 32000}; silently clamped to your account limit Ventana de tokens para el historial de chat
botMessagesLimit long 0 or multiple of 1000 (e.g. 1000, 2000, 10000) Respuestas máximas del bot por conversación (0 = sin límite)
internalLocale string locale code in ll_CC form 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 usuario del panel de administración muestra algunas áreas que intencionadamente no están expuestas en esta versión de la Management API:

  • Pestaña Flow (Flujo) - el editor visual Conversation Flow (etapas y transiciones). No está expuesto a través de la Management API.
  • Pestaña Actions (Acciones) - integraciones gestionadas de e-commerce / reservas, AI Search y funciones de API personalizadas. La llamada a herramientas nunca ha formado parte de la Management API.
  • El creador de formularios personalizados en sí - la creación y edición de formularios personalizados no está expuesta. Sin embargo, puedes vincular un formulario existente a un bot a través de 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 se expone el modo de interpretación, a través de security.countryFilterMode.

Endpoints

POST /v1/management/bots

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

Modo A - JSON simple (recomendado cuando 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 adelante 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 White Label (se aplica solo si tu cuenta incluye White Label)

En el JSON solo es obligatorio el campo name; el resto de campos adoptan el mismo valor predeterminado que establecería el asistente de la interfaz de administración.

Cuerpo completo de la solicitud

Este es el JSON maximal de data, con todas las secciones completadas. 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-MINI",
    "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áximo 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áximo 255 caracteres
  • humanSupport.enabled=true requiere que humanSupport.email esté definido
  • leadCollection.enabled=true requiere que al menos uno de los campos leadCollection.emailEnabled o leadCollection.phoneEnabled sea true; el canal activado requiere también su etiqueta correspondiente, además de leaveDetailsMessage y thankYouMessage
  • Los campos con límite (advanced.chatContextSize, advanced.botMessagesLimit, etc.) se ajustan automáticamente a los límites de tu cuenta

Los campos cuyo valor sea null en el servidor se omiten del cuerpo JSON; la transmisión solo incluye campos con valores distintos de null.

Cuerpo completo de la respuesta (201)

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. El servidor completa las URL de archivo de solo lectura (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) 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-MINI",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  },
  "meta": {
    "id": 4287,
    "createdAt": "2026-06-01T10:11:02Z",
    "updatedAt": "2026-06-01T10:11:02Z"
  },
  "apiKey": "ck_freshly_minted_bot_talk_key_here"
}

El campo apiKey aparece solo al crear el bot; es la clave de Bot Talk recién generada y vinculada al nuevo bot. El texto sin formato se muestra una sola vez y no se puede recuperar más tarde desde la API; guárdalo de inmediato por tu cuenta.

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

Ejemplos de Curl

Modo A - JSON simple (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 de tu propiedad.

Ejemplo de Curl

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

Cuerpo completo de la respuesta (200)

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

El avatar actual y el logotipo de White Label se devuelven como URL de solo lectura completas (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 sustituir cualquiera de los dos archivos, sube uno nuevo mediante la parte multipart avatar / 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-MINI",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  },
  "meta": {
    "id": 4287,
    "createdAt": "2026-06-01T10:11:02Z",
    "updatedAt": "2026-06-01T11:02:19Z"
  }
}

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: obtener con GET el bot de origen, eliminar los campos de identidad gestionados por el servidor y enviar con POST el resultado.

1. GET del bot de origen.

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

2. Eliminar el bloque de nivel superior meta. El objeto meta (id, createdAt, updatedAt) es gestionado por el servidor y de solo lectura; dejarlo en el cuerpo del POST no causa ningún problema (el servidor lo ignora), pero eliminarlo hace que la intención sea explícita y mantiene limpia la carga útil. Si lo deseas, puedes editar name para distinguir el clon del origen.

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

3. POST del cuerpo limpio para crear el clon. Consulta la referencia de POST /v1/management/bots más arriba 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 solo en esta respuesta de creación; cópialo antes de descartar el cuerpo de la respuesta, ya que no se puede recuperar más tarde.

Dos advertencias:

  • 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 marca blanca 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 del bot si las necesitas.

PATCH /v1/management/bots/{bot_id}

Actualiza uno o más campos de un bot que te pertenezca. Solo se modifican las secciones o campos presentes en el JSON; todo lo omitido (o enviado como null) se deja intacto. La semántica de actualización parcial se aplica por campo dentro de una sección enviada.

Se aceptan dos Content-Types equivalentes (igual que en POST):

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

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

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

  • Parte JSON data (opcional) - la modificación. Envíala solo si deseas cambiar campos. Omítela por completo si solo quieres subir un avatar o un logotipo.
  • Parte de archivo avatar (opcional) - reemplaza el avatar
  • Parte de archivo whitelabel_logo (opcional) - reemplaza el logotipo de marca blanca (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 sentido.

Cuerpo de solicitud completo (superficie máxima)

Cualquier campo aceptado por POST /v1/management/bots también puede enviarse aquí. El ejemplo a continuación muestra la superficie completa; 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 el valor guardado intacto.

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

Modifica mediante PATCH un solo campo enviando exactamente las claves que deseas cambiar; todo lo demás se conserva.

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

Ejemplos de curl

Modo A - JSON simple (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 reemplazar avatar o 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 - reemplazar 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 después de aplicar la modificación, 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 la modificación del Cuerpo de solicitud completo (superficie máxima) anterior al bot del ejemplo GET: los campos modificados reflejan los nuevos valores, los campos no modificados se conservan y meta.updatedAt se actualiza.

{
  "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 de la cuenta propietaria de la clave de Management.

Cuerpo de la respuesta (200)

{
  "subscriptionType": "standard",
  "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 (por ejemplo, standard en el ejemplo). Los planes provienen de un catálogo dinámico, por lo que el conjunto exacto de identificadores puede variar con el tiempo a medida que se cambian de nombre o se añaden nuevos planes; trátalo como una cadena opaca, no como un enum fijo.
  • messages.used / limit / remaining corresponden a los créditos de mensajes del periodo de facturación actual.
  • bots.used / limit / remaining cuantifican los bots activos respecto al límite de bots de tu cuenta.

Encabezados de límite de frecuencia

Las respuestas que llegan a la etapa de límite de frecuencia (es decir, cuando se superan 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 a esta llamada (10 por defecto, o tu rateLimitPerMinute configurado si es menor).
  • X-RateLimit-Remaining - tokens restantes en el depósito justo después de esta llamada.
  • X-RateLimit-Reset - segundos en tiempo Unix epoch en los que el siguiente token estará disponible (no es un restablecimiento completo del depósito; el depósito se recarga 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 enteros 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 después de que la autenticación y las comprobaciones de IP se completan con éxito.

Formato de error

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 usan code: "invalid_parameter" y anteponen la ruta del campo fallido al mensaje para que la sección con el error sea fácil de identificar:

{
  "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 enumeración o 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 la Bot Talk API.

Buscar en todos los artículosPregunta al agente