إنتقل إلى المحتوى الرئيسي

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

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

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

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

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

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

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

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 لقراءة الصفحة التالية. كل الحقول في مرجع عرض جهات الاتصال.

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

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

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" } }'

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

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

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

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." }'

الملاحظة المكتوبة بمفتاح تُنسَب إلى الشخص الذي أنشأ المفتاح. لا يعدّل الملاحظة أو يحذفها إلا كاتبها، فيستطيع المفتاح تغيير ملاحظات ذلك الشخص وحده. وملاحظات تغيير الحالة سجلات يحفظها مجيب، فلا يعدّلها أو يحذفها أحد. راجع مرجع الملاحظات.

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

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

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 مع العميل المحتمل. راجع مرجع إنشاء عميل محتمل.

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

أرسل PATCH بالحالة الجديدة في status. يجب أن تكون الحالة قيمة value لأحد عناصر options في الحقل ذي المفتاح status الذي يعيده عرض حقول العملاء المحتملين، وقد يُرفض انتقال لا يسمح به مسار الحالات لدى فريقك. وإذا لم تحوِ القائمة حقل status، أو لم يكن لهذا الحقل خيارات، يستخدم الوكيل الحالات new وprocessing وcompleted، ويبدأ العميل المحتمل الجديد في new.

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 ولا يتغيّر شيء.

في عرض حقول العملاء المحتملين، الحقول التي قيمة built_in فيها false هي التي أضافها فريقك، فاستخدم مفاتيحها في custom_fields. ويحفظ مجيب كل قيمة كما ترسلها دون أن يتحقق منها مقابل type أو options أو required للحقل، فتحقّق منها بنفسك مقابل تلك القائمة قبل الكتابة. ولإضافة هذه الحقول أو تغييرها أو حذفها، راجع إسناد العملاء المحتملين وتصفيتهم وحقولهم.

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

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

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 بدلاً من حذفه. راجع مرجع حذف عميل محتمل.

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

استبدل تعليمات حفظ العملاء. لكل وكيل أداة حفظ عميل المدمجة، وتخبر تعليماتها الذكاء الاصطناعي متى تحوي المحادثة عميلاً محتملاً وماذا يكتب في ملخصه. وهي النص نفسه الذي يعدّله فريقك في لوحة التحكم من قائمة النقاط الثلاث (⋮) في صفحة العملاء، عبر تعليمات الذكاء الاصطناعي. اقرأها بـ GET واستبدلها بـ PATCH.

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." }'

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

أسئلة شائعة​

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

لا. حين يعدّل أحد أعضاء الفريق عميلاً غير مُسنَد في لوحة التحكم يصبح العميل له. أما التعديل عبر الواجهة فلا يُسنِد العميل أبداً، فلا يسلّم تكاملك العملاء بصمت للشخص الذي أنشأ المفتاح. ولإسناد عميل محتمل عمداً، استخدم نقطة assign الخاصة به؛ راجع إسناد العملاء المحتملين وتصفيتهم وحقولهم.

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

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

ماذا تفعل null في custom_fields؟​

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

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

العملاء المثبَّتون يأتون أولاً، في الصفحة الأولى فقط، ثم البقية الأحدث أولاً؛ ويوضّح حقل pinned في كل عميل أيهم مثبَّت، وPATCH مع pinned يثبّت عميلاً أو يُلغي تثبيته. الصفحات التالية لا تحوي عملاء مثبَّتين، فإذا ثبّت فريقك أكثر من قيمة limit فلن يُعاد الزائد عنها: استخدم limit أكبر من عددهم، حتى الحد الأقصى المذكور في مرجع عرض العملاء المحتملين.

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

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

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

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

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

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

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

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

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

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