Sender-Info erfassen (captureSender)

Name/Email/Phone aus Chats persistieren — fuer Lead-Tracking, Support-Tickets, Reklamationen.

Wenn ein Chat mit einem anonymen Besucher (Bloomify-Widget, Public-Chat, Lead-Form) Kontaktdaten erfasst, willst du die später wiederfinden — in der Manage-Chat-Liste, in Reports, im CRM. Dafür gibt es das interne Tool captureSender unter _shared/tools/contacts/.

#Wann benutzen

captureSender ist kein Tool fürs LLM. Direkt aufrufen wäre unzuverlässig — das Modell vergisst es oder ruft's mit Mist-Daten auf. Stattdessen ruft jedes Domain-Tool das einen Vorgang abschließt es intern auf, mit den Werten die der User für genau diesen Vorgang angegeben hat:

• createLead({name, email, ...}) → kennt Name + Email zwingend
• createSupportTicket({email, message}) → kennt Email
• createReclamation({orderNumber, email, name}) → kennt Email + ggf. Name
• subscribeToNewsletter({email}) → kennt Email

Jedes dieser Tools macht am Ende:

$ctx['tool']('captureSender', [
    'name'    => $args['name'] ?? null,
    'email'   => $args['email'] ?? null,
    'phone'   => $args['phone'] ?? null,
    'company' => $args['company'] ?? null,
]);

#Verhalten

• Pro (tenant, chat_id) ein Eintrag in der Tabelle chat_senders.
• Partial-Update: leere/null Felder überschreiben nichts. So reichern sich Daten über mehrere Tool-Calls an. Beispiel: createSupportTicket capturet email, später setzt createLead auch name + company — am Ende hat der Chat alle vier.
• Email-Validierung per FILTER_VALIDATE_EMAIL. Ungültige Werte → Tool gibt error zurück, kein Speichern.
• Mindestens ein Feld muss non-null sein, sonst ist der Caller kaputt.

#Speicher-Layout

Tabelle chat_senders:

Index: idx_chat_senders_email für „welche Chats kommen von diesem Kontakt?" (z.B. wiederkehrende Support-Anfragen).

#Sichtbarkeit

Manage-Chat-Liste (/manage/chat-messages) zeigt Sender-Info als Fallback in der User-Spalte. Reihenfolge:

1. User-UUID aus chat_id (eingeloggter Nutzer der App)
2. Sender-Info (Name, Email darunter klein)
3. UUID-Stub (8 Zeichen, wenn vorhanden aber kein User-Match)
4. „–"

#Anti-Patterns

• Kein direkter LLM-Aufruf. captureSender ist internal: true und nicht in assistants.<slug>.tools gelistet. Wer das LLM zum Capturen ruft, bekommt halb-saubere Daten.
• Keine UI-State-Erfassung. Wenn der User beim Eintippen Email tippt aber nie submit macht, soll nichts gespeichert werden — nur was über ein Domain-Tool tatsächlich „eingereicht" wurde.
• Kein Stand-In für CRM. chat_senders ist Audit-Trail-Schicht, kein Customer-Master. Echte Lead-Pipelines (Shopify, Pipedrive) bleiben separat.