بيانات العملاء Customer CDP

واجهة بيانات العملاء Customer CDP هي سطح التكامل الموحّد بين HueChat وأنظمة ERP وCRM والتجارة: جهات الاتصال والملفات الموحدة والجماهير والتفضيلات والعضوية والرحلات. تستخدم قواعد التحقق وأقفال الهوية وسجل الأحداث نفسها المستخدمة في لوحة HueChat، ويُحصر كل طلب في الحساب الذي أصدر مفتاح API.

قبل البدء

أنشئ مفتاح API محدود النطاق من الحساب ← واجهة المطور مع contacts:read للقائمة والبحث وقراءة جهة الاتصال. تتطلب الملفات الموحدة والنشاط والجداول الزمنية وعروض العملاء المتقدمة أيضًا deals:read لأنها تحتوي بيانات الصفقات والمهام. أضف contacts:write للإنشاء والتحديث والدمج. ويتطلب الدمج أن يكون المالك الحالي للمفتاح مديرًا للحساب. تستخدم مسارات /cdp (العملاء والجماهير والتفضيلات والعضوية والوصول والرحلات) النطاقين cdp:read وcdp:write. وتستمر المفاتيح التي تملك contacts:* (أو workflows:* للرحلات) في العمل.

استخدم معرّف الحساب الذي أصدر المفتاح. يعيد مفتاح حساب آخر 403، ولا تُحل معرّفات جهات الاتصال أو المعرّفات الخارجية أو أسماء الدمج المستعارة خارج الحساب.

إنشاء جهة اتصال

استخدم identifier كمعرّف العميل الثابت في نظامك. يفرض HueChat تفرده داخل الحساب الواحد.

curl -X POST "https://app.huechat.ai/api/v2/accounts/$ACCOUNT_ID/contacts" \
  -H "Authorization: Bearer $HUECHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "erp-customer-8842",
    "name": "سارة العتيبي",
    "email": "sara@example.com",
    "phone_number": "0501234567",
    "phone_country": "SA",
    "gender": "female",
    "additional_attributes": {
      "company_name": "شركة تجريبية",
      "preferred_language": "ar"
    },
    "custom_attributes": {
      "customer_tier": "gold"
    }
  }'

تُوحّد أرقام الهاتف بصيغة E.164، وتُرفض تعارضات البريد والمعرّف والهاتف بدل دمج شخصين بصمت. كما تُرفض الحقول غير المعروفة والأجسام الكبيرة. يُحفظ إنشاء الجهة وحدث contact.created معًا.

الجنس

gender قيمة اختيارية في ملف العميل يرسلها العميل أو المشغّل المخوّل. يقبل HueChat القيم male أو female أو other فقط (مع تجاهل حالة الأحرف)، ويعيد القيمة بحروف صغيرة أو سلسلة فارغة عند عدم توفيرها. لا يستنتجها من الاسم أو المحادثة أو الموعد، ولا يجوز استخدامها لقرارات الرعاية أو الأهلية أو الإعلان أو توقع الحضور. عند الإنشاء، احذف الحقل إذا لم تكن القيمة معروفة. عند التحديث، احذف الحقل للحفاظ على القيمة الحالية أو أرسل "gender": "" لمسحها. تُحفظ القيمة أيضًا في additional_attributes.gender للتوافق مع عملاء CDP الأقدم؛ وإذا أُرسلت القيمتان فيجب أن تتطابقا.

curl -X PATCH "https://app.huechat.ai/api/v2/accounts/$ACCOUNT_ID/contacts/1042" \
  -H "Authorization: Bearer $HUECHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"gender":"other"}'

الاسم الأول والأوسط والأخير

يمكن لجهة الاتصال أيضًا حفظ اسمها في first_name وmiddle_name (اختياري) وlast_name. ويبقى name هو الاسم الكامل المعروض.

curl -X PATCH "https://app.huechat.ai/api/v2/accounts/$ACCOUNT_ID/contacts/1042" \
  -H "Authorization: Bearer $HUECHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "سارة",
    "middle_name": "محمد",
    "last_name": "العتيبي"
  }'

