# Widget IA

> Implementa un widget de chat IA en tu sitio web

Fuente: https://developers.plazbot.com/sdk/widget/

### 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.

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

> **Importante:** **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

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

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

```html
<script id="id-widget-agent-plz" type="module" defer
src="https://storagelaplazbot.z13.web.core.windows.net/widget.js?Id={ID_AGENT}&zone={ZONE}&workspaceId={WORKSPACE_ID}">
</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](https://developers.plazbot.com/sdk/widget-api).

### Desactivacion

```ts
await 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
{
"enableWidget": true,
"typeWidget": "widget",
"nameWidget": "Asistente",
"question": "En que puedo ayudarte?",
"colorWidget": "blue",
"darkWidget": false,
"iconWidget": "robot",
"initialShowWidget": false,
"multianswerWidget": true,
"formWidget": false,
"formTypeWidget": "chat",
"fUseAutomationFlowWidget": false,
"enablePoweredBy": true,
"enableWhatsappWidget": false,
"urlWhatsappWidget": null,
"examples": [
  { "value": "Cuales son sus horarios?", "color": "blue" },
  { "value": "Como puedo contactar a soporte?", "color": "green" }
]
}
```