🚀 WA-Gateway-Service: راهکار جامع و سازمانی مدیریت نشست‌های واتس‌اپ

📋 فهرست مطالب

🎯 چرا این پروژه؟
✨ قابلیت‌ها
🏗 معماری سیستم
📱 آماده‌سازی گوشی
📂 ساختار پروژه
🛠 نصب و راه‌اندازی سرور خارج
🌐 اتصال از بک‌اند داخلی (پروکسی گوگل اسکریپت)
⚙️ پیکربندی
📡 مستندات API مستقیم
🔗 وب‌هوک‌ها
🔒 امنیت
🚀 اجرا در محیط عملیاتی
❓ سوالات متداول (FAQ)
🤝 مشارکت در توسعه
📄 لایسنس

🎯 چرا این پروژه یک ضرورت استراتژیک است؟

WA-Gateway-Service یک میکروسرویس فوق‌پایدار، ماژولار و امن است که به عنوان یک لایه واسط (Bridge) بین زیرساخت‌های نرم‌افزاری شما (مانند لاراول، پایتون، جاوا و غیره) و اپلیکیشن واتس‌اپ عمل می‌کند.

این پروژه با هدف حذف هزینه‌های گزاف پیامک‌های بین‌المللی و دور زدن تحریم‌های ارتباطی برای استارتاپ‌ها و کسب‌وکارهای ایرانی توسعه یافته است.

💡 مشکلات حل شده:

مشکل	راه‌حل	تأثیر
💸 بحران هزینه‌های ارزی	استفاده از واتس‌اپ به جای پیامک	هزینه ارسال به تمام نقاط جهان صفر
🚫 تحریم سرویس‌دهنده‌ها	مالکیت ۱۰۰٪ زیرساخت	عدم وابستگی به Twilio و مشابهان
📉 نرخ تحویل پایین پیامک	ارسال از طریق واتس‌اپ	نرخ تحویل نزدیک به ۱۰۰٪
⛔ ریسک مسدود شدن	موتور ضد-بلاک هوشمند	شبیه‌سازی رفتار انسانی
🌐 قطعی ارتباط (ECONNRESET)	پروکسی اختصاصی Google Apps Script	اتصال پایدار از سرورهای داخلی (ایران) به خارج

🎯 موارد استفاده:

✅ ارسال کد تایید (OTP) به شماره‌های بین‌المللی
✅ اطلاع‌رسانی خودکار به کاربران
✅ پشتیبانی از چندین خطوط همزمان
✅ یکپارچه‌سازی با CRM و سیستم‌های موجود
✅ کاهش هزینه‌های ارتباطی تا ۹۹٪

✨ قابلیت‌های کلیدی و پیشرفته

🔐 مدیریت چند-نشستی (Multi-Session)

پشتیبانی همزمان از چندین شماره موبایل ایزوله روی یک سرور با مدیریت جداگانه هر سشن.

🧹 اصلاح هوشمند شماره (Smart Sanitization)

سیستم به صورت خودکار پیش‌وندهای + و 00 را حذف کرده و شماره را به فرمت استاندارد تبدیل می‌کند.

🔢 قالب‌بندی کدهای تایید (OTP Formatter)

امکان ارسال مجزای متن پیام و کد تایید؛ سیستم کد را به صورت Bold در انتهای پیام ترکیب می‌کند.

🌐 پروکسی اختصاصی گوگل (Anti-Filter Proxy)

بهینه‌سازی شده برای عبور از محدودیت‌های شبکه‌ای و فیلترینگ بدون نیاز به سرور واسط اضافی یا VPN. (جزئیات در بخش مربوطه)

📡 پشتیبانی کامل از وب‌هوک (Webhook)

ارسال گزارش لحظه‌ای رویدادها (وصل شدن، قطع شدن، تولید QR با تصویر Base64) به آدرس URL دلخواه شما.

📊 مانیتورینگ پیشرفته

مشاهده وضعیت مصرف RAM، زمان آنلاین بودن و سلامت لحظه‌ای خطوط.

🛡️ امنیت لایه‌بندی شده

محافظت از تمام مسیرها با X-API-KEY، قابلیت IP Whitelist و Trust Proxy برای کارکرد صحیح پشت Nginx.

🧹 پاکسازی خودکار

مکانیزم هوشمند حذف کش و فایل‌های موقت در صورت بروز خطا برای آماده‌سازی اسکن مجدد.

