كل أدلة الربط

ربط شات المنصة

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

العناوين

  • واجهة APIhttps://api-chat.alhawsaba.com/api
  • لوحة الشاتhttps://chat.alhawsaba.com
  • الاتصال اللحظي (Socket.IO)https://api-chat.alhawsaba.com

المفاتيح

  • مفتاح المشروعproject_key
    يسمّي مشروعك في كل توكن وكل نداء. لا يتغيّر.
  • سر التوقيع (JWT)jwt_secret
    يوقّع به سيرفرك توكنات الناس. لا يغادر سيرفرك أبدًا.
  • مفتاح APIapi_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' })
}

لوحة منصتك

  1. وقّع توكنًا للموظف

    من سيرفرك، بالدور admin، لحظة ضغط الموظف على «الشات» في لوحتك.

  2. افتح لوحة الشات بالتوكن

    وجّه الموظف (في تبويب جديد) إلى صفحة الدخول في لوحة الشات ومعه التوكن. تحفظ اللوحة الجلسة وتحذف التوكن من الرابط.

    المعاملمطلوبالمعنى
    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}
  3. الخروج يعود إلى لوحتك

    عند الخروج من الشات يعود الموظف إلى «عنوان لوحة منصتك» المسجّل في المشروع، ثم إلى return_url، ثم إلى لوحة الشات نفسها.

  4. صفحات الملف على لوحتك

    زر «الملف» في الشات يفتح صفحة الشخص على لوحتك. وفّر هذين المسارين على عنوان لوحتك، وإلا وصل الرابط إلى صفحة غير موجودة.

    الشخصالمسار على لوحتك
    العميل/advertisers/{external_id}?tab=details
    الموظف/team/employees/{external_id}/details?tab=details
  5. اربط حساب مالك الشات («اربط حسابك»)

    مالك الشات يدخل من الحوسبة لا من لوحتك، فيعرض عليه الشات أول مرة نافذة تربطه بحسابه عندك، مثل «الدخول بحساب جوجل».

    #منماذا
    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الحساب موقوف.