ابنِ على الواجهة البرمجية نفسها التي نبني عليها

كل ما تفعله المنصة — المحادثات وجهات الاتصال ووكلاء الذكاء الاصطناعي والمعرفة والتحليلات — تحرّكه واجهة REST API هذه. لا توجد واجهة خاصة أفضل وراءها: هذه هي. عنوان الأساس: `https://api.inteligenciaviva.com/v1`.

البداية السريعة: أول طلب لك في 60 ثانية

أنشئ مفتاح API في مساحة عملك، وصدِّره، واعرض قائمة محادثاتك. المفاتيح محصورة النطاق لكل مساحة عمل، ويمكن أن تكون للقراءة فقط أو للقراءة والكتابة.

curl https://api.inteligenciaviva.com/v1/workspaces/WORKSPACE_ID/conversations \
  -H "Authorization: Bearer sk_live_..."

كل استجابة هي JSON. تُرجع نقاط نهاية المجموعات مصفوفات `data`؛ وتُرجع الأخطاء كائن `error` يحمل `code` و`message` مع حالة HTTP مطابقة.

الواجهة البرمجية المجانية — بلا حساب وبلا مفتاح

الطبقة المجانية تتحدث API أيضًا. تستقبل `POST /v1/free/widget-snippet` الإعدادات نفسها بالضبط التي يبنيها المولِّد المرئي في صفحة مجانًا وتُرجع مقتطف HTML الجاهز للصق — بلا مصادقة وبلا تسجيل. استخدمها لتوليد أدوات لمواقع العملاء دفعة واحدة، أو لإعادة توليد التضمينات من CI عند تغيّر الجداول، أو ببساطة لتلمس الواجهة البرمجية قبل أن تدفع سنتًا واحدًا.

curl -X POST https://api.inteligenciaviva.com/v1/free/widget-snippet \
  -H "Content-Type: application/json" \
  -d @widget-config.json
# → { "snippet": "<link rel=\"stylesheet\" ..." }

المصادقة

تحمل كل الطلبات مفتاح API في ترويسة `Authorization` كرمز Bearer. تُنشأ المفاتيح وتُلغى من الواجهة البرمجية نفسها أو من لوحة التحكم، لكل مساحة عمل — وإلغاء مفتاح يقطع وصوله فورًا.

نقاط نهاية جلسات الحساب (التسجيل، وتسجيل الدخول، والدخول عبر Google، وتبادل التذاكر، والملف الشخصي، وحذف الحساب تحت `/v1/auth`) تشغّل تطبيقاتنا نحن؛ أما لتكاملات الخادم إلى الخادم فاستخدم دائمًا مفاتيح API الخاصة بمساحة العمل بدلًا من جلسات المستخدمين.

Authorization: Bearer sk_live_...

مرجع الموارد

كل المسارات أدناه تتفرع من `https://api.inteligenciaviva.com/v1/workspaces/{workspaceId}` ما لم يُذكر خلاف ذلك. هذا هو السطح الفعلي المركَّب في الخادم الخلفي الحالي — لا طموحات.

صندوق الوارد الموحّد /inbox

GET/conversationsكل المحادثات من جميع مساحات العمل التي تخدمها بيانات الاعتماد، في قائمة واحدة مرتبة حسب النشاط.
GET/conversations/{id}محادثة يتم البحث عنها في كل مساحات عملك دون معرفة أيها. تُعيد workspace_id.
GET/workspacesمساحات العمل التي يمكن لبيانات الاعتماد هذه خدمتها، مع الدور في كل منها.

المحادثات /conversations

GET/عرض قائمة المحادثات، مع إمكانية التصفية بالحالة.
GET/{id}محادثة واحدة مع حالتها وقناتها وجهة اتصالها وإسنادها.
GET/{id}/messagesسجل الرسائل (زائر، وكيل بشري، ذكاء اصطناعي، نظام).
POST/{id}/messagesإرسال رسالة داخل المحادثة بصفة وكيل.
POST/{id}/assignإسناد المحادثة إلى وكيل بشري أو قسم.
POST/{id}/resolveإغلاق المحادثة. إذا أغلقها الذكاء الاصطناعي بمفرده، تُحتسب محادثة محلولة قابلة للفوترة.
POST/فتح محادثة من خارج الأداة (مثلًا لترحيل محادثة قائمة).
GET/{id}/ai-turns«من أين أتى بذلك؟» — سجل كل دور للذكاء الاصطناعي: على ماذا استند، وأي نموذج، وكم استغرق، ولماذا حوّل.
GET/{id}/portal-caseحالة الحالة التي فتحتها هذه المحادثة في لوحة دعم البوابة، مع ردودها. يُستعلم عنها مباشرة.
POST/{id}/readوضع علامة مقروء من الفريق (عدّاد غير المقروء).
POST/{id}/reopenإعادة فتح محادثة مغلقة مع الحفاظ على السجل. بدونها كان الإغلاق بالخطأ نهائيًا.
POST/{id}/archiveأرشفة أو إلغاء الأرشفة. تخرج من الوارد دون إغلاقها ودون فقد شيء؛ الجسم {valor:true|false}.
POST/{id}/pinتثبيت في الأعلى أو إلغاؤه. المثبّتة تتصدّر الصفحة الأولى من الوارد. الجسم: {valor:true|false}.
POST/{id}/muteكتم التنبيهات لعدد N من الساعات، أو {horas:null} لسماعها من جديد.
POST/{id}/unreadتركها غير مقروءة: تُرجَع علامة القراءة إلى ما قبل آخر رسالة من العميل.

