Widget Configuration

Lee y actualiza la configuración del widget para sitios web mediante la API.

El widget es una interfaz de chat que incrustas en tu sitio web: aparece como una burbuja flotante en la esquina de la página que los visitantes pueden pulsar para abrir una conversación con tu Agente de IA. El widget es totalmente personalizable: controlas sus colores, tamaño, posición, mensajes de saludo y comportamiento.

Estos ajustes también afectan al embed, que es una versión a página completa o en línea de la misma interfaz de chat que puedes colocar directamente en el diseño de tu página web (en lugar de la burbuja flotante). Tanto el widget como el embed comparten la misma configuración de apariencia, mensajería y comportamiento.

Con estos endpoints puedes personalizar de forma programática cómo aparece Quickchat AI en tu sitio web: ajustar los colores a tu marca, configurar formularios previos al chat para recopilar información del visitante, configurar indicadores de escritura, activar la entrada por voz y más. Para instrucciones de configuración, consulta la guía del canal Website.

Scope: read_all

GET https://app.quickchat.ai/v1/api/widget/configuration

Shell
Python

curl https://app.quickchat.ai/v1/api/widget/configuration \
  -H 'Authorization: Bearer <API_TOKEN>'

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/widget/configuration",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Response 200 OK

{
  "welcome_message": "<p>Hello! How can I help?</p>",
  "welcome_message2": "",
  "header": "Support",
  "subtitle": "We typically reply within minutes",
  "conversation_starters": ["What are your opening hours?", "How do I track my order?", "Talk to a human"],
  "popup_active": true,
  "input_placeholder": "Type your message...",
  "primary_color": "rgb(0, 122, 255)",
  "voice_active": false,
  "header_color": "rgb(0, 122, 255)",
  "header_collapse": false,
  "header_text_color": true,
  "typing": true,
  "window_auto_open": false,
  "white_label": false,
  "prechat_active": false,
  "prechat_header_text": null,
  "prechat_button_text": null,
  "prechat_message_text": null,
  "background_disclaimer_text": null,
  "streaming_active": true,
  "link_tracking_active": false,
  "window_height": 600,
  "window_width": 400,
  "size": "medium",
  "location": "bottom-right",
  "launcher_label": "Ask AI",
  "launcher_draggable": false,
  "avatar_image": "https://storage.googleapis.com/quickchat-files/appquickchat/media/chat_avatars/default_bubble.png",
  "bubble_icon_image": "https://storage.googleapis.com/quickchat-files/appquickchat/media/chat_avatars/default_bubble.png",
  "default_avatar_image": "https://storage.googleapis.com/quickchat-files/appquickchat/media/chat_avatars/default_bubble.png",
  "theme": "light",
  "widget_theme_custom": {
    "colors": {
      "background": "#ffffff",
      "header": "#ffffff",
      "header_text": "#030712",
      "accent": "#27272a",
      "accent_hover": "#374151",
      "accent_text": "#ffffff",
      "bubble": "#27272a",
      "bubble_text": "#ffffff",
      "ai_bubble_text": "#030712",
      "tertiary": "#afafb2",
      "link": null,
      "input_background": "#ffffff",
      "input_text": "#030712",
      "input_placeholder": "#9ca3af",
      "border": "#e5e7eb",
      "sidebar": {
        "background": "#f5f5f5",
        "text": null,
        "accent": "#e5e5e5",
        "accent_text": null
      }
    },
    "radius": { "bubble": "full", "input": "full", "button": "full" },
    "font": { "size": "base" }
  }
}

Content & Messaging

Field	Description
`welcome_message` string	Mensaje de bienvenida principal que se muestra al abrir el widget (HTML). Dashboard: Website > Greeting
`welcome_message2` string	Mensaje de bienvenida secundario mostrado debajo del saludo principal
`header` string	Texto mostrado en la barra de cabecera del widget. Dashboard: Website > Header
`subtitle` string	Texto de subtítulo mostrado debajo de la cabecera. Dashboard: Website > Subtitle
`input_placeholder` string	Texto de marcador de posición en el campo de entrada de mensajes (p. ej., “Type your message…”)
`conversation_starters` array of strings or null	Sugerencias de apertura mostradas como botones pulsables cuando se abre el widget. Hasta 3 entradas, cada una de hasta ~100 caracteres
`background_disclaimer_text` string or null	Texto de aviso mostrado en la parte inferior de la ventana de chat

Appearance

