REST API · JSON
وثّق بسلاسة مع NovaMind
ادمج نظام الدعم الذكي في منصّتك خلال دقائق. Token واحد يكفي لتفعيل المحادثات المباشرة والردود الذكية لعملائك.
الويدجت الجاهز (الأسرع)
سطر واحد فقط ويعمل widget كامل على موقعك. مع تخصيص اللون والاسم من لوحتك، حفظ الجلسة، رفع الصور، الذكاء الاصطناعي، ومتجاوب مع الجوال.
موصى لـ 90% من العملاء
لا تحتاج تكتب JavaScript. الـ widget يستخدم نفس الـ API لكن بمزايا جاهزة.
أضف هذا السطر قبل </body>
<script src="https://cloud-chat.top/widget.js?token=YOUR_TOKEN_HERE" async></script>
استبدل YOUR_TOKEN_HERE
احصل على Token API من لوحة تحكم العميل → Token API → نسخ.
خصّص من لوحتك
كل التخصيصات (اللون، اسم البوت، رسالة الترحيب، الردود التلقائية، الذكاء الاصطناعي) تتم من لوحة العميل — تنطبق فوراً بدون تعديل الكود.
ما يفعله الويدجت تلقائياً
- ✅ تسجيل الزائر — يطلب الاسم والإيميل/الجوال قبل البدء
- ✅ حفظ الجلسة في localStorage — لا تتكرر المحادثة عند refresh
- ✅ Live polling كل 2 ثانية — الردود تصل بسرعة
- ✅ عرض الصور والصوت والفيديو تلقائياً (يكتشف
[صورة] URLو[رسالة صوتية] URL) - ✅ متجاوب مع الجوال — يعمل بشكل ممتاز على iPhone و Android
- ✅ دعم RTL كامل للعربية
- ✅ إشعار رسائل جديدة — badge أحمر على زر الـ widget
معاينة
الويدجت سيظهر كزر دائري في الزاوية اليمنى السفلية لموقعك. عند الضغط عليه، يفتح نافذة دردشة احترافية.
أمثلة متقدمة (اختيارية)
1. إضافة الويدجت في WordPress
اذهب لـ Appearance → Theme File Editor → footer.php وأضف السطر قبل </body>.
2. تأخير ظهور الويدجت
setTimeout(() => {
const s = document.createElement('script');
s.src = 'https://cloud-chat.top/widget.js?token=YOUR_TOKEN';
s.async = true;
document.body.appendChild(s);
}, 5000); // ينتظر 5 ثواني قبل التحميل
3. إخفاء الويدجت في صفحات معينة
<?php if (!is_page('checkout')): ?>
<script src="https://cloud-chat.top/widget.js?token=YOUR_TOKEN" async></script>
<?php endif; ?>
البدء السريع (التكامل اليدوي)
ثلاث خطوات لتفعيل الدردشة المباشرة في منصّتك.
1
احصل على Token
العميل يسجّل ويدفع، ويحصل على Token من لوحته.
2
أضف حقلاً في منصّتك
خانة "Token API" في إعدادات العميل، يضع فيها التوكن.
3
ابدأ الإرسال
استخدم التوكن في Header Authorization: Bearer.
مثال أول
تحقّق من صلاحية التوكن واشتراك العميل:
# cURL
curl https://cloud-chat.top/chat-api.php?action=provider_bootstrap \
-H "Authorization: Bearer nw_xxxxxxxxxxxxxxxxxxxxxx"
تدفق الاتصال الكامل
كيف تتواصل منصّتك مع NovaMind من بداية المحادثة حتى نهايتها.
الزائريكتب رسالة
←
منصّتكPOST /provider_send
←
NovaMindيعالج ويحفظ
←
رد تلقائيفوراً
منصّتكGET /provider_poll كل 4 ثوان
←
NovaMindيرجع ردود الإدارة
←
الإدارةترد من اللوحة أو iOS
ملاحظة
session_id هو معرّف فريد لكل محادثة زائر. منصّتك تولّده وتحتفظ به خلال جلسة الزائر (مثال: sess_abc123). نفس المعرّف يُستخدم في كل الطلبات المتعلقة بتلك المحادثة.
المصادقة
كل طلبات API تتطلّب Bearer Token في Header المصادقة.
Authorization: Bearer nw_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
تحذير أمني
لا تضع التوكن في روابط URL أو JavaScript على الواجهة الأمامية. احفظه في الخادم الخلفي فقط واستخدمه من هناك.
صيغة التوكن
كل توكن يبدأ بـ nw_ ويتبعه 40 رمز hex. مثال:
nw_20a69d992037f25bfaf98ca947c29a652ebc4280c193e3d2
فحص التوكن والاشتراك
استخدمه عند بدء جلسة الزائر للتحقق من أن العميل لديه اشتراك فعّال.
GET
/chat-api.php?action=provider_bootstrap
Headers
| المفتاح | الوصف | |
|---|---|---|
| Authorization | Bearer CLIENT_TOKEN | مطلوب |
curl https://cloud-chat.top/chat-api.php?action=provider_bootstrap \
-H "Authorization: Bearer nw_xxxx"
const res = await fetch('https://cloud-chat.top/chat-api.php?action=provider_bootstrap', {
headers: { 'Authorization': 'Bearer nw_xxxx' }
});
const data = await res.json();
$ch = curl_init('https://cloud-chat.top/chat-api.php?action=provider_bootstrap');
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => ['Authorization: Bearer nw_xxxx'],
CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
استجابة ناجحة (200)
{
"ok": true,
"active": true,
"customer_id": "cus_a1b2c3d4e5f6",
"bot_name": "مساعد NovaMind",
"bot_avatar": "🤖",
"chat_icon_url": "",
"welcome_message": "أهلاً! كيف يمكنني مساعدتك؟",
"primary_color": "#00d4ff",
"placeholder": "اكتب رسالتك...",
"allow_attachments": true,
"allow_voice": true,
"api": {
"send": "chat-api.php?action=provider_send",
"poll": "chat-api.php?action=provider_poll"
}
}
استجابة — اشتراك منتهي أو توكن غير صالح (200)
{
"ok": true,
"active": false,
"reason": "subscription_inactive_or_invalid_token"
}
إرسال رسالة
أرسل رسالة الزائر إلى NovaMind. يردّ النظام فوراً بالرد التلقائي (إن وُجد).
POST
/chat-api.php?action=provider_send
Body (JSON)
| الحقل | النوع | الوصف | |
|---|---|---|---|
| session_id | string | معرّف فريد للمحادثة | مطلوب |
| name | string | اسم الزائر | اختياري |
| message | string | نص الرسالة (حد أقصى 4000 حرف) | مطلوب |
curl -X POST https://cloud-chat.top/chat-api.php?action=provider_send \
-H "Authorization: Bearer nw_xxxx" \
-H "Content-Type: application/json" \
-d '{"session_id":"sess_abc","name":"Visitor","message":"مرحبا"}'
await fetch('https://cloud-chat.top/chat-api.php?action=provider_send', {
method: 'POST',
headers: {
'Authorization': 'Bearer nw_xxxx',
'Content-Type': 'application/json'
},
body: JSON.stringify({
session_id: 'sess_abc',
name: 'Visitor',
message: 'مرحبا'
})
});
استجابة ناجحة (200)
{
"ok": true,
"active": true,
"session_id": "cus_a1b2c3_sess_abc",
"reply": "أهلاً وسهلاً! 👋 يسعدني مساعدتك."
}
⚠️ ملاحظة مهمة عن session_id
الخادم يضيف
customer_id_ كبادئة على المعرّف الذي ترسله. احفظ session_id الذي يرجع من الاستجابة واستخدمه في طلبات provider_poll اللاحقة.
جلب ردود الإدارة
اسحب ردود الإدارة الجديدة دورياً لعرضها للزائر.
GET
/chat-api.php?action=provider_poll&session_id=SESSION_ID
Query Parameters
| المفتاح | الوصف | |
|---|---|---|
| session_id | نفس المعرّف المستخدم في provider_send | مطلوب |
curl https://cloud-chat.top/chat-api.php?action=provider_poll&session_id=sess_abc \
-H "Authorization: Bearer nw_xxxx"
استجابة ناجحة (200)
{
"ok": true,
"active": true,
"messages": [
{
"role": "admin",
"text": "شكراً لتواصلك، سأساعدك الآن.",
"time": "14:22 م",
"pending": false
}
]
}
نصيحة التحسين
نَفّذ
provider_poll كل 3–5 ثوان فقط عندما تكون نافذة الدردشة مفتوحة. الرسائل التي تم جلبها مرة لا تُرجَع مرة أخرى (يُعلم الخادم أنها استُلمت).
رموز الأخطاء
كل الأخطاء تُرجَع بـ JSON يحتوي ok: false مع رسالة وصفية.
| الرمز | المعنى | الحل |
|---|---|---|
| 400 | بيانات الطلب ناقصة (مثل empty_message) | تأكّد من إرسال message غير فارغة |
| 403 | التوكن غير صالح أو الاشتراك ملغى | تحقّق من Bearer Token أو جدّد اشتراك العميل |
| 404 | المورد غير موجود | تحقّق من صحة action |
| 429 | تجاوزت حد الطلبات (Rate Limit) | انتظر دقيقة ثم أعد المحاولة |
| 500 | خطأ داخلي | جرّب لاحقاً أو تواصل مع الدعم |
| 503 | قاعدة البيانات غير مُعدّة | راجع مسؤول النظام |
أمثلة على أشكال الأخطاء
التوكن غير صالح أو الاشتراك ملغى (HTTP 403):
{ "ok": false, "active": false, "error": "inactive_or_invalid_token" }
الرسالة فارغة (HTTP 400):
{ "ok": false, "error": "empty_message" }
تجاوز حد الطلبات (HTTP 429):
{ "ok": false, "error": "rate_limited" }
حدود الطلبات
حماية لمنع الاستخدام الزائد وضمان الجودة للجميع.
| Endpoint | الحد | النافذة |
|---|---|---|
| provider_bootstrap | 120 طلب | لكل دقيقة / IP |
| provider_send | 80 طلب | لكل دقيقة / IP |
| provider_poll | 180 طلب | لكل دقيقة / IP |
عند تجاوز الحد
يرجع الخادم
HTTP 429 مع error: "rate_limited". نفّذ backoff تصاعدي (5 → 10 → 20 ثانية) قبل إعادة المحاولة.
الكود المرجعي الكامل (موصى)
انسخ والصق هذا الكود في موقعك. يدعم: live polling كل ثانيتين، عرض الصور والصوت والفيديو تلقائياً، حفظ الجلسة في localStorage.
هذا الكود يحلّ مشاكل شائعة
استبدل widget القديم بهذا الكود لتحصل على: ✓ live updates ✓ الصور تظهر كصور ✓ الصوت كـ audio player ✓ تجربة موحّدة على الجوال واللابتوب
HTML (ضع في موقعك)
<!-- ضع في موقعك -->
<div id="chat-widget"></div>
<script>
// إعداداتك
const API = 'https://cloud-chat.top/chat-api.php';
const TOKEN = 'nw_xxxxxxxxxxxx'; // توكنك
// session_id محفوظ في localStorage
let sid = localStorage.getItem('cc_sid');
if (!sid) {
sid = 'sess_' + Date.now();
localStorage.setItem('cc_sid', sid);
}
// عرض رسالة
function renderMessage(role, text) {
const wrap = document.getElementById('chat-widget');
const div = document.createElement('div');
div.className = 'msg msg-' + role;
// كشف الصور والصوت والفيديو
const img = text.match(/^\[صورة\]\s+(https?:\/\/\S+)$/);
const aud = text.match(/^\[رسالة صوتية\]\s+(https?:\/\/\S+)$/);
const vid = text.match(/^\[فيديو\]\s+(https?:\/\/\S+)$/);
if (img) {
div.innerHTML = '<img src="' + img[1] + '" style="max-width:240px;border-radius:12px">';
} else if (aud) {
div.innerHTML = '<audio controls src="' + aud[1] + '"></audio>';
} else if (vid) {
div.innerHTML = '<video controls src="' + vid[1] + '" style="max-width:240px"></video>';
} else {
div.textContent = text;
}
wrap.appendChild(div);
wrap.scrollTop = wrap.scrollHeight;
}
// إرسال رسالة
async function sendMessage(text) {
renderMessage('user', text);
const res = await fetch(API + '?action=provider_send', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer ' + TOKEN
},
body: JSON.stringify({
session_id: sid,
name: 'زائر',
message: text
})
});
const data = await res.json();
if (data.reply) renderMessage('bot', data.reply);
}
// LIVE POLLING — كل ثانيتين تستلم ردود الأدمن
setInterval(async () => {
try {
const res = await fetch(API + '?action=provider_poll&session=' + sid, {
headers: { 'Authorization': 'Bearer ' + TOKEN }
});
const data = await res.json();
(data.messages || []).forEach(m => renderMessage('admin', m.text));
} catch (e) { /* تجاهل أخطاء الشبكة المؤقتة */ }
}, 2000); // كل 2 ثانية
// مثال إرسال
sendMessage('مرحباً');
</script>
ملاحظات مهمة
- polling = 2 ثانية — تجربة مستخدم سلسة (live)
- localStorage — يحفظ session_id فلا تتكرر المحادثة عند refresh
- regex للصور — يحوّل
[صورة] URLلصورة فعلية تلقائياً - للأمان في الإنتاج، احفظ TOKEN في الخادم الخلفي وأرسل الطلبات منه
الأمان
ممارسات موصى بها لحماية عملائك وبياناتهم.
تخزين التوكن
احفظ التوكن في قاعدة بيانات منصّتك مشفّراً. NovaMind يحفظه مشفّراً بـ AES-256-GCM أو sodium_crypto_secretbox، مع HMAC-SHA256 للفهرسة السريعة.
حماية الطلبات
- أرسل التوكن دائماً في Header
Authorization— ليس في URL - استخدم HTTPS فقط
- لا تُخزّن التوكن في JavaScript على الواجهة الأمامية
- استخدم الـ API من خادمك الخلفي فقط
دوّر التوكن عند الشك
إذا تسرّب التوكن، اطلب من العميل إعادة توليده فوراً من لوحته، ثم حدّث القيمة في منصّتك.
CORS
endpoint
chat-api.php يقبل طلبات من أي أصل بشرط وجود Bearer Token صحيح. هذا آمن لأن التوكن لا يمكن تزويره.
أسئلة شائعة
كيف أحصل على حساب اختباري؟
سجّل حساباً في صفحة التسجيل واطلب من الأدمن تفعيله يدوياً.
من يولّد session_id؟
منصّتك. يجب أن يكون فريداً لكل محادثة زائر (UUID أو IP+timestamp).
هل يوجد Webhook بدلاً من Polling؟
حالياً لا. استخدم polling كل 3–5 ثوان — Rate limit يسمح بذلك.
كيف أعرف أن العميل ألغى اشتراكه؟
استدعِ provider_bootstrap دورياً. إذا رجع active: false أخفِ الشات.
ماذا يحدث للرسائل بعد إغلاق الجلسة؟
تبقى محفوظة مع status: closed. يستطيع العميل مراجعتها من لوحته.
NovaMind API v1.0 · الرجوع للرئيسية