إسناد العملاء المحتملين وتصفيتهم وحقولهم

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

كيف أُسند عميلاً محتملاً إلى زميل؟

أرسل user_id الخاص بالزميل في assigned_to بـ POST إلى نقطة assign الخاصة بالعميل المحتمل. يصبح الزميل المسؤول عن العميل في لوحة التحكم، وتُسنَد إليه محادثة العميل أيضاً. ويجب أن يستطيع الزميل فتح الوكيل.

curl -X POST https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/leads/LEAD_ID/assign \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "assigned_to": "TEAMMATE_USER_ID", "reason": "Handles the Riyadh branch." }'

اعثر على user_id عبر عرض أعضاء الفريق لوكيل: لا يُسنَد العميل إلا إلى الزملاء الذين قيمة can_open_agent لديهم true. وأي شخص آخر يُعيد 422 assignee_not_allowed ولا يتغيّر شيء. وreason اختياري، ويُحفظ مع الإسناد في سجلات مجيب. والرد هو العميل المحتمل بقيمة assigned_to الجديدة. راجع مرجع إسناد عميل محتمل أو إلغاء إسناده.

كيف أُلغي إسناد عميل محتمل؟

أرسل assigned_to بقيمة null بـ POST إلى نقطة assign الخاصة بالعميل المحتمل. بعدها يظهر العميل في لوحة التحكم بدون مسؤول. والحقل مطلوب، فيُرفض الجسم الفارغ بدل أن يُلغى إسناد عميل بالخطأ.

curl -X POST https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/leads/LEAD_ID/assign \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "assigned_to": null }'

كيف أعرض عملاء زميل، أو العملاء غير المُسنَدين؟

أضف assigned_to إلى قائمة العملاء المحتملين: user_id لزميل، أو unassigned للعملاء غير المُسنَدين لأحد. ويجتمع مع بقية المرشحات، مثل status، فلا يظهر العميل إلا إذا طابقها كلها.

curl "https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/leads?assigned_to=unassigned&status=new" \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE"

لا تُقبل القيمة me، لأن المفتاح ليس شخصاً: هي وأي قيمة أخرى تُعيد 422 invalid_request_body مع param بقيمة assigned_to. راجع مرجع عرض العملاء المحتملين.

كيف أصفّي العملاء المحتملين حسب حقل مخصّص؟

مرّر custom_fields: كائن JSON مُرمَّز للرابط (URL-encoded) يربط مفتاح الحقل بشرط، أي op مع قيمه في values. ومع curl يتولى -G و--data-urlencode الترميز عنك.

curl -G https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/leads \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  --data-urlencode 'custom_fields={"city":{"op":"eq","values":["Cairo"]},"visit_date":{"op":"between","values":["2026-10-01","2026-11-01"]}}'

op	values	يطابق العميل حين يكون الحقل
eq	قيمة واحدة	مساوياً للقيمة
in	قيمة أو أكثر	مساوياً لإحدى القيم
ilike	قيمة واحدة	محتوياً القيمة دون اعتبار لحالة الأحرف؛ ويعمل % و_ كأحرف بدل
between	قيمتان	بين القيمة الأولى، وهي مشمولة، والثانية، وهي غير مشمولة
is_null	لا قيم	بلا قيمة

تُقارَن القيم بالقيمة المخزّنة كنص. اكتب التواريخ بصيغة YYYY-MM-DD ليرتّبها between ترتيباً صحيحاً، ولا تتوقع أن تُقارَن الأرقام حسب حجمها. وتجتمع الشروط بـ AND، والعميل الذي لا قيمة له تحت مفتاحٍ لا يطابق هناك إلا is_null. وعدد المفاتيح والقيم في الطلب محدود؛ راجع مرجع عرض العملاء المحتملين.

كيف أثبّت عميلاً محتملاً أو أُلغي تثبيته؟

أرسل PATCH إلى العميل المحتمل بـ pinned: القيمة true تثبّته لكل من يعمل على الوكيل، كما يفعل تثبيت في لوحة التحكم، وfalse تُلغي تثبيته. ويأتي العملاء المثبَّتون أولاً، في الصفحة الأولى من القائمة.

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 '{ "pinned": true }'

