Skip to content
توثيق API

دليل المطورين

كل ما تحتاجه لدمج WhatsApp API في تطبيقاتك — من المصادقة إلى إرسال الرسائل.

الرابط الأساسي: https://whatsapilight.cloud/api

نظرة عامة

WA API هي منصة SaaS توفر واجهة برمجية RESTful لإرسال واستقبال رسائل WhatsApp. تعتمد على Evolution API وتدعم إدارة جلسات متعددة، إرسال رسائل نصية ووسائط، واستقبال إشعارات عبر Webhooks.

سريع

زمن استجابة أقل من 200ms

آمن

مصادقة عبر API Keys مع تشفير

سهل الدمج

RESTful API بتنسيق JSON

البداية السريعة

bash
# 1. احصل على مفتاح API من لوحة التحكم
# 2. أنشئ جلسة واتساب
curl -X POST https://whatsapilight.cloud/api/whatsapp/instances \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-instance"}'

# 3. امسح رمز QR للاتصال
# 4. أرسل رسالة
curl -X POST https://whatsapilight.cloud/api/whatsapp/send \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instanceName": "my-instance", "phone": "12025550123", "purpose": "otp", "message": "رمز التحقق: 123456"}'

المصادقة

يتم التحقق من الهوية عبر مفتاح API يُرسل في ترويسة الطلب. يمكنك إنشاء مفاتيح API من لوحة التحكم.

⚠️ حافظ على سرية مفتاح API — لا تشاركه في الكود المصدري العام أو في المتصفح.

http
# أضف الترويسة التالية لكل طلب
x-api-key: sk_live_xxxxxxxxxxxxxx

# مثال كامل
GET /api/whatsapp/instances HTTP/1.1
Host: whatsapilight.cloud
x-api-key: sk_live_xxxxxxxxxxxxxx
Content-Type: application/json

إنشاء مفتاح API

  1. سجّل الدخول إلى لوحة التحكم
  2. انتقل إلى تبويب "مفاتيح API"
  3. انقر على "إنشاء مفتاح جديد"
  4. انسخ المفتاح واحفظه في مكان آمن

إدارة الجلسات

كل جلسة تمثل اتصال برقم WhatsApp واحد. يمكنك إنشاء وحذف وإعادة توصيل الجلسات عبر API.

GET/api/whatsapp/instances

استعراض جميع جلسات WhatsApp الخاصة بحسابك.

الاستجابة:
json
{
  "success": true,
  "data": [
    {
      "name": "my-instance",
      "status": "open",
      "ownerJid": "12025550123@s.whatsapp.net",
      "profileName": "John"
    }
  ]
}
POST/api/whatsapp/instances

إنشاء جلسة WhatsApp جديدة.

الطلب:
json
{
  "name": "my-instance",
  "webhookUrl": "https://your-app.com/webhook"  // اختياري
}
الاستجابة:
json
{
  "success": true,
  "data": {
    "name": "my-instance",
    "status": "connecting",
    "qrcode": "data:image/png;base64,..."
  }
}
GET/api/whatsapp/instances/:name/qrcode

الحصول على رمز QR للمسح والاتصال بـ WhatsApp.

الاستجابة:
json
{
  "success": true,
  "data": {
    "qrcode": "data:image/png;base64,...",
    "status": "connecting"
  }
}
POST/api/whatsapp/instances/:name/reconnect

إعادة توصيل جلسة WhatsApp غير متصلة.

الاستجابة:
json
{
  "success": true,
  "message": "تمت إعادة التوصيل"
}
DELETE/api/whatsapp/instances/:name

حذف جلسة WhatsApp نهائياً.

الاستجابة:
json
{
  "success": true,
  "message": "تم حذف الجلسة"
}

إرسال الرسائل

أرسل رسائل نصية عبر جلسة WhatsApp متصلة. يجب أن يكون الرقم بالصيغة الدولية بدون + أو 00.

POST/api/whatsapp/send

إرسال رسالة نصية أو OTP أو إشعار تشغيلي عبر نفس الواجهة. استخدم purpose لضبط السياسات وتقليل مخاطر الحظر.