جهات الاتصال /contacts

GET/عرض قائمة جهات الاتصال.
GET/{id}جهة اتصال واحدة مع هوياتها وسجل محادثاتها.

وكلاء الذكاء الاصطناعي /ai-agents

GET/عرض وكلاء الذكاء الاصطناعي في مساحة العمل.
POST/إنشاء وكيل ذكاء اصطناعي: التعليمات، والقسم، وعتبة الثقة.
PATCH/{id}تحديث التعليمات أو العتبة أو القسم.
GET/{id}/knowledge-sourcesمصادر المعرفة الموصولة بهذا الوكيل.
POST/{id}/knowledge-sourcesوصل مصدر معرفة بهذا الوكيل.
GET/{aiAgentId}وكيل ذكاء اصطناعي واحد: التعليمات وعتبة الثقة والأدوات والقسم.

المعرفة (RAG) /knowledge-sources

POST/documentفهرسة مستند كمعرفة تُبنى عليها الإجابات.
POST/urlفهرسة رابط URL.
GET/{id}حالة المصدر وبياناته الوصفية.
DELETE/{id}إزالة مصدر ومتجهاته.
POST/{id}/reindexإعادة قراءة مصدر عنوان URL دون حذفه: إذا فشل التنزيل، لا يتغيّر شيء.
GET/سرد مصادر المعرفة مع حالة الفهرسة.

القنوات /channels

GET/عرض القنوات. العاملة اليوم: دردشة الويب والواجهة البرمجية؛ وتُوصَل قنوات أخرى فور إطلاقها.
PUT/{id}/credentialsضبط بيانات اعتماد قناة.
PUT/{id}/statusتفعيل قناة أو تعطيلها.
POST/إنشاء قناة.
GET/{channelId}قناة واحدة بنوعها وحالتها وإعداداتها.
GET/{channelId}/snippetالسطر الوحيد الذي يلصقه العميل في موقعه. كل ما عداه يُضبط من هنا.
GET/{channelId}/configإعدادات الدردشة: المنشور (`config`) وما تتجاوزه هذه القناة (`settings`). وهما مختلفان.
PUT/{channelId}/configحفظ الإعدادات. الحفظ والنشر خطوة واحدة: إذا فشلت الشبكة، فشل الطلب.
POST/{channelId}/config/publishإعادة نشر الإعدادات إلى الشبكة دون تغييرها.
POST/{channelId}/avatarرفع صورة المساعد (≤512 كيلوبايت). تُخزَّن في R2 وتُقدَّم عبر الشبكة.
POST/republicar-todosإعادة نشر كل قنوات مساحة العمل. يقوم بذلك المجدول عند تغيّر حزمة النصوص؛ وهذا لتفادي الانتظار.

الوكلاء البشريون والأقسام /agents · /departments

GET/agentsعرض الوكلاء البشريين في مساحة العمل.
POST/agents/{userId}/departmentsإلحاق وكيل بقسم.
GET/departmentsعرض الأقسام.
PUT/departments/{id}/routing-rulesضبط قواعد توجيه المحادثات الواردة.
POST/agentsدعوة شخص إلى مساحة العمل بدوره وأقسامه.
GET/agents/{userId}عضو واحد من الفريق.
POST/departmentsإنشاء قسم بقواعد التوجيه الخاصة به.
GET/departments/{id}قسم واحد.

Webhooks والمفاتيح والفوترة والتحليلات /webhooks · /api-keys · /billing · /analytics

