# نظرة عامة على الواجهة البرمجية العامة

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

تتيح الواجهة البرمجية العامة (Public API) لمجيب لخادمك (CRM، أتمتة، تطبيق مخصص، أو مساعد ذكاء اصطناعي) العمل مع الوكلاء الذين أعددتهم في مجيب. تستخدم مفاتيح API طويلة الأمد، وتقبل JSON، وتُعيد ظروف أخطاء بأسلوب Stripe — مصمّمة للتكامل المتوقَّع بين الخوادم.

## ماذا يمكنني أن أفعل بالواجهة البرمجية العامة؟

- **مفتاحك ووكلاؤه.** تحقّق من المفتاح الذي تحمله واعرض الوكلاء الذين يستطيع العمل عليهم، أول استدعاءين في أي تكامل. راجع [مفتاحك ووكلاؤه](./agents/key-and-agents).
- **إعدادات الوكيل.** اقرأ اسم الوكيل ووصفه وتعليماته الرئيسية ومنطقته الزمنية وإيقاف الذكاء الاصطناعي بعد رد فريقك ومدته والإخفاء التلقائي للتعليقات، وغيّرها. راجع [إعدادات الوكيل](./agents/agent-settings).
- **رسائل واتساب.** أرسل رسائل حرة داخل نافذة الـ24 ساعة من ميتا، وأرسل القوالب المعتمدة في أي وقت، واعرض قوالب الرقم وما يحتاجه كل قالب، واستعلم عن حالة تسليم رسالة. راجع [أدلّة واتساب](./whatsapp/send-message) و[عرض قوالب واتساب](./whatsapp/list-templates).
- **المحادثات والرسائل.** اعرض محادثات الوكيل، وتابع الرسائل الجديدة، ورُد على العملاء باسم فريقك، وافتح المحادثة أو أغلقها أو أرشفها وعلّمها مقروءة أو غير مقروءة، وأوقف الذكاء الاصطناعي فيها أو أنهِ إيقافه المؤقت، وعلّمها عاجلة أو محلولة، وأسندها. راجع [المحادثات والرسائل](./agents/conversations).
- **جهات الاتصال والملاحظات والعملاء المحتملون.** ابحث عن جهات الاتصال وحدّثها، واكتب ملاحظات يراها فريقك على سجل جهة الاتصال، وأنشئ عملاء محتملين وانقلهم بين حالاتك أو احذفهم، وغيّر متى يحفظ الذكاء الاصطناعي عميلاً محتملاً. راجع [جهات الاتصال والملاحظات والعملاء المحتملون](./agents/contacts-and-leads).
- **إسناد العملاء المحتملين وتصفيتهم وحقولهم.** أسند العملاء المحتملين إلى أعضاء فريقك، وصفِّهم حسب المُسنَد إليه أو حقل مخصّص، وثبّتهم، وأضف حقول العملاء المحتملين المخصّصة للوكيل وغيّرها واحذفها. راجع [إسناد العملاء المحتملين وتصفيتهم وحقولهم](./agents/lead-assignment-and-fields).
- **فريقك.** اعرض أعضاء فريقك بأدوارهم وبريدهم الإلكتروني، ومن يمكن إسناد عملاء الوكيل المحتملين إليه. راجع [فريقك](./agents/team).
- **معرفة الوكيل.** أضف ما يجيب منه ذكاء الوكيل الاصطناعي واستبدله واحذفه. راجع [معرفة الوكيل](./agents/knowledge).
- **القنوات والمتابعات.** شغّل الذكاء الاصطناعي أو أوقفه لكل قناة في الرسائل والتعليقات، وحدّد متى يتابع العملاء الذين توقفوا عن الرد. راجع [القنوات والمتابعات](./agents/channels-and-follow-ups).
- **التعليقات.** اقرأ تعليقات فيسبوك وإنستجرام على صفحات الوكيل مع الرد على كل منها، واعرف ما أخفاه الذكاء الاصطناعي ولماذا، وأخفِ تعليقًا أو أظهِره. راجع [التعليقات والإخفاء التلقائي](./agents/comments).
- **أداة الموقع.** اجلب أداة الدردشة لموقع الوكيل وكود التضمين الذي تلصقه في موقعك. راجع [أداة الموقع](./agents/website-widget).
- **أدوات ربط نظامك.** امنح ذكاء الوكيل الاصطناعي أدوات تستدعي نظامك الخاص، واختبرها وشغّلها واقرأ سجل تشغيلها. راجع [أدوات ربط نظامك](./agents/custom-api-tools).
- **تحليلات الوكيل.** اقرأ نشاط الوكيل يوماً بيوم: المحادثات الجديدة، والرسائل، ومزاج العملاء، والمحادثات الغاضبة، والإجراءات المكتملة. راجع [تحليلات الوكيل](./agents/analytics).
- **الباقة والاستخدام.** اطّلع على باقتك، وعلى ما استخدمته من رسائل ووكلاء في هذه الفترة، وعلى فترات الفوترة السابقة. راجع [الباقة والاستخدام](./agents/plan-and-usage).