إرسال أي جزء يجعل name هو الأجزاء المعبأة مفصولة بمسافة واحدة بترتيب الأول ثم الأوسط ثم الأخير. ويُتجاهل name المرسل في الطلب نفسه.
الجزء الذي لا ترسله أو ترسله null يحتفظ بقيمته المحفوظة، و"" يمسحه. إذا أصبحت كل الأجزاء فارغة تُمسح الأجزاء ويبقى name كما هو، أو يصبح name الذي أرسلته.
في جهة اتصال بلا أجزاء، تُملأ الأجزاء التي لم ترسلها من اسمها: إرسال {"last_name": "العتيبي"} إلى “سارة محمد” يعطي سارة، بلا اسم أوسط، والعتيبي. ولا يُقسَّم اسم بلا حروف، مثل رقم هاتف.
إرسال name وحده يعيد تسمية جهة الاتصال ولا يغيّر الأجزاء، ولا يُقسَّم الاسم إلى أجزاء أبدًا.
الحد الأقصى لكل جزء، ولـname، وللاسم الذي تكوّنه الأجزاء 255 حرفًا. تعيد القيمة الأطول 422، ويعيد الجزء الذي ليس نصًا 400.

تتضمن استجابات إنشاء جهة الاتصال وتحديثها وقراءتها وقائمتها وبحثها الحقول الثلاثة دائمًا، وقيمة كل منها null عند عدم تعيينه. وتكون null أيضًا بعد إعادة تسمية جهة الاتصال بـname وحده، لأن الأجزاء المحفوظة لم تعد تكوّن name. وتتضمنها استجابات قائمة المحادثات وتفاصيلها وتصفيتها في meta.sender. كما تحملها أحداث contact.created وcontact.updated الناتجة عن إنشاء جهات الاتصال وتحديثها ودمجها عبر الواجهة، وتسلّم webhooks الحساب هذه الأحداث باسم contact_created وcontact_updated.

عنوان التوصيل

additional_attributes.address هو عنوان توصيل العميل: كائن واحد بهذه المفاتيح، وكل قيمة فيه نص من سطر واحد.

المفتاح	إلزامي	الحد الأقصى للأحرف
`recipient`	لا	120
`line1`	نعم، عنوان الشارع	200
`district`	لا	120
`city`	نعم	120
`postal_code`	لا	20
`country_code`	لا	2

curl -X PATCH "https://app.huechat.ai/api/v2/accounts/$ACCOUNT_ID/contacts/1042" \
  -H "Authorization: Bearer $HUECHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "additional_attributes": {
      "address": {
        "recipient": "سارة العتيبي",
        "line1": "طريق الملك فهد 1234",
        "district": "العليا",
        "city": "الرياض",
        "postal_code": "12214",
        "country_code": "SA"
      }
    }
  }'

تُزال المسافات من طرفي كل قيمة. country_code رمز دولة من حرفين يُحفظ بأحرف كبيرة، وهو دولة التوصيل، وقد تختلف عن دولة إقامة العميل في additional_attributes.country_code. يستبدل إرسال address العنوان المحفوظ كله، وتُدمج الخصائص الأخرى كالمعتاد. أرسل "address": null أو عنوانًا كل حقوله فارغة لمسحه. يرفض HueChat الطلب بالرمز 400 ولا يحفظ شيئًا إذا احتوى العنوان مفتاحًا غير معروف، أو قيمة ليست نصًا من سطر واحد، أو قيمة تتجاوز حدها، أو country_code غير صالح، أو محتوى بلا line1 وcity:

{ "error": "address.street is not a supported address field" }

عند إنشاء رابط دفع يتضمن عنوان توصيل لجهة الاتصال، يحفظ HueChat ذلك العنوان هنا. يحتاج رابط الدفع المطلوب عبر POST /api/v2/accounts/{accountId}/payments/requests (النطاق messages:write) إلى دولة التوصيل. عندما يحتوي delivery_address (بالمفاتيح نفسها أعلاه) على line1 وcity دون country_code، يعيد HueChat 422 قبل التواصل مع أي مزود دفع، ولا يحفظ شيئًا:

{
  "code": "delivery_address_incomplete",
  "message": "The delivery address needs its country. Choose the delivery country and try again.",
  "missing": ["delivery_address_incomplete", "delivery_country_missing"]
}

لا تُرفض روابط الدفع التي يرسلها وكلاء الذكاء الاصطناعي ورحلات العملاء بسبب غياب الدولة. يأخذ HueChat دولتها من عنوان التوصيل المحفوظ لجهة الاتصال، ثم من دولة إقامتها، ثم من دولة التاجر إن كانت معروفة.

