Документація

Властивості контакту

Визначайте власні поля для контактів — наприклад тип акаунта, регіон або рівень контракту — і передавайте їх через віджет. Властивості показуються в профілі контакту, оператори можуть їх редагувати, а у спільній скриньці за ними можна фільтрувати.

Огляд

Властивості контакту дають змогу прикріплювати до розмов структуровані дані понад вбудовані поля (email, name, userId). На відміну від довільних metadata, властивості мають визначену схему з типами, підписами та валідацією — подібно до власних полів у HubSpot чи Salesforce.

Визначте схему

Створюйте визначення властивостей у налаштуваннях агента з типами на кшталт string, number, enum, boolean, date, url

Передавайте з віджета

Надсилайте значення властивостей через Respondo.identify() — вони зберігаються та відображаються автоматично

Фільтруйте та редагуйте

Фільтруйте розмови за значеннями властивостей у спільній скриньці. Оператори можуть переглядати й редагувати атрибути контакту в його профілі.

Визначення властивостей

Властивості визначаються для кожного агента в Налаштування агента → Властивості контакту. Кожна властивість має:

ПолеОпис
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Зарезервовано для майбутнього керування фільтрами; зберігається разом із визначенням, але добірник фільтрів Inbox наразі показує всі визначені властивості (за замовчуванням: true)
is_visibleЗарезервовано для майбутнього керування відображенням; зберігається разом із визначенням, але поки не застосовується в UI (за замовчуванням: true)
До 50 властивостей на агента. Порядок властивостей можна змінювати перетягуванням в інтерфейсі налаштувань.

Передавання з віджета

Передавайте значення властивостей у полі properties виклику Respondo.identify(). Ключі мають збігатися з визначеннями властивостей із налаштувань агента.

Інтеграція віджета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 → бейдж).

Фрагмент для інтеграції

Фрагмент для інтеграції з’являється автоматично в Налаштування агента → Властивості контакту, щойно ви визначили принаймні одну властивість, з усіма наперед заповненими ключами властивостей. Натисніть Copy, щоб узяти його, і вставте у свій застосунок. Згенерований фрагмент також містить плейсхолдер userHash для верифікації особи (HMAC-SHA256).

Як зберігаються значення

Значення властивостей зберігаються в полі metadata (JSONB) розмови з префіксом cp_. Наприклад, властивість із ключем account_type зберігається як cp_account_type.

Властивості оновлюються з кожним повідомленням — якщо віджет надсилає нові значення, вони перезаписують наявні. Це означає, що значення властивостей завжди відображають найсвіжіші дані з вашого застосунку.

Фільтрація у спільній скриньці

Фільтруйте розмови за значеннями властивостей через панель фільтрів Inbox або збережене представлення (View). Додайте умову Property, виберіть властивість за назвою — добірник показує кожне визначення в усіх ваших агентах і також приймає сирий ключ без визначення — а потім виберіть значення. Поле значення підказує спостережені значення та будь-які enum-значення в міру введення.

Через API ендпоінти списку розмов приймають query-параметр cp.<key>=<value> (точний аліас attr.<key>). Вільнотекстового синтаксису запитів немає:

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

Редагування значень

Значення властивостей задає ваш застосунок — через інтеграцію віджета або API — і на панелі деталей розмови вони доступні лише для читання. Панель веде до профілю контакту, де оператори можуть переглядати й редагувати атрибути контакту (Contacts → контакт → Attributes).

Властивості проти Metadata

Можливістьpropertiesmetadata
СхемаВизначається в налаштуваннях агента з типамиДовільні пари ключ-значення
ФільтраціяТак, через панель фільтрів / збережені View (API: параметр cp.<key>)Ні
Редагування операторамиНі — значення надходять із вашого застосунку; атрибути контакту редагуються в профілі контактуНі
Типізоване відображенняТак (бейджі, посилання, дати, булеві значення)Лише звичайний текст
АвтозаповненняТак, підказки значень у полі значення фільтраНі
Використовуйте metadata для тимчасових полів, яким не потрібні фільтрація чи типізоване відображення. Використовуйте properties для структурованих даних, які ваша команда активно використовуватиме для сегментації та в робочих процесах.