الطلب:
json
{
  "instanceName": "my-instance",
  "phone": "12025550123",
  "purpose": "otp",
  "message": "رمز التحقق: 485923"
}
الاستجابة:
json
{
  "success": true,
  "data": {
    "messageId": "msg_abc123",
    "status": "sent",
    "to": "12025550123@s.whatsapp.net"
  }
}
GET/api/whatsapp/messages?instance=my-instance&limit=20

استعراض سجل الرسائل المرسلة والمستلمة.

الاستجابة:
json
{
  "success": true,
  "data": {
    "messages": [...],
    "total": 150,
    "page": 1
  }
}

عقد الإرسال الاحترافي (Purpose + Headers)

هذه القواعد مهمة لعملاء API الحاليين: نفس الواجهة، لكن بسلوك أوضح وأكثر أمانًا. لا يوجد كسر للتكاملات الحالية.

purposeالاستخدامالسلوك
otpرموز التحققيسمح لأول إرسال مع حماية معدل صارمة لكل رقم.
transactionalإشعارات تشغيليةمناسب للفواتير والحالة والشحن مع حدود وقائية.
defaultرسائل عامةتطبيق سياسة الموافقة + نافذة 24 ساعة + Template خارج النافذة.

ترويسات التشخيص

http
X-Message-Purpose: otp | transactional | default
X-Message-Purpose-Mode: explicit | inferred | default

قاعدة إعادة المحاولة

text
OTP_RATE_LIMIT -> retry after 60-120s
TRANSACTIONAL_RATE_LIMIT -> retry after 5-15m
TENANT_SEND_PAUSED -> use retryAfterSec if provided

أمثلة بلغات مختلفة

javascript
// Node.js / JavaScript
const response = await fetch('https://whatsapilight.cloud/api/whatsapp/send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'sk_live_xxxxxxxxxxxxxx'
  },
  body: JSON.stringify({
    instanceName: 'my-instance',
    phone: '12025550123',
    purpose: 'transactional',
    message: 'تم تحديث حالة طلبك إلى: قيد الشحن'
  })
});

const data = await response.json();
const purpose = response.headers.get('X-Message-Purpose');
const mode = response.headers.get('X-Message-Purpose-Mode');
console.log({ data, purpose, mode });
python
# Python
import requests

response = requests.post(
    'https://whatsapilight.cloud/api/whatsapp/send',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'sk_live_xxxxxxxxxxxxxx'
    },
    json={
        'instanceName': 'my-instance',
      'phone': '12025550123',
      'purpose': 'otp',
      'message': 'رمز التحقق: 748392'
    }
)

  print(response.json())
  print(response.headers.get('X-Message-Purpose'))
php
// PHP
$ch = curl_init('https://whatsapilight.cloud/api/whatsapp/send');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'x-api-key: sk_live_xxxxxxxxxxxxxx'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'instanceName' => 'my-instance',
        'phone' => '12025550123',
        'purpose' => 'transactional',
      'message' => 'تم إنشاء فاتورتك بنجاح'
    ])
]);

$raw = curl_exec($ch);
$response = json_decode($raw, true);
curl_close($ch);

الرسائل التفاعلية

أرسل رسائل تفاعلية مع أزرار، قوائم، استطلاعات، مواقع، وجهات اتصال. جميعها عبر نفس النقطة /api/whatsapp/send مع تحديد النوع.

رسالة بأزرار

POST/api/whatsapp/send

إرسال رسالة مع أزرار تفاعلية (حتى 3 أزرار)

الطلب:
json
{
  "instanceName": "my-instance",
  "to": "12025550123",
  "type": "buttons",
  "message": "اختر أحد الخيارات التالية:",
  "buttons": [
    { "id": "btn_1", "text": "عروض اليوم" },
    { "id": "btn_2", "text": "تواصل مع الدعم" },
    { "id": "btn_3", "text": "معلومات الحساب" }
  ],
  "footer": "WhatsApp API Service"
}
الاستجابة:
json
{
  "success": true,
  "data": {
    "messageId": "msg_xyz789",
    "status": "sent"
  }
}

رسالة قائمة