Field	Description
`primary_color` string	Color de acento del widget como valor CSS rgb (p. ej., `"rgb(0, 122, 255)"`). Se usa para botones, enlaces y burbujas de mensaje del usuario
`header_color` string	Color de fondo de la cabecera como valor CSS rgb
`header_text_color` boolean	Brillo del texto de la cabecera. `true` = texto blanco/claro (para cabeceras oscuras), `false` = texto oscuro (para cabeceras claras). Nota: a pesar del nombre, es un boolean, no una cadena de color
`size` string	Preset de tamaño del launcher: `"small"`, `"medium"` o `"large"` (mostrados en el dashboard como Small, Input Only y Classic)
`location` string	Posición del widget en la página: `"top-left"`, `"top-right"`, `"bottom-left"` o `"bottom-right"`
`launcher_label` string or null	Texto del botón launcher small (`size: "small"`), máx. 25 caracteres. `null` usa el valor por defecto (`"Ask AI"`); `""` muestra un launcher solo con icono
`launcher_draggable` boolean	Permitir que los visitantes arrastren el launcher a una posición distinta de la página
`window_height` integer	Altura del widget en píxeles (400-1200)
`window_width` integer	Anchura del widget en píxeles (300-700)
`avatar_image` string or null	URL del AI Agent Avatar, mostrado tanto en la cabecera del chat como en el icono de la burbuja flotante. Súbelo mediante PATCH como base64. `null` significa que el avatar se eliminó y el widget no muestra avatar
`bubble_icon_image` string or null	Obsoleto. Siempre refleja `avatar_image`: el icono de la burbuja y el avatar del chat son ahora una sola imagen (consulta Unificación del AI Agent Avatar)
`default_avatar_image` string	Solo lectura. URL del AI Agent Avatar por defecto que restaura `use_default_avatar`
`theme` string	Modo del tema de color: `"light"` o `"dark"` (presets fijos) o `"custom"` (aplica la paleta `widget_theme_custom`)
`widget_theme_custom` object	Paleta personalizada que se aplica cuando `theme` es `"custom"`. Contiene `colors` (header, accent, burbuja de mensaje, texto de la IA, `link`, input, border y más, como hex o `rgb()`/`rgba()`), `radius` (`"sm"`/`"base"`/`"lg"`/`"full"` para burbujas, input y botones) y `font.size` (`"sm"`/`"base"`/`"lg"`). En PATCH, envía el objeto completo: las claves que falten se restablecen a sus valores por defecto. `colors.link` es `null` por defecto, lo que significa que los enlaces heredan el color del texto que los rodea. `colors.sidebar` (`background`, `text`, `accent`, `accent_text`) aplica el tema únicamente a la barra lateral de la Chat Page independiente (las vistas de burbuja y embed lo ignoran); sus `text` y `accent_text` son `null` por defecto, lo que significa que se deriva automáticamente un color legible a partir del fondo correspondiente

Behavior

Field	Description
`popup_active` boolean	Mostrar un aviso emergente cerca de la burbuja del widget para animar a los visitantes a iniciar una conversación
`window_auto_open` boolean	Abrir automáticamente el widget al cargar la página (en lugar de mostrar solo la burbuja)
`header_collapse` boolean	Permitir que los visitantes contraigan el área de la cabecera para tener más espacio de chat
`typing` boolean	Mostrar una animación de indicador de escritura mientras la IA genera una respuesta
`streaming_active` boolean	Transmitir las respuestas de la IA palabra por palabra en lugar de mostrar el mensaje completo de golpe
`voice_active` boolean	Activar la entrada por voz: los visitantes pueden enviar mensajes usando su micrófono
`link_tracking_active` boolean	Registrar cuándo los visitantes pulsan enlaces en las respuestas de la IA. Los clics registrados aparecen como eventos `tracked_link` en Conversation Events
`white_label` boolean	Eliminar la marca “Powered by Quickchat” del widget

Pre-chat Form

Field	Description
`prechat_active` boolean	Activar el formulario previo al chat. Cuando está activo, los visitantes deben rellenar el formulario antes de chatear
`prechat_header_text` string or null	Texto de cabecera del formulario previo al chat
`prechat_button_text` string or null	Etiqueta del botón de envío del formulario previo al chat
`prechat_message_text` string or null	Texto/instrucciones del cuerpo mostradas en el formulario previo al chat (HTML)

Scope: write_all

PATCH https://app.quickchat.ai/v1/api/widget/configuration

Request Body — Todos los campos son opcionales. Incluye solo los campos que quieras actualizar.

AI Agent Avatar unification

El avatar del chat (logo de la cabecera) y el icono de la burbuja flotante (launcher) se fusionaron en una sola imagen, el AI Agent Avatar, almacenado en avatar_image. El icono de la burbuja siempre lo refleja: ya no existe una imagen de launcher independiente. Si te integras directamente con este endpoint, ten en cuenta los siguientes cambios de comportamiento:

Subir mediante bubble_icon_image está obsoleto: ahora establece el AI Agent Avatar unificado, que también reemplaza la imagen mostrada en la cabecera del chat. Usa avatar_image en su lugar.
bubble_icon_image: null es una operación sin efecto. Antes borraba el icono del launcher; como el launcher refleja el avatar, elimínalo con avatar_image: null en su lugar.
Los Agentes que nunca personalizaron su avatar muestran el AI Agent Avatar por defecto (consulta default_avatar_image en la respuesta) tanto en la cabecera como en el launcher.

Shell
Python

curl -X PATCH https://app.quickchat.ai/v1/api/widget/configuration \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "primary_color": "rgb(255, 87, 34)",
  "header": "Sales Assistant",
  "window_auto_open": true
}'

import requests

response = requests.patch(
    url="https://app.quickchat.ai/v1/api/widget/configuration",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "primary_color": "rgb(255, 87, 34)",
        "header": "Sales Assistant",
        "window_auto_open": True,
    },
)
data = response.json()

Response 200 OK — Devuelve la configuración del widget actualizada (mismo esquema que la respuesta de Get Widget Configuration).

Widget Configuration