# API de JavaScript: abre el agente de Nodale desde tu código

<https://nodale.ai/es/docs/api>

Los comandos nodale() que una página puede llamar: abrir el agente desde tu botón o formulario, pasar un correo y contexto, comunicar el consentimiento.

Una vez [instalada la etiqueta](https://nodale.ai/es/docs), tu página puede enviarle comandos con una sola función, `nodale()`. Hay dos comandos: `open` y `consent`. La etiqueta no expone ningún otro método y no envía ningún evento a tu página.

## La cola de comandos

La etiqueta define `window.nodale` cuando se ejecuta. Para llamar a un comando antes de que la etiqueta se haya cargado, pega este stub encima de ella. Los comandos esperan en una cola hasta que la etiqueta está lista:

```html
<script>
  window.nodale = window.nodale || function(){(window.nodale.q = window.nodale.q || []).push(arguments)}
</script>
<script src="https://tag.nodale.app/v1/tag.js" data-workspace="YOUR_WORKSPACE_ID" async></script>
```

Conserva el `||`. Un script que más tarde asigna `window.nodale` sin él elimina el comando de la etiqueta, y las llamadas posteriores no llegan a ninguna parte.

## `nodale('open')`

Abre el agente desde tu propio código, por ejemplo desde tu propio botón o cuando se ha enviado tu propio formulario.

```js
nodale('open')

nodale('open', {
  email: 'sam@acme.io',
  context: { 'Contactos al mes': '1500' }
})
```

La llamada inicia una conversación escrita en el diálogo del agente. No se pide el micrófono: espera al visitante.

### Opciones

| Opción | Tipo | Qué hace |
|---|---|---|
| `email` | string | El correo del visitante, cuando tu página ya lo conoce. Queda identificado antes del saludo del agente. |
| `context` | object | Lo que el visitante ya te ha dicho, en pares de nombre y respuesta. El agente lo recibe cuando empieza la conversación. Se registra en la conversación y nunca se muestra al visitante. |

Las dos son opcionales. La etiqueta comprueba el argumento antes de que nada salga de la página:

- **El argumento** es nada, o un objeto simple sin más claves que `email` y `context`. Con cualquier otra cosa, no se abre nada.
- **`email`** es una cadena de 1 a 254 caracteres una vez recortada. Si no, se descarta, y el agente se abre igualmente. La etiqueta no juzga la dirección: el servidor decide si la acepta.
- **`context`** contiene 20 respuestas como máximo. Un nombre tiene de 1 a 60 caracteres, una respuesta es una cadena de 300 caracteres como máximo, y un nombre se usa una sola vez. Los nombres y las respuestas se recortan, y una respuesta vacía se omite. Si se incumple una regla, se descarta el contexto entero, nunca se corta, y el agente se abre igualmente sin él.

`nodale('open')` nunca lanza una excepción y devuelve `undefined`.

### Dónde funciona

- **Solo en la barra y en la visualización `hidden`.** Con la visualización de botón, con un `<div data-nodale-agent>` insertado en la página, y en una página donde el agente no se muestra (una regla de página, o una parte de los visitantes), la llamada no hace nada. Si usas `open`, deja desactivada la parte de los visitantes, o la llamada no hará nada para algunos visitantes.
- **Antes de que la etiqueta se haya cargado**, con el stub de arriba. Solo se reproduce el último `open` en cola, una vez.
- **Una sola conversación.** El widget inicia una conversación como máximo y conserva el primer correo y el primer contexto que recibió. Un `open` durante una conversación, o después de que haya terminado, solo muestra el diálogo.
- **Cuando el agente pide primero el correo**, la llamada muestra ese paso, y tu correo y tu contexto se envían cuando el visitante lo envía.

### Desde un botón

```html
<button type="button" onclick="nodale('open')">Haz una pregunta</button>
```

### Después de tu propio formulario

```js
form.addEventListener('submit', function () {
  nodale('open', {
    email: form.elements.email.value,
    context: {
      'Tamaño de la empresa': form.elements.size.value,
      'Qué quiere hacer': form.elements.message.value
    }
  })
})
```

## La visualización hidden

`hidden` es una visualización del espacio de trabajo, junto a la barra y el botón. Con ella, no se muestra nada hasta que tu página llama a `nodale('open')`.

- **La página sigue siendo totalmente utilizable.** El marco del agente está montado pero es invisible, y no recibe ningún clic.
- **Una vez abierto, es la barra.** Cerrar el diálogo vuelve a la barra y conserva la conversación. La barra se queda después durante el resto de la pestaña.
- **La pestaña lo recuerda.** Una página posterior de tu sitio en la misma pestaña muestra la barra de inmediato, para que el visitante encuentre de nuevo la conversación. La etiqueta lo guarda en `sessionStorage`, en una clave que no contiene ningún identificador. Una pestaña nueva empieza oculta.
- **Probado solo en navegadores Chromium.** Safari y Firefox todavía no están cubiertos por nuestras pruebas de navegador: un navegador que ralentiza los marcos invisibles puede responder a `open` más tarde.

## `nodale('consent')`

Indica a la etiqueta si el visitante ha aceptado la medición de visitas. Úsalo cuando tu sitio no tiene un banner de cookies que la etiqueta pueda leer, o cuando gestionas tú el consentimiento.

```js
nodale('consent', 'granted')
nodale('consent', 'revoked')
```

- **Solo cuenta cuando la medición de visitas está activada** en tu espacio de trabajo. La medición está desactivada por defecto, y el agente se monta en ambos casos.
- **La medición empieza denegada.** No se pide nada y no se escribe ninguna cookie antes de una aceptación. Con `revoked`, la etiqueta se detiene y elimina su cookie.
- **Está por encima de cualquier banner.** Una vez que tu página lo ha llamado, la etiqueta sigue tu llamada e ignora lo que diga un banner.
- **Global Privacy Control gana a todo.** Un navegador que lo envía sigue denegado durante toda la visita, llame a lo que llame tu página.

Sin la llamada, la etiqueta lee la respuesta de la herramienta de consentimiento de la página: Axeptio, Didomi, Cookiebot, OneTrust, Usercentrics, CookieYes, tarteaucitron.js, WP Consent API, Complianz, el banner de HubSpot, iubenda, Osano, Cookie-Script, CookieFirst, Klaro, Shopify, Wix, IAB TCF v2.2, IAB GPP y Google Consent Mode v2. Algunas necesitan que Nodale esté declarado como proveedor o como servicio: la guía de medición de visitas de la aplicación da la configuración de cada una.

## Depuración

La etiqueta nunca lanza una excepción en tu página. Se explica en `console.debug`, en líneas que empiezan por `nodale tag:`. Activa el nivel detallado de la consola de tu navegador para verlas.

| Línea | Qué ha pasado |
|---|---|
| `open refused` | El argumento no es un objeto simple, o contiene otra clave que `email` y `context`. |
| `open email dropped` | `email` no es una cadena de 1 a 254 caracteres. |
| `open context dropped` | `context` incumple una de sus reglas. |
| `open needs the floating or hidden display` | El espacio de trabajo usa la visualización de botón, o la página monta el agente insertado en ella. |
| `open: agent not on this page` | Una regla de página o la parte de los visitantes deja el agente fuera de esta página. |
| `open not acknowledged` | El widget no respondió en 30 segundos. |

## Docs

- [Instala el agente de Nodale en tu web](https://nodale.ai/es/docs): Una sola etiqueta script pone el agente de Nodale en tu web. Dónde pegarla, qué debe permitir tu web y cómo comprobar que funciona. (Markdown: https://nodale.ai/es/docs.md)
- [Servidor MCP: gestiona tu espacio de Nodale desde Claude Code](https://nodale.ai/es/docs/mcp): Conecta Claude Code al servidor MCP de Nodale y lee y cambia tu espacio de trabajo: conocimiento, recursos de demo, ajustes del agente, sitios, despliegue. (Markdown: https://nodale.ai/es/docs/mcp.md)