🤖 موتور ضد-بلاک (Anti-Ban Engine)

شبیه‌سازی رفتار انسانی (محاسبه زمان تایپ بر اساس طول متن)
ایجاد تأخیرهای تصادفی هوشمند
مدیریت نرخ ارسال (Rate Limiting)
جلوگیری از ارسال پشت سر هم توسط یک سشن

🏗 معماری سیستم

معماری فعلی از دو مسیر ارتباطی پشتیبانی می‌کند تا پایداری ۱۰۰٪ در هر شرایط جغرافیایی تضمین شود:

۱. ارتباط مستقیم (برای سرورهای خارجی)

┌─────────────────────────────────────────────────────────────┐
│                    Client Applications                       │
│         (Laravel / Python / Java / Mobile Apps)             │
└─────────────────────┬───────────────────────────────────────┘
                      │ HTTP/HTTPS
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                    Nginx Reverse Proxy                      │
│              (SSL Termination + Load Balancing)             │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│               WA-Gateway-Service (Port: 30033)              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │   API    │  │ Session  │  │ Anti-Ban │  │ Webhook  │    │
│  │  Layer   │  │ Manager  │  │  Engine  │  │ Handler  │    │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                  │
│  │  Logger  │  │Sanitizer │  │ Monitor  │                  │
│  └──────────┘  └──────────┘  └──────────┘                  │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                 WhatsApp Web (Multiple Sessions)            │
│     ┌─────────┐  ┌─────────┐  ┌─────────┐                 │
│     │Session 1│  │Session 2│  │Session N│                 │
│     └─────────┘  └─────────┘  └─────────┘                 │
└─────────────────────────────────────────────────────────────┘

۲. ارتباط از طریق پروکسی (برای سرورهای داخلی/ایران)

به دلیل مسدود بودن ارتباط‌های مستقیم با هدرهای کاستوم از داخل ایران، از Google Apps Script به عنوان یک پل (Bridge) استفاده می‌شود:

┌─────────────────────┐        ┌──────────────────────┐        ┌─────────────────────┐
│  سرور داخلی (ایران) │        │  Google Apps Script  │        │  سرور خارج (مثلا آلمان)  │
│    (Laravel / PHP)   │ ────▶ │   (Proxy Layer)      │ ────▶ │   (Node.js / WA)    │
└─────────────────────┘        └──────────────────────┘        └──────────┬──────────┘
                                                                         │
                                                                         ▼
                                                               ┌─────────────────────┐
                                                               │   WhatsApp Web API  │
                                                               └─────────────────────┘

📱 گام اول: آماده‌سازی حیاتی گوشی موبایل

⚠️ مهم: قبل از استقرار سرویس، انجام تنظیمات زیر روی گوشی فرستنده (Sender) برای پایداری سشن الزامی است:

✅ چک‌لیست آماده‌سازی:

#	اقدام	جزئیات	اهمیت
1	به‌روزرسانی واتس‌اپ	مطمئن شوید آخرین نسخه رسمی (Original/Business) را دارید	🔴 ضروری
2	غیرفعال کردن Battery Optimization	تنظیمات → Apps → WhatsApp → Battery → Don't Optimize	🔴 ضروری
3	اتصال منظم اینترنت	حداقل هر ۱۰ روز یک بار آنلاین باشید	🟡 توصیه شده
4	پاکسازی Linked Devices	تمام سشن‌های قبلی و غیرضروری را پاک کنید	🟡 توصیه شده

📱 مراحل تنظیم Battery Optimization:

Settings → Apps → WhatsApp → Battery 
→ Select "Don't optimize" یا "Unrestricted"

📂 ساختار پوشه‌بندی پروژه

/opt/WA-Gateway-Service/          # مسیر استاندارد نصب در لینوکس
│
├── 📁 helpers/                    # توابع کمکی و لاگر حرفه‌ای
│   └── logger.js                  # مدیریت ثبت وقایع غیرهمگان (Non-blocking) برای جلوگیری از فریز سرور
│
├── 📁 services/                   # هسته پردازشی واتس‌اپ
│   └── whatsapp.js                # منطق اتصال، ریکاوری خودکار قطعی، ضد-بلاک و تولید QR Base64
│
├── 📁 .wwebjs_auth/               # محل ذخیره توکن‌های ورود (ایزوله برای هر سشن - غیرقابل دسترسی از وب)
│
├── 📄 server.js                   # نقطه شروع برنامه، APIها، IP Whitelist و مدیریت خطاهای مهلک
├── 📄 wa-gateway-service.sh       # اسکریپت نصب تمام‌خودکار (Enterprise)
├── 📄 ecosystem.config.js         # تنظیمات مدیریت فرآیند PM2 (حداقل 1G RAM)
├── 📄 .env                        # متغیرهای حساس و کلیدهای امنیتی
│
├── 📄 package.json                # وابستگی‌های پروژه
├── 📄 README.md                   # مستندات پروژه (این فایل)
└── 📄 .gitignore                  # فایل‌های نادیده گرفته شده توسط گیت

