> ## Documentation Index
> Fetch the complete documentation index at: https://developers.huechat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

> إنشاء جهات الاتصال والبحث عنها وتحديثها ودمجها وقراءة ملف العميل الموحّد بمفتاح API معزول لكل حساب.

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

## قبل البدء

أنشئ [مفتاح API محدود النطاق](/ar/api-keys) مع `contacts:read` للقائمة والبحث
وقراءة جهة الاتصال. تتطلب الملفات الموحدة والنشاط والجداول الزمنية وعروض
العملاء المتقدمة أيضًا `deals:read` لأنها تحتوي بيانات الصفقات والمهام. أضف
`contacts:write` للإنشاء والتحديث والدمج. ويتطلب الدمج أن يكون المالك الحالي
للمفتاح مديرًا للحساب.

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

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

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

```bash theme={null}
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`.

```bash theme={null}
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`. السجل الأساسي هو
المحتفظ به، والسجل المدموج هو المكرر الذي سيزال.

```bash theme={null}
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` بدل منح النقاط مرتين.

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

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

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

راجع [مرجع API](/ar/api-reference/overview) لكل الحقول والاستجابات.