واجهة برمجة التطبيقات العامة

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

المصادقة

أرسل مفتاح موقعك كترويسة (header). كما يتم التحقق من الطلبات مقابل القائمة المسموح بها لنطاقك، بحيث لا يمكن استخدام مفتاح مسرّب من موقع آخر.

X-Site-Key: your-site-key

جلب إعدادات الودجت

GET /public/widget-config

يعيد إعدادات المظهر. يُستخدم بواسطة الودجت عند التحميل.

{
  "widgetPosition": "bottom_right",
  "widgetPrimaryColor": "#075CE5",
  "widgetFontFamily": "inherit",
  "widgetLogoUrl": null,
  "widgetAssistantName": "Minaya",
  "widgetWelcomeMessage": "Hi, I am Minaya your AI assistant...",
  "widgetHeaderTextColor": "#FFFFFF",
  "widgetBotBubbleColor": "#F1F1F3",
  "widgetBotTextColor": "#18181B",
  "widgetUserTextColor": "#FFFFFF",
  "widgetOpenByDefault": false,
  "widgetPathMode": "all",
  "widgetPathRules": [],
  "widgetCustomCss": null
}

يتم تحديد widgetAssistantName من جانب الخادم — وهو دائمًا نص (string)، ولا يكون أبدًا null.

يحدّد widgetPathMode وwidgetPathRules أين يجب أن تظهر الأداة (all أو include أو exclude، مع أنماط مسارات مثل/blog/*). تطبّقها الأداة المرفقة؛ وينبغي لأي عميل مخصّص فعل ذلك أيضًا.

التخزين المؤقت

تُخزَّن نقاط القراءة مؤقتًا على الخادم وتُمسح فور تغيّر الإعدادات الأساسية، لذا يصبح أي تغيير محفوظ ساريًا مع الطلب التالي. تحمل الاستجابات ترويسة X-Cache(HIT أو MISS)؛ أرسل Cache-Control: no-cacheلتجاوز التخزين المؤقت لطلب واحد.

إرسال رسالة

POST /public/chat

{
  "message": "Do you ship to Canada?",
  "sessionId": "optional-existing-session",
  "visitorIdentifier": "optional-stable-visitor-id",
  "stream": false,
  "origin": "https://example.com",
  "country": "CA"
}

احذف sessionId لبدء محادثة جديدة؛ يُعيد الرد معرّفًا لإعادة استخدامه في الرسائل التالية.

{ "sessionId": "…", "reply": "Yes — 3 to 5 business days…", "messageId": "…" }

عند تفعيل stream: true يصل الرد على شكل أحداث مرسلة من الخادم (server-sent events)، تحمل كل منها جزءًا من content وحدث done نهائيًا.

جلب السجل

GET /public/chat/history/:sessionId

يعيد الرسائل ضمن جلسة معينة، مقيّدة بنطاق عملك بحيث لا يمكن لودجت موقع ما قراءة محادثات موقع آخر أبدًا. يُستخدم لاستعادة المحادثة عند إعادة فتح الزائر للودجت.

تقييم رسالة

POST /public/chat/feedback

{ "messageId": "…", "feedback": "up" }

يقبل up أو down، ولرسائل المساعد فقط. تظهر التقييمات في تحليلات لوحة التحكم لديك.

أحداث التحليلات

POST /public/track-click
POST /public/track-page-view

تُطلق عند فتح الودجت وعند تحميل صفحة. تقبل كلتاهما بشكل اختياري sessionId وvisitorIdentifier وorigin و country.

الحدود والسقوف

• طلبات المحادثة محدودة المعدل لكل مفتاح موقع.
• 50 رسالة لكل جلسة.
• 500 حرف لكل رسالة.
• للأعمال على الخطة المجانية سقف يومي للرسائل.
• للخطط المدفوعة حصة شهرية — 2,000 رسالة في Starter و10,000 في Pro — تُحسب عبر كل المحادثات وكل النطاقات التي تعمل عليها الأداة، من تجديد إلى تجديد.
• مع ذكاء Minaya الاصطناعي، يُحتسب الرد الذي ينفّذ إجراءً — يسجّل عميلًا محتملًا أو يستدعي أداة MCP — 3 رسائل من الحصة. ومع مفتاحك الخاص يُحتسب كل رد رسالة واحدة.
• سقف يومي في الخطط المدفوعة، يساوي ثلاثة أضعاف المتوسط اليومي للخطة، يمنع حلقة خارجة عن السيطرة من استهلاك الشهر كله في يوم واحد.

تجاوز أحد الحدود يُعيد ردًا عاديًا يشرح الوضع بدلاً من خطأ، بحيث يمكن لواجهة مخصصة عرضه كأي رسالة أخرى.

واجهة برمجة تطبيقات لوحة التحكم

تعتمد إدارة مصادر المعرفة، والمظهر، وخوادم MCP على نقاط نهاية موثّقة على نفس المضيف، وموثّقة في مواصفة OpenAPI عند /api/docs على نشرتك.