🛠 نصب و راه‌اندازی سرور خارج

(این مرحله فقط روی یک سرور خارج از ایران مثلاً آلمان/هلند انجام می‌شود)

📋 پیش‌نیازها:

سیستم عامل: Ubuntu 20.04+ / Debian 11+
Node.js: نسخه 18 یا بالاتر
PM2: Process Manager برای Node.js
Nginx: (اختیاری) برای Reverse Proxy و SSL
حافظه RAM: حداقل 1 گیگابایت (بسیار مهم برای اجرای مرورگر پشت پرده واتس‌اپ)

۱. روش نصب خودکار (توصیه شده ⭐)

اسکریپت Bash طراحی شده تمامی پیش‌نیازها را به صورت خودکار نصب می‌کند:

# کلون کردن مخزن
git clone https://github.com/mmozani/WA-Gateway-Service.git
cd WA-Gateway-Service

# اجرای اسکریپت نصب (نیازمند دسترسی root)
sudo chmod +x wa-gateway-service.sh
sudo ./wa-gateway-service.sh

✨ این اسکریپت چه کارهایی انجام می‌دهد:

نصب Node.js نسخه 20 LTS
نصب PM2 Process Manager
نصب کتابخانه‌های گرافیکی Chromium
کپی پروژه به /opt/WA-Gateway-Service
نصب وابستگی‌های npm
ایجاد فایل .env نمونه
تنظیم مجوزهای امنیتی

۲. روش نصب دستی

# ۱. نصب Node.js (اگر ندارید)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# ۲. نصب PM2
sudo npm install -g pm2

# ۳. نصب کتابخانه‌های سیستمی
sudo apt update
sudo apt install -y libasound2t64 libatk-bridge2.0-0 libcups2 libxkbcommon0 \
    libxdamage1 libxrandr2 libgbm1 libpango-1.0-0 libcairo2 libasound2

# ۴. کلون و نصب پروژه
git clone https://github.com/mmozani/WA-Gateway-Service.git
cd WA-Gateway-Service
npm install

# ۵. تنظیم متغیرهای محیطی
cp .env.example .env
nano .env  # ویرایش تنظیمات

# ۶. اجرای سرویس
pm2 start ecosystem.config.js
pm2 save
pm2 startup

۳. پیکربندی Nginx (اختیاری اما توصیه شده)

برای استفاده از دامنه و SSL، از بلاک زیر در تنظیمات Nginx استفاده کنید:

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    # SSL Configuration
    ssl_certificate /etc/nginx/ssl/your-domain/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/your-domain/privateKey.pem;
    
    # Security Headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;

    location / {
        proxy_pass http://127.0.0.1:30033;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # WebSocket Support (for future real-time features)
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        
        # Timeouts
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }
}

# HTTP to HTTPS Redirect
server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

📸 نحوه اسکن کد QR و راه‌اندازی خطوط

🔄 مراحل اتصال:

┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│   ۱. مشاهده لاگ  │ ──▶ │  ۲. اسکن QR     │ ──▶ │  ۳. تأیید جلسه  │
│  pm2 logs        │      │  گوشی → واتساپ  │      │  Session READY  │
└─────────────────┘      └─────────────────┘      └─────────────────┘

📝 دستورالعمل گام‌به‌گام:

# ۱. مشاهده لاگ‌های زنده
pm2 logs wa-gateway

# خروجی نمونه:
# [WA-Gateway] 🔄 Generating QR Code...
# [WA-Gateway] 📱 Scan this QR with your phone:
# [QR CODE WILL APPEAR HERE]

مراحل اسکن:

☝️ گوشی خود را بردارید
📱 وارد اپلیکیشن واتس‌اپ شوید
⚙️ به بخش Linked Devices بروید
➕ روی Link a Device کلیک کنید
📷 کد نمایش داده شده در ترمینال را اسکن کنید
✅ پیام Session is READY. Number: 989XXXXXXXXX را مشاهده خواهید کرد

💡 نکته: اطلاعات ورود ذخیره شده و برای دفعات بعد نیازی به اسکن مجدد نیست.

🌐 اتصال از بک‌اند داخلی (پروکسی گوگل اسکریپت)

اگر بک‌اند شما (مثلاً لاراول) روی سروری در ایران قرار دارد، به دلیل مسدود بودن ارتباط‌های مستقیم با هدرهای کاستوم، درخواست مستقیم به سرور خارج با ارور ECONNRESET قطع می‌شود. برای حل قطعی این مشکل از Google Apps Script استفاده می‌کنیم.

مرحله ۱: ساخت پروکسی در گوگل اسکریپت

به script.google.com بروید و یک پروژه جدید بسازید.
کدهای زیر را در آن پیست کنید (مقادیر PROXY_SECRET و TARGET_BASE_URL را تغییر دهید):

var PROXY_SECRET = "YOUR_SECURE_PROXY_SECRET_HERE"; // یک رمز قوی بسازید
var TARGET_BASE_URL = "https://Wa-OTP.Your-Server.com";     // آدرس سرور خارجی شما

function doPost(e) {
  if (typeof e !== 'undefined') return handlePostRequest(e);
}

function doGet(e) {
  if (typeof e !== 'undefined') return handleGetRequest(e);
}

function handlePostRequest(e) {
  if (e.parameter.secret !== PROXY_SECRET) {
    return ContentService.createTextOutput(JSON.stringify({ error: "Forbidden" }));
  }

  var path = e.parameter.path || "/send-otp";
  var targetUrl = TARGET_BASE_URL + path;
  var waApiKey = e.parameter.api_key || "";
  var payloadData = e.parameter.body || "{}";
  
  var options = {
    'method': 'post',
    'contentType': 'application/json',
    'payload': payloadData,
    'headers': { 'X-API-KEY': waApiKey },
    'muteHttpExceptions': true
  };

  var res = UrlFetchApp.fetch(targetUrl, options);
  return ContentService.createTextOutput(res.getContentText());
}

function handleGetRequest(e) {
  if (e.parameter.secret !== PROXY_SECRET) {
    return ContentService.createTextOutput(JSON.stringify({ error: "Forbidden" }));
  }

  var path = e.parameter.path || "/health";
  var targetUrl = TARGET_BASE_URL + path;
  var waApiKey = e.parameter.api_key || "";

  var options = {
    'method': 'get',
    'headers': { 'X-API-KEY': waApiKey },
    'muteHttpExceptions': true
  };

  var res = UrlFetchApp.fetch(targetUrl, options);
  return ContentService.createTextOutput(res.getContentText());
}

از منوی Deploy > New deployment > نوع Web app را انتخاب کنید.
در بخش Who has access حتماً گزینه Anyone را انتخاب کرده و دیپلوی کنید.
آدرس .../exec تولید شده را کپی کنید.

مرحله ۲: استفاده در لاراول / PHP (کد آماده)

در سرور ایران خود، به هیچ وجه از Http::post لاراول یا هدرهای مستقیم استفاده نکنید. دقیقاً از ساختار cURL زیر استفاده کنید:

$proxyUrl = "https://script.google.com/macros/s/YOUR_EXEC_ID/exec";
$jsonData = json_encode([
    "phone" => "+989123456789",
    "message" => "Your Code is: ",
    "code" => "123456",
    "session_id" => "primary"
]);

// ترفند حیاتی: استفاده از http_build_query
$fullUrl = $proxyUrl . "?" . http_build_query([
    'secret'  => 'YOUR_SECURE_PROXY_SECRET_HERE',
    'path'    => '/send-otp',
    'api_key' => 'YOUR_WA_API_KEY',
    'body'    => $jsonData
]);

$ch = curl_init($fullUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true); // بسیار مهم
$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);

// ⚠️ تله گوگل اسکریپت: همیشه کد 200 برمی‌گرداند، حتما داخل جیسون را چک کنید!
if (isset($result['success']) && $result['success'] === true) {
    // ارسال موفق
} else {
    // ارور در $result['error']
}

⚙️ متغیرهای فایل تنظیمات (.env)