القائمة والبحث

استخدم GET /api/v2/accounts/{accountId}/contacts مع page وper_page (بحد أقصى 100) وsort. أضف q أو استخدم /contacts/search?q=… للبحث في الاسم والبريد والهاتف والمعرّف والشركة والموقع والنطاق. ينطبق الفرز على القائمة العادية ولا يمكن جمعه مع q.

curl --get "https://app.huechat.ai/api/v2/accounts/$ACCOUNT_ID/contacts/search" \
  -H "Authorization: Bearer $HUECHAT_API_KEY" \
  --data-urlencode "q=erp-customer-8842"

البحث تقريبي ومرتب؛ استخدم id الرقمي من النتيجة للطلبات اللاحقة.

القراءة والتحديث

يعيد GET /contacts/{contactId} السجل ونسخة updated_at. يغيّر PATCH /contacts/{contactId} الحقول المرسلة فقط، وتُدمج كائنات الخصائص. لا يعيد تحديث الملف توجيه هويات صناديق الوارد التي تملكها قنوات المراسلة. ولا يقبل سطح إنشاء/قراءة جهة الاتصال روابط صناديق الوارد أو يكشفها؛ استخدم ملف CDP لسياق المصدر المقيد بعضوية صندوق الوارد. إذا أزيل المعرّف بدمج مُراجع، يحل HueChat الاسم المستعار داخل الحساب إلى السجل المحتفظ به ويعيد merged_from_contact_id.

دمج العملاء المكررين

اقرأ السجلين قبل الدمج مباشرة، ثم أرسل قيمتي updated_at. السجل الأساسي هو المحتفظ به، والسجل المدموج هو المكرر الذي سيزال.

curl -X POST "https://app.huechat.ai/api/v2/accounts/$ACCOUNT_ID/contacts/merge" \
  -H "Authorization: Bearer $HUECHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base_contact_id": 1042,
    "mergee_contact_id": 1088,
    "confirmed": true,
    "base_updated_at": "2026-09-12T12:00:00Z",
    "mergee_updated_at": "2026-09-12T12:01:00Z",
    "field_choices": {
      "name": "base",
      "email": "mergee"
    }
  }'

قيمة كل اختيار هي base أو mergee. المفاتيح المدعومة: name وemail وphone_number وidentifier وcompany_name وlocation وcity وcountry وcountry_code وnotes وwebsite وdomain. يتم الدمج في معاملة واحدة مع حفظ المحادثات وأدلة الموافقة والتصنيفات والمرفقات والصفقات والمواعيد والرحلات والعضويات. تُرفض النسخ القديمة والعمل الجاري وتعارضات العضوية. إعادة الدمج المكتمل نفسه آمنة وتعيد replayed: true.

ملف CDP الموحّد

للحسابات التي فُعّل فيها Customer CDP، وبنطاقي contacts:read وdeals:read:

GET /contacts/{contactId}/profile يعيد العميل والمصادر والموافقات والنشاط والصفقات والعضويات والتصنيفات وأول صفحة من الخط الزمني.
GET /contacts/{contactId}/timeline?cursor=… يعيد الرسائل والأحداث والصفقات والمهام بترقيم يعتمد مؤشرًا آمنًا.

تظل بيانات صناديق الوارد الخاصة مقيدة بعضوية المالك الحالي للمفتاح. يعيد عدم تفعيل خطة CDP الرمز 402 من دون التأثير في عمليات جهات الاتصال الأساسية. وتتضمن سجلات قائمة العملاء وملف CDP الحقل gender في المستوى الأعلى، مع الإبقاء على additional_attributes.gender للتوافق.

مزامنة دليل الموافقة

يمكن للمدير استدعاء POST /contacts/{contactId}/consent مع channel وpurpose وstatus وevidence الواضح وexpected_version الحالي. يرتبط الدليل بعنوان البريد أو الهاتف الحالي ولا يمنح إذنًا لعنوان مستقبلي. تعيد النسخة القديمة 409. كما يحدّث إلغاء موافقة تسويق واتساب قائمة منع البث الدائمة في HueChat.

واجهة Customer CDP المتقدمة

