ویژگی‌های مخاطب

برای مخاطبان فیلدهای سفارشی تعریف کنید — مانند نوع حساب، منطقه یا سطح قرارداد — و آن‌ها را از راه ویجت بفرستید. ویژگی‌ها در نمایهٔ مخاطب نشان داده می‌شوند، کارشناسان می‌توانند ویرایششان کنند و در صندوق ورودی قابل فیلترند.

نمای کلی#

ویژگی‌های مخاطب به شما امکان می‌دهند فراتر از فیلدهای درون‌ساخت (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	برای کنترل فیلتر در آینده رزرو شده است؛ همراه تعریف ذخیره می‌شود، اما انتخاب‌گر فیلتر صندوق ورودی فعلاً همهٔ ویژگی‌های تعریف‌شده را فهرست می‌کند (پیش‌فرض: true)
is_visible	برای کنترل نمایش در آینده رزرو شده است؛ همراه تعریف ذخیره می‌شود اما هنوز در رابط اعمال نمی‌شود (پیش‌فرض: 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) در بر دارد.

مقدارها چگونه ذخیره می‌شوند#

مقدار ویژگی‌ها در فیلد JSONB با نام metadata مربوط به گفت‌وگو و با پیشوند cp_ ذخیره می‌شود. برای نمونه، ویژگی‌ای با کلید account_type به شکل cp_account_type ذخیره می‌شود.

ویژگی‌ها با هر پیام به‌روزرسانی می‌شوند — اگر ویجت مقدارهای تازه بفرستد، روی مقدارهای موجود نوشته می‌شوند. یعنی مقدار ویژگی‌ها همیشه تازه‌ترین دادهٔ برنامهٔ شما را بازتاب می‌دهند.

فیلتر در صندوق ورودی#

گفت‌وگوها را با نوار فیلتر صندوق ورودی یا یک نمای ذخیره‌شده بر پایهٔ مقدار ویژگی‌ها فیلتر کنید. یک شرط Property اضافه کنید، ویژگی را با نامش انتخاب کنید — انتخاب‌گر همهٔ تعریف‌های میان عامل‌هایتان را فهرست می‌کند و کلید خامِ بدون تعریف را هم می‌پذیرد — و سپس مقدار را انتخاب کنید. فیلد مقدار همزمان با تایپ، مقدارهای دیده‌شده و هر مقدار enum را پیشنهاد می‌دهد.

روی API، endpointهای فهرست گفت‌وگوها یک پارامتر پرس‌وجوی cp.<key>=<value> می‌پذیرند (نام دیگری دقیقاً برابر با attr.<key>). نحو پرس‌وجوی متنی آزاد وجود ندارد:

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

ویرایش مقادیر#

مقدار ویژگی‌ها را برنامهٔ شما تعیین می‌کند — از راه یکپارچه‌سازی ویجت یا API — و در پنل جزئیات گفت‌وگو فقط-خواندنی‌اند. پنل به نمایهٔ مخاطب پیوند می‌دهد؛ کارشناسان آنجا می‌توانند صفت‌های مخاطب را ببینند و ویرایش کنند (مخاطبان ← مخاطب ← صفت‌ها).

ویژگی‌ها در برابر فراداده

قابلیت	properties	metadata
شِما	در تنظیمات عامل همراه با نوع تعریف می‌شود	جفت‌های کلید-مقدار با قالب آزاد
قابل فیلتر	بله، از راه نوار فیلتر / نماهای ذخیره‌شده (API: پارامتر `cp.<key>`)	خیر
قابل ویرایش توسط کارشناسان	خیر — مقدارها از برنامهٔ شما می‌آیند؛ صفت‌های مخاطب در نمایهٔ مخاطب ویرایش می‌شوند	خیر
نمایش متناسب با نوع	بله (نشان، پیوند، تاریخ، مقدار بولی)	فقط متن ساده
تکمیل خودکار	بله، پیشنهاد مقدار در فیلد مقدارِ فیلتر	خیر

برای فیلدهای موردی که نیازی به فیلتر یا نمایش نوع‌دار ندارند از metadata استفاده کنید. برای دادهٔ ساختاریافته‌ای که تیم شما فعالانه برای بخش‌بندی و گردش‌کار به کار می‌برد از properties استفاده کنید.