# ===========================================
# WA-Gateway-Service Configuration
# ===========================================

# Server Configuration
PORT=30033                          # پورت اجرای سرویس
NODE_ENV=production                 # محیط اجرایی (development/production)
TRUST_PROXY=1                       # عدد 1 یا true بگذارید تا آی‌پی واقعی پشت Nginx شناسایی شود

# Security
# ⚠️ نکته مهم: کلید API را بدون دابل کوتیشن " " بنویسید تا مشکل هدر پیش نیاید
SECRET_API_KEY=YOUR-SECRET_API_KEY
ALLOWED_IPS=127.0.0.1,::1,192.168.  # لیست آی‌پی‌های مجاز
IGNORE_IP_WHITELIST=true            # برای غیرفعال کردن محدودیت آی‌پی (true/false)

# Sessions
SESSION_IDS=primary,second           # نام سشن‌ها (با کاما جدا شوند)

# Webhook
WEBHOOK_URL=https://your-domain.com/webhook  # آدرس دریافت رویدادها (اگر سرور ایران است، خالی بگذارید)

# Anti-Ban Settings
TYPING_DELAY_MIN=1000               # حداقل تأخیر تایپ (میلی‌ثانیه)
TYPING_DELAY_MAX=3000               # حداکثر تأخیر تایپ (میلی‌ثانیه)
RATE_LIMIT_PER_MINUTE=30            # حداکثر پیام در دقیقه

# Logging
DEBUG_MODE=false                    # فعال‌سازی لاگ‌های جزئیاتی
LOG_LEVEL=info                      # سطح لاگ (debug/info/warn/error)

# Health Check
HEALTH_CHECK_INTERVAL=30000         # فاصله سلامت‌سنجی (میلی‌ثانیه)

📡 مستندات کامل API

(این مستندات برای درخواست‌های مستقیم از خارج از ایران است. اگر در ایران هستید از بخش پروکسی گوگل اسکریپت استفاده کنید).

🔐 احراز هویت

تمامی درخواست‌ها نیاز به هدر زیر دارند:

Header	Value	Description
`Content-Type`	`application/json`	فرمت داده‌ها
`X-API-KEY`	`(your secret key)`	کلید API از فایل `.env`

۱. ارسال پیام OTP

POST /send-otp ارسال کد تایید به شماره موبایل مشخص شده.

Request Body:

{
  "phone": "++989123456789",
  "message": "کد ورود شما:",
  "code": "1234",
  "session_id": "primary"
}

Parameters:

Parameter	Type	Required	Description
`phone`	string	✅ Yes	شماره موبایل مقصد (با یا بدون پیشوند)
`message`	string	✅ Yes	متن پیام (قبل از کد)
`code`	string/number	✅ Yes	کد تایید
`session_id`	string	❌ No	شناسه سشن (پیش‌فرض: primary)

Success Response (200):

{
  "success": true,
  "via": "primary",
  "sender": "989151112233",
  "status": "Sent"
}

Error Response (400/401/500):

{
  "success": false,
  "error": "Invalid phone number format"
}

۲. مشاهده وضعیت خطوط

GET /status دریافت لیست تمام سشن‌ها و وضعیت آن‌ها.

Response (200):

{
  "success": true,
  "data": [
    {
      "id": "primary",
      "status": "READY",
      "number": "989151112233",
      "ready_since": "2026-04-15T10:29:45Z"
    }
  ]
}

۳. مانیتورینگ سلامت سرور

GET /health (نیاز به API Key ندارد) بررسی سلامت سرویس و منابع سیستم.

Response (200):

{
  "status": "UP",
  "uptime": "45h 12m",
  "memory_usage": "245 MB",
  "timestamp": "2026-04-15T10:30:00Z"
}

۴. حذف سشن و آماده‌سازی مجدد

DELETE /session/:id قطع اتصال، پاکسازی کش و آماده‌سازی برای اسکن جدید.

Parameters:

Parameter	Type	Location	Description
`id`	string	URL Path	شناسه سشن

Response (200):

{
  "success": true,
  "message": "Session 'primary' deleted successfully. Ready for new QR scan."
}

🔗 مستندات وب‌هوک (Webhooks)

با تنظیم WEBHOOK_URL در فایل .env، رویدادهای زیر به صورت POST به آدرس مشخص شده ارسال می‌شوند:

📥 رویدادهای دریافتی:

