# Verifica dell'identità: di' all'agente chi sono i visitatori che hanno effettuato l'accesso

> Firma gli ID dei tuoi utenti sul tuo server con un segreto HMAC perché intoCHAT sappia chi sta chattando: conversazioni verificate, segnaposto {{user.*}} nelle azioni API e un'opzione per far chattare solo i visitatori che hanno effettuato l'accesso.

La verifica dell'identità permette al tuo sito di dire all'agente chi è un visitatore che ha effettuato l'accesso, in un modo che nessuno può falsificare. Il tuo server firma l'ID dell'utente con un segreto che conoscete solo tu e intoCHAT, e la tua pagina passa l'ID e la firma al widget di chat.

## Che cosa fa

Per un visitatore verificato:

- La conversazione mostra **Verified:** e l'ID utente in **Activity**, con il nome e l'email passati dalla tua pagina. L'export CSV ha una colonna **Verified user ID**, e i [webhook](/it/docs/webhooks) per lead, moduli e prenotazioni includono un oggetto `identity`.
- Le [azioni API lato server](/it/docs/api-actions) possono usare ID, email, nome e metadati del visitatore come [segnaposto](#segnaposto-nelle-azioni-lato-server), compilati da intoCHAT e mai dall'AI.
- Gli handler delle [azioni lato client](/it/docs/client-actions) nella tua pagina ricevono il visitatore come `context.user`.
- L'AI sa che il visitatore è verificato e conosce il suo nome, così può salutarlo. Nient'altro; vedi [Che cosa vede l'AI](#che-cosa-vede-l-ai).

Se vuoi, puoi far chattare [solo i visitatori verificati](#solo-i-visitatori-verificati-possono-chattare).

La verifica dell'identità richiede la bolla della chat del [tag script](/it/docs/script-tag), perché l'identità arriva dalla tua pagina tramite il [JavaScript SDK](/it/docs/javascript-sdk).

## Configurazione

### 1. Generare un segreto

1. Apri l'agente e vai alla scheda **Share**.
2. Nel riquadro **Identity verification**, fai clic su **Generate secret**.
3. Copia il segreto e conservalo sul tuo server, per esempio in una variabile d'ambiente chiamata `INTOCHAT_IDENTITY_SECRET`.

Solo il proprietario dell'account e gli admin possono generare, mostrare o ruotare il segreto. Editor e viewer vedono se è impostato e i suoi ultimi quattro caratteri.

> Il segreto deve stare solo sul tuo server. Non metterlo mai nell'HTML o nel JavaScript della tua pagina: chiunque lo abbia può firmare qualsiasi ID utente e chattare come quell'utente.

### 2. Firmare l'ID utente sul tuo server

Per l'utente che ha effettuato l'accesso, calcola `userHash`: l'HMAC-SHA256 dell'ID utente, con il segreto come chiave, scritto in esadecimale minuscolo. Firma esattamente il testo che passerai come `userId`.

Node.js:

```js
import { createHmac } from "node:crypto";

const userHash = createHmac("sha256", process.env.INTOCHAT_IDENTITY_SECRET)
  .update(String(user.id))
  .digest("hex");
```

PHP:

```php
<?php
$userHash = hash_hmac('sha256', (string) $user->id, getenv('INTOCHAT_IDENTITY_SECRET'));
```

Python:

```python
import hashlib, hmac, os

user_hash = hmac.new(
    os.environ["INTOCHAT_IDENTITY_SECRET"].encode(),
    str(user.id).encode(),
    hashlib.sha256,
).hexdigest()
```

Inserisci l'ID utente e l'hash nella pagina che invii a quell'utente.

### 3. Identificare il visitatore nella pagina

Dopo lo snippet, chiama `IntoChat.identify` a ogni caricamento di pagina finché il visitatore ha effettuato l'accesso:

```html
<script src="https://www.intochat.ai/api/embed.js" data-chatbot-id="YOUR_AGENT_ID"></script>
<script>
  window.IntoChat.identify({
    userId: "4711",
    userHash: "THE_HASH_FROM_YOUR_SERVER",
    name: "Ada Lovelace",         // optional
    email: "ada@example.com",     // optional
    metadata: { plan: "pro" }     // optional
  });
</script>
```

I limiti di ogni campo sono elencati in [identify](/it/docs/javascript-sdk#identify). Il widget invia l'identità con ogni messaggio, e il server di intoCHAT controlla la firma ogni volta.

### 4. Reimpostare all'uscita

Quando il visitatore esce dal suo account, chiama:

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

In questo modo l'identità viene dimenticata e si avvia una nuova chat, così la persona successiva su quel browser non vede la conversazione precedente. Anche identificare un utente diverso avvia da solo una nuova chat. Un visitatore che ha chattato prima di accedere mantiene quella conversazione, che diventa verificata.

## Solo i visitatori verificati possono chattare

Attiva **Only verified visitors can chat** nello stesso riquadro per riservare la chat agli utenti che hanno effettuato l'accesso:

- Finché la tua pagina non identifica il visitatore con una firma valida, al posto del campo del messaggio il widget mostra un breve avviso che gli chiede di accedere, nella lingua del widget.
- L'API della chat rifiuta i messaggi senza un'identità valida, con il motivo `identity_required`, quindi la regola vale anche fuori dal widget.
- Un [iframe incorporato, un link diretto](/it/docs/iframe-and-link) e la [pagina di assistenza](/it/docs/help-page) non possono identificare nessuno, quindi mostrano solo l'avviso. I [link di anteprima](/it/docs/preview-links) per i potenziali clienti continuano a funzionare: hanno una chat propria.
- Il tuo [Playground](/it/docs/instructions#prova-nel-playground) continua a funzionare, quindi puoi sempre provare l'agente.

L'interruttore richiede un segreto, quindi generane prima uno. Anche gli editor possono attivarlo o disattivarlo.

## Segnaposto nelle azioni lato server

Un'[azione API lato server](/it/docs/api-actions) può usare questi segnaposto in qualsiasi punto di URL, parametri, header e body:

| Segnaposto | Compilato con |
| --- | --- |
| `{{user.id}}` | L'ID utente verificato |
| `{{user.email}}` | L'email passata dalla tua pagina |
| `{{user.name}}` | Il nome passato dalla tua pagina |
| `{{user.metadata.<key>}}` | Un valore dei metadati, per esempio `{{user.metadata.plan}}` |

```text
GET https://api.example.com/customers/{{user.id}}/orders
```

intoCHAT li compila sui propri server, solo a partire dall'identità verificata:

- Per un visitatore non verificato sono vuoti. Un parametro o un campo del body vuoto viene tolto dalla richiesta.
- L'AI non li vede mai e non può sceglierli né modificarli. Anche se l'AI passa un valore che sembra `{{user.id}}`, viene inviato come semplice testo.
- **Send test request** nell'editor non ha un visitatore, quindi anche lì sono vuoti.
- Un segnaposto che nel body è solo `{{user.metadata.seats}}` mantiene il tipo del valore, quindi un numero resta un numero.

Qualsiasi altro segnaposto `{{user.…}}`, come `{{user.phone}}`, non si può salvare. In un'[azione lato client](/it/docs/client-actions), la cui richiesta viene costruita nel browser del visitatore, questi segnaposto restano vuoti; il tuo handler riceve invece il visitatore come `context.user`.

> Viene firmato solo l'ID utente. Nome, email e metadati sono ciò che la tua pagina ha passato insieme a una firma valida, quindi un visitatore che ha effettuato l'accesso potrebbe modificarne la propria copia nel browser. Tutto ciò che conta, come ordini o permessi, cercalo dalla tua parte in base a `{{user.id}}`.

## I visitatori verificati diventano contatti

Ogni visitatore verificato viene conservato come [contatto](/it/docs/contacts) dell'agente, con il suo ID utente come **External ID**, il nome e l'email passati dalla tua pagina, e come attributi le chiavi dei metadati che sono nomi di attributo validi (lettere minuscole, cifre e trattini bassi, che iniziano con una lettera). Quando la tua pagina passa nuovi dati, il contatto si aggiorna. Il contatto viene trovato solo tramite l'ID utente: un visitatore verificato non viene mai unito a un altro contatto perché le email coincidono, e riceve l'email solo se nessun altro contatto ce l'ha. Le azioni lato server possono poi leggere il contatto, compresi gli attributi che hai importato o aggiunto tramite l'API, come segnaposto `{{contact.*}}`. I visitatori di **Test as a signed-in visitor** nel Playground non diventano contatti.

## Che cosa vede l'AI

All'AI viene detto che il visitatore ha effettuato l'accesso ed è verificato, insieme al nome passato dalla tua pagina, che può usare per salutarlo. Non riceve mai l'indirizzo email, l'ID utente o i metadati, quindi non può ripeterli né essere convinta a rivelarli. Se vuoi che l'agente sappia di più, scrivilo tu stesso nelle tue [istruzioni](/it/docs/instructions).

## Provare nel Playground

Per provare i segnaposto o il saluto dell'agente senza accedere al tuo sito, apri il **Playground** ed espandi **Test as a signed-in visitor** sopra la chat. Inserisci uno **User ID** e, se vuoi, un **Name**, un'**Email** e dei **Metadata** come oggetto JSON, per esempio `{"plan": "pro", "seats": 5}`. Valgono gli stessi limiti del tuo sito; vedi [Limiti](#limiti). Finché qualcosa non è corretto, un messaggio in rosso dice che cosa, e il Playground chatta come visitatore anonimo.

Con un ID utente compilato, i tuoi messaggi nel Playground contano come verificati:

- Le [azioni lato server](#segnaposto-nelle-azioni-lato-server) ricevono questi valori come segnaposto `{{user.*}}`.
- All'AI viene detto che il visitatore è verificato, insieme al suo nome, come descritto in [Che cosa vede l'AI](#che-cosa-vede-l-ai).
- La conversazione del Playground registra l'utente, quindi mostra **Verified** nella scheda Conversations.

Non serve una firma, perché hai effettuato l'accesso a intoCHAT. L'identità di prova viene accettata solo dal Playground nella tua dashboard, dal proprietario, da un admin o da un editor; i viewer non possono usarla, e il widget di chat, i link e la REST API la ignorano. I visitatori del tuo sito hanno sempre bisogno di una firma valida. Il Playground non viene mai bloccato da [Solo i visitatori verificati possono chattare](#solo-i-visitatori-verificati-possono-chattare), con o senza identità di prova.

Una conversazione mantiene il primo utente verificato che incontra, quindi premi **Reset** prima di provare come un altro utente.

## Il segreto

- **Reveal** mostra di nuovo il segreto attuale, al proprietario e agli admin.
- **Rotate** crea un nuovo segreto, dopo una conferma. Quello vecchio smette subito di funzionare: finché il tuo server non firma con il nuovo segreto, ogni visitatore risulta non verificato e, con **Only verified visitors can chat** attivo, non può chattare.
- Il segreto viene conservato cifrato. Duplicare un agente non copia né il segreto né l'interruttore.

## Limiti

- Un segreto per agente. Con più agenti nella stessa pagina, ognuno verifica solo le firme fatte con il proprio segreto.
- Una firma errata o mancante non viene mai mostrata al visitatore come errore: chatta semplicemente da non verificato, a meno che possano chattare solo i visitatori verificati.
- Una conversazione appartiene al primo utente verificato in essa. Se un altro utente verificato scrive nella stessa sessione, senza la nuova chat che `identify` normalmente avvia, quei messaggi vengono trattati come non verificati.
- Un ID utente ha fino a 200 caratteri, un nome fino a 100, un'email fino a 254, e i metadati fino a 20 chiavi e 2 KB.
- L'identità non viene controllata quando un visitatore riapre una chat precedente dall'elenco del suo browser; [Reimpostare all'uscita](#4-reimpostare-all-uscita) svuota quell'elenco.