Widget IA | Plazbot Docs

Introducción

Con el SDK de Plazbot puedes activar un Widget de chat IA para tu página web. El widget es una funcionalidad del Agente de IA.

La activacion del widget requiere una llamada independiente al método enableWidget. No se activa al actualizar el agente con updateAgent.

Importante: Los agentes asociados a Widgets deben tener useToolCalling: true activado para que el streaming SSE funcione correctamente. Los nuevos agentes ya se crean con esta opción activada por defecto.

Activacion

01const result = await plazbot.agent.enableWidget({ id: agentId, enable: true });
02console.log(result.script); // Script para instalar en tu web

El sistema retorna el script HTML que debes instalar en tu página web:

html

01<script id="id-widget-agent-plz" type="module" defer
02  src="https://storagelaplazbot.z13.web.core.windows.net/widget.js?Id={ID_AGENT}&zone={ZONE}&workspaceId={WORKSPACE_ID}">
03</script>

Funcionalidades del chat

Funcionalidad	Descripción
Respuestas rapidas	Si un campo de un servicio o acción del agente tiene botones configurados (`requiredFields[].buttons`), el widget los muestra bajo el mensaje del agente. El usuario responde con un clic
Asesor humano	Cuando un asesor responde desde el CRM, su mensaje aparece con su nombre, diferenciado de la IA. Si el bot esta apagado para el contacto, el usuario ve el aviso "Un asesor te respondera por aquí en breve"
Mensajes sin leer	Si llega un mensaje con el widget cerrado o la pestaña en segundo plano, el botón flotante muestra un contador y el título de la pestaña indica `(n)`
Conversación persistente	Volver a la pantalla de inicio no borra la conversación: el usuario la retoma con "Continuar conversación"
Resumen por correo	Al solucionar el chat, el contacto recibe un correo con el resumen y el historial de la conversación. Se activa en Settings → Chat → Enviar resumen por correo al solucionar el chat (apagado por defecto, aplica a todos los canales y requiere que el contacto tenga email)

Para controlar el widget desde tu sitio (abrirlo desde tus botones, identificar al usuario, escuchar mensajes), usa la API JavaScript del Widget.

Desactivacion

01await plazbot.agent.enableWidget({ id: agentId, enable: false });

Configuración en agent.config.json

Basicos

Campo	Tipo	Descripción
`enableWidget`	`boolean`	Activa o desactiva el widget
`typeWidget`	`string`	Tipo de widget: `widget` (chat lateral) o `search` (buscador centrado)
`nameWidget`	`string`	Texto de la cabecera del widget
`question`	`string`	Pregunta principal de la pantalla de inicio
`initialShowWidget`	`boolean`	Si el widget aparece abierto al cargar la página
`initialViewWidget`	`string \| null`	Vista inicial al abrir el widget: `home`, `chat` o `avatar`. `null` equivale a `home` (legacy)
`positionWidget`	`string`	Posición al abrirse: `down` (abajo-derecha clasico) o `center` (centrado en pantalla). Solo aplica en desktop; en mobile siempre es fullscreen. Default: `down`
`iconWidget`	`string`	Icono del botón flotante: `robot`, `message`, `support`, `qa`, `chat`, `smile`, `voice`, `uservoice`

Tema visual

El widget soporta 5 temas. colorWidget tiene prioridad sobre darkWidget (legacy).

Campo	Tipo	Descripción
`colorWidget`	`string \| null`	Tema visual: `white` \| `dark` \| `green` \| `blue` \| `gray`. Si es `null`/ausente se aplica el fallback legacy `darkWidget`
`darkWidget`	`boolean`	Modo oscuro legacy (fallback cuando `colorWidget` no esta definido)

Reglas de alcance por tema:

white y dark aplican el tema a TODO el widget (container, header, body, footer).
green, blue, gray aplican SOLO a la cabecera/accent. El body siempre queda en light.

Comportamiento y mensajes

