جهات الاتصال وملف العميل CDP

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

قبل البدء

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

استخدم معرّف الحساب الذي أصدر المفتاح. يعيد مفتاح حساب آخر 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",
    "additional_attributes": {
      "company_name": "شركة تجريبية",
      "preferred_language": "ar"
    },
    "custom_attributes": {
      "customer_tier": "gold"
    }
  }'

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

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

استخدم 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 من دون التأثير في عمليات جهات الاتصال الأساسية.

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

يمكن للمدير استدعاء 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 لكل الحقول والاستجابات.

ابدأ هنا

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

التكامل

جهات الاتصال وملف العميل CDP

قبل البدء

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

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

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

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

ملف CDP الموحّد

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

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

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

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

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

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

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

​قبل البدء

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

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

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

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

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

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

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

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

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

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

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

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

قبل البدء

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

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

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

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

ملف CDP الموحّد

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

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

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

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

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

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

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