الرسائل المُرسَلة عبر الواجهة تنضم إلى نفس المحادثة التي تنشئها رسائل webhook الواردة، فتظل لوحة التحكم موحّدة — عميل واحد، محادثة واحدة، بصرف النظر عن من بدأ الحديث. نقاط نهاية الوكيل تقع على `/v1/agents/{agentId}` وتحته، بمعرّف `id` من `GET /v1/agents`، أما نقطتا إرسال واتساب فتأخذان `agent_id` في الجسم. والقراءات التي تشمل المنظمة كلها (أعضاؤك، وباقتك واستخدامك) تقع تحت `/v1/organization/`.

## من أين أحصل على مفتاح API؟

ادخل إلى [لوحة تحكم مجيب](https://app.mojeeb.app) وافتح صفحة **مفاتيح API** من الشريط الجانبي. الميزة متاحة في باقتي Starter وProfessional. تبدو المفاتيح هكذا: `mk_live_8aB3cDe4FgH5iJ6kLm7nOp_a1b2c3d4e5` وتُعرض **مرة واحدة فقط** عند الإنشاء — احفظها كأي كلمة سر قاعدة بيانات.

راجع [التوثيق](./authentication) لمزيد من التفاصيل عن صيغة المفتاح، النطاقات (scopes)، التقييد لكل وكيل، وما يستطيع المفتاح فعله.

## هل الواجهة البرمجية مستقرة؟

نعم. كل ما تحت `/v1/` **مستقر إلى الأبد** — تغييرات إضافية فقط. حقول اختيارية جديدة، رموز خطأ جديدة، ونقاط نهاية جديدة قد تظهر دون إشعار؛ لا شيء قائم سيُعاد تسميته أو يُحذف أو يتغير معناه. أي تغيير يكسر التوافق يتطلب مساراً جديداً `/v2/`. تكاملك مع `/v1/` سيظل يعمل مع تطوّر المنصة.

## من أين أبدأ؟

أسرع طريق هو [البدء السريع في 5 دقائق](./quickstart) — أمر curl واحد يُرسل رسالتك الأولى. بعد أن يعمل ذلك، تغطي صفحات [التوثيق](./authentication) و[الإعادة الآمنة](./idempotency) و[حدود المعدّل](./rate-limits) و[كتالوج الأخطاء](./errors) كل ما تحتاجه للإنتاج.

العقد الكامل القابل للقراءة آلياً معروض في [مرجع الواجهة](./api-reference/mojeeb-public-api) وتقدّمه الواجهة نفسها على `https://api.mojeeb.app/v1/openapi.yaml` (دون مفتاح) — مفيد لإنشاء SDKs ولاستيراد Postman ولأدوات الذكاء الاصطناعي التي تقرأ OpenAPI.

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

### هل هذه الواجهة مخصّصة لعملاء المتصفح أو الجوّال؟

لا. تستخدم الواجهة العامة مفاتيح API طويلة الأمد ويجب أن تعمل من جانب الخادم فقط. لعملاء المتصفح، استخدم [أداة الموقع](/docs/channels/website-widget)؛ ولتطبيقات الجوّال، اعرض الدردشة نفسها في WebView (راجع [إضافة الدردشة إلى تطبيق الجوال](./mobile-apps))؛ أو استخدم الواجهات المضمَّنة في لوحة التحكم. ويستطيع خادمك جلب كود تضمين الأداة عبر `GET /v1/agents/{agentId}/widget`.

### هل يمكنني ربط مساعد ذكاء اصطناعي مثل Claude أو Cursor؟

نعم، عبر خادم MCP من مجيب على `https://mcp.mojeeb.app/mcp`. يحوّل هذه الواجهة إلى 49 أداة يستطيع Claude وCursor وVS Code وn8n وغيرها من عملاء MCP استدعاءها بمفتاح API الخاص بك، مع وضع قراءة فقط اختياري ودون أي حذف. انظر [مساعدو الذكاء الاصطناعي (MCP)](./mcp).

### كيف يختلف هذا عن أزرار "إرسال" في لوحة التحكم؟

الإرسال من لوحة التحكم يستخدم جلسة المستخدم المسجَّل (JWT) ويمر بنفس مُنسّق الإرسال الذي تستخدمه الواجهة العامة — آلية التسليم الفعلية متطابقة. تتيح لك الواجهة العامة فقط تشغيل عمليات الإرسال من خادمك بمفتاح API بدلاً من النقر على الأزرار.

### ما القنوات المدعومة؟

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

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

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

### أين توجد SDKs الرسمية؟

لا نُصدر SDKs رسمية بعد. [مواصفة OpenAPI 3.1](./api-reference/mojeeb-public-api) تتيح لك إنشاء واحد بأي لغة باستخدام [openapi-generator](https://openapi-generator.tech/)، أو استيرادها إلى Postman/Insomnia للاختبار السريع. إذا احتجت لغة معيّنة، تواصل مع الدعم.