۱. تولید کد QR (برای نمایش در پنل)

{
  "event": "qr",
  "session": "primary",
  "timestamp": "2026-04-15T10:25:00Z",
  "data": {
    "qr": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "expires_in": 20
  }
}

۲. احراز هویت موفق

{
  "event": "authenticated",
  "session": "primary",
  "timestamp": "2026-04-15T10:26:30Z",
  "data": {
    "number": "++989123456789"
  }
}

۳. قطع اتصال

{
  "event": "disconnected",
  "session": "primary",
  "timestamp": "2026-04-15T10:28:00Z",
  "data": {
    "reason": "connection_closed"
  }
}

۴. ارسال موفق پیام

{
  "event": "message_sent",
  "session": "primary",
  "timestamp": "2026-04-15T10:30:00Z",
  "data": {
    "to": "+989123456789",
    "message_id": "true_989123456789@c.us_3EBxxxxxxx"
  }
}

⚠️ نکته مهم برای سرورهای ایران: اگر وب‌هوک روی سرور ایران باشد، ممکن است به دلیل محدودیت‌های شبکه دریافت نشود. پیشنهاد می‌شود وب‌هوک خاموش بماند و بک‌اند ایران با متد /status وضعیت را چک کند (Pooling).

🔒 امنیت

🛡️ لایه‌های امنیتی:

┌─────────────────────────────────────┐
│  Layer 1: API Key Authentication    │ ← X-API-KEY Header
├─────────────────────────────────────┤
│  Layer 2: Rate Limiting             │ ← Anti-Ban Engine
├─────────────────────────────────────┤
│  Layer 3: IP Whitelist              │ ← فیلتر آی‌پی‌های مجاز
├─────────────────────────────────────┤
│  Layer 4: Input Validation          │ ← Smart Sanitization
├─────────────────────────────────────┤
│  Layer 5: Secure Storage            │ ← Encrypted Auth Tokens
├─────────────────────────────────────┤
│  Layer 6: Network Security          │ ← HTTPS + Nginx Hardening
├─────────────────────────────────────┤
│  Layer 7: Fatal Error Handling      │ ← خروج اجباری (Process Exit) در ارورهای مهلک
└─────────────────────────────────────┘

✅ بهترین شیوه‌ها:

تغییر کلید API: همیشه مقدار SECRET_API_KEY را تغییر دهید (بدون دابل کوتیشن).
استفاده از HTTPS: همیشه از SSL/TLS استفاده کنید.
محدود کردن دسترسی: فقط IPهای مجاز به API دسترسی داشته باشند.
به‌روزرسانی: همیشه آخرین نسخه را استفاده کنید.
لاگ‌برداری: لاگ‌ها را بررسی و نظارت کنید.

🚀 اجرا در محیط عملیاتی (Production)

📋 دستورات مدیریتی PM2:

# ▶️ شروع سرویس
pm2 start ecosystem.config.js

# 📊 مشاهده وضعیت
pm2 status

# 📜 مشاهده لاگ‌ها (بسیار مهم برای عیب‌یابی!)
pm2 logs wa-gateway

# 🔄 ریستارت سرویس
pm2 restart wa-gateway

# ⏹️ توقف سرویس
pm2 stop wa-gateway

# ❌ حذف سرویس
pm2 delete wa-gateway

# 💾 ذخیره وضعیت (اجرا پس از ریبوت)
pm2 save
pm2 startup

# 📈 مانیتورینگ بلادرنگ
pm2 monit

🔧 عیب‌یابی رایج:

# بررسی لاگ‌های خطا
pm2 logs wa-gateway --err

# بررسی مصرف منابع
pm2 show wa-gateway

# پاک کردن لاگ‌ها
pm2 flush

# بررسی وضعیت سیستم
df -h
free -m
top -bn1 | head -20

❓ سوالات متداول (FAQ)

❓ س: در سرور ایران ارور `Recv failure: Connection was reset` می‌گیرم!

ج: فایروال ایران درخواست‌های مستقیم با هدرهای کاستوم را مسدود می‌کند. حتماً از روش پروکسی Google Apps Script و متد http_build_query در PHP استفاده کنید (راهنمای کامل در همین README وجود دارد).

❓ س: ارور `Execution context was destroyed` در سرور خارج اتفاق می‌افتد.

