دليل المطورين
كل ما تحتاجه لدمج WhatsApp API في تطبيقاتك — من المصادقة إلى إرسال الرسائل.
https://whatsapilight.cloud/apiنظرة عامة
WA API هي منصة SaaS توفر واجهة برمجية RESTful لإرسال واستقبال رسائل WhatsApp. تعتمد على Evolution API وتدعم إدارة جلسات متعددة، إرسال رسائل نصية ووسائط، واستقبال إشعارات عبر Webhooks.
سريع
زمن استجابة أقل من 200ms
آمن
مصادقة عبر API Keys مع تشفير
سهل الدمج
RESTful API بتنسيق JSON
البداية السريعة
# 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 — لا تشاركه في الكود المصدري العام أو في المتصفح.
# أضف الترويسة التالية لكل طلب
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
- سجّل الدخول إلى لوحة التحكم
- انتقل إلى تبويب "مفاتيح API"
- انقر على "إنشاء مفتاح جديد"
- انسخ المفتاح واحفظه في مكان آمن
إدارة الجلسات
كل جلسة تمثل اتصال برقم WhatsApp واحد. يمكنك إنشاء وحذف وإعادة توصيل الجلسات عبر API.
/api/whatsapp/instancesاستعراض جميع جلسات WhatsApp الخاصة بحسابك.
{
"success": true,
"data": [
{
"name": "my-instance",
"status": "open",
"ownerJid": "966512345678@s.whatsapp.net",
"profileName": "أحمد"
}
]
}/api/whatsapp/instancesإنشاء جلسة WhatsApp جديدة.
{
"name": "my-instance",
"webhookUrl": "https://your-app.com/webhook" // اختياري
}{
"success": true,
"data": {
"name": "my-instance",
"status": "connecting",
"qrcode": "data:image/png;base64,..."
}
}/api/whatsapp/instances/:name/qrcodeالحصول على رمز QR للمسح والاتصال بـ WhatsApp.
{
"success": true,
"data": {
"qrcode": "data:image/png;base64,...",
"status": "connecting"
}
}/api/whatsapp/instances/:name/reconnectإعادة توصيل جلسة WhatsApp غير متصلة.
{
"success": true,
"message": "تم إعادة التوصيل"
}/api/whatsapp/instances/:nameحذف جلسة WhatsApp نهائياً.
{
"success": true,
"message": "تم حذف الجلسة"
}إرسال الرسائل
أرسل رسائل نصية عبر جلسة WhatsApp متصلة. يجب أن يكون الرقم بالصيغة الدولية بدون + أو 00.
/api/whatsapp/sendإرسال رسالة نصية إلى رقم واتساب.
{
"instanceName": "my-instance",
"to": "966512345678",
"message": "مرحباً! هذه رسالة تجريبية 🎉"
}{
"success": true,
"data": {
"messageId": "msg_abc123",
"status": "sent",
"to": "966512345678@s.whatsapp.net"
}
}/api/whatsapp/messages?instance=my-instance&limit=20استعراض سجل الرسائل المرسلة والمستلمة.
{
"success": true,
"data": {
"messages": [...],
"total": 150,
"page": 1
}
}أمثلة بلغات مختلفة
// 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
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
$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 | تحديث حالة الرسالة (تم التسليم، تم القراءة) |
// مثال 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 | خطأ في السيرفر | تواصل مع الدعم الفني |
// مثال استجابة خطأ
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "مفتاح API غير صالح أو منتهي الصلاحية"
}
}المكتبات و SDK
يمكنك استخدام أي مكتبة HTTP للتواصل مع API. إليك أمثلة سريعة:
JavaScript
fetch() / axios
Python
requests / httpx
PHP
curl / Guzzle
جاهز للبدء؟
أنشئ حسابك المجاني وابدأ بإرسال رسائل واتساب خلال دقائق