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

إعدادات الوكيل

تحدّد إعدادات الوكيل كيف يتصرف ذكاؤه الاصطناعي: التعليمات الرئيسية التي يتبعها في كل رد، والمنطقة الزمنية التي يحسب بها، وهل يتوقف حين يرد أحد من فريقك. عبر الواجهة البرمجية العامة تقرؤها وتغيّرها من أنظمتك، كأن تُبقي التعليمات متزامنة مع المكان الذي يكتبها فيه فريقك. يستخدم الاستدعاءان /v1/agents/{agentId}.

كيف أقرأ إعدادات الوكيل؟​

اجلب الوكيل بـ GET. إلى جانب البيانات الأساسية التي تعيدها قائمة الوكلاء، يحمل الرد إعداداته: التعليمات الرئيسية في instructions، وإيقاف الذكاء الاصطناعي بعد رد فريقك في ai_handoff_enabled وai_handoff_window_minutes، والإخفاء التلقائي للتعليقات في comment_auto_hide_enabled.

curl https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE"

أما GET /v1/agents فيُبقي البيانات الأساسية وحدها، فاجلب الوكيل نفسه حين تحتاج إعداداته. تعود التعليمات كما خُزّنت تماماً، وهو ما يقرؤه الذكاء الاصطناعي: نصاً عادياً، أو HTML إن حفظها أحدٌ آخر مرة من محرّر لوحة التحكم. كل الحقول في مرجع جلب وكيل.

كيف أغيّر التعليمات الرئيسية؟​

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

curl -X PATCH https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "instructions": "You are the front desk of Acme Clinics.\n\nAnswer in the language the customer writes in.\n\nNever quote prices; offer a call back instead." }'

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

كيف أغيّر إيقاف الذكاء الاصطناعي بعد رد فريقي؟​

أرسل PATCH بـ ai_handoff_enabled أو ai_handoff_window_minutes أو بالاثنين. حين تكون ai_handoff_enabled مفعّلة، يوقف ردُّ أحد أعضاء فريقك في محادثةٍ الذكاءَ الاصطناعي فيها حتى لا يتكلم فوقكم، طوال المدة المحددة محسوبةً من آخر رسالة لفريقك، ويمدّها كل رد إضافي. وحين تكون متوقفة يستمر الذكاء الاصطناعي في الرد حتى بعد رد الموظف مباشرة.

curl -X PATCH https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "ai_handoff_enabled": true, "ai_handoff_window_minutes": 30 }'

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

كيف أشغّل الإخفاء التلقائي للتعليقات أو أوقفه؟​

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

كيف أغيّر المنطقة الزمنية؟​

أرسل PATCH بـ time_zone منطقةً زمنية من IANA بصيغة Region/City، مثل Asia/Riyadh أو Africa/Cairo. هي الساعة التي يرد بها الوكيل: أوقات العمل، و«اليوم» و«غداً»، ومواعيد الحجز. والنص الفارغ يعيد الوكيل إلى المنطقة الافتراضية للمنصة.

curl -X PATCH https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "time_zone": "Asia/Riyadh" }'

الاسم الذي ليس منطقة IANA، مثل Cairo أو Egypt Standard Time، يُعيد 422 unknown_timezone ولا يتغيّر شيء. ويبيّن time_zone في الرد المنطقة التي يستخدمها الوكيل الآن، ومنها المنطقة الافتراضية حين ترسل نصاً فارغاً.

كيف أغيّر اسم الوكيل أو وصفه؟​

أرسل PATCH بـ name أو description أو بالاثنين. يُحفظ كلٌّ منهما دون المسافات المحيطة به، ولا يقبل أيٌّ منهما الأقواس الزاوية. ولا يكون الاسم فارغاً، والوصف الفارغ يمسح الوصف.

curl -X PATCH https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Sales assistant", "description": "Answers product questions and books demos." }'

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

ما الذي لا يستطيع المفتاح تغييره؟​

حالة الوكيل status، فلا يستطيع المفتاح حذف وكيل؛ ونموذج الذكاء الاصطناعي (ai_model وmodel_provider)؛ وصورة الوكيل (avatar_url)؛ ورمز لغته language. إرسال أيٍّ منها بقيمة يُعيد 422 field_not_writable مع param يسمّي الحقل، ولا يتغيّر شيء. والحقل المُرسَل بقيمة null يُعدّ غير مُرسَل.

{
  "error": {
    "type":           "validation_error",
    "code":           "field_not_writable",
    "message":        "An API key can't change an agent's status or delete it; delete agents in the dashboard.",
    "param":          "status",
    "correlation_id": "req_01KQ..."
  }
}

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

أسئلة شائعة​

هل يغيّر language اللغة التي يرد بها الوكيل؟​

لا. هو رمز محفوظ على الوكيل، en لكل الوكلاء تقريباً، ولا يقرؤه شيء: يرد الوكيل على كل عميل بلغته، كما تقول تعليماته الرئيسية. ولهذا لا يستطيع المفتاح تغييره. لتحديد اللغة أو اللهجة، اكتبها في التعليمات الرئيسية.

لماذا تظهر تعليماتي فقرةً واحدة في لوحة التحكم؟​

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

لماذا تعود التعليمات بصيغة HTML؟​

تعيدها الواجهة البرمجية كما خُزّنت تماماً. والتعليمات التي حُفظت آخر مرة من محرّر لوحة التحكم تُخزَّن بصيغة HTML الخاصة به: وسوم الفقرات والقوائم والخط العريض والمائل. لتقرّر هل ترسل، قارن مصدرك بما أرسلته آخر مرة (كبصمة hash تحتفظ بها)، لا بالنص المُعاد.

هل يعيد إرسال التعليمات نفسها بناء الذكاء الاصطناعي؟​

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

هل للتعليمات حد في الطول؟​

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

ماذا يعني 422 no_settings؟​

لم يرسل الطلب أي إعداد بقيمة: كائن JSON فارغ، أو قيم null فقط، أو حقول لا تأخذها نقطة النهاية فقط. أرسل إعداداً واحداً على الأقل.

ماذا لو عدّل أحدٌ الوكيل من لوحة التحكم في الوقت نفسه؟​

آخر حفظ هو الذي يبقى، كما بين تبويبين في لوحة التحكم. اجلب الوكيل مرة أخرى بعدها إن أردت التأكد مما خُزّن.

هل يستطيع المفتاح إنشاء وكيل أو حذفه؟​

لا. يبقى إنشاء الوكلاء وحذفهم في لوحة التحكم. وإرسال status يُعيد 422 field_not_writable، فلا يحذف المفتاح وكيلاً بالخطأ أبداً.

من يستطيع تغيير هذه الإعدادات بمفتاح؟​

يعمل المفتاح بصلاحيات مدير الوكيل على وكلائه، وهي الصلاحية التي تطلبها لوحة التحكم لتغيير إعدادات الوكيل. والمفتاح المقيّد ببعض الوكلاء لا يغيّر إلا إعداداتهم، ووكيل آخر في منظمتك يُعيد 403 agent_not_authorized. ويحتاج تغيير الإعدادات إلى نطاق agents:write، وقراءتها إلى agents:read، ويحمل كل مفتاح الاثنين اليوم.