# 📱 دليل استخدام WhatsApp Gateway (رقمك الشخصي)

## 🎯 نظرة عامة

تم إضافة نظام **WhatsApp Gateway** الذي يتيح لك إرسال رسائل واتساب من رقم موبايلك الشخصي **بدون الحاجة لـ Twilio**.

### ✅ الميزات:
- ✨ استخدام رقمك الشخصي مجاناً
- 🔒 لا حاجة لاشتراك مدفوع
- 📱 ربط عبر QR Code فقط
- 🚀 إرسال رسائل نصية وملفات PDF
- ⚡ يعمل بجانب Twilio (لا يستبدله)

---

## 📋 الخيارات المتاحة

يدعم النظام عدة أنواع من الـ Gateways:

### 1️⃣ Evolution API ⭐ (موصى به)
- **المميزات:** سهل التثبيت، دعم كامل للميزات، مجاني
- **التثبيت:** Docker أو Node.js
- **الموقع:** [Evolution API GitHub](https://github.com/EvolutionAPI/evolution-api)

### 2️⃣ WAHA (WhatsApp HTTP API)
- **المميزات:** خفيف، سريع، مفتوح المصدر
- **التثبيت:** Docker
- **الموقع:** [WAHA GitHub](https://github.com/devlikeapro/waha)

### 3️⃣ WPPConnect
- **المميزات:** دعم واسع، مجتمع نشط
- **التثبيت:** Node.js
- **الموقع:** [WPPConnect GitHub](https://github.com/wppconnect-team/wppconnect)

### 4️⃣ Custom Gateway
- يمكنك استخدام أي Gateway آخر يدعم HTTP API

---

## 🔧 التثبيت والإعداد

### الطريقة 1: Evolution API (Docker) - الأسهل ⭐

#### الخطوة 1: تثبيت Evolution API

```bash
# تثبيت عبر Docker
docker run -d \
  --name evolution-api \
  -p 8080:8080 \
  -e AUTHENTICATION_API_KEY="your-secret-key-123" \
  atendai/evolution-api:latest
```

#### الخطوة 2: إعداد Laravel

أضف هذه الإعدادات إلى ملف `.env`:

```env
# WhatsApp Gateway Configuration
WHATSAPP_GATEWAY_ENABLED=true
WHATSAPP_GATEWAY_TYPE=evolution
WHATSAPP_GATEWAY_API_URL=http://localhost:8080
WHATSAPP_GATEWAY_API_KEY=your-secret-key-123
WHATSAPP_GATEWAY_INSTANCE=my_instance
WHATSAPP_GATEWAY_COUNTRY_CODE=+20
```

#### الخطوة 3: إنشاء Instance وربط الهاتف

```bash
# 1. إنشاء Instance جديد
curl -X POST http://localhost:8080/instance/create \
  -H "apikey: your-secret-key-123" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceName": "my_instance",
    "qrcode": true
  }'

# 2. الحصول على QR Code
curl -X GET http://localhost:8080/instance/connect/my_instance \
  -H "apikey: your-secret-key-123"

# 3. افتح WhatsApp على موبايلك > Linked Devices > 
#    امسح الـ QR Code ضوئياً
```

---

### الطريقة 2: WAHA (Docker)

```bash
# تثبيت WAHA
docker run -d \
  --name waha \
  -p 3000:3000 \
  -e WHATSAPP_API_KEY="your-api-key" \
  devlikeapro/waha
```

#### إعداد .env:

```env
WHATSAPP_GATEWAY_ENABLED=true
WHATSAPP_GATEWAY_TYPE=waha
WHATSAPP_GATEWAY_API_URL=http://localhost:3000
WHATSAPP_GATEWAY_API_KEY=your-api-key
WAHA_SESSION=default
```

---

### الطريقة 3: WPPConnect (Node.js)

```bash
# تثبيت
git clone https://github.com/wppconnect-team/wppconnect-server
cd wppconnect-server
npm install
npm start
```

#### إعداد .env:

```env
WHATSAPP_GATEWAY_ENABLED=true
WHATSAPP_GATEWAY_TYPE=wppconnect
WHATSAPP_GATEWAY_API_URL=http://localhost:21465
WPPCONNECT_SECRET_KEY=your-secret-key
WPPCONNECT_SESSION=default
```

---

## 🚀 الاستخدام

### من واجهة Filament:

#### 1. إرسال رسالة نصية (مع نافذة منبثقة):
1. انتقل إلى **العملاء** > **قائمة العملاء**
2. ستجد زرين للواتساب:
   - 💬 **إرسال واتساب (Twilio)** - يستخدم Twilio
   - 📱 **إرسال واتساب (رقمي الخاص)** - يستخدم رقمك الشخصي ⭐ جديد
3. اضغط على الزر الجديد 📱
4. اكتب رسالتك واضغط إرسال

#### 2. إرسال رسائل سريعة (بدون نافذة) ⭐ جديد:
1. انتقل إلى **العملاء** > **قائمة العملاء**
2. ستجد أزرار سريعة جديدة:
   - ✉️ **رسالة ترحيب سريعة** - إرسال تحية فورية
   - 🔔 **إرسال تذكير** - تذكير بالرصيد (يظهر لمن عليهم مبالغ)
3. اضغط على أي زر
4. أكّد الإرسال - تم! ✅

**المميزات:**
- ⚡ بضغطة واحدة فقط
- 📝 رسائل جاهزة ومحفوظة
- 🎯 تملأ البيانات تلقائياً (الاسم، الرصيد)

#### 3. إرسال كشف حساب:
1. انتقل إلى **كشف حساب العميل**
2. اختر العميل والتواريخ
3. اضغط **إنشاء التقرير**
4. ستجد زرين:
   - 📱 **إرسال عبر واتساب (Twilio)**
   - 📱 **إرسال عبر واتساب (رقمي الخاص)** ⭐ جديد
5. اضغط على الزر الجديد

---

### من الكود:

#### إرسال رسالة نصية:

```php
use App\Jobs\SendWhatsAppGatewayMessageJob;

// إرسال رسالة
SendWhatsAppGatewayMessageJob::dispatch(
    phoneNumber: '+201234567890',
    message: 'مرحباً! هذه رسالة من رقمي الشخصي',
    metadata: ['customer_id' => 1]
);
```

#### إرسال كشف حساب:

```php
use App\Jobs\SendWhatsAppGatewayStatementJob;

SendWhatsAppGatewayStatementJob::dispatch(
    type: 'customer',
    entityId: $customerId,
    farmId: null,
    fromDate: '2026-01-01',
    toDate: '2026-01-25',
    customMessage: 'إليك كشف حسابك'
);
```

#### استخدام Service مباشرة:

```php
use App\Services\WhatsAppGatewayService;

$gateway = app(WhatsAppGatewayService::class);

// إرسال رسالة نصية
$result = $gateway->sendMessage('+201234567890', 'مرحباً!');

if ($result['success']) {
    echo "تم الإرسال! Message ID: " . $result['message_id'];
}

// إرسال ملف
$result = $gateway->sendMessageWithMedia(
    '+201234567890',
    'إليك الملف المطلوب',
    'https://example.com/file.pdf',
    'document'
);
```

---

## 🔍 التحقق من حالة الاتصال

```php
$gateway = app(WhatsAppGatewayService::class);

// التحقق من الاتصال
$status = $gateway->getConnectionStatus();

if ($status['connected']) {
    echo "متصل بنجاح!";
} else {
    echo "غير متصل: " . $status['message'];
}

// الحصول على QR Code
$qrCode = $gateway->getQRCode();
if ($qrCode) {
    echo "QR Code: " . $qrCode;
}
```

---

## 📊 المقارنة بين Twilio و Gateway

| الميزة | Twilio | Gateway (رقمك) |
|--------|--------|----------------|
| **التكلفة** | مدفوع | مجاني ✅ |
| **الإعداد** | سهل | متوسط |
| **الموثوقية** | عالية جداً | عالية |
| **القيود** | محدود بالرصيد | غير محدود ✅ |
| **الصيانة** | لا يحتاج | يحتاج Server |
| **رقم الإرسال** | رقم تجاري | رقمك الشخصي ✅ |

---

## 🛠️ استكشاف الأخطاء

### مشكلة: "WhatsApp Gateway is disabled"

**الحل:**
```env
WHATSAPP_GATEWAY_ENABLED=true
```

### مشكلة: لا يظهر زر "رقمي الخاص"

**الحل:**
1. تأكد من `WHATSAPP_GATEWAY_ENABLED=true`
2. امسح الـ cache:
   ```bash
   php artisan config:clear
   php artisan cache:clear
   ```

### مشكلة: "Connection refused"

**الحل:**
1. تأكد من تشغيل الـ Gateway:
   ```bash
   docker ps  # للتحقق من Docker
   ```
2. تحقق من الـ URL والـ Port في `.env`

### مشكلة: الرسائل لا ترسل

**الحل:**
1. تأكد من ربط الهاتف عبر QR Code
2. تحقق من الـ Logs:
   ```bash
   tail -f storage/logs/laravel.log
   ```
3. تأكد من تشغيل Queue Worker:
   ```bash
   php artisan queue:work
   ```

### مشكلة: QR Code لا يظهر

**الحل:**
```bash
# Evolution API
curl http://localhost:8080/instance/connect/my_instance \
  -H "apikey: your-api-key"

# WAHA
curl http://localhost:3000/api/qr
```

---

## 🔐 الأمان

### 1. حماية API Key
```env
# استخدم مفتاح قوي
WHATSAPP_GATEWAY_API_KEY=$(openssl rand -base64 32)
```

### 2. تقييد الوصول للـ Gateway
```bash
# في Docker، استخدم network داخلي فقط
docker network create whatsapp-network
docker network connect whatsapp-network evolution-api
```

### 3. استخدام HTTPS
```nginx
# Nginx reverse proxy
server {
    listen 443 ssl;
    server_name whatsapp.yourdomain.com;
    
    location / {
        proxy_pass http://localhost:8080;
    }
}
```

---

## 💡 نصائح وأفضل الممارسات

### 1. استخدم Server مخصص
- لا تشغل الـ Gateway على نفس سيرفر Laravel
- استخدم VPS منفصل أو Docker Container

### 2. احتياطي دائم
- احتفظ بنسخة احتياطية من الـ Session
- في حالة انقطاع الاتصال، ستحتاج لمسح QR مرة أخرى

### 3. راقب الأداء
```php
// أضف هذا في AppServiceProvider
\Illuminate\Support\Facades\Event::listen(
    \Illuminate\Queue\Events\JobProcessed::class,
    function ($event) {
        if ($event->job->resolveName() === SendWhatsAppGatewayMessageJob::class) {
            \Log::info('Gateway message processed', [
                'time' => $event->time,
            ]);
        }
    }
);
```

### 4. استخدم Rate Limiting
```php
// في RouteServiceProvider
RateLimiter::for('whatsapp-gateway', function (Request $request) {
    return Limit::perMinute(10);
});
```

---

## 📚 موارد إضافية

### Documentation:
- [Evolution API Docs](https://doc.evolution-api.com/)
- [WAHA Documentation](https://waha.devlike.pro/)
- [WPPConnect Docs](https://wppconnect.io/)
- [دليل الرسائل السريعة](WHATSAPP_QUICK_MESSAGES_GUIDE.md) ⭐ جديد

### Community:
- [Evolution API Discord](https://discord.gg/evolution-api)
- [WAHA GitHub Discussions](https://github.com/devlikeapro/waha/discussions)

---

## 🎯 الفرق بين النظامين

### ✅ يمكنك استخدام الاثنين معاً!

```php
// الخيار 1: Twilio (للرسائل المهمة)
SendWhatsAppMessageJob::dispatch($phone, $message);

// الخيار 2: Gateway الشخصي (للرسائل العادية)
SendWhatsAppGatewayMessageJob::dispatch($phone, $message);
```

**متى تستخدم Twilio؟**
- رسائل تجارية رسمية
- عندما تحتاج ضمان 99.9% uptime
- للعملاء الدوليين

**متى تستخدم Gateway؟**
- رسائل يومية للعملاء
- توفير التكلفة
- رسائل من "رقم الشركة" الشخصي

---

## 📞 ملاحظات مهمة

⚠️ **تحذيرات:**
1. لا تستخدم رقمك الشخصي للـ Spam
2. احترم سياسات WhatsApp
3. قد يتم حظر رقمك إذا أرسلت رسائل كثيرة جداً
4. استخدم Delay بين الرسائل:
   ```php
   SendWhatsAppGatewayMessageJob::dispatch($phone, $message)
       ->delay(now()->addSeconds(5));
   ```

✅ **الحد الآمن:**
- لا تتجاوز 100 رسالة/ساعة من نفس الرقم
- استخدم تأخير 3-5 ثواني بين كل رسالة

---

## 🎉 الخلاصة

تم إضافة نظام WhatsApp Gateway كامل يتيح لك:
- ✅ إرسال من رقمك الشخصي مجاناً
- ✅ أزرار منفصلة (لا تؤثر على Twilio)
- ✅ دعم Evolution API, WAHA, WPPConnect
- ✅ سهل التخصيص لأي Gateway آخر

**ابدأ الآن:**
1. ثبّت Evolution API عبر Docker
2. أضف الإعدادات في `.env`
3. امسح QR Code
4. جرب إرسال رسالة!

---

**تم التطوير بواسطة:** GitHub Copilot  
**التاريخ:** 25 يناير 2026  
**الإصدار:** 2.0.0