# JavaScript SDK: controlla il widget di chat dalla tua pagina

> Apri e chiudi la bolla di chat di intoCHAT dal tuo codice, identifica i visitatori che hanno effettuato l'accesso, cambia la lingua del widget e ascolta gli eventi della chat con window.IntoChat.

Lo script di incorporamento aggiunge `window.IntoChat` alla tua pagina. Con questo oggetto il tuo JavaScript può aprire e chiudere la bolla della chat, dire all'agente chi è il visitatore che ha effettuato l'accesso, cambiare la lingua del widget e reagire a ciò che succede nella chat.

## Prima di iniziare

L'SDK è incluso nel [tag script](/it/docs/script-tag). Non c'è nient'altro da installare:

```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` esiste non appena lo script è stato eseguito, prima che la finestra della chat sia caricata. Le chiamate fatte presto attendono che la bolla e la finestra della chat siano pronte, quindi puoi chiamare qualsiasi metodo subito dopo lo snippet.

L'SDK funziona solo con la bolla della chat aggiunta dallo script. Un [iframe incorporato o un link diretto](/it/docs/iframe-and-link) non ha nella pagina uno script con cui comunicare.

## Metodi

| Metodo | Che cosa fa |
| --- | --- |
| `IntoChat.open()` | Apre la finestra della chat |
| `IntoChat.close()` | La chiude |
| `IntoChat.toggle()` | La apre se è chiusa, la chiude se è aperta |
| `IntoChat.identify(user)` | Dice all'agente chi è il visitatore che ha effettuato l'accesso; vedi [identify](#identify) |
| `IntoChat.reset()` | Dimentica l'identità del visitatore e avvia una nuova chat |
| `IntoChat.setLanguage(code)` | Cambia la lingua del widget |
| `IntoChat.on(event, callback)` | Chiama `callback` quando si verifica `event` |
| `IntoChat.off(event, callback)` | Smette di chiamarla |

### open, close e toggle

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

Aprire la chat in questo modo conta come un uso della chat da parte del visitatore, quindi il pop-up di benvenuto e l'apertura automatica non compaiono più durante quella visita.

`IntoChat.open()` funziona anche per i visitatori che non vedono la bolla a causa di [Show the chat to a share of visitors](/it/docs/appearance#mostrare-la-chat-a-una-parte-dei-visitatori). Il rilascio graduale nasconde solo la bolla e i suoi inviti, quindi un pulsante "Chatta con noi" sulla tua pagina apre comunque la chat per tutti. Per questi visitatori la finestra di chat viene caricata la prima volta che si apre. Con [Center Stage](/it/docs/appearance#come-si-apre-la-chat), `open()` apre la finestra centrata e `close()` la chiude come fa 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` è il modo in cui funziona la [verifica dell'identità](/it/docs/identity-verification). `userHash` è l'HMAC-SHA256 di `userId`, con il segreto di identità del tuo agente come chiave, calcolato sul tuo server, così nessuno può fingersi un altro utente. Senza un `userHash` valido il visitatore resta semplicemente non verificato.

| Campo | Regole |
| --- | --- |
| `userId` | Obbligatorio. Testo (un numero viene convertito in testo), fino a 200 caratteri. Firma esattamente questo valore. |
| `userHash` | Obbligatorio. 64 caratteri esadecimali. |
| `name` | Facoltativo. Fino a 100 caratteri. |
| `email` | Facoltativo. Un indirizzo email valido, fino a 254 caratteri. |
| `metadata` | Facoltativo. Un oggetto piatto con al massimo 20 chiavi. Le chiavi usano lettere, cifre e trattini bassi (fino a 40 caratteri); i valori sono testo (fino a 500 caratteri), numeri oppure `true`/`false`. Al massimo 2 KB in tutto. |

`identify` restituisce `true` quando i dati rispettano queste regole, e `false` (con un avviso nella console del browser) quando non le rispettano. La validità della firma viene controllata solo dal server di intoCHAT, quando il visitatore invia un messaggio.

Chiama `identify` a ogni caricamento di pagina finché il visitatore ha effettuato l'accesso. Se identifichi un utente diverso dall'ultimo su questo browser, si avvia automaticamente una nuova chat, così una persona non vede mai la conversazione di un'altra. Un visitatore che ha chattato prima di accedere mantiene quella chat.

### reset

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

Chiamalo quando il visitatore esce dal suo account. Dimentica l'identità e avvia una nuova chat vuota. Viene svuotato anche l'elenco delle chat precedenti su questo browser; le conversazioni restano nella tua dashboard.

### setLanguage

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

Cambia i testi del widget (pulsanti, etichette, avvisi) in inglese (`en`), tedesco (`de`), francese (`fr`), italiano (`it`) o spagnolo (`es`). Un codice con regione come `de-CH` vale come `de`. Qualsiasi altro codice restituisce `false`. Prende il posto dell'attributo `lang` della tua pagina, quindi non ha effetto se hai scelto una lingua fissa per il widget nella scheda [Appearance](/it/docs/appearance). Non cambia i tuoi messaggi di benvenuto né la lingua in cui risponde l'agente.

### on e off

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

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

`on` restituisce anche una funzione che rimuove il listener. Un listener che genera un errore non blocca gli altri; l'errore viene registrato nella console.

## Eventi

Ogni callback riceve un oggetto. Contiene sempre `chatbotId`, l'agente da cui proviene l'evento.

| Evento | Quando | Campi aggiuntivi |
| --- | --- | --- |
| `open` | La finestra della chat si è aperta: dal visitatore, dal tuo codice o con l'apertura automatica | nessuno |
| `close` | La finestra della chat si è chiusa | nessuno |
| `message` | Il visitatore ha inviato un messaggio | `text` |
| `reply` | L'agente ha finito una risposta | `text`: la risposta senza le schede prodotto, i pulsanti, i moduli o le fonti mostrati sotto |
| `lead` | Il visitatore ha inviato il [modulo di contatto](/it/docs/lead-collection) | nessuno |
| `booking` | Il visitatore ha prenotato un orario con la [prenotazione](/it/docs/booking) | nessuno |
| `live_chat` | Lo stato della [live chat](/it/docs/live-chat) è cambiato mentre la pagina era aperta | `status`: `requested`, `active`, `ended` oppure `null` |

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

In una chat temporanea gli eventi `lead` e `booking` non partono, perché lì modulo lead e prenotazione non vengono proposti. I contatti che un visitatore scrive nella chat, invece di usare il modulo, non generano `lead`.

## Chiamarlo prima che lo script sia caricato

Se il tuo codice può essere eseguito prima dello snippet, aggiungi le chiamate a `window.IntoChatQueue`. Ogni voce è il nome del metodo seguito dai suoi argomenti:

```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>
```

Lo script esegue la coda quando si carica. Le voci aggiunte dopo vengono eseguite subito.

## Più agenti nella stessa pagina

Con gli snippet di più agenti nella stessa pagina, ogni chiamata vale per tutte le loro bolle, e il `chatbotId` di ogni evento indica da quale agente proviene. Ogni agente ha il suo segreto di identità, quindi un `userHash` verifica il visitatore solo per l'agente il cui segreto l'ha firmato.

## Il rapporto con IntoChatActions

`window.IntoChatActions` è separato e funziona esattamente come prima: esegue le [azioni lato client](/it/docs/client-actions) quando l'agente le chiama. `IntoChat` serve al tuo codice per controllare il widget. Puoi usarli insieme. Quando il visitatore è verificato, anche l'handler di un'azione lato client lo riceve come `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 };
});
```

## Sicurezza

La finestra della chat gira sul dominio di intoCHAT. Lo script nella tua pagina scambia messaggi solo con la propria finestra di chat, e solo mentre quella finestra mostra intoCHAT: altri frame nella tua pagina non possono ricevere l'identità del visitatore, inviare eventi falsi o avviare azioni. Gli eventi contengono ciò che il visitatore ha scritto e le risposte dell'agente, quindi trattali come qualsiasi altro dato dei visitatori nella tua pagina.