ربط شات المنصة
محادثات بين عملائك وفريق الدعم داخل تطبيقك وموقعك ولوحة منصتك، مربوطة بحسابات منصتك: لا يسجّل أحد دخولًا جديدًا، فسيرفرك يعرّف الشات بكل شخص بتوكن يوقّعه.
العناوين
- واجهة API
https://api-chat.alhawsaba.com/api - لوحة الشات
https://chat.alhawsaba.com - الاتصال اللحظي (Socket.IO)
https://api-chat.alhawsaba.com
المفاتيح
- مفتاح المشروعيسمّي مشروعك في كل توكن وكل نداء. لا يتغيّر.
project_key - سر التوقيع (JWT)يوقّع به سيرفرك توكنات الناس. لا يغادر سيرفرك أبدًا.
jwt_secret - مفتاح APIيصل مع كل نداء من الشات إلى سيرفرك لتتحقق منه، وترسله أنت مع تحديثات الناس.
api_key
تظهر المفاتيح مرة واحدة عند إضافة الخدمة إلى المشروع، وتجدها بعد ذلك داخل الخدمة في إعدادات المشروع.
توكن الشخص
لكل شخص يفتح الشات، يوقّع سيرفرك توكن JWT بخوارزمية HS256 وسر التوقيع. التوكن يقول من هو الشخص ودوره، ولا يُوقَّع أبدًا داخل التطبيق أو المتصفح.
| الحقل | مطلوب | المعنى |
|---|---|---|
project_key | نعم | مفتاح مشروعك. |
user_id | نعم | رقم الشخص عندك (external_id). |
role | نعم | user للعميل، admin لموظفك. |
name, email, phone, image_path | يُفضَّل | تُحدَّث بها بطاقة الشخص في كل طلب. |
iat, exp | نعم | وقت الإصدار والانتهاء. |
// npm i jsonwebtoken
import jwt from 'jsonwebtoken'
export function serviceToken(user, role) {
return jwt.sign({
project_key: process.env.ALHAWSABA_PROJECT_KEY,
user_id: String(user.id),
role, // 'user' = customer, 'admin' = staff
name: user.name,
email: user.email,
}, process.env.ALHAWSABA_JWT_SECRET, { algorithm: 'HS256', expiresIn: '7d' })
}لوحة منصتك
وقّع توكنًا للموظف
من سيرفرك، بالدور admin، لحظة ضغط الموظف على «الشات» في لوحتك.
افتح لوحة الشات بالتوكن
وجّه الموظف (في تبويب جديد) إلى صفحة الدخول في لوحة الشات ومعه التوكن. تحفظ اللوحة الجلسة وتحذف التوكن من الرابط.
المعامل مطلوب المعنى token نعم التوكن الموقّع. project_key يُفضَّل مفتاح مشروعك. base_url اختياري واجهة API الشات. return_url اختياري وجهة الخروج حين لا يكون للمشروع عنوان لوحة. الرابطhttps://chat.alhawsaba.com/auth?token={JWT}&project_key={project_key}&base_url=https://api-chat.alhawsaba.com/api&return_url={your_dashboard_page}الخروج يعود إلى لوحتك
عند الخروج من الشات يعود الموظف إلى «عنوان لوحة منصتك» المسجّل في المشروع، ثم إلى return_url، ثم إلى لوحة الشات نفسها.
صفحات الملف على لوحتك
زر «الملف» في الشات يفتح صفحة الشخص على لوحتك. وفّر هذين المسارين على عنوان لوحتك، وإلا وصل الرابط إلى صفحة غير موجودة.
الشخص المسار على لوحتك العميل /advertisers/{external_id}?tab=details الموظف /team/employees/{external_id}/details?tab=details اربط حساب مالك الشات («اربط حسابك»)
مالك الشات يدخل من الحوسبة لا من لوحتك، فيعرض عليه الشات أول مرة نافذة تربطه بحسابه عندك، مثل «الدخول بحساب جوجل».
# من ماذا 1 الشات يفتح {dashboard_url}/chat-link?state=…&project={name} في نافذة صغيرة. 2 لوحتك تُدخل المدير إن لزم، وتعرض من سيُربط وزر «سماح». عند السماح تُصدر رمزًا لمرة واحدة لهذا المدير وهذه الحالة، ثم ترسله للشات وتغلق النافذة. 3 الشات ← سيرفرك يستبدل الرمز بالمدير عبر link-exchange (في «سيرفر منصتك»). لوحتك: إرسال الرمزwindow.opener.postMessage({ type: 'alhawsaba-chat-link', code, state }, 'https://chat.alhawsaba.com') window.close()أرسل الرسالة إلى عنوان لوحة الشات فقط، لا إلى *. الرمز لمرة واحدة ولهذه الحالة فقط.
الأخطاء الشائعة
| الحالة | المعنى |
|---|---|
401 Token not provided | لا يوجد توكن. |
401 Invalid token payload | ينقص التوكن project_key أو user_id أو role. |
401 Invalid token | التوقيع خاطئ أو التوكن منتهٍ. |
404 Project not found or blocked | مفتاح المشروع خاطئ أو المشروع موقوف. |
403 Account is blocked | الحساب موقوف. |