توثيق API

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

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

Base URL: 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", "to": "966512345678", "message": "مرحبا!"}'

المصادقة

يتم التحقق من الهوية عبر مفتاح 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 الخاصة بحسابك.

Response:
json
{
  "success": true,
  "data": [
    {
      "name": "my-instance",
      "status": "open",
      "ownerJid": "966512345678@s.whatsapp.net",
      "profileName": "أحمد"
    }
  ]
}
POST/api/whatsapp/instances

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

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

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

Response:
json
{
  "success": true,
  "data": {
    "qrcode": "data:image/png;base64,...",
    "status": "connecting"
  }
}
POST/api/whatsapp/instances/:name/reconnect

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

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

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

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

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

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

POST/api/whatsapp/send

إرسال رسالة نصية إلى رقم واتساب.

Body:
json
{
  "instanceName": "my-instance",
  "to": "966512345678",
  "message": "مرحباً! هذه رسالة تجريبية 🎉"
}
Response:
json
{
  "success": true,
  "data": {
    "messageId": "msg_abc123",
    "status": "sent",
    "to": "966512345678@s.whatsapp.net"
  }
}
GET/api/whatsapp/messages?instance=my-instance&limit=20

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

Response:
json
{
  "success": true,
  "data": {
    "messages": [...],
    "total": 150,
    "page": 1
  }
}

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

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',
    to: '966512345678',
    message: 'مرحباً من Node.js!'
  })
});

const data = await response.json();
console.log(data);
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',
        'to': '966512345678',
        'message': 'مرحباً من Python!'
    }
)

print(response.json())
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',
        'to' => '966512345678',
        'message' => 'مرحباً من PHP!'
    ])
]);

$response = json_decode(curl_exec($ch));
curl_close($ch);

Webhooks

استقبل إشعارات فورية عند وصول رسائل جديدة أو تغيّر حالة الاتصال. حدد عنوان 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": "966512345678@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

جاهز للبدء؟

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