POST/webhooksتسجيل نقطة نهاية؛ تتلقى سرّ توقيعها مرة واحدة فقط.
DELETE/webhooks/{id}إزالة نقطة نهاية.
POST/api-keysإنشاء مفتاح (للقراءة فقط أو للقراءة والكتابة).
DELETE/api-keys/{id}إلغاء مفتاح فورًا.
GET/billing/subscriptionالخطة، والمحادثات المحلولة بالذكاء الاصطناعي المشمولة، والاستخدام في هذه الفترة.
GET/analyticsمقاييس مجمعة لمساحة العمل.
GET/webhooksسرد نقاط الويب هوك.
GET/webhooks/{id}/deliveriesسجل عمليات تسليم الويب هوك مع إعادات المحاولة. هو ما يوضح إن كان الخلل لديك أم لدينا.
GET/api-keysسرد المفاتيح. لا يُعاد السر أبدًا، بل بادئته فقط.

أدوات الوكيل /conversations/{id} · /canned-responses · /tags · /presence

GET/conversations/{id}/notesملاحظات داخلية على المحادثة. لا يراها الزائر أبدًا.
POST/conversations/{id}/notesإضافة ملاحظة داخلية.
DELETE/conversations/{id}/notes/{noteId}حذف ملاحظة داخلية.
GET/canned-responsesالردود الجاهزة لمساحة العمل، مع اختصارها.
POST/canned-responsesإنشاء رد جاهز.
PATCH/canned-responses/{cannedId}تعديل رد جاهز.
DELETE/canned-responses/{cannedId}حذف رد جاهز.
POST/presenceنبضة التواجد: تعلن أن هناك شخصًا متاحًا. بالجلسة فقط — مفتاح API ينبض ليس شخصًا أمام الشاشة، ويُرفض بالرمز 400.
GET/presenceهل يوجد أحد متصل الآن؟ هذا يحدد ما إذا كان التحويل ينتظر أم يُحوَّل.
GET/ai-usageاستهلاك الاستدلال لمساحة العمل يوميًا والمحادثات الأكثر استهلاكًا.
GET/tagsوسوم مساحة العمل.
GET/conversations/{id}/tagsوسوم محادثة.
POST/conversations/{id}/tagsوسم محادثة. يُنشئ الوسم إن لم يكن موجودًا.
DELETE/conversations/{id}/tags/{tagId}إزالة وسم من المحادثة.
POST/conversations/{id}/transferتحويل المحادثة إلى قسم. له الأولوية على قواعد التوجيه: التحويل اليدوي لا يُلغى تلقائيًا.
POST/contacts/{contactId}/blockحظر جهة اتصال. تتلقى 403 بدون تفاصيل: لا يُشرح للمُسيء كيف تم اكتشافه.

المرفقات والأجهزة ومساحات العمل /conversations/{id}/attachments · /devices · /workspaces

POST/conversations/{id}/attachmentsرفع مرفق كوكيل. قائمة سماح صارمة و10 ميغابايت: لا يمر شيء يمكن للمتصفح تنفيذه.
GET/conversations/{id}/attachmentsمرفقات محادثة.
GET/attachments/{attachmentId}تنزيل مرفق. يُقدَّم برؤوس صارمة و`nosniff`؛ الصور والصوت فقط تُعرض ضمن الصفحة.
POST/devices/registerتسجيل رمز الإشعارات لجهاز، لتنبيه شخص عند تحويل الذكاء الاصطناعي. خارج بادئة مساحة العمل: `/v1/devices/register`.
POST/workspacesإنشاء مساحة عمل. خارج البادئة: `/v1/workspaces`.

أمثلة حقيقية

إرسال رسالة وكيل (curl)

curl -X POST \
  https://api.inteligenciaviva.com/v1/workspaces/$WS/conversations/$CONV/messages \
  -H "Authorization: Bearer $IV_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Hi! I checked your order — it ships tomorrow."}'

عرض قائمة المحادثات (JavaScript)

const res = await fetch(
  `https://api.inteligenciaviva.com/v1/workspaces/${WS}/conversations`,
  { headers: { Authorization: `Bearer ${process.env.IV_KEY}` } }
);
const { data } = await res.json();

التحقق من توقيع webhook (Node)

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret, rawBody, header, toleranceSec = 300) {
  const { t, v1 } = Object.fromEntries(
    header.split(",").map((p) => p.split("="))
  );
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) return false;
  const expected = createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Webhooks

سجّل نقطة نهاية HTTPS ونرسل إليها كل حدث عبر POST، موقَّعًا. الترويسة هي `iv-signature: t=<unix>,v1=<hex>`، حيث `v1` هو HMAC-SHA256 لـ `<timestamp>.<raw body>` بسرّ نقطة نهايتك — ارفض أي شيء أقدم من 5 دقائق (حماية من إعادة الإرسال). يُعاد إرسال التسليمات الفاشلة تلقائيًا بتوقيع جديد، حتى 5 محاولات.

