Widget IA | Plazbot Docs

Introduccion

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

La activacion del widget requiere una llamada independiente al metodo 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 opcion 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 pagina 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>

Desactivacion

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

Configuracion en agent.config.json

Basicos

Campo	Tipo	Descripcion
`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 pagina
`initialViewWidget`	`string \| null`	Vista inicial al abrir el widget: `home`, `chat` o `avatar`. `null` equivale a `home` (legacy)
`positionWidget`	`string`	Posicion 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 boton flotante: `robot`, `message`, `support`, `qa`, `chat`, `smile`, `voice`, `uservoice`

Tema visual

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

Campo	Tipo	Descripcion
`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	Descripcion
`multianswerWidget`	`boolean`	Divide la respuesta del agente IA en varios mensajes consecutivos. Hace la conversacion mas natural cuando las respuestas son largas
`formWidget`	`boolean`	Muestra un formulario de registro (nombre, apellido, correo, WhatsApp) antes de iniciar el chat
`fUseAutomationFlowWidget`	`boolean`	Prioriza los flujos de automatizacion sobre el agente IA
`enablePoweredBy`	`boolean`	Muestra el pie de pagina "Powered by Plazbot" en el widget. Solo editable para administradores de Plazbot (para marcas blancas queda en `false`)

Canal WhatsApp

Campo	Tipo	Descripcion
`enableWhatsappWidget`	`boolean`	Muestra boton 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	Descripcion
`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 vacio para la voz nativa del avatar
`avatarLanguage`	`string`	Codigo 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	Descripcion
`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  "fUseAutomationFlowWidget": false,
13  "enablePoweredBy": true,
14  "enableWhatsappWidget": false,
15  "urlWhatsappWidget": null,
16  "examples": [
17    { "value": "Cuales son sus horarios?", "color": "blue" },
18    { "value": "Como puedo contactar a soporte?", "color": "green" }
19  ]
20}