إرسال الحالة التي عليها العميل أصلاً لا يغيّر شيئاً، فيحتفظ العميل المثبَّت بمكانه. ولا تحوي الصفحات التالية من القائمة عملاء مثبَّتين، فأبقِ عدد المثبَّتين أقل من قيمة limit التي تعرض بها. راجع مرجع تحديث عميل محتمل.

كيف أضيف حقلاً للعملاء المحتملين؟

أرسل بـ POST مفتاحاً في key وتسمية في label ونوعاً في type إلى حقول العملاء المحتملين للوكيل. يُضاف الحقل بعد حقول الوكيل المخصّصة الأخرى، في نموذج العميل المحتمل وعموداً في جدول العملاء في لوحة التحكم، وتبدأ أداة حفظ عميل في جمعه في الخلفية، عادةً خلال دقيقة.

curl -X POST https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/lead-fields \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "key": "preferred_branch", "label": "Preferred branch", "type": "enum", "options": [ { "value": "riyadh", "label": "Riyadh" }, { "value": "jeddah", "label": "Jeddah" } ] }'

التسمية تخبر الذكاء الاصطناعي بما يسأل عنه، فاكتبها كما تشرح الحقل لزميل جديد. و"required": true يجعل الذكاء الاصطناعي يعدّ الحقل لازماً قبل أن يحفظ عميلاً محتملاً. يأخذ حقل enum خياراته في options، ولا تأخذ الأنواع الأخرى خيارات. والمفتاح هو مكان القيمة في custom_fields لكل عميل، ولا يتغيّر لاحقاً.

المفتاح الذي يحجزه مجيب، مثل name أو status أو source، يُعيد 422 invalid_request. وأي مفتاح آخر لدى الوكيل أصلاً، ومنه الحقول المدمجة مثل notes، يُعيد 409 field_key_taken، والوكيل الذي لا يتسع لحقل مخصّص آخر يُعيد 422 lead_field_limit_reached. صيغة المفتاح والأنواع والحدود في مرجع إضافة حقل.

كيف أغيّر حقلاً للعملاء المحتملين؟

أرسل PATCH إلى حقل مخصّص بمفتاحه لتغيير تسميته label، أو هل هو مطلوب required، أو خياراته options. أرسل ما يتغيّر فقط. يبقى المفتاح والنوع كما هما؛ ولنوع آخر أضف حقلاً جديداً. ويتبع الذكاء الاصطناعي التغيير في الخلفية، عادةً خلال دقيقة.

curl -X PATCH https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/lead-fields/preferred_branch \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "options": [ { "value": "riyadh", "label": "Riyadh" }, { "value": "jeddah", "label": "Jeddah" }, { "value": "dammam", "label": "Dammam" } ] }'

تحل options محل كل الخيارات، بالترتيب الذي ترسله. والخيار الذي تبقى قيمته value يحتفظ بما ضبطته عليه لوحة التحكم، مثل لونه، ويحتفظ العملاء بالقيم التي تزيلها. ويُطابَق المفتاح في المسار حرفياً، بما في ذلك حالة الأحرف، والمفتاح الذي لا حقل له لدى الوكيل يُعيد 404 not_found. ولا تُغيَّر الحقول المدمجة، ومنها حالات العملاء المحتملين، عبر الواجهة البرمجية (422 system_field). راجع مرجع تغيير حقل.

كيف أحذف حقلاً للعملاء المحتملين؟

أرسل DELETE إلى حقل مخصّص بمفتاحه. يخرج الحقل من نموذج العملاء المحتملين للوكيل نهائياً، ويتوقف الذكاء الاصطناعي عن جمعه في الخلفية، عادةً خلال دقيقة. والرد 204 بلا جسم.

curl -X DELETE https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/lead-fields/preferred_branch \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE"

يحتفظ العملاء بالقيم التي كانت لهم تحت المفتاح: تظل الواجهة البرمجية تعيدها في custom_fields، ويتوقف جدول لوحة التحكم عن عرضها، وتظهر مجدداً إن أضفت حقلاً بالمفتاح نفسه. ولا تُحذف الحقول المدمجة (422 system_field). راجع مرجع حذف حقل.

أسئلة شائعة

من يُسجَّل صاحباً للإسناد عبر الواجهة البرمجية؟

الشخص الذي أنشأ المفتاح. يسجّل مجيب الإسناد باسمه إسناداً يدوياً، كما يسجّله كاتباً لملاحظات المفتاح.

