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

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

المصادقة

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

X-Site-Key: your-site-key

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

GET /public/widget-config

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

{
  "widgetPosition": "bottom_right",
  "widgetPrimaryColor": "#14B8A6",
  "widgetFontFamily": "inherit",
  "widgetLogoUrl": null,
  "widgetAssistantName": "Minaya",
  "widgetWelcomeMessage": "Hi, I am Minaya your AI assistant...",
  "widgetHeaderTextColor": "#FFFFFF",
  "widgetBotBubbleColor": "#F1F1F3",
  "widgetBotTextColor": "#18181B",
  "widgetUserTextColor": "#FFFFFF",
  "widgetOpenByDefault": false,
  "widgetCustomCss": null
}

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

إرسال رسالة

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 رسالة لكل جلسة.
• 2000 حرف لكل رسالة.
• للأعمال على الخطة المجانية سقف يومي للرسائل.

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

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

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