توثيق Webchatix
دردشة مباشرة تعتمد على Telegram أولًا: يكتب الزائر في أداة الدردشة على الموقع، ويجيب فريقك من Telegram ومن لوحة التحكم على الويب. الأقسام على اليسار، والتفاصيل على اليمين.
في 5 دقائق
- افتح البوت ←
/start— يُنشأ حساب على خطة Free والموقع الأول. - انسخ مقتطف HTML والصقه في موقعك قبل
</body>. /panel— رابط لمرة واحدة إلى لوحة التحكم على الويب (أو عنصر القائمة «لوحة التحكم على الويب»).- ادعُ مشغّلًا:
/inviteأو القائمة ← «الفريق» ← ➕. - اربط مجموعة Telegram: أضف البوت إلى المجموعة (أو نفّذ
/addgroupداخلها) وعيّنها لموقع ضمن «المسارات». - خيار احتياطي لموقع كامل في مجموعة واحدة:
/bindsite site_keyداخل المجموعة.
الخطط والفوترة
التسجيل مفتوح: الأمر /start في البوت ينشئ حسابًا على خطة Free. تُشترى الخطط المدفوعة بالبطاقة من لوحة التحكم، في قسم الفوترة — ويتم الدفع عبر Stripe.
| الخطة | المواقع | العملاء / شهريًا | المشغّلون | شهريًا |
|---|---|---|---|---|
free | 1 | 30 | 1 | $0 |
basic | 20 | 1000 | 5 | $10 ($8 عند الدفع سنويًا) |
unlimited | ∞ | ∞ | ∞ | $20 ($16 عند الدفع سنويًا) |
الأسعار معروضة شهريًا. الدفع لسنة كاملة أرخص بنسبة 20% ويُحصَّل دفعةً واحدة ($96 و$192 سنويًا)؛ والخيار السنوي محدَّد مسبقًا في لوحة التحكم.
Premium (من Basic فما فوق): القوالب، والدعوة النشطة، وقواعد الظهور، والملاحظات، والتقييمات.
العميل هو زائر فريد بدأ محادثة خلال الشهر الميلادي الحالي — ويُعاد ضبط العدّاد في اليوم الأول من كل شهر.
كيف يتم الدفع
- لوحة التحكم ← الفوترة: الخطة الحالية، والاستهلاك، وتغيير الخطة، وقائمة الفواتير مع روابط PDF.
- لا تصل بيانات البطاقة إلى خوادمنا أبدًا — فصفحة الدفع وبوابة العميل تابعتان لـ Stripe.
- يحتسب Stripe تغيير الخطة في منتصف الفترة بالتناسب؛ أما الإلغاء فيُبقي الخطة المدفوعة حتى نهاية الفترة المدفوعة، ثم يعود الحساب إلى Free.
- يتلقى عنوان البريد الإلكتروني في القسم نفسه الإيصال، وإشعار فشل الدفع، وتذكيرًا بالتجديد قبل عدة أيام.
- لا تزال المنصة قادرة على تعيين أي خطة يدويًا:
/setplan <id|tg> <plan>.
أوامر البوت
| الأمر | من | المعنى |
|---|---|---|
/start [CODE] | الجميع | البدء / استخدام دعوة. |
/menu | عضو | القائمة الرئيسية للحساب. |
/help | الجميع | مرجع الأوامر الخاصة بدورك. |
/panel | عضو | رابط سحري إلى لوحة التحكم على الويب. |
/newsite [name | origin] | admin+ | إنشاء موقع (+ مصادر CORS). |
/addgroup | admin+ في مجموعة | ربط المجموعة كمشغّل جماعي (دون الحاجة إلى chat_id). |
/bindsite KEY | admin+ في مجموعة | ربط المجموعة كدردشة احتياطية. |
/invite | admin+ | دعوة مشغّل. |
/op_me CODE | أي شخص | قبول دعوة. |
/tpl | عضو | القائمة / add / del / الإرسال بالرد + /tpl id. |
/note | عضو | ملاحظة على محادثة (من Basic فما فوق). |
/release | عضو | تحرير محادثة (+ طلب تقييم). |
/lang | الجميع | لغة واجهة البوت: en / pl / de / ru / uk / be / ar. |
/setrole id role | المالك | owner|admin|operator. |
/crm on|off | المالك | تشغيل/إيقاف جسر CRM للحساب. |
/deleteaccount | المالك | حذف الحساب. |
/setplan | المنصة | تغيير خطة الحساب. |
/platform | المنصة | نظرة عامة على الحسابات + رابط إلى /admin/platform/. |
/id | في دردشة | عرض chat_id. |
لوحة التحكم على الويب
دخول المستأجر: الرابط من /panel أو رمز على /admin/login/. لمالك المنصة مدخل منفصل: /admin/platform/ (كلمة المرور admin_password).
| القسم | الغرض |
|---|---|
| نظرة عامة | العدّادات وآخر المحادثات؛ اسم الشركة؛ جسر CRM للمالك — مفتاح التشغيل ورابط webhook (إذا تُرك فارغًا يُستخدم الرابط الموجود في الإعدادات). |
| المواقع | الإنشاء، والمقتطف، وإعدادات الأداة الكاملة. |
| المشغّلون | الأعضاء، والدعوات، والأدوار، والمجموعات. |
| المسارات | التعيينات: الموقع ← المشغّل/المجموعة. |
| المحادثات | السجل، والتحرير، والملاحظات، والتقييم. |
| القوالب | إدارة القوالب (CRUD) + ملخص التقييمات (من Basic فما فوق). |
| الحسابات | للمنصة فقط: الخطة، والتعليق، وانتحال الهوية، والحذف. |
إعدادات الموقع
متاحة في البوت («الإعدادات») وفي لوحة التحكم على الويب ضمن المواقع ← أيقونة الترس.
| الحقل | المعنى |
|---|---|
| الاسم / العنوان / العنوان الفرعي | ترويسة الدردشة. |
| التحية / الشعار | الرسالة الأولى والعلامة التجارية. |
| متصل من–إلى، المنطقة الزمنية، الإيقاف المؤقت | حالة Online/Offline. |
| التصعيد (دقائق) | تنبيه عند عدم وجود رد. |
| اللون / الموضع / الإزاحات | زر الأداة. |
| اللغة / الصوت | en|pl|de|ru|uk|be|ar ورابط URL لملف mp3. |
| المصادر المسموح بها | CORS: نطاقات مفصولة بفواصل أو *. |
| الدعوة * | دعوة في فقاعة (من Basic فما فوق). |
| JSON الظهور | أين يظهر الزر/الدعوة (من Basic فما فوق). |
| GDPR | مربع موافقة قبل الإرسال الأول. |
| المجيب الذكي | يجيب الزائر إذا لم يردّ أحد خلال N دقيقة (3 افتراضيًا). |
المجيب الذكي (Gemini)
كتب الزائر، والمشغّل صامت — بعد عدد الدقائق المحدد يجيب Google Gemini في الدردشة. يرى الزائر الرد في الأداة، ويتلقى المشغّلون بطاقة «ردّ الذكاء الاصطناعي» في Telegram بالنص نفسه، حتى لا يكرره أحد.
- يُفعَّل لكل موقع على حدة: المواقع ← الترس ← المجيب الذكي. تحتوي الكتلة نفسها على مدة التأخير وحقل «ما يجب أن يعرفه الذكاء الاصطناعي» — ساعات العمل، والتوصيل، وما لا يجوز الوعد به.
- ردّ الإنسان يعيد ضبط المؤقت؛ ولا يتدخل في محادثة تولّاها مشغّل.
- لا يلغي رد الذكاء الاصطناعي التصعيد: يظل المسؤول يتلقى تنبيهًا بأن أحدًا من البشر لم يرد.
- يحافظ النموذج على إيجاز الإجابات، ولا يختلق الأسعار أو المواعيد أبدًا، ويعترف بأنه مساعد آلي عند سؤاله مباشرة.
- يُضبط مفتاح API مرة واحدة لكل تثبيت:
gemini_api_keyفيconfig/config.php(احصل عليه من Google AI Studio، وله مستوى مجاني). بدون المفتاح لا يفعل مربع الاختيار شيئًا.
مثال على الظهور
{"include":["/pricing","/contacts"],"exclude":["/admin"],"desktop":true,"mobile":true}أداة الموقع
<script async src="https://YOUR_DOMAIN/widget/webchatix.js"
data-site-key="YOUR_KEY"></script>التحكم من الصفحة:
webchatix("show"); // show the button
webchatix("hide"); // hide it
webchatix("open"); // open the chat
webchatix("close"); // close the panelتتبع لغة الأداة data-lang، ثم <html lang> الخاص بالصفحة، ثم المتصفح؛ اللغات المدعومة هي en / pl / de / ru / uk / be / ar، والإنجليزية هي اللغة الاحتياطية. بعد تغيير الإعدادات، أعد تحميل صفحة العميل (إصدار الأداة موجود في الاستعلام ?v=).
إذا كان موقعك يعيّن Content-Security-Policy، فاسمح بنطاق الأداة في ثلاث توجيهات: script-src وstyle-src وconnect-src. تحمّل الأداة تنسيقاتها من ملف منفصل هو webchatix.css، لذا لا حاجة للإبقاء على 'unsafe-inline' في style-src من أجلها.
المشغّلون والأدوار
- owner — تحكم كامل، وطلبات الخطط، وحذف الحساب، وCRM، ونقل الملكية.
- admin — المواقع، والدعوات، والمسارات، والإعدادات.
- operator — الرد في المحادثات، والملاحظات/القوالب بحسب الخطة.
مستخدم Telegram واحد = حساب مملوك واحد. ويمكنك أن تكون مشغّلًا في حسابات الآخرين بدعوة.
المجموعات
إلى جانب الأشخاص، يمكن لمجموعة Telegram أن تكون مشغّلًا: تصل الطلبات كبطاقة في الدردشة، ويجيب أي عضو في المجموعة بالرد عليها. لربط مجموعة، أضف البوت إليها (القائمة ← 💬 المجموعات ← «ربط مجموعة») أو نفّذ /addgroup داخلها — لا حاجة لكتابة chat_id، فالبوت يقرؤه بنفسه. لا تُحتسب المجموعات ضمن حد المشغّلين في الخطة.
المحادثات
- تذهب رسالة العميل إلى Telegram (المجموعة/المشغّل وفق المسار).
- تولّي — يأخذ المحادثة؛ وتُضاف رسالة نظام إلى السجل.
- تحويل — فقط إلى عضو نشط في الحساب نفسه.
- تحرير — يمكنك أن تطلب من الزائر تقييمًا.
- الملاحظات — مرئية للفريق، لا للعميل (من Basic فما فوق).
- القوالب — الرد على المحادثة مع
/tpl id، أو زر القالب ← رد.
المنصة (مالك التطبيق)
معرّفات Telegram من ADMIN_IDS / platform_tg_ids بالإضافة إلى admin_password.
- الويب:
/admin/platform/← الحسابات، وsetplan، والتعليق، وانتحال الهوية، والحذف. - البوت:
/platform،/setplan id|tg plan.
يُسجَّل انتحال الهوية في platform_audit (من/IP/الحساب).
الأمان وGDPR
- الحسابات معزولة بواسطة
account_id. - الرابط السحري لمرة واحدة؛ وإصدار الروابط محدود المعدّل.
- التعليق يوقف الأداة والبوت ولوحة تحكم المستأجر.
- CORS: اضبط allowed_origins (لا تترك
*في بيئة الإنتاج دون سبب). - يأتي مربع GDPR قبل الرسالة الأولى من العميل.
- حصة الرفع تعتمد على الخطة (
max_upload_mb). - لا أكثر من 10 مواقع جديدة في الساعة لكل حساب.
النسخ الاحتياطي والنشر
سكربت النسخ الاحتياطي لـ SQLite مع التدوير:
chmod +x scripts/backup-sqlite.sh
# daily cron:
15 3 * * * /path/to/chat-widget/scripts/backup-sqlite.shالنسخ: data/backups/chat_*.sqlite.gz (14 افتراضيًا).
بعد تحديث قواعد rewrite في aaPanel، أضف docs بجوار faq|contact|blog وبادئات اللغات pl|de|ru|uk|be|ar، ثم أعد تشغيل البوت.