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

مفتاحك ووكلاؤه

استدعاءان يُخبران التكامل، أو مساعد الذكاء الاصطناعي، بما يستطيع فعله قبل أن يفعل أي شيء: GET /v1/me يصف المفتاح الذي تحمله، وGET /v1/agents يعرض الوكلاء الذين يستطيع العمل عليهم. وكل نقطة نهاية للوكيل تأخذ id الوكيل من هذه القائمة على أنه agentId.

كيف أتحقّق من أن مفتاحي يعمل؟​

استدعِ GET /v1/me. يصف المفتاح الذي تحمله ومنظمته وحد المعدّل الذي يعمل به؛ وكل حقوله في مرجع وصف المفتاح المستدعي.

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

يستطيع أي مفتاح صالح استدعاءه أياً كانت نطاقاته، لذا فهو أول استدعاء تجرّبه بمفتاح جديد. والرد 401 برمز invalid_api_key يعني أن المفتاح مفقود أو خاطئ أو مُلغى أو منتهي الصلاحية. أما 401 برمز internal_server_error فيعني أنه تعذّر على مجيب فحص المفتاح: أعد المحاولة بتراجع متصاعد ولا تُدوّره. راجع التوثيق. ولا يعود المفتاح نفسه أبداً: يعرض الرد منه فقط الجزأين اللذين تعرضهما صفحة مفاتيح API، لتميّز مفاتيحك بعضها عن بعض.

كيف أجد معرّف الوكيل؟​

استدعِ GET /v1/agents. يعرض الوكلاء الذين يستطيع مفتاحك العمل عليهم، الأحدث أولاً.

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

استخدم id الوكيل على أنه agentId في كل نقطة نهاية للوكيل، مثل /v1/agents/{agentId}/leads. وid نفسه هو agent_id الذي تأخذه نقطتا إرسال واتساب في جسم الطلب. راجع مرجع عرض الوكلاء ومرجع جلب وكيل. وجلب وكيل واحد يُعيد إعداداته أيضاً؛ راجع إعدادات الوكيل.

ويمكنك أيضاً نسخ معرّفات الوكلاء من قسم "معرّفات الوكلاء" في صفحة مفاتيح API بلوحة التحكم.

أسئلة شائعة​

لماذا لا يظهر وكيل في القائمة؟​

إما أن المفتاح مقيّد ببعض الوكلاء، أو أن الوكيل حُذف، أو أنه يتبع منظمة أخرى. المفتاح المقيّد ببعض الوكلاء لا يعرض سواهم، ويُظهر GET /v1/me قائمته في agent_ids؛ والقيمة null هناك تعني كل وكلاء منظمتك، ومنهم من تضيفهم لاحقاً. ولا يصل المفتاح إلا إلى المنظمة التي يُظهرها organization في GET /v1/me. أما الوكلاء المحذوفون فلا يظهرون أبداً.

هل agent_ids في /v1/me هي نفسها قائمة الوكلاء؟​

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

هل يحتاج /v1/me إلى نطاق؟​

لا. تعرض صفحته في المرجع x-scope: none: يستطيع أي مفتاح صالح استدعاءه، لأنه لا يُعيد إلا بيانات المفتاح نفسه ومعرّف منظمتك واسمها. أما عرض الوكلاء وقراءتهم فيحتاجان agents:read، وتغيير إعداداتهم agents:write، ويحمل كل مفتاح الاثنين اليوم.

هل يمكنني قراءة تعليمات الوكيل أو تغييرها عبر الواجهة البرمجية؟​

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

لماذا لا تظهر حالة الوكيل؟​

الحالة المخزّنة على الوكيل، مسودة كانت أو نشطة، لا تغيّر طريقة عمله اليوم، لذا لا تعرضها الواجهة البرمجية، ولا يستطيع المفتاح تغييرها: إرسال status في PATCH /v1/agents/{agentId} يُعيد 422 field_not_writable. والوكلاء المحذوفون لا يظهرون في القائمة أبداً، وجلب أحدهم عبر GET /v1/agents/{agentId} يُعيد 404 agent_not_found.