Contact Properties

Define custom fields for contacts — like account type, region, or contract tier — and pass them through the widget. Properties are shown on the contact's profile, 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 view and edit a contact's attributes on the contact profile.

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 (editable). Lowercase letters, digits and underscores; must start with a letter; 2-63 chars. System keys (`user_id`, `visitor_id`, `timezone`, `page_url`, …) are reserved. 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	Reserved for future filter control; stored with the definition, but the Inbox filter picker currently lists all defined properties (default: true)
is_visible	Reserved for future display control; stored with the definition but not yet enforced in the UI (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#

The Integration Snippet appears automatically under Agent Settings → Contact Properties once you have defined at least one property, with all your property keys pre-filled. Click Copy to grab it and paste it into your application. The generated snippet also includes a userHash placeholder for identity verification (HMAC-SHA256).

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#

Filter conversations by property values using the Inbox filter bar or a saved View. Add a Property condition, pick the property by name — the picker lists every definition across your agents and also accepts a raw key that has no definition — then choose a value. The value field suggests observed values and any enum values as you type.

Over the API, the conversations list endpoints accept a cp.<key>=<value> query parameter (an exact alias of attr.<key>). There is no free-text query syntax:

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

Editing Values#

Property values are set by your application — via the widget integration or the API — and are read-only in the conversation details panel. The panel links to the contact's profile, where operators can view and edit the contact's attributes (Contacts → contact → Attributes).

Properties vs Metadata

Feature	properties	metadata
Schema	Defined in Agent Settings with types	Free-form key-value pairs
Filterable	Yes, via the filter bar / saved Views (API: `cp.<key>` param)	No
Editable by operators	No — values come from your application; contact attributes are edited on the contact profile	No
Typed display	Yes (badges, links, dates, booleans)	Plain text only
Autocomplete	Yes, value suggestions in the filter value field	No

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