# SDK de JavaScript: controla el widget de chat desde tu página

> Abre y cierra la burbuja de chat de intoCHAT desde tu propio código, identifica a los visitantes con sesión iniciada, cambia el idioma del widget y escucha los eventos del chat con window.IntoChat.

El script de inserción añade `window.IntoChat` a tu página. Con él, tu propio JavaScript puede abrir y cerrar la burbuja de chat, decirle al agente quién es el visitante con sesión iniciada, cambiar el idioma del widget y reaccionar a lo que ocurre en el chat.

## Antes de empezar

El SDK viene con la [etiqueta script](/es/docs/script-tag). No hay nada más que instalar:

```html
<script src="https://www.intochat.ai/api/embed.js" data-chatbot-id="YOUR_AGENT_ID"></script>
<script>
  window.IntoChat.on("reply", function (event) {
    console.log("The agent replied:", event.text);
  });
</script>
```

`window.IntoChat` existe en cuanto se ha ejecutado el script, antes de que cargue la ventana del chat. Las llamadas que hagas antes esperan a que la burbuja y la ventana del chat estén listas, así que puedes llamar a cualquier método justo después del snippet.

El SDK solo funciona con la burbuja de chat que añade el script. Un [iframe en la página o un enlace directo](/es/docs/iframe-and-link) no tiene ningún script en la página con el que comunicarse.

## Métodos

