ابنِ فوق iNTELIGENCIA VIVA
الواجهة البرمجية العامة هي نقطة التوسّع لأي شيء يريد مطوّر بناءه فوق مساحة عمل: توجيه المحادثات إلى نظامه الخاص، أو منح وكيل ذكاء اصطناعي أداة تستعلم عن نظام ERP لعميل، أو مزامنة جهات الاتصال مع CRM، أو بث الأحداث الحيّة إلى لوحة تحكمه الخاصة. إنها REST، مُرقَّمة كإصدار v1، وكل مورد في نموذج بيانات المنتج يمكن الوصول إليه من خلالها.
المصادقة
تُوثَّق كل طلب بمفتاح API صادر من لوحة مساحة العمل، يُرسَل كـ `Authorization: Bearer sk_live_...`.
يحمل كل مفتاح نطاق صلاحيات خاصًا به قابلًا للإعداد — يمكن قصر مفتاح على وصول للقراءة فقط، أو على موارد محددة، أو منحه وصولًا كاملًا للقراءة والكتابة، بشكل مستقل عن أي مفتاح آخر صادر لنفس مساحة العمل.
تُعرَض المفاتيح كاملة مرة واحدة فقط، لحظة إنشائها؛ وبعد ذلك لا يمكن لأحد رؤيتها مجددًا سوى صاحبها، ويمكن إلغاء أي مفتاح فورًا من اللوحة دون التأثير على المفاتيح الأخرى.
Authorization: Bearer sk_live_...الموارد
كل مورد في نموذج البيانات الأساسي متاح عبر الواجهة البرمجية:
| Workspace | الإعدادات العامة، واللغة الافتراضية، والقنوات المفعَّلة. |
| Contact | إنشاء العملاء النهائيين الذين يكتبون إليك والبحث عنهم والاطلاع عليهم. |
| Conversation | سرد المحادثات وإنشاؤها وإغلاقها وإعادة إسنادها. |
| Message | إرسال الرسائل وقراءتها داخل محادثة. |
| Department | إدارة الفرق وقواعد توجيهها. |
| Agent | إدارة المستخدمين البشريين، والأدوار، والانتماء إلى الأقسام. |
| AIAgent | إنشاء وإعداد وكلاء الذكاء الاصطناعي: التعليمات، وقاعدة المعرفة، والأدوات القابلة للاستدعاء. |
| KnowledgeSource | رفع وإدارة المستندات والروابط لأغراض RAG. |
| Channel | إعداد القنوات وبيانات اعتمادها. |
| Webhook | الاشتراك في الأحداث الصادرة، الموقَّعة بـ HMAC. |
| APIKey | إصدار المفاتيح وإلغاؤها. |
أحداث Webhook
اشترك بـ `WebhookEndpoint` في أي من هذه الأحداث؛ يُوقَّع كل تسليم بـ HMAC باستخدام السر المرتبط بتلك النقطة، بحيث يمكنك التحقق من أنه صادر منّا قبل أن تثق بمحتواه:
| conversation.created | بدأت محادثة جديدة على أي قناة. |
| conversation.assigned | أُسنِدت محادثة إلى وكيل بشري أو قسم. |
| conversation.resolved | أُغلقت محادثة، سواء بواسطة الذكاء الاصطناعي أو إنسان. |
| message.received | وصلت رسالة واردة جديدة من جهة اتصال. |
| message.sent | أُرسِلت رسالة إلى جهة اتصال، بواسطة الذكاء الاصطناعي أو وكيل. |
| handoff.requested | انخفضت ثقة الذكاء الاصطناعي عن عتبة مساحة العمل فطلب إنسانًا. |
| ai_agent.tool_call | استدعى وكيل ذكاء اصطناعي إحدى أدواته المُعدَّة، بما في ذلك أدوات سجّلتها أنت بنفسك. |
يُعاد تسليم الأحداث الفاشلة، ولا يُضمَن التسليم لمرة واحدة بالضبط — صمّم معالج الـ webhook الخاص بك ليكون مثاليًا (idempotent). التفاصيل الكاملة لدلالات التسليم وإعادة المحاولة موثَّقة في شروط واجهة برمجة التطبيقات للمطورين.
البث الفوري في الوقت الحقيقي
للتكاملات التي تحتاج إلى استهلاك الأحداث حيّةً بدلًا من الـ webhooks أو بالإضافة إليها، تكشف كل مساحة عمل نقطة نهاية للبث عبر WebSocket:
wss://api.inteligenciaviva.com/v1/workspaces/{id}/streamحدود المعدل والاستخدام العادل
يخضع الوصول إلى الواجهة البرمجية لحدود معدَّل مرتبطة بخطة مساحة عملك؛ يُشار إلى أي طلب يتجاوز الحد برمز HTTP 429 وترويسات حد المعدل الحالية، بحيث يمكنك تطبيق تراجع (backoff) صحيح. الحدود الدقيقة والشروط المُلزِمة بالكامل لاستخدام الواجهة البرمجية — بما في ذلك ما يجوز وما لا يجوز فعله بالبيانات التي تحصل عليها — مبيّنة في شروط واجهة برمجة التطبيقات للمطورين، المرتبطة من صفحة القانونية.