# جهات الاتصال والملاحظات والعملاء المحتملون

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

وكيلك يجمع بالفعل الأشخاص الذين يتحدث معهم. عبر الواجهة البرمجية العامة يستطيع نظام CRM أو الأتمتة لديك قراءتهم، وإبقاء بياناتهم محدّثة، وكتابة ملاحظات يراها فريقك في لوحة التحكم، وإنشاء عملاء محتملين ونقلهم بين الحالات التي أعددتها، وتغيير متى يحفظ الذكاء الاصطناعي عميلاً محتملاً. كل نقطة نهاية تقع تحت وكيل واحد: `/v1/agents/{agentId}/…`.

## كيف ترتبط جهات الاتصال والملاحظات والعملاء المحتملون ببعضها؟

- **جهة الاتصال شخص.** ينشئها مجيب أول مرة يراسل فيها أحدٌ الوكيل أو يُحفَظ عميل محتمل، ويتعرّف عليه لاحقاً من رقم واتساب أو معرّف فيسبوك أو إنستجرام أو رقم الهاتف. لهذا تستطيع الواجهة تحديث جهة الاتصال لا إنشاءها.
- **الملاحظات على جهة الاتصال.** سجل واحد يتبع الشخص عبر كل محادثة وعميل محتمل. يضم ملاحظات فريقك أو تكاملك، وتغييرات الحالة التي يسجّلها مجيب حين ينتقل عميل محتمل.
- **العميل المحتمل فرصة بيع** في جدول العملاء في لوحة التحكم. ينتمي لجهة اتصال، ويحمل حقولك المخصّصة، وينتقل بين الحالات التي حددتها للوكيل.

راجع [جهات الاتصال](/docs/features/contacts) و[إدارة العملاء المحتملين](/docs/features/lead-management) لترى كيف يستخدمها فريقك في لوحة التحكم. ولإسناد العملاء المحتملين وتصفيتهم وتثبيتهم، أو تغيير حقول العملاء المحتملين للوكيل، راجع [إسناد العملاء المحتملين وتصفيتهم وحقولهم](./lead-assignment-and-fields).

## كيف أجد جهة اتصال؟

اعرض جهات اتصال الوكيل، الأحدث أولاً. صفِّ حسب `channel`، أو `search` (الاسم أو الجوال أو البريد)، أو تاريخ الإنشاء عبر `date_from` و`date_to` (تواريخ بتوقيت UTC، واليومان مشمولان).

```bash
curl "https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/contacts?search=sara&limit=20" \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE"
```

الاستجابة صفحة: `items` ومعها `next_cursor` و`has_more`. أعد `next_cursor` في `cursor` لقراءة الصفحة التالية. كل الحقول في [مرجع عرض جهات الاتصال](../api-reference/list-contacts).

## كيف أحدّث جهة اتصال؟

أرسل `PATCH` بالحقول التي تريد تغييرها فقط. تُدمَج `custom_fields` مفتاحاً بمفتاح، فتضبط حقلاً واحداً دون إعادة إرسال البقية، والقيمة `null` تمسح ذلك الحقل. يجب أن يكون رقم الجوال بصيغة E.164 مثل `+201001234567`، والنص الفارغ يمسحه؛ وأي صيغة أخرى تُعيد `422 invalid_request_body` مع `param` بقيمة `mobile`.

```bash
curl -X PATCH https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/contacts/CONTACT_ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Sara Example", "custom_fields": { "city": "Cairo" } }'
```

يبقى البريد ومعرّفا فيسبوك وإنستجرام للقراءة فقط. أما رقم الجوال فيمكن تغييره، لكنه ما يربط به مجيب رسائل واتساب والعملاء المحتملين الجدد بهذا الشخص، فغيّره فقط لتصحيح رقم خاطئ: بعد التغيير لا تُربَط رسالة واتساب من الرقم القديم بجهة الاتصال هذه. راجع [مرجع تحديث جهة الاتصال](../api-reference/update-contact).

## كيف أضيف ملاحظة يراها فريقي؟

أرسل النص بـ `POST` إلى ملاحظات جهة الاتصال. تظهر فوراً على سجل جهة الاتصال في لوحة التحكم.

```bash
curl -X POST https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/contacts/CONTACT_ID/notes \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Asked for a call back on Sunday." }'
```

الملاحظة المكتوبة بمفتاح تُنسَب إلى الشخص الذي أنشأ المفتاح. لا يعدّل الملاحظة أو يحذفها إلا كاتبها، فيستطيع المفتاح تغيير ملاحظات ذلك الشخص وحده. وملاحظات تغيير الحالة سجلات يحفظها مجيب، فلا يعدّلها أو يحذفها أحد. راجع [مرجع الملاحظات](../api-reference/create-contact-note).

## كيف أنشئ عميلاً محتملاً؟

