联系人属性

为联系人定义自定义字段——例如账户类型、地区或合同等级——并通过挂件传递这些字段。属性会显示在联系人的资料页上，可由客服编辑，并可在收件箱中用于筛选。

概览#

联系人属性让您能够在内置字段（email、name、userId）之外，为对话附加结构化数据。与自由格式的 metadata 不同，属性拥有定义好的模式，包含类型、标签和校验——类似于 HubSpot 或 Salesforce 中的自定义字段。

定义模式

在 Agent Settings 中创建属性定义，支持 string、number、enum、boolean、date、url 等类型

从挂件传递

通过 Respondo.identify() 发送属性值——它们会被自动存储并显示

筛选与编辑

在收件箱中按属性值筛选对话。客服可以在联系人资料页上查看和编辑联系人的属性。

定义属性#

属性按 agent 定义，位于 Agent Settings → Contact Properties。每个属性包含：

字段	说明
key	在代码中使用的唯一标识符。根据标签自动生成（可编辑）。仅限小写字母、数字和下划线；必须以字母开头；长度 2–63 个字符。系统键（`user_id`、 `visitor_id`、 `timezone`、 `page_url` 等）为保留键。示例： `account_type`
label	在仪表盘中显示的可读名称。示例："Account Type"
type	值的类型：`string`、 `number`、`boolean`、 `enum`、`date`、 `url`
enum_values	对于 `enum` 类型——允许值的列表。示例： `["starter", "pro", "enterprise"]`
is_filterable	为未来的筛选控制预留；随定义一起存储，但收件箱的筛选选择器目前会列出所有已定义的属性（默认：true）
is_visible	为未来的显示控制预留；随定义一起存储，但 UI 中尚未强制执行（默认：true）

每个 agent 最多 50 个属性。可在设置界面中通过拖放来重新排序属性。

在 Respondo.identify() 的 properties 字段中传递属性值。键必须与 Agent Settings 中的属性定义匹配。

挂件集成javascript

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（以字符串形式传递）
    is_partner: 'true',           // boolean（以字符串形式传递）
    contract_end: '2026-12-31',   // date
    dashboard_url: 'https://app.example.com/org/123'  // url
  }
});

所有属性值都以字符串形式传递。仪表盘会处理与类型相关的显示（例如 boolean → 是/否，url → 可点击链接，enum → 徽章）。

集成代码片段#

当您至少定义了一个属性后，Integration Snippet 会自动出现在 Agent Settings → Contact Properties 下方，其中已预填所有属性键。点击 Copy 获取它并粘贴到您的应用中。生成的代码片段还包含一个用于身份校验（HMAC-SHA256）的 userHash 占位符。

值如何被存储#

属性值存储在对话的 metadata JSONB 字段中，并带有 cp_ 前缀。例如，键为 account_type 的属性会被存储为 cp_account_type。

属性在每条消息时都会更新——如果挂件发送了新值，它们会覆盖已有的值。这意味着属性值始终反映您应用中的最新数据。

在收件箱中筛选#

通过收件箱的筛选栏或保存的视图（View），按属性值筛选对话。添加一个 Property 条件，按名称选择属性 —— 选择器会列出您所有 agent 下的每一个定义，也接受没有定义的原始键 —— 然后选择一个值。值输入框会在您输入时给出已观察到的值以及所有枚举值的建议。

在 API 层面，对话列表端点接受 cp.<key>=<value> 查询参数（它是 attr.<key> 的完全等价别名）。不存在自由文本查询语法：

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

编辑属性值#

属性值由您的应用设置——通过挂件集成或 API——在对话详情面板中是只读的。面板会链接到联系人的资料页，客服可以在那里查看和编辑联系人的属性（Contacts → 联系人 → Attributes）。

属性与元数据的对比

特性	properties	metadata
模式	在 Agent Settings 中定义，带类型	自由格式的键值对
可筛选	可以，通过筛选栏 / 保存的视图（API： `cp.<key>` 参数）	不可以
客服可编辑	不可以——值来自您的应用；联系人属性在联系人资料页上编辑	不可以
类型化显示	可以（徽章、链接、日期、布尔值）	仅纯文本
自动补全	可以，在筛选器的值输入框中提供值建议	不可以

对于不需要筛选或类型化显示的临时字段，使用 metadata。对于团队会主动用于细分和工作流的结构化数据，使用 properties。