Proprietà del contatto

Definisci campi personalizzati per i contatti — come tipo di account, regione o livello di contratto — e trasmettili attraverso il widget. Le proprietà sono mostrate sul profilo del contatto, modificabili dagli operatori e filtrabili nell’Inbox.

Panoramica#

Le proprietà del contatto ti permettono di allegare dati strutturati alle conversazioni oltre i campi integrati (email, name, userId). A differenza dei metadata in formato libero, le proprietà hanno uno schema definito con tipi, etichette e validazione — simile ai campi personalizzati di HubSpot o Salesforce.

Definisci lo schema

Crea le definizioni delle proprietà nelle Impostazioni agente con tipi come string, number, enum, boolean, date, url

Trasmetti dal widget

Invia i valori delle proprietà tramite Respondo.identify() — vengono memorizzati e visualizzati automaticamente

Filtra e modifica

Filtra le conversazioni per valori di proprietà nell’Inbox. Gli operatori possono visualizzare e modificare gli attributi di un contatto sul profilo del contatto.

Definire le proprietà#

Le proprietà sono definite per agente in Impostazioni agente → Proprietà del contatto. Ogni proprietà ha:

Campo	Descrizione
key	Identificatore univoco usato nel codice. Generato automaticamente dall’etichetta (modificabile). Lettere minuscole, cifre e underscore; deve iniziare con una lettera; 2-63 caratteri. Le chiavi di sistema (`user_id`, `visitor_id`, `timezone`, `page_url`, …) sono riservate. Esempio: `account_type`
label	Nome leggibile mostrato nella dashboard. Esempio: "Account Type"
type	Tipo di valore: `string`, `number`, `boolean`, `enum`, `date`, `url`
enum_values	Per il tipo `enum` — elenco dei valori consentiti. Esempio: `["starter", "pro", "enterprise"]`
is_filterable	Riservato per un futuro controllo dei filtri; memorizzato con la definizione, ma il selettore dei filtri dell’Inbox attualmente elenca tutte le proprietà definite (default: true)
is_visible	Riservato per un futuro controllo della visualizzazione; memorizzato con la definizione ma non ancora applicato nell’interfaccia (default: true)

Fino a 50 proprietà per agente. Le proprietà possono essere riordinate tramite drag-and-drop nell’interfaccia delle impostazioni.

Trasmetti i valori delle proprietà nel campo properties di Respondo.identify(). Le chiavi devono corrispondere alle definizioni delle proprietà nelle Impostazioni agente.

Integrazione del widgetjavascript

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 (passato come stringa)
    is_partner: 'true',           // boolean (passato come stringa)
    contract_end: '2026-12-31',   // date
    dashboard_url: 'https://app.example.com/org/123'  // url
  }
});

Tutti i valori delle proprietà vengono trasmessi come stringhe. La dashboard gestisce la visualizzazione specifica per tipo (ad es. boolean → Sì/No, url → link cliccabile, enum → badge).

Snippet di integrazione#

Lo Snippet di integrazione appare automaticamente in Impostazioni agente → Proprietà del contatto una volta definita almeno una proprietà, con tutte le chiavi delle proprietà già precompilate. Clicca su Copia per prenderlo e incollarlo nella tua applicazione. Lo snippet generato include anche un segnaposto userHash per la verifica dell’identità (HMAC-SHA256).

Come vengono memorizzati i valori#

I valori delle proprietà vengono memorizzati nel campo JSONB metadata della conversazione con un prefisso cp_. Per esempio, una proprietà con chiave account_type viene memorizzata come cp_account_type.

Le proprietà vengono aggiornate a ogni messaggio — se il widget invia nuovi valori, questi sovrascrivono quelli esistenti. Ciò significa che i valori delle proprietà riflettono sempre i dati più recenti dalla tua applicazione.

Filtrare nell’Inbox#

Filtra le conversazioni per valori di proprietà usando la barra dei filtri dell’Inbox o una Vista salvata. Aggiungi una condizione Property, scegli la proprietà per nome — il selettore elenca ogni definizione tra i tuoi agenti e accetta anche una chiave grezza senza definizione — poi scegli un valore. Il campo del valore suggerisce i valori osservati e gli eventuali valori enum mentre digiti.

Via API, gli endpoint di elenco delle conversazioni accettano un parametro di query cp.<key>=<value> (un alias esatto di attr.<key>). Non esiste una sintassi di query a testo libero:

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

Modifica dei valori#

I valori delle proprietà vengono impostati dalla tua applicazione — tramite l’integrazione del widget o l’API — e sono in sola lettura nel pannello dei dettagli della conversazione. Il pannello rimanda al profilo del contatto, dove gli operatori possono visualizzare e modificare gli attributi del contatto (Contatti → contatto → Attributi).

Proprietà vs Metadata

Caratteristica	properties	metadata
Schema	Definito nelle Impostazioni agente con i tipi	Coppie chiave-valore in formato libero
Filtrabile	Sì, tramite la barra dei filtri / Viste salvate (API: parametro `cp.<key>`)	No
Modificabile dagli operatori	No — i valori provengono dalla tua applicazione; gli attributi del contatto si modificano sul profilo del contatto	No
Visualizzazione tipizzata	Sì (badge, link, date, booleani)	Solo testo semplice
Completamento automatico	Sì, suggerimenti di valori nel campo del valore del filtro	No

Usa metadata per campi ad hoc che non richiedono filtraggio o visualizzazione tipizzata. Usa properties per dati strutturati che il tuo team utilizzerà attivamente per la segmentazione e i flussi di lavoro.