Contact Properties

Define custom fields for contacts — like account type, region, or contract tier — and pass them through the widget. Properties are visible in conversation details, editable by operators, and filterable in the Inbox.

Overview#

Contact Properties let you attach structured data to conversations beyond the built-in fields (email, name, userId). Unlike free-form metadata, properties have a defined schema with types, labels, and validation — similar to custom fields in HubSpot or Salesforce.

Define Schema

Create property definitions in Agent Settings with types like string, number, enum, boolean, date, url

Pass from Widget

Send property values via Respondo.identify() — they are stored and displayed automatically

Filter & Edit

Filter conversations by property values in the Inbox. Operators can edit values inline.

Defining Properties#

Properties are defined per agent in Agent Settings → Contact Properties. Each property has:

Field	Description
key	Unique identifier used in code. Auto-generated from label. Lowercase, underscores only. Example: `account_type`
label	Human-readable name shown in the dashboard. Example: "Account Type"
type	Value type: `string`, `number`, `boolean`, `enum`, `date`, `url`
enum_values	For `enum` type — list of allowed values. Example: `["starter", "pro", "enterprise"]`
is_filterable	Whether this property appears in Inbox query filters (default: true)
is_visible	Whether this property is shown in conversation details panel (default: true)

Up to 50 properties per agent. Properties can be reordered via drag-and-drop in the settings UI.

Pass property values in the properties field of Respondo.identify(). Keys must match the property definitions from Agent Settings.

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

All property values are passed as strings. The dashboard handles type-specific display (e.g., boolean → Yes/No, url → clickable link, enum → badge).

Integration Snippet#

In Agent Settings → Contact Properties, click Get Integration Snippet to generate a ready-to-use code snippet with all your property keys pre-filled. Copy and paste it into your application.

How Values Are Stored#

Property values are stored in the conversation's metadata JSONB field with a cp_ prefix. For example, a property with key account_type is stored as cp_account_type.

Properties are updated on every message — if the widget sends new values, they overwrite the existing ones. This means property values always reflect the latest data from your application.

Filtering in the Inbox#

Use the prop.key:value syntax in Query Mode to filter conversations by property values:

prop.account_type:enterprise
prop.region:eu-west status:escalated
prop.is_partner:true

The search field provides autocomplete suggestions for property values as you type.

Inline Editing#

Operators can edit property values directly from the conversation details panel. Click the edit icon next to the Contact Properties section, modify values, and save. Changes are persisted immediately.

Properties vs Metadata

Feature	properties	metadata
Schema	Defined in Agent Settings with types	Free-form key-value pairs
Filterable	Yes, via `prop.key:value`	No
Editable by operators	Yes, inline in conversation panel	No
Typed display	Yes (badges, links, dates, booleans)	Plain text only
Autocomplete	Yes, value suggestions in search	No

Use metadata for ad-hoc fields that don't need filtering or operator editing. Use properties for structured data that your team will actively use for segmentation and workflow.