Kontakteigenschaften

Definieren Sie benutzerdefinierte Felder für Kontakte — etwa Kontotyp, Region oder Vertragsstufe — und übergeben Sie sie über das Widget. Eigenschaften werden im Profil des Kontakts angezeigt, sind von Mitarbeitern bearbeitbar und im Posteingang filterbar.

Übersicht#

Mit Kontakteigenschaften können Sie strukturierte Daten an Konversationen anhängen, die über die integrierten Felder (email, name, userId) hinausgehen. Anders als bei formlosen metadata verfügen Eigenschaften über ein definiertes Schema mit Typen, Beschriftungen und Validierung — ähnlich wie benutzerdefinierte Felder in HubSpot oder Salesforce.

Schema definieren

Erstellen Sie Eigenschaftsdefinitionen in den Agent-Einstellungen mit Typen wie string, number, enum, boolean, date, url

Aus dem Widget übergeben

Übergeben Sie Eigenschaftswerte via Respondo.identify() — sie werden automatisch gespeichert und angezeigt

Filtern & bearbeiten

Filtern Sie Konversationen im Posteingang nach Eigenschaftswerten. Mitarbeiter können die Attribute eines Kontakts im Kontaktprofil einsehen und bearbeiten.

Eigenschaften definieren#

Eigenschaften werden pro Agent in Agent-Einstellungen → Kontakteigenschaften definiert. Jede Eigenschaft hat:

Feld	Beschreibung
key	Eindeutige Kennung, die im Code verwendet wird. Wird automatisch aus der Beschriftung generiert (bearbeitbar). Kleinbuchstaben, Ziffern und Unterstriche; muss mit einem Buchstaben beginnen; 2–63 Zeichen. Systemschlüssel (`user_id`, `visitor_id`, `timezone`, `page_url`, …) sind reserviert. Beispiel: `account_type`
label	Menschenlesbarer Name, der im Dashboard angezeigt wird. Beispiel: „Kontotyp“
type	Werttyp: `string`, `number`, `boolean`, `enum`, `date`, `url`
enum_values	Für den Typ `enum` — Liste der erlaubten Werte. Beispiel: `[„starter“, „pro“, „enterprise“]`
is_filterable	Für künftige Filtersteuerung reserviert; wird mit der Definition gespeichert, aber die Filterauswahl im Posteingang listet derzeit alle definierten Eigenschaften (Standard: true)
is_visible	Für künftige Anzeigesteuerung reserviert; wird mit der Definition gespeichert, aber in der UI noch nicht durchgesetzt (Standard: true)

Bis zu 50 Eigenschaften pro Agent. Eigenschaften können in der Einstellungsoberfläche per Drag-and-drop neu angeordnet werden.

Übergeben Sie Eigenschaftswerte im Feld properties von Respondo.identify(). Die Schlüssel müssen mit den Eigenschaftsdefinitionen aus den Agent-Einstellungen übereinstimmen.

Widget-Integrationjavascript

Respondo.identify({
  email: 'user@example.com',
  name: 'Jane Smith',
  userId: 'usr_456',
  properties: {
    account_type: 'enterprise',   // enum
    region: 'eu-west',            // string
    monthly_spend: '15000',       // number (als String übergeben)
    is_partner: 'true',           // boolean (als String übergeben)
    contract_end: '2026-12-31',   // date
    dashboard_url: 'https://app.example.com/org/123'  // url
  }
});

Alle Eigenschaftswerte werden als Strings übergeben. Das Dashboard übernimmt die typspezifische Darstellung (z. B. boolean → Ja/Nein, url → anklickbarer Link, enum → Badge).

Integrations-Snippet#

Das Integrations-Snippet erscheint automatisch unter Agent-Einstellungen → Kontakteigenschaften, sobald Sie mindestens eine Eigenschaft definiert haben — mit allen vorausgefüllten Eigenschaftsschlüsseln. Klicken Sie auf Kopieren, um es zu übernehmen und in Ihre Anwendung einzufügen. Das generierte Snippet enthält außerdem einen userHash-Platzhalter für die Identitätsverifizierung (HMAC-SHA256).

Wie Werte gespeichert werden#

Eigenschaftswerte werden im metadata-JSONB-Feld der Konversation mit einem Präfix cp_ gespeichert. Eine Eigenschaft mit dem Schlüssel account_type wird zum Beispiel als cp_account_type gespeichert.

Eigenschaften werden bei jeder Nachricht aktualisiert — wenn das Widget neue Werte sendet, überschreiben sie die vorhandenen. Das bedeutet, dass Eigenschaftswerte stets die aktuellsten Daten aus Ihrer Anwendung widerspiegeln.

Filtern im Posteingang#

Filtern Sie Konversationen nach Eigenschaftswerten über die Filterleiste des Posteingangs oder eine gespeicherte Ansicht. Fügen Sie eine Bedingung Eigenschaft hinzu, wählen Sie die Eigenschaft nach Namen aus — die Auswahl listet jede Definition über alle Ihre Agenten hinweg und akzeptiert auch einen rohen Schlüssel ohne Definition — und wählen Sie dann einen Wert. Das Wertfeld schlägt beim Tippen beobachtete Werte und etwaige Enum-Werte vor.

Über die API akzeptieren die Endpunkte der Konversationsliste einen cp.<key>=<value> Query-Parameter (ein exakter Alias von attr.<key>). Es gibt keine Freitext-Abfragesyntax:

GET /api/v1/conversations?cp.account_type=enterprise

Werte bearbeiten#

Eigenschaftswerte werden von Ihrer Anwendung gesetzt — über die Widget-Integration oder die API — und sind im Konversationsdetail-Panel schreibgeschützt. Das Panel verlinkt auf das Profil des Kontakts, wo Mitarbeiter die Attribute des Kontakts einsehen und bearbeiten können (Kontakte → Kontakt → Attribute).

Eigenschaften vs. Metadata

Merkmal	properties	metadata
Schema	In den Agent-Einstellungen mit Typen definiert	Formlose Schlüssel-Wert-Paare
Filterbar	Ja, über die Filterleiste / gespeicherte Ansichten (API: `cp.<key>`-Parameter)	Nein
Von Mitarbeitern bearbeitbar	Nein — Werte kommen aus Ihrer Anwendung; Kontaktattribute werden im Kontaktprofil bearbeitet	Nein
Typisierte Anzeige	Ja (Badges, Links, Daten, Booleans)	Nur einfacher Text
Autovervollständigung	Ja, Wertvorschläge im Wertfeld des Filters	Nein

Verwenden Sie metadata für Ad-hoc-Felder, die keine Filterung oder typisierte Anzeige benötigen. Verwenden Sie properties für strukturierte Daten, die Ihr Team aktiv für Segmentierung und Workflows nutzt.