> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plazbot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Widget IA

> Implementa un widget de chat IA en tu sitio web

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

<Note>
  La activacion del widget requiere una llamada independiente al metodo `enableWidget`. No se activa al actualizar el agente con `updateAgent`.
</Note>

<Warning>
  **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.
</Warning>

### Activacion

```ts theme={null}
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 pagina web:

```html theme={null}
<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>
```

<img style={{ borderRadius: '0.5rem' }} src="https://mintcdn.com/plazbot/Hg1ZdNXWjISFp5fx/images/sdk/widget-ligth.png?fit=max&auto=format&n=Hg1ZdNXWjISFp5fx&q=85&s=549713c554ad75f122e5a780c880c7a5" width="824" height="1266" data-path="images/sdk/widget-ligth.png" />

<img style={{ borderRadius: '0.5rem' }} src="https://mintcdn.com/plazbot/Hg1ZdNXWjISFp5fx/images/sdk/widget-dark.png?fit=max&auto=format&n=Hg1ZdNXWjISFp5fx&q=85&s=73bf259c2fdd37f863cabdbc71cd93ae" width="826" height="1272" data-path="images/sdk/widget-dark.png" />

### Desactivacion

```ts theme={null}
await 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                                                     |
| `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` tinen TODO el widget (container, header, body, footer).
* `green`, `blue`, `gray` tinen SOLO 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

| Campo                | Tipo      | Descripcion                    |
| -------------------- | --------- | ------------------------------ |
| `enableAvatarWidget` | `boolean` | Activa avatar animado con voz  |
| `avatarGender`       | `string`  | `male` o `female`              |
| `avatarVoiceId`      | `string`  | ID de voz de Google Cloud TTS  |
| `avatarLanguage`     | `string`  | Codigo de idioma (ej: `es-US`) |
| `avatarFaceId`       | `string`  | Face ID del avatar de video    |

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