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

# API programatica

> Controla el widget por codigo

El widget expone una API global en `window.ThaliqWidget` que permite controlarlo programaticamente desde JavaScript.

## Como acceder a la instancia

Hay dos formas de inicializar el widget, y cada una expone la API de manera distinta:

### Opcion A — Auto-init con `data-api-key`

```html theme={null}
<script src="https://cdn.thaliq.com/widget.js" data-api-key="tq_live_xxx"></script>
```

Despues de cargar, `window.ThaliqWidget` **es directamente la instancia**. Podes llamar metodos sobre el global:

```js theme={null}
window.ThaliqWidget.open();
window.ThaliqWidget.send('Hola');
```

### Opcion B — Init programatico

```js theme={null}
const widget = ThaliqWidget.init({ apiKey: 'tq_live_xxx' });
window.thaliq = widget; // guardalo donde quieras
```

`ThaliqWidget.init()` **retorna** la instancia. El global `window.ThaliqWidget` sigue siendo `{ init, _class }` (no la instancia). Guarda el retorno para llamar metodos despues.

<Warning>
  No mezcles estilos. Si usas `<script data-api-key>` para auto-init, **no** llames `ThaliqWidget.init()` despues — sobreescribirias la instancia.
</Warning>

## Metodos de la instancia

### `open()`

Abre la ventana de chat.

```javascript theme={null}
window.ThaliqWidget.open();
```

### `close()`

Cierra la ventana de chat.

```javascript theme={null}
window.ThaliqWidget.close();
```

### `toggle()`

Alterna entre abierto y cerrado.

```javascript theme={null}
window.ThaliqWidget.toggle();
```

### `send(text)`

Envia un mensaje programaticamente. Util para iniciar conversaciones contextuales. Internamente escribe el texto en el input y dispara el envio.

```javascript theme={null}
window.ThaliqWidget.send('Necesito ayuda con mi pedido #12345');
```

**Ejemplo: Boton contextual**

```html theme={null}
<button onclick="ThaliqWidget.send('Quiero saber mas sobre el Plan Growth')">
  Preguntar sobre Plan Growth
</button>
```

### `reset()`

Reinicia la conversacion: limpia los mensajes en pantalla, descarta el `conversationId` activo y vuelve al estado inicial. La proxima request crea un thread nuevo.

```javascript theme={null}
window.ThaliqWidget.reset();
```

### `setMcpTokens(tokens)`

Actualiza los tokens MCP en runtime (passthrough al backend en el header `X-MCP-Tokens`). Util cuando el usuario se loguea contra un sistema externo despues de cargar el widget y necesitas darle acceso al MCP server correspondiente sin recargar.

```javascript theme={null}
window.ThaliqWidget.setMcpTokens({
  'github-mcp': 'ghp_xxx',
  'jira-mcp': 'eyJh...',
});
```

### `destroy()`

Elimina el widget completamente del DOM y limpia listeners + suscripcion SSE. Util para SPAs cuando navegas a otra pagina o cuando el componente que lo monta se desmontya.

```javascript theme={null}
window.ThaliqWidget.destroy();
```

## Ejemplo: Abrir el chat automaticamente

```html theme={null}
<script
  src="https://cdn.thaliq.com/widget.js"
  data-api-key="tq_live_xxx"
></script>

<script>
  // Abrir el chat 3 segundos despues de cargar la pagina
  setTimeout(() => {
    window.ThaliqWidget.open();
  }, 3000);
</script>
```

## Ejemplo: Abrir con un boton custom

Usa `data-show-launcher="false"` para ocultar el boton flotante y controlar el chat con tu propio boton:

```html theme={null}
<!-- Tu propio boton -->
<button id="help-btn" class="my-help-button">
  ¿Necesitas ayuda?
</button>

<script
  src="https://cdn.thaliq.com/widget.js"
  data-api-key="tq_live_xxx"
  data-show-launcher="false"
></script>

<script>
  document.getElementById('help-btn').addEventListener('click', () => {
    window.ThaliqWidget.open();
  });
</script>
```

## Ejemplo: Mensaje contextual segun la pagina

```html theme={null}
<script>
  // Detectar la pagina actual y enviar mensaje contextual
  document.addEventListener('DOMContentLoaded', () => {
    const path = window.location.pathname;

    if (path.includes('/pricing')) {
      // En la pagina de pricing, pre-cargar pregunta
      window.ThaliqWidget.open();
      window.ThaliqWidget.send('Quiero mas informacion sobre los planes');
    }
  });
</script>
```