ج: دو دلیل دارد: ۱. مقدار max_memory_restart در فایل ecosystem.config.js زیر 1 گیگابایت است (حتماً روی '1G' بگذارید). ۲. فایل‌های کش واتس‌اپ خراب شده‌اند (سشن را از طریق API حذف و دوباره QR بزنید).

❓ س: اگر شماره من مسدود (Ban) شد چکار کنم؟

ج:

سشن را با متد DELETE /session/:id پاک کنید
حداقل ۲۴ ساعت صبر کنید
با یک شماره جدید اسکن را انجام دهید
فاصله زمانی ارسال‌ها را در تنظیمات بررسی کنید
مطمئن شوید موتور ضد-بلاک فعال است

❓ س: چرا خطای ERR_ERL_UNEXPECTED_X_FORWARDED_FOR دریافت می‌کنم؟

ج:

اگر سرویس را پشت Nginx قرار داده‌اید، مطمئن شوید خط app.set('trust proxy', 1); در فایل server.js فعال است
یا متغیر TRUST_PROXY=1 را در فایل .env تنظیم کنید

❓ س: چرا کد QR در ترمینال نمایش داده نمی‌شود؟

ج:

مطمئن شوید کتابخانه‌های گرافیکی اوبونتو نصب شده‌اند
اسکریپت نصب خودکار را دوباره اجرا کنید: sudo ./wa-gateway-service.sh
یا دستی نصب کنید: sudo apt install -y libasound2t64 libatk-bridge2.0-0 libcups2

❓ س: پاسخ گوگل اسکریپت در PHP همیشه با موفقیت ارسال می‌شود اما پیام واتس‌اپ نمی‌رود!

ج: این یک ویژگی عجیب گوگل اسکریپت است. گوگل حتی در صورت ارور 500 از سرور خارجی، به شما کد 200 OK برمی‌گرداند. هرگز به کد وضعیت cURL اعتماد نکنید، حتماً مقدار $result['success'] را داخل JSON چک کنید.

❓ س: آیا می‌توانم چندین شماره را همزمان مدیریت کنم؟

ج:

بله! کافی است متغیر SESSION_IDS را در فایل .env تنظیم کنید
مثال: SESSION_IDS=sales,support,marketing
هر سشن نیاز به اسکن QR جداگانه دارد

❓ س: چگونه می‌توانم اطمینان حاصل کنم که سرویس پس از ریبوت سرور اجرا می‌شود؟

ج:

pm2 save
pm2 startup

این دستورات PM2 را به عنوان systemd service ثبت می‌کنند.

❓ س: آیا این سرویس برای محیط Production مناسب است؟

ج:

بله! این سرویس برای محیط Production طراحی شده است
ویژگی‌هایی مانند: PM2 process manager، Auto-restart، Logging، Health monitoring
پیشنهاد می‌شود از Nginx به عنوان Reverse Proxy استفاده کنید

🤝 مشارکت در توسعه

ما از مشارکت شما استقبال می‌کنیم! 🎉

📝 نحوه مشارکت:

🍴 Fork پروژه را Fork کنید
🌿 یک Branch جدید بسازید: git checkout -b feature/AmazingFeature
✅ تغییراتتان را Commit کنید: git commit -m 'Add some AmazingFeature'
📤 به Fork خود Push کنید: git push origin feature/AmazingFeature
🔀 یک Pull Request باز کنید

🐛 گزارش باگ:

از طریق Issues باگ را گزارش دهید.

👨‍💻 نویسنده

MMozani

📧 Email: mozani@parsian.digital
💼 GitHub: @mmozani

🙏 تشکر و قدردانی

whatsapp-web.js - کتابخانه اصلی واتس‌اپ
PM2 - Process Manager
جامعه برنامه‌نویسان ایران 🇮🇷

📄 لایسنس

این پروژه تحت لایسنس MIT منتشر شده است.

MIT License

Copyright (c) 2026 Mohamad Mozani

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

⭐ اگر این پروژه به شما کمک کرد، لطفاً Star کنید! ⭐

توسعه داده شده با ❤️ برای جامعه برنامه‌نویسان ایران 🇮🇷

🔗 لینک‌های مفید:
🐛 گزارش مشکل • 💬 بحث و گفتگو •