أرسل `POST` إلى العملاء المحتملين للوكيل. كل الحقول اختيارية. يبدأ العميل في الحالة الافتتاحية للوكيل (`new` ما لم يختر فريقك حالة أخرى)، غير مُسنَد. والهاتف، حين ترسله، يجب أن يكون رقماً صالحاً بصيغة E.164 كما في المثال؛ فيربط مجيب العميل بجهة الاتصال التي تحمل الرقم، أو ينشئ جهة اتصال جديدة. وأي صيغة أخرى تُعيد `422 invalid_request_body` مع `param` بقيمة `phone`. والنص الفارغ يساوي عدم إرسال الهاتف حين تنشئ عميلاً محتملاً، ويمسح الهاتف حين تحدّث عميلاً.

```bash
curl -X POST https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/leads \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Sara Example", "phone": "+201001234567", "summary": "Wants a quote for 20 units." }'
```

الاستجابة `201 Created` مع العميل المحتمل. راجع [مرجع إنشاء عميل محتمل](../api-reference/create-lead).

## كيف أنقل عميلاً محتملاً إلى حالة أخرى؟

أرسل `PATCH` بالحالة الجديدة في `status`. يجب أن تكون الحالة قيمة `value` لأحد عناصر `options` في الحقل ذي المفتاح `status` الذي يعيده [عرض حقول العملاء المحتملين](../api-reference/list-lead-fields)، وقد يُرفض انتقال لا يسمح به مسار الحالات لدى فريقك. وإذا لم تحوِ القائمة حقل `status`، أو لم يكن لهذا الحقل خيارات، يستخدم الوكيل الحالات `new` و`processing` و`completed`، ويبدأ العميل المحتمل الجديد في `new`.

```bash
curl -X PATCH https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/leads/LEAD_ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "status": "processing" }'
```

يسجّل مجيب التغيير على سجل جهة الاتصال حين يكون للعميل جهة اتصال. والانتقال إلى حالة غير موجودة لدى الوكيل، أو الانتقال المرفوض، يُعيد `422 invalid_request` ولا يتغيّر شيء.

في [عرض حقول العملاء المحتملين](../api-reference/list-lead-fields)، الحقول التي قيمة `built_in` فيها `false` هي التي أضافها فريقك، فاستخدم مفاتيحها في `custom_fields`. ويحفظ مجيب كل قيمة كما ترسلها دون أن يتحقق منها مقابل `type` أو `options` أو `required` للحقل، فتحقّق منها بنفسك مقابل تلك القائمة قبل الكتابة. ولإضافة هذه الحقول أو تغييرها أو حذفها، راجع [إسناد العملاء المحتملين وتصفيتهم وحقولهم](./lead-assignment-and-fields).

## كيف أحذف عميلاً محتملاً؟

أرسل `DELETE` إلى العميل المحتمل. الحذف نهائي: لا تراجع عنه، وحذف العميل نفسه مرة ثانية يُعيد `404 not_found`. وتبقى جهة الاتصال وملاحظاتها والمحادثة، فيبقى الشخص وسجله في لوحة التحكم.

```bash
curl -X DELETE https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/leads/LEAD_ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE"
```

الرد `204` بلا جسم. وتبقى ملاحظات تغيير الحالة التي تذكر العميل على سجل جهة الاتصال. وإن حفظ الذكاء الاصطناعي لاحقاً عميلاً محتملاً من المحادثة نفسها، فهو عميل جديد بمعرّف جديد. ولإخراج عميل من العمل المفتوح لفريقك دون أن تفقده، انقله إلى حالة نهائية مثل `completed` بدلاً من حذفه. راجع [مرجع حذف عميل محتمل](../api-reference/delete-lead).

## كيف أغيّر متى يحفظ الذكاء الاصطناعي عميلاً محتملاً؟

استبدل تعليمات حفظ العملاء. لكل وكيل أداة [حفظ عميل](/docs/tools/capture-lead) المدمجة، وتخبر تعليماتها الذكاء الاصطناعي متى تحوي المحادثة عميلاً محتملاً وماذا يكتب في ملخصه. وهي النص نفسه الذي يعدّله فريقك في لوحة التحكم من قائمة النقاط الثلاث (⋮) في صفحة العملاء، عبر **تعليمات الذكاء الاصطناعي**. اقرأها بـ `GET` واستبدلها بـ `PATCH`.

```bash
curl -X PATCH https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/lead-capture \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "Capture a lead when the customer shares a phone number and asks about prices. In the summary, say what they want and by when." }'
```

