خصائص جهة الاتصال

عرّف حقولاً مخصصة لجهات الاتصال — مثل نوع الحساب أو المنطقة أو مستوى العقد — ومرّرها عبر الأداة. تظهر الخصائص في الملف الشخصي لجهة الاتصال، ويمكن لموظفي الدعم تحريرها، وتصفيتها في صندوق الوارد.

نظرة عامة#

تتيح لك خصائص جهة الاتصال إرفاق بيانات منظّمة بالمحادثات تتجاوز الحقول المدمجة (البريد الإلكتروني، الاسم، 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',       // رقم (يُمرَّر كنص)
    is_partner: 'true',           // boolean (يُمرَّر كنص)
    contract_end: '2026-12-31',   // date
    dashboard_url: 'https://app.example.com/org/123'  // url
  }
});

تُمرَّر جميع قيم الخصائص كنصوص. تتولى لوحة التحكّم العرض الخاص بكل نوع (مثلاً boolean ← نعم/لا، url ← رابط قابل للنقر، enum ← شارة).

مقتطف التكامل#

يظهر مقتطف التكامل تلقائياً ضمن إعدادات الوكيل ← خصائص جهة الاتصال بمجرد تعريف خاصية واحدة على الأقل، مع جميع مفاتيح خصائصك معبأة مسبقاً. انقر نسخ لأخذه والصقه في تطبيقك. يتضمن المقتطف المُنشأ أيضاً عنصراً نائباً لـ userHash للتحقق من الهوية (HMAC-SHA256).

كيف تُخزَّن القيم#

تُخزَّن قيم الخصائص في حقل metadata من نوع JSONB الخاص بالمحادثة مع بادئة cp_. على سبيل المثال، خاصية بالمفتاح account_type تُخزَّن باسم cp_account_type.

تُحدَّث الخصائص مع كل رسالة — إذا أرسلت الأداة قيماً جديدة، فإنها تحل محل القيم الموجودة. هذا يعني أن قيم الخصائص تعكس دائماً أحدث بيانات من تطبيقك.

التصفية في صندوق الوارد#

صفِّ المحادثات حسب قيم الخصائص باستخدام شريط المرشحات في صندوق الوارد أو عرض محفوظ. أضف شرط Property، واختر الخاصية بالاسم — يعرض المنتقي كل تعريف عبر وكلائك ويقبل أيضاً مفتاحاً خاماً بلا تعريف — ثم اختر قيمة. يقترح حقل القيمة القيم الملاحَظة وأي قيم enum أثناء الكتابة.

عبر API، تقبل نقاط نهاية قائمة المحادثات معامل استعلام cp.<key>=<value> (اسم بديل مطابق تماماً لـ attr.<key>). لا توجد صيغة استعلام نصية حرة:

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

تحرير القيم#

تُضبط قيم الخصائص من تطبيقك — عبر تكامل الأداة أو API — وهي للقراءة فقط في لوحة تفاصيل المحادثة. تحيل اللوحة إلى الملف الشخصي لجهة الاتصال، حيث يمكن لموظفي الدعم عرض سمات جهة الاتصال وتحريرها (جهات الاتصال ← جهة الاتصال ← السمات).

الخصائص مقابل البيانات الوصفية

الميزة	properties	metadata
المخطط	مُعرَّف في إعدادات الوكيل بأنواع	أزواج مفتاح-قيمة حرّة
قابلة للتصفية	نعم، عبر شريط المرشحات / العروض المحفوظة (API: معامل `cp.<key>`)	لا
قابلة للتحرير من موظفي الدعم	لا — تأتي القيم من تطبيقك؛ تُحرَّر سمات جهة الاتصال في الملف الشخصي لجهة الاتصال	لا
عرض حسب النوع	نعم (شارات، روابط، تواريخ، قيم منطقية)	نص عادي فقط
الإكمال التلقائي	نعم، اقتراحات قيم في حقل قيمة المرشح	لا

استخدم metadata للحقول المؤقتة التي لا تحتاج إلى تصفية أو عرض منسّق حسب النوع. استخدم properties للبيانات المنظّمة التي سيستخدمها فريقك بفاعلية للتقسيم وسير العمل.