```

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
helpers		helpers
services		services
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
ecosystem.config.js		ecosystem.config.js
package.json		package.json
server.js		server.js
wa-gateway-service.sh		wa-gateway-service.sh

Folders and files

Latest commit

History

Repository files navigation

🚀 WA-Gateway-Service: راهکار جامع و سازمانی مدیریت نشست‌های واتس‌اپ

📋 فهرست مطالب

🎯 چرا این پروژه یک ضرورت استراتژیک است؟

💡 مشکلات حل شده:

🎯 موارد استفاده:

✨ قابلیت‌های کلیدی و پیشرفته

🔐 مدیریت چند-نشستی (Multi-Session)

🧹 اصلاح هوشمند شماره (Smart Sanitization)

🔢 قالب‌بندی کدهای تایید (OTP Formatter)

🌐 پروکسی اختصاصی گوگل (Anti-Filter Proxy)

📡 پشتیبانی کامل از وب‌هوک (Webhook)

📊 مانیتورینگ پیشرفته

🛡️ امنیت لایه‌بندی شده

🧹 پاکسازی خودکار

🤖 موتور ضد-بلاک (Anti-Ban Engine)

🏗 معماری سیستم

۱. ارتباط مستقیم (برای سرورهای خارجی)

۲. ارتباط از طریق پروکسی (برای سرورهای داخلی/ایران)

📱 گام اول: آماده‌سازی حیاتی گوشی موبایل

✅ چک‌لیست آماده‌سازی:

📱 مراحل تنظیم Battery Optimization:

📂 ساختار پوشه‌بندی پروژه

🛠 نصب و راه‌اندازی سرور خارج

📋 پیش‌نیازها:

۱. روش نصب خودکار (توصیه شده ⭐)

✨ این اسکریپت چه کارهایی انجام می‌دهد:

۲. روش نصب دستی

۳. پیکربندی Nginx (اختیاری اما توصیه شده)

📸 نحوه اسکن کد QR و راه‌اندازی خطوط

🔄 مراحل اتصال:

📝 دستورالعمل گام‌به‌گام:

🌐 اتصال از بک‌اند داخلی (پروکسی گوگل اسکریپت)

مرحله ۱: ساخت پروکسی در گوگل اسکریپت

مرحله ۲: استفاده در لاراول / PHP (کد آماده)

⚙️ متغیرهای فایل تنظیمات (.env)

📡 مستندات کامل API

🔐 احراز هویت

۱. ارسال پیام OTP

Request Body:

Parameters:

Success Response (200):

Error Response (400/401/500):

۲. مشاهده وضعیت خطوط

Response (200):

۳. مانیتورینگ سلامت سرور

Response (200):

۴. حذف سشن و آماده‌سازی مجدد

Parameters:

Response (200):

🔗 مستندات وب‌هوک (Webhooks)

📥 رویدادهای دریافتی:

۱. تولید کد QR (برای نمایش در پنل)

۲. احراز هویت موفق

۳. قطع اتصال

۴. ارسال موفق پیام

🔒 امنیت

🛡️ لایه‌های امنیتی:

✅ بهترین شیوه‌ها:

🚀 اجرا در محیط عملیاتی (Production)

📋 دستورات مدیریتی PM2:

🔧 عیب‌یابی رایج:

❓ سوالات متداول (FAQ)

❓ س: در سرور ایران ارور Recv failure: Connection was reset می‌گیرم!

❓ س: ارور Execution context was destroyed در سرور خارج اتفاق می‌افتد.

❓ س: اگر شماره من مسدود (Ban) شد چکار کنم؟

❓ س: چرا خطای ERR_ERL_UNEXPECTED_X_FORWARDED_FOR دریافت می‌کنم؟

❓ س: چرا کد QR در ترمینال نمایش داده نمی‌شود؟

❓ س: پاسخ گوگل اسکریپت در PHP همیشه با موفقیت ارسال می‌شود اما پیام واتس‌اپ نمی‌رود!

❓ س: آیا می‌توانم چندین شماره را همزمان مدیریت کنم؟

❓ س: چگونه می‌توانم اطمینان حاصل کنم که سرویس پس از ریبوت سرور اجرا می‌شود؟

❓ س: آیا این سرویس برای محیط Production مناسب است؟

🤝 مشارکت در توسعه

📝 نحوه مشارکت:

🐛 گزارش باگ:

👨‍💻 نویسنده

🙏 تشکر و قدردانی

❓ س: در سرور ایران ارور `Recv failure: Connection was reset` می‌گیرم!

❓ س: ارور `Execution context was destroyed` در سرور خارج اتفاق می‌افتد.

Packages