conversation.createdبدأت محادثة جديدة على أي قناة.
message.createdوصلت رسالة (زائر أو إنسان أو ذكاء اصطناعي أو نظام).
handoff.requestedقرر الذكاء الاصطناعي أنه يحتاج إلى إنسان — اللحظة بعينها، مع الملخص.
conversation.resolvedأُغلقت محادثة؛ ويخبرك ما إذا كان الذكاء الاصطناعي قد أغلقها بمفرده.

يُسجَّل كل تسليم وحالته — فالـ webhook الذي لا يمكنك الوثوق به أسوأ من لا شيء.

البث في الوقت الفعلي

لواجهات المستخدم الحية، افتح اتصال WebSocket على بث مساحة العمل وتلقَّ أحداث المحادثات فور حدوثها — القناة نفسها التي تستخدمها تطبيقات وكلائنا.

wss://api.inteligenciaviva.com/v1/workspaces/{workspaceId}/stream

الأخطاء والحدود

الأخطاء هي HTTP التقليدية: `400` طلب مشوَّه، `401` مفتاح مفقود أو غير صالح، `403` مفتاح بلا نطاق صلاحية، `404` مورد ليس في مساحة العمل هذه، `429` تجاوز حد المعدل (تراجع وأعد المحاولة مع تشويش عشوائي)، `5xx` خطأنا نحن — أعد محاولة الطلبات العديمة الأثر الجانبي. يحمل الجسم دائمًا `error.code` و`error.message` مفهومة للبشر. حدود المعدل لكل مفتاح، وهي سخية للتكاملات الحقيقية.

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

هل هذه الوثائق طموحات أم السطح الحقيقي؟

حقيقية. كُتبت مقابل المسارات المركَّبة في الخادم الخلفي الحالي. عندما يقول شيء هنا "قريبًا"، فهو غير موجود بعد — نحن لا نوثّق السراب.

هل أحتاج إلى خطة مدفوعة لاستخدام الواجهة البرمجية؟

نعم — الواجهة البرمجية جزء من المنصة المدفوعة (Pro تتضمنها). الأداة المجانية وإضافة ووردبريس تعملان في جهة العميل ولا تحتاجان إلى أي واجهة برمجية.

ما الفرق بين مفاتيح القراءة فقط ومفاتيح القراءة والكتابة؟

مفاتيح القراءة فقط يمكنها العرض والجلب لكنها لا تعدّل أبدًا — مثالية للوحات المعلومات وذكاء الأعمال. مفاتيح القراءة والكتابة يمكنها إنشاء الرسائل وجهات الاتصال ووكلاء الذكاء الاصطناعي والإعدادات.

كيف أُخطَر بالرسائل الجديدة — بالاستطلاع الدوري أم بالـ webhooks؟

الـ webhooks (`message.created`) للخوادم، وبث WebSocket لواجهات المستخدم الحية. الاستطلاع الدوري يعمل لكنك ستصطدم بحدود المعدل قبل أن تصل إلى الزمن الفعلي.

كيف أتحقق بالضبط من أن webhook جاء منكم؟

أعد حساب HMAC-SHA256 لـ `<t>.<raw body>` بسرّ نقطة نهايتك وقارنه بزمن ثابت مع قيمة `v1` في ترويسة `iv-signature`؛ وارفض إذا كان `t` أقدم من 300 ثانية. الكود العامل موجود في هذه الصفحة.

ماذا يحدث إذا كانت نقطة نهاية الـ webhook لديّ متوقفة؟

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

هل يستطيع الذكاء الاصطناعي التسليم إلى نظام التصعيد الخاص بي؟

نعم — هذا بالضبط ما يفعله `handoff.requested`. يُطلق لحظة انخفاض ثقة الذكاء الاصطناعي دون عتبة مساحة العمل، حاملًا ملخص المحادثة، لتتمكن من استدعاء شخص أو فتح تذكرة في نظام آخر.

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

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

هل توجد حزمة SDK؟

حزمة Flutter SDK تشغّل تطبيق وكلائنا نحن، وهي أساس حزمة Enterprise ذات العلامة البيضاء. أما للخوادم، فسطح REST بسيط عمدًا — أي عميل HTTP يعمل دون غلاف.

أين أبلغ عن خطأ في الواجهة البرمجية أو نقص في هذه الوثائق؟

اكتب إلى l@inteligenciaviva.com. الوثائق التي تكذب أخطاء أيضًا — ونعاملها بالجدية نفسها.