# Paradise Pools Chatbot (WhatsApp + Messenger + IG + Facebook/IG Comments)

هذا البوت مُجهّز ليشتغل على:
- **WhatsApp Cloud API**
- **Facebook Messenger**
- **Instagram Direct (IG Messaging API)**
- **تعليقات Facebook + Instagram**: يعمل **Like للتعليق** ثم **Reply على التعليق** ثم **Private Reply (رسالة خاصة)**

✅ حسب طلبك: **رقم الإدارة هو نفسه رقم المعاينة**
- **عرض الرقم للعميل:** +20 10 94945225
- **إرسال تنبيه للإدارة عند أي تفاعل** (رسالة/تعليق) + تحويل **أي صور معاينات** تلقائياً لنفس الرقم مع بيانات المستخدم.

---

## 1) المتطلبات
- PHP **8.1+** (يفضل 8.2)
- Extensions: `curl`, `json`, `mbstring`, `fileinfo`
- صلاحيات كتابة للمجلدات:
  - `logs/`, `cache/`, `customers/`, `chats/`, `imports/`
- (اختياري) `ffmpeg` لو عايز استخراج Frame من الفيديو.

---

## 2) الإعداد السريع (Deployment)
1) ارفع ملفات المشروع على السيرفر (مثلاً داخل `/var/www/html/paradise-bot/`).
2) اضبط Document Root أو routing بحيث **webhook** يوصل لملف `bot.php`.
   - مثال URL: `https://YOUR-DOMAIN.com/paradise-bot/bot.php`
   - هذا هو نفس **Callback URL** الذي ستضعه في Meta Webhooks.
3) انسخ `.env.example` → `.env` واملأ القيم (أو ضعها كـ Environment Variables في السيرفر).

> مهم: **لا تضع التوكنات داخل الكود**. التوكنات تُقرأ من Environment Variables عبر `config.php`.

---

## 3) Environment Variables (أهم القيم)
في `.env`:
- `META_WHATSAPP_TOKEN`
- `META_PHONE_NUMBER_ID`
- `META_PAGE_ACCESS_TOKEN` (لـ Messenger + IG + التعليقات)
- `META_IG_USER_ID` (اختياري لكنه مفيد في IG Private Replies)
- `PARADISE_ADMIN_NUMBER=201094945225`  ← نفس رقم المعاينة (digits فقط)
- `PARADISE_PREVIEW_NUMBER_DISPLAY=+20 10 94945225`

---

## 4) إعداد Meta (WhatsApp + Messenger + IG + Webhooks)
### A) WhatsApp Cloud API
- فعّل WhatsApp في Meta App
- اربط رقم WhatsApp Business وأخذ:
  - `Phone Number ID`
  - `Permanent Access Token`
- Webhooks: فعّل **messages**

### B) Messenger
- فعّل Messenger
- اربط الـ App بالـ Facebook Page
- خُد **Page Access Token**
- في **Meta App > Webhooks**:
  - `Callback URL`: رابط `bot.php` (HTTPS)
  - `Verify Token`: نفس قيمة `META_VERIFY_TOKEN`
  - عند التحقق، Meta يرسل:
    - `hub.mode=subscribe`
    - `hub.verify_token=...`
    - `hub.challenge=...`
- Webhooks (object: page): فعّل `messages` (وممكن `messaging_postbacks` لو هتستخدم أزرار لاحقاً)

### C) Instagram Messaging + Comments
- اربط Instagram Professional Account بالـ Facebook Page
- فعّل Instagram Messaging + Webhooks
- Webhooks (object: instagram): فعّل `messages` و `comments` (حسب إعدادات حسابك)

### D) Comments (Facebook Page feed)
- Webhooks (object: page): فعّل field `feed`
- البوت سيعمل: Like → Reply → Private Reply

> **معلومة مهمة:** ميزة Private Replies تسمح **برسالة واحدة** كـ رد خاص على تعليق/منشور الزائر، ومسموح بها خلال **7 أيام** من تفاعل المستخدم. (راجع سياسة Messenger Platform) 

---

## 5) ما الذي يفعله البوت تلقائياً؟
### الرسائل (WhatsApp/Messenger/IG)
- رد سريع + احترافي
- تقليل استهلاك الموارد:
  - ردود سريعة بدون AI لعبارات شائعة
  - كاش للـ AI
  - تقليل التاريخ المرسل للـ AI
- **أي رسالة/تفاعل → إشعار للإدارة على WhatsApp**
- **أي صورة معاينة** (WhatsApp أو Messenger أو IG) → تتحول تلقائياً لنفس رقم الإدارة مع:
  - المنصة
  - رقم/ID العميل
  - اسم العميل (لو متاح)

### التعليقات (Facebook/IG)
- يعمل Like للتعليق
- يرد Reply على التعليق
- يرسل **Private Reply** للمستخدم
- يرسل إشعار للإدارة بتفاصيل التعليق

---

## 6) إعدادات مهمة داخل config.php
- `notify_admin_on_every_interaction` = true
- `admin_notify_rate_limit_seconds` = 60  (منع تكرار إشعارات مزعجة)
- `forward_media_to_admin` = true
- `forward_media_types` = ['image']  (يمكن إضافة video/document إذا رغبت)
- `ensure_preview_line` = true  (يضيف سطر رقم المعاينة تلقائياً في كل رد)

---

## 7) اختبار سريع
- افتح endpoint للتحقق:
  - GET `bot.php?hub.mode=subscribe&hub.verify_token=YOUR_TOKEN&hub.challenge=123`
  - (مدعوم أيضًا للصيغة القديمة: `hub_verify_token` / `hub_challenge`)
- ابعت رسالة على WhatsApp → تتأكد من الرد + وصول إشعار للإدارة
- اكتب تعليق على منشور بالـ Page → تتأكد من Like + Reply + Private Reply + إشعار الإدارة

---

## 8) ملاحظات تشغيل (Best Practices)
- استخدم HTTPS
- فعّل Logging لكن راقب مساحة `logs/`
- استعمل cron لحذف ملفات `cache/` القديمة (اختياري)
- لو هترسل رسائل بعد نافذة 24 ساعة في WhatsApp: جهّز **WhatsApp Message Template** واكتب اسمه في:
  - `WHATSAPP_ALERT_TEMPLATE`

---

## 9) دعم / تخصيص
تقدر تعدل نصوص الرسائل السريعة + ردود التعليقات من:
- `buildCommentReplies()`
- `getFastIntentReply()`
- `buildSystemPrompt()`