ماذا يعني 422 assignee_not_allowed؟

لا يستطيع الزميل فتح الوكيل: فهو مقيّد بوكلاء آخرين، أو غادر منظمتك، أو أن المعرّف ليس لأحد زملائك. اختر شخصاً قيمة can_open_agent لديه true، أو امنحه الوكيل من لوحة التحكم أولاً؛ راجع إدارة الفريق. وإن تعذّر على مجيب فحص صلاحية الزميل، يكون الرد 503 access_unavailable بدلاً من ذلك: أعد المحاولة بتراجع متصاعد.

لماذا يُعيد assigned_to=me الخطأ 422؟

المفتاح ليس شخصاً، فليس له عملاء خاصون به. استخدم user_id للزميل الذي تقصده، من عرض أعضاء الفريق لوكيل.

هل أستطيع إسناد عميل محتمل إلى الزميل المُسنَد إليه أصلاً؟

نعم. ينجح الطلب ويبقى العميل له، فيستطيع تكاملك إرسال الإسناد دون فحص مسبق.

لماذا لا يُعيد مرشح الحقل المخصّص شيئاً؟

تحقّق من أربعة أمور. يجب أن يطابق المفتاح مفتاح الحقل حرفياً، بما في ذلك حالة الأحرف. ويطابق eq وin النص المخزّن حرفياً، فاستخدم ilike لتجاهل حالة الأحرف. ويستثني between قيمته الثانية، فلتشمل آخر يوم في شهر اجعل النهاية أول يوم في الشهر التالي. وتُقارَن الأرقام كنص.

هل أستطيع تصفية الأرقام حسب حجمها؟

لا. تُقارَن القيم كنص، فلا يتبع between الترتيب العددي. استخدم eq أو in بالقيم الدقيقة، أو صفِّ الأرقام في نظامك.

هل أستطيع تغيير نوع الحقل أو مفتاحه؟

لا. أضف حقلاً جديداً بالمفتاح والنوع اللذين تحتاجهما. والحقل الذي تحذفه ثم تضيفه بالمفتاح نفسه ونوع آخر يجد القيم القديمة كما كانت، دون تحويل.

هل أستطيع تغيير حالات العملاء المحتملين عبر الواجهة البرمجية؟

ليس بعد. الحالات هي خيارات الحقل المدمج status، والحقول المدمجة لا تُغيَّر عبر الواجهة البرمجية (422 system_field). عدّلها من لوحة التحكم عبر تعديل الحالات. أما نقل عميل محتمل من حالة إلى أخرى فيعمل عبر الواجهة؛ راجع جهات الاتصال والملاحظات والعملاء المحتملون.

لماذا أعاد إنشاء الحقل 409؟

لدى الوكيل حقل بهذا المفتاح أصلاً، ومنه الحقول المدمجة، ولم يُنشأ شيء. والإنشاء الذي تعيد محاولته بعد رد ضائع ينتهي هنا أيضاً: اعرض حقول العملاء المحتملين وتابع.

لماذا لا يجمع الذكاء الاصطناعي حقلاً أضفته؟

لا تلتقط أداة حفظ عميل تغييرات الحقول إلا وهي مفعّلة. فإن كانت متوقفة، شغّلها من بطاقتها في صفحة الأدوات، ثم افتح تعديل الأعمدة في صفحة العملاء واحفظ مرة واحدة، كما تشرح صفحة حفظ عميل.

هل أستطيع تثبيت أي عدد من العملاء المحتملين؟

نعم، لا حد لذلك، لكن القائمة لا تعيد العملاء المثبَّتين إلا في صفحتها الأولى، في الواجهة البرمجية ولوحة التحكم على السواء. ثبّت ما يحتاج إلى انتباه الآن فقط، وألغِ تثبيت العميل بعد إنجازه.

هل أستطيع حذف عميل محتمل؟

نعم: DELETE /v1/agents/{agentId}/leads/{leadId} يحذفه نهائياً دون تراجع، وحذف العميل نفسه مرة ثانية يُعيد 404 not_found. وتبقى جهة الاتصال وملاحظاتها والمحادثة. ولإخراج عميل من العمل المفتوح لفريقك دون أن تفقده، انقله إلى حالة نهائية بدلاً من حذفه. راجع جهات الاتصال والملاحظات والعملاء المحتملون.