POST/api/whatsapp/send

إرسال قائمة تفاعلية مع أقسام وعناصر متعددة

الطلب:
json
{
  "instanceName": "my-instance",
  "to": "12025550123",
  "type": "list",
  "message": "مرحبًا! اختر من القائمة:",
  "listTitle": "القائمة",
  "sections": [
    {
      "title": "المنتجات",
      "rows": [
        { "id": "p1", "title": "منتج 1", "description": "وصف المنتج الأول" },
        { "id": "p2", "title": "منتج 2", "description": "وصف المنتج الثاني" }
      ]
    },
    {
      "title": "الخدمات",
      "rows": [
        { "id": "s1", "title": "خدمة 1", "description": "وصف الخدمة" }
      ]
    }
  ],
  "footer": "اختر لمعرفة المزيد"
}

استطلاع رأي

POST/api/whatsapp/send

إرسال استطلاع رأي (حتى 12 خيارًا)

الطلب:
json
{
  "instanceName": "my-instance",
  "to": "12025550123",
  "type": "poll",
  "pollTitle": "ما هو يومك المفضل للتوصيل؟",
  "pollOptions": ["السبت", "الأحد", "الاثنين", "الثلاثاء"],
  "pollMultiSelect": false
}

إرسال موقع

POST/api/whatsapp/send

إرسال موقع جغرافي مع اسم وعنوان

الطلب:
json
{
  "instanceName": "my-instance",
  "to": "12025550123",
  "type": "location",
  "latitude": 40.7128,
  "longitude": -74.0060,
  "locationName": "نيويورك",
  "locationAddress": "New York, United States"
}

إرسال جهة اتصال

POST/api/whatsapp/send

إرسال بطاقة جهة اتصال

الطلب:
json
{
  "instanceName": "my-instance",
  "to": "12025550123",
  "type": "contact",
  "contactName": "John Smith",
  "contactPhone": "12025550199"
}

إرسال وسائط

POST/api/whatsapp/send

إرسال صورة أو فيديو أو مستند أو تسجيل صوتي

الطلب:
json
{
  "instanceName": "my-instance",
  "to": "12025550123",
  "type": "media",
  "mediaUrl": "https://example.com/image.jpg",
  "mediaType": "image",  // image | video | audio | document
  "caption": "صورة المنتج الجديد"
}

أنواع الرسائل المدعومة

النوعالقيمةالوصف
texttype: "text"رسالة نصية عادية
mediatype: "media"صورة / فيديو / صوت / مستند
buttonstype: "buttons"رسالة مع أزرار تفاعلية
listtype: "list"قائمة تفاعلية بأقسام
polltype: "poll"استطلاع رأي
locationtype: "location"موقع جغرافي
contacttype: "contact"بطاقة جهة اتصال

القوالب

أنشئ قوالب رسائل قابلة لإعادة الاستخدام مع متغيرات ديناميكية. يمكنك استخدامها في الرسائل الجماعية أو إرسالها مباشرة.

GET/api/whatsapp/templates

استرجاع جميع القوالب مع فلترة وبحث