يبدأ السطح الكامل من /api/v2/accounts/{accountId}/cdp. يعيد كل طلب التحقق من أن مالك المفتاح ما زال عضوًا في الحساب. تعيد المسارات المتخصصة 402 إذا لم تكن ميزة Customer CDP أو Audiences أو Journeys أو Membership مفعلة في الخطة.

دليل العملاء والإعدادات

الطريقة	المسار	النطاق	الغرض
`GET`	`/cdp/access`	`contacts:read`	معرفة ميزات CDP المفعلة وصلاحية الإدارة
`GET`	`/cdp/customers`	`contacts:read` + `deals:read`	تصفية العملاء حسب العرض والمعرّفات والمصدر والتصنيف والشركة والموقع وتوفر حقول الاتصال
`GET`	`/cdp/customers/{contactId}/activity`	`contacts:read` + `deals:read`	قراءة النشاط بمؤشر `before_id` ثابت
`GET`	`/cdp/preferences`	`contacts:read`	قراءة وحدات النشاط المفعلة
`PUT`	`/cdp/preferences`	`contacts:write`	حفظ الوحدات مع `revision` الحالي

يتطلب تعديل الإعدادات مديرًا. استخدم /contacts للمزامنة المعتادة، واستخدم /cdp/customers عند الحاجة إلى عروض CDP والملخصات المجمعة.

شرائح الجمهور

تتطلب Audiences تفعيل الميزة في الخطة. تدعم الشريحة الديناميكية 12 قاعدة متحققًا منها، والثابتة 5,000 معرّف جهة اتصال متاح كحد أقصى. يُرفض أي معرّف من حساب آخر أو صندوق وارد خاص لا يستطيع مالك المفتاح الوصول إليه.

الطريقة	المسار	النطاق	الغرض
`GET`, `POST`	`/cdp/audiences`	`contacts:read`, `contacts:write`	عرض الشرائح أو إنشاؤها
`PUT`, `DELETE`	`/cdp/audiences/{audienceId}`	`contacts:write`	التحديث أو الحذف مع `revision` الحالي
`POST`	`/cdp/audiences/preview`	`contacts:read`	معاينة شروط غير محفوظة من دون تغيير البيانات
`GET`	`/cdp/audiences/{audienceId}/customers`	`contacts:read`	إعادة احتساب العملاء من القواعد المحفوظة

يتطلب الإنشاء والتحديث والحذف مديرًا. يسرد مخطط API التفاعلي جميع الحقول والعوامل المسموحة.

رحلات العملاء

تتطلب الرحلات workflows:read أو workflows:write مع تفعيل Journeys. لا يرسل إنشاء المسودة أو المعاينة أي رسالة. يؤدي النشر إلى تفعيل انضمام الأحداث المستقبلية وقد يؤدي إلى إرسال واتساب فعلي بعد إعادة التحقق من الموافقة والمنع وصندوق الوارد والقالب المعتمد وجاهزية المزود.

الطريقة	المسار	الغرض
`GET`, `POST`	`/cdp/journeys`	عرض الرحلات أو إنشاء مسودة
`POST`	`/cdp/journeys/preview`	تقييم التعريف على عميل حالي من دون آثار جانبية
`GET`	`/cdp/journeys/options`	عرض مراحل الصفقات الخاصة بالحساب
`GET`, `PUT`	`/cdp/journeys/{workflowId}`	قراءة مسودة أو تحديثها مع النسخة
`POST`	`/cdp/journeys/{workflowId}/publish`	التحقق من النسخة الحالية ونشرها
`GET`	`/cdp/journeys/{workflowId}/runs`	قراءة التشغيلات وسجل الإجراءات المرئي
`POST`	`/cdp/journeys/{workflowId}/runs/{runId}/cancel`	إيقاف تشغيل غير مكتمل ولا ينفذ أثرًا حاليًا
`POST`	`/cdp/journeys/{workflowId}/runs/{runId}/review`	تسجيل مراجعة تسليم غير مؤكد من دون إعادة تنفيذه

تتطلب كل تعديلات الرحلات workflows:write ومديرًا.

برامج العضوية

تتطلب المسارات تفعيل Membership. تستخدم القراءة contacts:read، وتستخدم الكتابة العادية contacts:write وتتطلب مديرًا.

