# Identitätsprüfung: dem Agenten sagen, wer deine angemeldeten Besucher sind

> Signiere die IDs deiner Nutzer auf deinem Server mit einem HMAC-Secret, damit intoCHAT weiß, wer chattet: verifizierte Gespräche, {{user.*}}-Platzhalter in API-Aktionen und eine Option, nur angemeldete Besucher chatten zu lassen.

Mit der Identitätsprüfung teilt deine Website dem Agenten mit, wer ein angemeldeter Besucher ist, und zwar so, dass niemand es fälschen kann. Dein Server signiert die ID des Nutzers mit einem Secret, das nur du und intoCHAT kennen, und deine Seite gibt die ID und die Signatur an das Chat-Widget weiter.

## Was sie bewirkt

Bei einem verifizierten Besucher:

- zeigt das Gespräch unter **Activity** **Verified:** mit der User-ID, dazu Name und E-Mail-Adresse, die deine Seite übergeben hat. Der CSV-Export hat eine Spalte **Verified user ID**, und [Webhooks](/de/docs/webhooks) für Leads, Formulare und Buchungen enthalten ein Objekt `identity`.
- können [server-seitige API-Aktionen](/de/docs/api-actions) ID, E-Mail-Adresse, Name und Metadaten des Besuchers als [Platzhalter](#platzhalter-in-server-seitigen-aktionen) nutzen, die intoCHAT ausfüllt, nie die KI.
- bekommen Handler für [client-seitige Aktionen](/de/docs/client-actions) auf deiner Seite den Besucher als `context.user`.
- erfährt die KI, dass der Besucher verifiziert ist, und seinen Namen, damit sie ihn begrüßen kann. Sonst nichts; siehe [Was die KI sieht](#was-die-ki-sieht).

Auf Wunsch kannst du [nur verifizierte Besucher chatten lassen](#nur-verifizierte-besucher-konnen-chatten).

Die Identitätsprüfung braucht die Chat-Bubble aus dem [Script-Tag](/de/docs/script-tag), weil die Identität über das [JavaScript-SDK](/de/docs/javascript-sdk) von deiner Seite kommt.

## Einrichten

### 1. Secret erzeugen

1. Öffne deinen Agenten und wechsle in den Tab **Share**.
2. Klicke auf der Karte **Identity verification** auf **Generate secret**.
3. Kopiere das Secret und leg es auf deinem Server ab, zum Beispiel in einer Umgebungsvariablen namens `INTOCHAT_IDENTITY_SECRET`.

Nur der Owner des Kontos und Admins können das Secret erzeugen, anzeigen oder austauschen. Editoren und Viewer sehen, ob eines gesetzt ist, und seine letzten vier Zeichen.

> Das Secret gehört nur auf deinen Server. Schreib es nie in das HTML oder JavaScript deiner Seite: Wer es hat, kann jede beliebige User-ID signieren und als dieser Nutzer chatten.

### 2. User-ID auf deinem Server signieren

Berechne für den angemeldeten Nutzer `userHash`: das HMAC-SHA256 der User-ID mit dem Secret als Schlüssel, geschrieben als Hexadezimalzahl in Kleinbuchstaben. Signiere genau den Text, den du als `userId` übergibst.

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

Schreib die User-ID und den Hash in die Seite, die du an diesen Nutzer schickst.

### 3. Besucher auf der Seite identifizieren

Rufe nach dem Snippet bei jedem Seitenaufruf `IntoChat.identify` auf, solange der Besucher angemeldet ist:

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

Die Grenzen für jedes Feld findest du unter [identify](/de/docs/javascript-sdk#identify). Das Widget sendet die Identität mit jeder Nachricht, und der Server von intoCHAT prüft die Signatur jedes Mal.

### 4. Beim Abmelden zurücksetzen

Meldet sich der Besucher ab, rufe Folgendes auf:

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

Das vergisst die Identität und startet einen neuen Chat, damit die nächste Person in diesem Browser das vorherige Gespräch nicht sieht. Auch das Identifizieren eines anderen Nutzers startet von selbst einen neuen Chat. Ein Besucher, der schon vor der Anmeldung gechattet hat, behält dieses Gespräch, und es wird dann verifiziert.

## Nur verifizierte Besucher können chatten

Schalte auf derselben Karte **Only verified visitors can chat** ein, um den Chat angemeldeten Nutzern vorzubehalten:

- Bis deine Seite den Besucher mit einer gültigen Signatur identifiziert, zeigt das Widget statt des Nachrichtenfelds einen kurzen Hinweis in der Sprache des Widgets, der ihn bittet, sich anzumelden.
- Die Chat-API lehnt Nachrichten ohne gültige Identität mit dem Grund `identity_required` ab, die Regel gilt also auch außerhalb des Widgets.
- Ein [iframe oder ein Direktlink](/de/docs/iframe-and-link) und die [Hilfeseite](/de/docs/help-page) können niemanden identifizieren und zeigen daher nur den Hinweis. [Vorschaulinks](/de/docs/preview-links) für Interessenten funktionieren weiter: Sie haben ihren eigenen Chat.
- Dein eigener [Playground](/de/docs/instructions#im-playground-testen) funktioniert weiter, du kannst den Agenten also weiterhin testen.

Der Schalter braucht ein Secret, erzeuge also zuerst eines. Editoren können ihn ein- und ausschalten.

## Platzhalter in server-seitigen Aktionen

Eine [server-seitige API-Aktion](/de/docs/api-actions) kann diese Platzhalter überall in URL, Parametern, Headern und Body verwenden:

| Platzhalter | Gefüllt mit |
| --- | --- |
| `{{user.id}}` | Der verifizierten User-ID |
| `{{user.email}}` | Der E-Mail-Adresse, die deine Seite übergeben hat |
| `{{user.name}}` | Dem Namen, den deine Seite übergeben hat |
| `{{user.metadata.<key>}}` | Einem Metadaten-Wert, zum Beispiel `{{user.metadata.plan}}` |

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

intoCHAT füllt sie auf seinen Servern aus, und zwar nur aus der verifizierten Identität:

- Bei einem Besucher, der nicht verifiziert ist, bleiben sie leer. Ein leerer Parameter oder ein leeres Body-Feld fällt aus der Anfrage heraus.
- Die KI sieht sie nie und kann sie weder wählen noch ändern. Selbst wenn die KI einen Wert übergibt, der wie `{{user.id}}` aussieht, wird er als reiner Text gesendet.
- **Send test request** im Editor hat keinen Besucher, dort sind sie also ebenfalls leer.
- Ein Platzhalter, der im Body allein steht, etwa `{{user.metadata.seats}}`, behält den Typ des Werts, eine Zahl bleibt also eine Zahl.

Andere `{{user.…}}`-Platzhalter wie `{{user.phone}}` lassen sich nicht speichern. In einer [client-seitigen Aktion](/de/docs/client-actions), deren Anfrage im Browser des Besuchers gebaut wird, bleiben diese Platzhalter leer; dein Handler bekommt den Besucher stattdessen als `context.user`.

> Signiert ist nur die User-ID. Name, E-Mail-Adresse und Metadaten sind das, was deine Seite zusammen mit einer gültigen Signatur übergeben hat. Ein angemeldeter Besucher könnte seine eigene Kopie im Browser also ändern. Schlag alles, was wichtig ist, etwa Bestellungen oder Berechtigungen, auf deiner Seite anhand von `{{user.id}}` nach.

## Verifizierte Besucher werden zu Kontakten

Jeder verifizierte Besucher wird als [Kontakt](/de/docs/contacts) des Agenten gespeichert, mit seiner User-ID als **External ID**, dem Namen und der E-Mail-Adresse, die deine Seite übergeben hat, und den Metadaten-Schlüsseln, die gültige Attributnamen sind (Kleinbuchstaben, Ziffern und Unterstriche, beginnend mit einem Buchstaben), als Attribute. Übergibt deine Seite neue Angaben, zieht der Kontakt nach. Der Kontakt wird nur anhand der User-ID gefunden: Ein verifizierter Besucher wird nie mit einem anderen Kontakt zusammengeführt, weil die E-Mail-Adressen übereinstimmen, und bekommt die E-Mail-Adresse nur, wenn kein anderer Kontakt sie hat. Server-seitige Aktionen können den Kontakt dann als `{{contact.*}}`-Platzhalter lesen, auch Attribute, die du importiert oder über die API hinzugefügt hast. Besucher aus **Test as a signed-in visitor** im Playground werden nicht zu Kontakten.

## Was die KI sieht

Die KI erfährt, dass der Besucher angemeldet und verifiziert ist, und den Namen, den deine Seite übergeben hat, mit dem sie ihn begrüßen darf. E-Mail-Adresse, User-ID und Metadaten bekommt sie nie, sie kann sie also weder wiederholen noch sich dazu überreden lassen, sie preiszugeben. Soll der Agent mehr wissen, schreib es selbst in deine [Anweisungen](/de/docs/instructions).

## Im Playground testen

Um die Platzhalter oder die Begrüßung des Agenten auszuprobieren, ohne dich auf deiner Website anzumelden, öffne den **Playground** und klappe über dem Chat **Test as a signed-in visitor** auf. Trag eine **User ID** ein und, wenn du willst, einen **Name**, eine **Email** und **Metadata** als JSON-Objekt, zum Beispiel `{"plan": "pro", "seats": 5}`. Es gelten dieselben Grenzen wie auf deiner Website; siehe [Grenzen](#grenzen). Solange etwas zu korrigieren ist, sagt eine rote Meldung, was, und der Playground chattet als anonymer Besucher.

Mit eingetragener User-ID gelten deine Nachrichten im Playground als verifiziert:

- [Server-seitige Aktionen](#platzhalter-in-server-seitigen-aktionen) bekommen diese Werte als `{{user.*}}`-Platzhalter.
- Die KI erfährt, dass der Besucher verifiziert ist, und seinen Namen, wie unter [Was die KI sieht](#was-die-ki-sieht) beschrieben.
- Das Playground-Gespräch speichert den Nutzer und zeigt deshalb im Tab Conversations **Verified**.

Eine Signatur ist nicht nötig, weil du bei intoCHAT angemeldet bist. Die Test-Identität wird nur aus dem Playground in deinem Dashboard angenommen, vom Owner, von Admins und von Editoren; Viewer können sie nicht nutzen, und Chat-Widget, Links und REST-API ignorieren sie. Besucher auf deiner Website brauchen immer eine gültige Signatur. [Nur verifizierte Besucher können chatten](#nur-verifizierte-besucher-konnen-chatten) sperrt den Playground nie, mit oder ohne Test-Identität.

Ein Gespräch behält den ersten verifizierten Nutzer, den es sieht. Drück deshalb auf **Reset**, bevor du als anderer Nutzer testest.

## Das Secret

- **Reveal** zeigt dem Owner und Admins das aktuelle Secret erneut an.
- **Rotate** erstellt nach einer Rückfrage ein neues Secret. Das alte funktioniert sofort nicht mehr: Bis dein Server mit dem neuen Secret signiert, gilt jeder Besucher als nicht verifiziert, und mit eingeschaltetem **Only verified visitors can chat** kann niemand chatten.
- Das Secret wird verschlüsselt gespeichert. Beim Duplizieren eines Agenten werden weder das Secret noch der Schalter kopiert.

## Grenzen

- Ein Secret pro Agent. Mit mehreren Agenten auf einer Seite prüft jeder nur Signaturen, die mit seinem eigenen Secret erstellt wurden.
- Eine falsche oder fehlende Signatur wird dem Besucher nie als Fehler gezeigt: Er chattet einfach unverifiziert, außer wenn nur verifizierte Besucher chatten dürfen.
- Ein Gespräch gehört dem ersten Nutzer, der darin verifiziert wurde. Schreibt ein anderer verifizierter Nutzer in derselben Sitzung, ohne den neuen Chat, den `identify` normalerweise startet, gelten diese Nachrichten als unverifiziert.
- Eine User-ID hat bis zu 200 Zeichen, ein Name bis zu 100, eine E-Mail-Adresse bis zu 254, und Metadaten haben bis zu 20 Schlüssel und 2 KB.
- Öffnet ein Besucher einen früheren Chat aus der Liste in seinem Browser erneut, wird die Identität nicht geprüft; [Beim Abmelden zurücksetzen](#4-beim-abmelden-zurucksetzen) leert diese Liste.