連絡先プロパティ

連絡先プロパティを使うと、組み込みフィールド（email、name、userId）を超えた構造化データを会話に付与できます。自由形式の metadata とは異なり、プロパティは型・ラベル・検証を備えた定義済みスキーマを持ちます。HubSpot や Salesforce のカスタムフィールドに似ています。

プロパティは エージェント設定 → 連絡先プロパティ でエージェントごとに定義します。各プロパティには次の項目があります:

プロパティ値は Respondo.identify() の properties フィールドで渡します。キーはエージェント設定のプロパティ定義と一致している必要があります。

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
  }
});

連携スニペット は、プロパティを 1 つ以上定義すると、エージェント設定 → 連絡先プロパティの下に自動的に表示され、すべてのプロパティキーがあらかじめ入力されています。 コピー をクリックして取得し、アプリケーションに貼り付けてください。生成されたスニペットには、本人確認（HMAC-SHA256）用の userHash プレースホルダーも含まれます。

プロパティ値は、会話の metadata JSONB フィールドに cp_ というプレフィックス付きで保存されます。例えば、キー account_type のプロパティは cp_account_type として保存されます。

プロパティはメッセージごとに更新されます。ウィジェットが新しい値を送ると、既存の値が上書きされます。つまりプロパティ値は常にアプリケーションの最新データを反映します。

受信トレイのフィルターバーまたは保存済みビューを使って、プロパティ値で会話をフィルタリングできます。 プロパティ 条件を追加し、名前でプロパティを選び — ピッカーはすべてのエージェントにわたる定義を一覧表示し、定義のない生のキーも受け付けます — 値を選択します。値フィールドは、入力に応じて観測された値と enum の値を候補として表示します。

API では、会話リストのエンドポイントが cp.<key>=<value> クエリパラメータ（attr.<key> の完全なエイリアス）を受け付けます。フリーテキストのクエリ構文はありません:

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

プロパティ値はあなたのアプリケーションによって — ウィジェット連携または API 経由で — 設定され、会話詳細パネルでは読み取り専用です。パネルには連絡先プロフィールへのリンクがあり、担当者はそこで連絡先の属性を確認・編集できます（Contacts → 連絡先 → 属性）。