Campo	Tipo	Descripción
`multianswerWidget`	`boolean`	Divide la respuesta del agente IA en varios mensajes consecutivos. Hace la conversación más natural cuando las respuestas son largas
`formWidget`	`boolean`	Muestra un formulario de registro (nombre, apellido, correo, WhatsApp) antes de iniciar el chat
`formTypeWidget`	`string`	Estilo del formulario de registro: `chat` (pide los datos conversando) o `fields` (campos en una sola pantalla). Solo aplica si `formWidget` es `true`. Default: `chat`
`formFieldsWidget`	`array`	Hasta 5 campos adicionales del formulario `fields`. Cada campo: `label`, `type` (`text`, `select` o `date`), `options` (si es `select`), `variable` (código de la variable de contacto donde se guarda) y `required`. El combo guarda el texto elegido y la fecha en formato `yyyy-MM-dd`
`fUseAutomationFlowWidget`	`boolean`	Prioriza los flujos de automatización sobre el agente IA
`advisorNameModeWidget`	`string`	Nombre que ve el cliente sobre los mensajes de un asesor humano: `agent` (nombre del asesor asignado, default) o `custom` (usa `advisorNameWidget`)
`advisorNameWidget`	`string \| null`	Nombre personalizado del asesor (ej: `"Equipo de Soporte"`). Solo aplica si `advisorNameModeWidget` es `custom`; si está vacío se usa el asesor asignado
`enablePoweredBy`	`boolean`	Muestra el pie de página "Powered by Plazbot" en el widget. Solo editable para administradores de Plazbot (para marcas blancas queda en `false`)

Canal WhatsApp

Campo	Tipo	Descripción
`enableWhatsappWidget`	`boolean`	Muestra botón de acceso directo a WhatsApp
`urlWhatsappWidget`	`string`	URL completa: `https://wa.me/1234567890`

Avatar virtual

El avatar animado con voz usa la plataforma HeyGen para el streaming de video.

Campo	Tipo	Descripción
`enableAvatarWidget`	`boolean`	Activa avatar animado con voz
`avatarFaceId`	`string`	`avatar_id` de HeyGen (ej: `Annie_expressive12_public`)
`avatarVoiceId`	`string`	`voice_id` de HeyGen (Multilingual). Usa `default` o vacío para la voz nativa del avatar
`avatarLanguage`	`string`	Código ISO corto: `es`, `en`, `pt`, `fr`, `it`, `de`
`avatarQuality`	`string`	Calidad del streaming: `low`, `medium`, `high`. A mayor calidad, mayor consumo de creditos. Default: `medium`
`avatarApiKey`	`string`	API Key personal de HeyGen del cliente (BYOK). Opcional
`avatarBackground`	`string \| null`	URL de imagen de fondo personalizada para el avatar. Si tiene valor, se aplica chroma key sobre fondo verde
`avatarGender`	`string`	Deprecado (legacy). HeyGen no lo usa: el genero es inherente al `avatarFaceId`. Se mantiene por retrocompatibilidad

Preguntas de ejemplo

Campo	Tipo	Descripción
`examples`	`array`	Lista de preguntas sugeridas en la pantalla de inicio. Cada entrada: `{ value: string, color: "orange" \| "blue" \| "green" \| "gray" \| "white" }`

Ejemplo completo

json

01{
02  "enableWidget": true,
03  "typeWidget": "widget",
04  "nameWidget": "Asistente",
05  "question": "En que puedo ayudarte?",
06  "colorWidget": "blue",
07  "darkWidget": false,
08  "iconWidget": "robot",
09  "initialShowWidget": false,
10  "multianswerWidget": true,
11  "formWidget": false,
12  "formTypeWidget": "chat",
13  "fUseAutomationFlowWidget": false,
14  "enablePoweredBy": true,
15  "enableWhatsappWidget": false,
16  "urlWhatsappWidget": null,
17  "examples": [
18    { "value": "Cuales son sus horarios?", "color": "blue" },
19    { "value": "Como puedo contactar a soporte?", "color": "green" }
20  ]
21}