الاستجابة:
json
{
  "success": true,
  "data": [
    {
      "id": "tpl_abc123",
      "name": "welcome_message",
      "category": "marketing",
      "messageType": "text",
      "content": "مرحبًا {{name}}! شكرًا لتسجيلك...",
      "variables": ["name"],
      "usageCount": 150
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 5 }
}
POST/api/whatsapp/templates

إنشاء قالب رسالة جديد

الطلب:
json
{
  "name": "order_confirmation",
  "category": "transactional",
  "messageType": "buttons",
  "content": "مرحبًا {{name}}، تم تأكيد طلبك #{{orderId}}",
  "buttons": [
    { "id": "track", "text": "تتبع الطلب" },
    { "id": "support", "text": "تواصل مع الدعم" }
  ],
  "footer": "شكرًا لتسوقك معنا",
  "variables": ["name", "orderId"]
}
الاستجابة:
json
{
  "success": true,
  "data": {
    "id": "tpl_xyz789",
    "name": "order_confirmation",
    "category": "transactional",
    "messageType": "buttons"
  }
}
GET/api/whatsapp/templates/:id

استرجاع تفاصيل قالب محدد

الاستجابة:
json
{
  "success": true,
  "data": {
    "id": "tpl_abc123",
    "name": "welcome_message",
    "content": "مرحبًا {{name}}! ...",
    "messageType": "text",
    "category": "marketing",
    "variables": ["name"],
    "usageCount": 150,
    "createdAt": "2024-01-15T10:30:00Z"
  }
}
PUT/api/whatsapp/templates/:id

تحديث قالب موجود

الطلب:
json
{
  "content": "مرحبًا {{name}}! عروضنا الجديدة:",
  "buttons": [
    { "id": "offers", "text": "عرض العروض" }
  ]
}
DELETE/api/whatsapp/templates/:id

حذف قالب

الاستجابة:
json
{
  "success": true,
  "message": "Template deleted"
}
POST/api/whatsapp/templates/:id/send

إرسال قالب مباشرة إلى رقم محدد مع استبدال المتغيرات

الطلب:
json
{
  "instanceName": "my-instance",
  "to": "12025550123",
  "variables": {
    "name": "John",
    "orderId": "12345"
  }
}

استخدم {{name}} و {{phone}} كمتغيرات ديناميكية في محتوى القالب. يتم استبدالها تلقائيًا عند الإرسال.

الرسائل الجماعية (Broadcast)

أنشئ حملات رسائل جماعية لإرسال رسائل لعدة مستلمين دفعة واحدة. يدعم جميع أنواع الرسائل مع نظام إرسال ذكي لمنع الحظر.

GET/api/whatsapp/broadcasts

استرجاع جميع حملات الرسائل الجماعية

الاستجابة:
json
{
  "success": true,
  "data": [
    {
      "id": "bc_abc123",
      "name": "حملة العروض الموسمية",
      "status": "completed",
      "instanceName": "my-instance",
      "totalRecipients": 500,
      "sentCount": 498,
      "failedCount": 2,
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ]
}
POST/api/whatsapp/broadcasts

إنشاء حملة رسائل جماعية جديدة

الطلب:
json
{
  "name": "حملة العروض",
  "instanceName": "my-instance",
  "message": "مرحبًا! لدينا عروض حصرية اليوم.",
  "messageType": "buttons",
  "recipients": ["12025550123", "12025550199", "12025550000"],
  "buttons": [
    { "id": "view", "text": "عرض العروض" },
    { "id": "ignore", "text": "لاحقًا" }
  ],
  "footer": "WhatsApp API",
  "scheduledAt": "2024-03-15T09:00:00Z"  // اختياري - للجدولة
}
الاستجابة:
json
{
  "success": true,
  "data": {
    "id": "bc_xyz789",
    "name": "حملة العروض",
    "status": "draft",
    "totalRecipients": 3
  }
}
POST/api/whatsapp/broadcasts/:id/send

بدء إرسال حملة (يستخدم نظام الإرسال الذكي لمنع الحظر)

الاستجابة:
json
{
  "success": true,
  "message": "Campaign started",
  "data": {
    "id": "bc_xyz789",
    "status": "sending",
    "totalRecipients": 500
  }
}
DELETE/api/whatsapp/broadcasts/:id

حذف حملة رسائل جماعية

الاستجابة:
json
{
  "success": true,
  "message": "Broadcast deleted"
}

مثال كامل: إنشاء وإرسال حملة

javascript
// 1. Create the broadcast campaign
const campaign = await fetch('https://whatsapilight.cloud/api/whatsapp/broadcasts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'sk_live_xxxxxxxxxxxxxx'
  },
  body: JSON.stringify({
    name: 'Ramadan Offers',
    instanceName: 'my-instance',
    message: 'مرحبًا {{name}}! عروض اليوم المميزة.',
    messageType: 'buttons',
    recipients: ['12025550123', '12025550199'],
    buttons: [
      { id: 'view', text: 'عرض العروض' },
      { id: 'later', text: 'لاحقًا' }
    ]
  })
});
const { data } = await campaign.json();

