Verifica dell'identità: di' all'agente chi sono 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 per lead, moduli e prenotazioni includono un oggetto identity.
• Le azioni API lato server possono usare ID, email, nome e metadati del visitatore come segnaposto, compilati da intoCHAT e mai dall'AI.
• Gli handler delle azioni lato client 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.

Se vuoi, puoi far chattare solo i visitatori verificati.

La verifica dell'identità richiede la bolla della chat del tag script, perché l'identità arriva dalla tua pagina tramite il 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.

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:

import { createHmac } from "node:crypto";

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

PHP:

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

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:

<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. 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:

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 e la pagina di assistenza non possono identificare nessuno, quindi mostrano solo l'avviso. I link di anteprima per i potenziali clienti continuano a funzionare: hanno una chat propria.
• Il tuo 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 può usare questi segnaposto in qualsiasi punto di URL, parametri, header e body:

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, la cui richiesta viene costruita nel browser del visitatore, questi segnaposto restano vuoti; il tuo handler riceve invece il visitatore come context.user.

I visitatori verificati diventano contatti

Ogni visitatore verificato viene conservato come contatto 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.

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. 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 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.
• 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, 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 svuota quell'elenco.