| Método | Qué hace |
| --- | --- |
| `IntoChat.open()` | Abre la ventana del chat |
| `IntoChat.close()` | La cierra |
| `IntoChat.toggle()` | La abre si está cerrada y la cierra si está abierta |
| `IntoChat.identify(user)` | Le dice al agente quién es el visitante con sesión iniciada; consulta [identify](#identify) |
| `IntoChat.reset()` | Olvida la identidad del visitante y empieza un chat nuevo |
| `IntoChat.setLanguage(code)` | Cambia el idioma del widget |
| `IntoChat.on(event, callback)` | Llama a `callback` cuando ocurre `event` |
| `IntoChat.off(event, callback)` | Deja de llamarlo |

### open, close y toggle

```html
<button type="button" onclick="IntoChat.open()">Chat with us</button>
```

Abrir el chat de esta forma cuenta como que el visitante usa el chat, así que la ventana emergente de bienvenida y la apertura automática ya no aparecen durante esa visita.

`IntoChat.open()` también funciona para los visitantes que no ven la burbuja por [Show the chat to a share of visitors](/es/docs/appearance#mostrar-el-chat-a-una-parte-de-los-visitantes). El despliegue solo oculta la burbuja y sus invitaciones, así que un botón «Chatea con nosotros» en tu página sigue abriendo el chat para todos. Para esos visitantes, la ventana del chat se carga la primera vez que se abre. Con [Center Stage](/es/docs/appearance#como-se-abre-el-chat), `open()` abre la ventana centrada y `close()` la cierra igual que Esc.

### identify

```js
IntoChat.identify({
  userId: "4711",                  // required: the user's id on your site
  userHash: "9f2c…",               // required: computed on your server
  name: "Ada Lovelace",            // optional
  email: "ada@example.com",        // optional
  metadata: { plan: "pro", seats: 3 } // optional
});
```

`identify` es la base de la [verificación de identidad](/es/docs/identity-verification). `userHash` es el HMAC-SHA256 de `userId`, con el secreto de identidad de tu agente como clave y calculado en tu servidor, para que nadie pueda hacerse pasar por otro usuario. Sin un `userHash` válido, el visitante simplemente sigue sin verificar.

| Campo | Reglas |
| --- | --- |
| `userId` | Obligatorio. Texto (un número se convierte en texto), hasta 200 caracteres. Firma exactamente este valor. |
| `userHash` | Obligatorio. 64 caracteres hexadecimales. |
| `name` | Opcional. Hasta 100 caracteres. |
| `email` | Opcional. Una dirección de correo válida, hasta 254 caracteres. |
| `metadata` | Opcional. Un objeto plano de hasta 20 claves. Las claves usan letras, dígitos y guiones bajos (hasta 40 caracteres); los valores son texto (hasta 500 caracteres), números o `true`/`false`. Como mucho 2 KB en total. |

`identify` devuelve `true` cuando los datos cumplen estas reglas, y `false` (con un aviso en la consola del navegador) cuando no. Si la firma es válida solo lo comprueba el servidor de intoCHAT, cuando el visitante envía un mensaje.

Llama a `identify` en cada carga de página mientras el visitante tenga la sesión iniciada. Identificar a un usuario distinto del último en este navegador empieza automáticamente un chat nuevo, así que una persona nunca ve la conversación de otra. Un visitante que chateó antes de iniciar sesión conserva ese chat.

### reset

```js
IntoChat.reset();
```

Llámalo cuando el visitante cierre sesión. Olvida la identidad y empieza un chat nuevo y vacío. También se vacía la lista de chats anteriores en este navegador; las conversaciones en sí se quedan en tu panel.

### setLanguage

```js
IntoChat.setLanguage("de");
```

Cambia los textos propios del widget (botones, etiquetas, avisos) a inglés (`en`), alemán (`de`), francés (`fr`), italiano (`it`) o español (`es`). Un código regional como `de-CH` cuenta como `de`. Cualquier otro código devuelve `false`. Sustituye al atributo `lang` de tu página, así que no tiene efecto si elegiste un idioma fijo para el widget en la pestaña [Appearance](/es/docs/appearance). No cambia tus mensajes de bienvenida ni el idioma en que responde el agente.

### on y off

```js
function onReply(event) {
  analytics.track("chat_reply", { agent: event.chatbotId });
}

IntoChat.on("reply", onReply);
// later
IntoChat.off("reply", onReply);
```

`on` también devuelve una función que quita el listener. Un listener que lanza un error no detiene a los demás; el error se registra en la consola.

## Eventos

Cada callback recibe un objeto. Siempre tiene `chatbotId`, el agente del que viene el evento.

| Evento | Cuándo | Campos adicionales |
| --- | --- | --- |
| `open` | Se abrió la ventana del chat: por el visitante, por tu código o por la apertura automática | ninguno |
| `close` | Se cerró la ventana del chat | ninguno |
| `message` | El visitante envió un mensaje | `text` |
| `reply` | El agente terminó una respuesta | `text`: la respuesta sin las tarjetas de producto, los botones, los formularios ni las fuentes que aparecen debajo |
| `lead` | El visitante envió el [formulario de contacto](/es/docs/lead-collection) | ninguno |
| `booking` | El visitante reservó una hora con las [reservas](/es/docs/booking) | ninguno |
| `live_chat` | El estado del [chat en vivo](/es/docs/live-chat) cambió mientras la página estaba abierta | `status`: `requested`, `active`, `ended` o `null` |

```js
IntoChat.on("live_chat", function (event) {
  if (event.status === "active") document.title = "A team member is chatting with you";
});
```

En un chat temporal no se disparan `lead` ni `booking`, porque ahí no se ofrecen. Los datos de contacto que un visitante escribe en el chat, en lugar de usar el formulario, no disparan `lead`.

## Llamarlo antes de que cargue el script

Si tu código puede ejecutarse antes del snippet, añade las llamadas a `window.IntoChatQueue`. Cada entrada es el nombre del método seguido de sus argumentos:

```html
<script>
  window.IntoChatQueue = window.IntoChatQueue || [];
  window.IntoChatQueue.push(["identify", { userId: "4711", userHash: "9f2c…" }]);
  window.IntoChatQueue.push(["on", "lead", function () { console.log("New lead"); }]);
</script>
<script src="https://www.intochat.ai/api/embed.js" data-chatbot-id="YOUR_AGENT_ID"></script>
```

El script aplica la cola al cargar. Lo que se añada después se ejecuta al momento.

## Varios agentes en una página

Con los snippets de varios agentes en una página, cada llamada se aplica a todas sus burbujas, y el `chatbotId` de cada evento indica de qué agente viene. Cada agente tiene su propio secreto de identidad, así que un `userHash` solo verifica al visitante para el agente cuyo secreto lo firmó.

## Relación con IntoChatActions

`window.IntoChatActions` es independiente y funciona exactamente igual que antes: ejecuta las [acciones del lado del cliente](/es/docs/client-actions) cuando el agente las llama. `IntoChat` sirve para que tu propio código controle el widget. Los dos se pueden usar juntos. Cuando el visitante está verificado, un manejador de una acción del lado del cliente también lo recibe como `context.user`:

```js
IntoChatActions.register("Get_cart", async function (args, context) {
  // context.user: { id, name, email, metadata }, only for a verified visitor
  return { items: window.myStore.cart.items };
});
```

## Seguridad

La ventana del chat se ejecuta en el dominio de intoCHAT. El script de tu página solo intercambia mensajes con su propia ventana del chat, y solo mientras esa ventana muestra intoCHAT: otros frames de tu página no pueden recibir la identidad del visitante, enviar eventos falsos ni activar acciones. Los eventos llevan lo que escribió el visitante y las respuestas del agente, así que trátalos como cualquier otro dato de visitantes en tu página.