// 2. Start sending (anti-ban system activates automatically)
await fetch(`https://whatsapilight.cloud/api/whatsapp/broadcasts/${data.id}/send`, {
  method: 'POST',
  headers: { 'x-api-key': 'sk_live_xxxxxxxxxxxxxx' }
});

الحماية من الحظر (Anti-Ban)

نظام إرسال ذكي مدمج يحاكي السلوك البشري لحماية حسابك من الحظر عند إرسال الرسائل الجماعية.

تأخير ذكي

تأخير 2-45 ثانية بين كل رسالة مع عشوائية ±1.5 ثانية لمحاكاة السلوك الطبيعي

إرسال بالدفعات

كل 8 رسائل يتوقف 5 ثوانٍ، وكل 30 رسالة يتوقف 15 ثانية

استراحات طويلة

كل 100 رسالة يأخذ استراحة 60 ثانية تحاكي الاستراحة البشرية

تكيف تلقائي

عند فشل الإرسال، يزيد التأخير تلقائيًا ويعيد المحاولة، وعند النجاح يقلل التأخير تدريجيًا

نصائح لتجنب الحظر

  • - لا ترسل أكثر من 500 رسالة في اليوم الواحد لحساب جديد
  • - ابدأ بعدد قليل (50-100) ثم زد تدريجيًا
  • - تأكد أن المحتوى ليس مكررًا تمامًا، استخدم المتغيرات {{name}}
  • - لا ترسل في أوقات غير طبيعية (2-6 صباحًا)
  • - استخدم رقمًا تم تفعيله منذ فترة وليس رقمًا جديدًا

آلية الإرسال الذكي

المرحلةالتأخيرالوصف
بين كل رسالة2-45s + jitterتأخير أساسي مع عشوائية ±1.5 ثانية
كل 8 رسائل5sاستراحة بين الدفعات
كل 30 رسالة15sاستراحة متوسطة
كل 100 رسالة60sاستراحة طويلة (محاكاة بشرية)
عند الفشلx2 backoffيضاعف التأخير عند الخطأ ثم يعيد المحاولة

الويب هوكس

استقبل إشعارات فورية عند وصول رسائل جديدة أو تغيّر حالة الاتصال. حدد عنوان Webhook عند إنشاء الجلسة.

💡 يجب أن يكون عنوان Webhook متاح عبر HTTPS ويرد بـ 200 OK خلال 5 ثوانٍ.

أحداث Webhook

الحدثالوصف
messages.upsertرسالة جديدة مستلمة أو مرسلة
connection.updateتغيّر حالة الاتصال (متصل، غير متصل)
qrcode.updatedتم تحديث رمز QR
messages.updateتحديث حالة الرسالة (تم التسليم، تم القراءة)
json
// مثال payload للرسالة المستلمة
{
  "event": "messages.upsert",
  "instance": "my-instance",
  "data": {
    "key": {
      "remoteJid": "12025550123@s.whatsapp.net",
      "fromMe": false,
      "id": "3EB0..."
    },
    "message": {
      "conversation": "مرحبًا!"
    },
    "messageTimestamp": 1700000000
  }
}

رموز الأخطاء

جميع الاستجابات تتبع نفس التنسيق. في حالة الخطأ، ستحصل على كود HTTP مناسب مع رسالة توضيحية.

الكودالوصفالحل
400طلب غير صالحتحقق من البيانات المرسلة
401غير مصادقتحقق من مفتاح API
403غير مصرحتأكد من صلاحيات المفتاح
404غير موجودتحقق من اسم الجلسة أو المسار
429تجاوز الحدانتظر ثم أعد المحاولة
500خطأ في السيرفرتواصل مع الدعم الفني
json
// مثال استجابة خطأ
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "مفتاح API غير صالح أو منتهي الصلاحية"
  }
}

المكتبات و SDK

يمكنك استخدام أي مكتبة HTTP للتواصل مع API. إليك أمثلة سريعة:

JavaScript

fetch() / axios

Python

requests / httpx

PHP

curl / Guzzle

جاهز للبدء؟

أنشئ حسابك المجاني وابدأ بإرسال رسائل واتساب خلال دقائق