الطريقة	المسار	الغرض
`GET`, `POST`	`/cdp/membership/programs`	عرض البرامج أو إنشاؤها
`GET`	`/cdp/membership/inboxes`	عرض صناديق العضوية المتاحة من دون بيانات اعتماد
`GET`, `PUT`	`/cdp/membership/programs/{programId}`	قراءة البرنامج أو تحديثه مع النسخة
`GET`	`/cdp/membership/programs/{programId}/readiness`	فحص جاهزية الصندوق والمزود والقالب المتزامن
`GET`	`/cdp/membership/programs/{programId}/activity`	قراءة نشاط البرنامج بمؤشر
`GET`, `POST`	`/cdp/membership/programs/{programId}/members`	عرض الأعضاء أو تسجيل عميل مع دليل قبول الشروط
`POST`	`/cdp/membership/programs/{programId}/invites`	إنشاء رابط تسجيل قصير العمر يتحقق عبر واتساب
`GET`	`/cdp/membership/members`	عرض العضويات المتاحة
`GET`	`/cdp/membership/members/{membershipId}`	قراءة العضوية والسجل والنقاط والمزايا والإيصالات
`POST`	`/cdp/membership/members/{membershipId}/activity`	تنفيذ إجراء عضوية آمن للإعادة ومقيد بالنسخة
`POST`	`/cdp/membership/members/{membershipId}/receipts/{receiptId}/fulfill`	تسجيل دليل تنفيذ آمن للإعادة
`POST`	`/cdp/membership/members/{membershipId}/member-link`	إنشاء رابط عضو قصير العمر يتحقق عبر واتساب

تمنح أنظمة التجارة الخارجية النقاط عبر POST /cdp/membership/members/{membershipId}/events. امنح التكامل مفتاحًا مخصصًا بنطاق membership:events فقط، مع بقاء شرط أن يكون مالكه الحالي مديرًا. يشكل provider + event_id مفتاح تكرار على مستوى الحساب، ولذلك يعيد التكرار المتعارض 409 بدل منح النقاط مرتين.

استخدم مفاتيح منفصلة بأقل صلاحيات لجهات الاتصال والرحلات وأحداث العضوية. يخزن HueChat تجزئة المفتاح، ويفرض انتهاءه وقائمة IP اختيارية وحدودًا لكل مفتاح، ويرفض معرّف حساب لا يملك المفتاح.

عمليات غير معروضة عمدًا

الحذف النهائي والحذف الجماعي ليسا جزءًا من واجهة التكامل. استخدم مسار الخصوصية الموثق داخل HueChat عندما يلزم محو سجل يمتد عبر المحادثات والموافقات ونشاط CDP. كما أن حالة دليل البدء في لوحة CDP ليست مسارًا للتكامل عمدًا. راجع مرجع API لكل الحقول والاستجابات.

ابدأ هنا

العمل مع الواجهة

التكامل

بيانات العملاء Customer CDP

قبل البدء

إنشاء جهة اتصال

الجنس

الاسم الأول والأوسط والأخير

عنوان التوصيل

القائمة والبحث

القراءة والتحديث

دمج العملاء المكررين

ملف CDP الموحّد

مزامنة دليل الموافقة

واجهة Customer CDP المتقدمة

دليل العملاء والإعدادات

شرائح الجمهور

رحلات العملاء

برامج العضوية

عمليات غير معروضة عمدًا

​قبل البدء

​إنشاء جهة اتصال

​الجنس

​الاسم الأول والأوسط والأخير

​عنوان التوصيل

​القائمة والبحث

​القراءة والتحديث

​دمج العملاء المكررين

​ملف CDP الموحّد

​مزامنة دليل الموافقة

​واجهة Customer CDP المتقدمة

​دليل العملاء والإعدادات

​شرائح الجمهور

​رحلات العملاء

​برامج العضوية

​عمليات غير معروضة عمدًا

قبل البدء

إنشاء جهة اتصال

الجنس

الاسم الأول والأوسط والأخير

عنوان التوصيل

القائمة والبحث

القراءة والتحديث

دمج العملاء المكررين

ملف CDP الموحّد

مزامنة دليل الموافقة

واجهة Customer CDP المتقدمة

دليل العملاء والإعدادات

شرائح الجمهور

رحلات العملاء

برامج العضوية

عمليات غير معروضة عمدًا