يتبع الذكاء الاصطناعي التعليمات الجديدة في ردوده التالية، عادةً خلال دقيقة، وإرسال التعليمات الموجودة لدى الوكيل أصلاً لا يغيّر شيئاً. ويحفظها مجيب دون المسافات وفواصل الأسطر في بدايتها ونهايتها. ولا يتغيّر إلا نص التعليمات: تبقى إعدادات الأداة الأخرى، ومنها مفتاح تشغيلها وإيقافها، في لوحة التحكم. لحدود الطول راجع [مرجع تحديث تعليمات حفظ العملاء](../api-reference/update-lead-capture)، ويشرح [مرجع جلب تعليمات حفظ العملاء](../api-reference/get-lead-capture) قراءتها.

## أسئلة شائعة

### هل يُسنِد تحديث العميل المحتمل عبر الواجهة العميلَ لأحد؟

لا. حين يعدّل أحد أعضاء الفريق عميلاً غير مُسنَد في لوحة التحكم يصبح العميل له. أما التعديل عبر الواجهة فلا يُسنِد العميل أبداً، فلا يسلّم تكاملك العملاء بصمت للشخص الذي أنشأ المفتاح. ولإسناد عميل محتمل عمداً، استخدم نقطة `assign` الخاصة به؛ راجع [إسناد العملاء المحتملين وتصفيتهم وحقولهم](./lead-assignment-and-fields).

### لماذا لا أستطيع إنشاء جهة اتصال؟

ينشئ مجيب جهات الاتصال بنفسه ليبقى الشخص الواحد جهة اتصال واحدة عبر القنوات. لإضافة شخص يدوياً، أنشئ عميلاً محتملاً برقم هاتفه مع رمز الدولة: يربطه مجيب بجهة الاتصال التي تحمل الرقم، أو ينشئ واحدة.

### ماذا تفعل `null` في `custom_fields`؟

تجعل ذلك الحقل وحده `null`، ويبقى مفتاحه. الحقول التي لا ترسلها تحتفظ بقيمها. وتعمل بالطريقة نفسها لجهات الاتصال والعملاء المحتملين.

### لماذا تأتي بعض العملاء المحتملين أولاً دائماً؟

العملاء المثبَّتون يأتون أولاً، في الصفحة الأولى فقط، ثم البقية الأحدث أولاً؛ ويوضّح حقل `pinned` في كل عميل أيهم مثبَّت، و`PATCH` مع `pinned` يثبّت عميلاً أو يُلغي تثبيته. الصفحات التالية لا تحوي عملاء مثبَّتين، فإذا ثبّت فريقك أكثر من قيمة `limit` فلن يُعاد الزائد عنها: استخدم `limit` أكبر من عددهم، حتى الحد الأقصى المذكور في [مرجع عرض العملاء المحتملين](../api-reference/list-leads).

### هل أستطيع حذف عميل محتمل أو جهة اتصال؟

العميل المحتمل، نعم: `DELETE` يحذفه نهائياً دون تراجع. أما جهة الاتصال فلا: يبقى حذف سجل الشخص في لوحة التحكم حيث يؤكده أحد. ويمكنك أيضاً حذف الملاحظات التي كتبها منشئ مفتاحك.

### لماذا تُعيد تعليمات حفظ العملاء `404 lead_capture_not_found`؟

ليس لدى الوكيل أداة حفظ عميل، فلا تعليمات لحفظ العملاء لديه، ولا يحفظ ذكاؤه الاصطناعي عملاء محتملين من المحادثات أيضاً. يحصل كل وكيل على الأداة عند إنشائه؛ فإن غابت عن أحدهم فتواصل مع دعم مجيب لإضافتها.

### ماذا لو كانت أداة حفظ عميل متوقفة؟

تظل الواجهة البرمجية تقرأ تعليماتها وتستبدلها، لكن الذكاء الاصطناعي لا يحفظ عملاء محتملين حتى يعيد أحدٌ تشغيل الأداة من بطاقتها في صفحة الأدوات. لا يستطيع المفتاح تشغيلها، ولا يبيّن `GET` لتعليمات حفظ العملاء هل الأداة مفعّلة: راجع بطاقتها.

### هل أستطيع تغيير ما تحفظه أداة حفظ عميل أو إلى أين ترسله؟

إلى أين، لا: كل عميل محتمل تحفظه ينتهي في جدول العملاء للوكيل. أما ما تحفظه فيتبع حقول العملاء المحتملين لديك: أضفها أو غيّرها أو احذفها عبر الواجهة البرمجية (راجع [إسناد العملاء المحتملين وتصفيتهم وحقولهم](./lead-assignment-and-fields)) أو من **تعديل الأعمدة** في لوحة التحكم. وتحدّد التعليمات متى يُحفظ العميل وماذا يُكتب في الملخص.

### لماذا تُعيد جهة اتصال من وكيل آخر 404؟

كل جهة اتصال وملاحظة وعميل محتمل ينتمي لوكيل واحد. طلبه تحت وكيل آخر يُعيد `404 not_found` حتى داخل منظمتك، فلا تكشف المعرّفات بيانات بين الوكلاء.