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

الخطوة الأولى

من الصفر إلى أول رسالة

ابدأ بالبيانات المرسلة إليك عند تفعيل خدمة الـ API.

01
جهّز بيانات الربط
عنوان الخدمة BASE_URL، واسم الجلسة SESSION، ومفتاح API_KEY المرسل إليك.
02
اربط رقمك
ابدأ الجلسة، ثم امسح QR عند طلبه وانتظر حتى تصبح الحالة WORKING.
03
أرسل أول رسالة
استخدم مثال الإرسال مع رقم اختبار تملكه، ثم أضف الربط إلى تطبيقك.

عنوان الخدمة BASE URLhttps://waha.whats-flow.netHTTPS

استخدم عنوان الخدمة أعلاه مباشرة، واسم الجلسة والمفتاح المرسلين عند التفعيل. استبدل default باسم جلستك والقيم YOUR_… و.example ببياناتك. v2 هو إصدار الدليل؛ الطلبات تبدأ بـ /api ولا تُضاف إليها /docs/v2 أو /dashboard.

export BASE_URL="https://waha.whats-flow.net"
export SESSION="default"
export API_KEY="YOUR_API_KEY"

نفّذ إعداد المتغيرات مرة واحدة في جلسة الطرفية قبل أمثلة cURL. في تطبيقك، احفظ القيم ضمن إعدادات الخادم.

اتصال موثّق

مفتاح واحد لطلباتك

أرسل مفتاح حسابك في ترويسة X-Api-Key مع كل طلب. أرسل جسم الطلب بصيغة JSON عند إرسال الرسائل أو تعديل الإعدادات.

الترويسة	القيمة	الاستخدام
`X-Api-Key`	`YOUR_API_KEY`	مطلوبة لكل الطلبات
`Content-Type`	`application/json`	مع جسم الطلب JSON
`Accept`	`application/json`	لطلب استجابة JSON، بما فيها صورة QR المشفرة.

مفتاحك يظل على الخادم.

نفّذ الطلبات من الخادم، ولا تضع المفتاح في المتصفح أو مستودع عام. {session} في المسار وsession في جسم الطلب هما اسم الجلسة المخصص لحسابك، وليس رقم الهاتف.

الاتصال

بدء الجلسة#

ابدأ الجلسة التي جهّزها فريق Whatsflow لحسابك. يجب أن تكون موجودة بالفعل؛ هذا الطلب لا ينشئ جلسة جديدة.

POST/api/sessions/{session}/startAPI KEY

بيانات الطلب

sessionpath · stringمطلوب

اسم الجلسة المرسل عند التفعيل؛ استبدل default باسم جلستك.

هذا الطلب لا يحتاج إلى جسم (Body).

استخدم اسم الجلسة المرسل عند التفعيل بدلًا من default. بعد البدء، راقب حالة الجلسة؛ اطلب QR عندما تصبح SCAN_QR_CODE، وأرسل الرسائل فقط عند WORKING.

curl --request POST "${BASE_URL}/api/sessions/${SESSION}/start" \
  --header "X-Api-Key: ${API_KEY}" \
  --header "Accept: application/json"

مثال استجابة مختصر201

{
    "name": "default",
    "status": "STARTING"
}

الاتصال

ربط رقم واتساب#

عندما تكون الجلسة في حالة SCAN_QR_CODE، اطلب صورة الرمز وامسحها من واتساب ← الأجهزة المرتبطة ← ربط جهاز.

GET/api/{session}/auth/qrAPI KEY

بيانات الطلب

sessionpath · stringمطلوب

اسم الجلسة المرسل عند التفعيل؛ استبدل default باسم جلستك.

هذا الطلب لا يحتاج إلى جسم (Body).

أرسل Accept: application/json للحصول على الصورة بصيغة Base64؛ بدونها قد تكون الاستجابة صورة ثنائية. اعرض الصورة باستخدام data:image/png;base64, متبوعة بقيمة data. المثال توضيحي وليس رمزًا صالحًا للمسح.

curl --request GET "${BASE_URL}/api/${SESSION}/auth/qr" \
  --header "X-Api-Key: ${API_KEY}" \
  --header "Accept: application/json"

مثال استجابة مختصر200

{
    "mimetype": "image/png",
    "data": "BASE64_QR_IMAGE_DATA"
}

الاتصال

حالة الاتصال#

اقرأ status قبل الإرسال. WORKING تعني أن الجلسة متصلة. STARTING تعني بدء الاتصال، وSCAN_QR_CODE تعني انتظار مسح الرمز.

GET/api/sessions/{session}API KEY

بيانات الطلب

sessionpath · stringمطلوب

اسم الجلسة المرسل عند التفعيل؛ استبدل default باسم جلستك.

هذا الطلب لا يحتاج إلى جسم (Body).

STOPPED تعني أن الجلسة متوقفة؛ استخدم طلب البدء. FAILED تعني تعذر الاتصال؛ راجع الهاتف وتواصل مع الدعم إذا احتجت لإعادة الربط. الاستجابة مختصرة وقد تتضمن بيانات الحساب وإعدادات config.

curl --request GET "${BASE_URL}/api/sessions/${SESSION}" \
  --header "X-Api-Key: ${API_KEY}" \
  --header "Accept: application/json"

مثال استجابة مختصر200

{
    "name": "default",
    "status": "WORKING"
}

الرسائل

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

أرسل رسالة إلى chatId. للمحادثات الفردية، اكتب الرقم الدولي بأرقام فقط ثم أضف @c.us؛ مثل 201000000000@c.us.

POST/api/sendTextAPI KEY

بيانات الطلب

sessionstringمطلوب

اسم الجلسة المخصص لحسابك. default قيمة توضيحية.

chatIdstringمطلوب

معرّف المحادثة؛ رقم دولي متبوع بـ @c.us للمحادثات الفردية.

textstringمطلوب

نص الرسالة المراد إرساله.

linkPreviewbooleanاختياري

تفعيل معاينة الروابط داخل الرسالة.

reply_tostringاختياري

معرّف رسالة سابقة للرد عليها؛ استخدم المعرّف كما أعادته الخدمة.

احفظ id كما هو لتتبع الرسالة أو الرد عليها. الاستجابة مختصرة، ونجاح الطلب لا يؤكد وصول الرسالة؛ راقب message.ack لمعرفة تحديثات التسليم والقراءة عند توفرها.

curl --request POST "${BASE_URL}/api/sendText" \
  --header "X-Api-Key: ${API_KEY}" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{
    "session": "${SESSION}",
    "chatId": "201000000000@c.us",
    "text": "مرحبًا أحمد، تم تأكيد طلبك #1042. شكرًا لاختيارك لنا!",
    "linkPreview": false
}
JSON

// Node.js 18+ · server-side
const baseUrl = process.env.BASE_URL.replace(/\/$/, "");

const response = await fetch(`${baseUrl}/api/sendText`, {
  method: "POST",
  headers: {
    "X-Api-Key": process.env.API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    session: process.env.SESSION,
    chatId: "201000000000@c.us",
    text: "مرحبًا أحمد، تم تأكيد طلبك #1042.",
    linkPreview: false
  })
});

if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}
const message = await response.json();
console.log(message.id);

استخدم متغيرات البيئة الموضحة في البداية السريعة. المثال يعمل على الخادم.

use Illuminate\Support\Facades\Http;

$baseUrl = rtrim(config('services.whatsflow_v2.url'), '/');

$message = Http::withHeaders([
    'X-Api-Key' => config('services.whatsflow_v2.key'),
])->timeout(30)->post("{$baseUrl}/api/sendText", [
    'session' => config('services.whatsflow_v2.session'),
    'chatId' => '201000000000@c.us',
    'text' => 'مرحبًا أحمد، تم تأكيد طلبك #1042.',
    'linkPreview' => false,
])->throw()->json();

$messageId = $message['id'];

أضف url وsession وkey داخل services.whatsflow_v2 في config/services.php، واقرأ قيمها من متغيرات البيئة.

مثال استجابة مختصر201

{
    "id": "true_201000000000@c.us_EXAMPLE_MESSAGE_ID",
    "fromMe": true,
    "to": "201000000000@c.us"
}

الرسائل

إرسال صورة#

أرسل صورة مع وصف اختياري باستخدام رابط مباشر للملف. يتطلب هذا الطلب تفعيل إرسال الوسائط على حسابك.

POST/api/sendImageAPI KEY

بيانات الطلب

sessionstringمطلوب

اسم الجلسة المخصص لحسابك. default قيمة توضيحية.

chatIdstringمطلوب

معرّف المحادثة؛ رقم دولي متبوع بـ @c.us للمحادثات الفردية.

file.urlstringمطلوب

رابط مباشر يمكن للخدمة تحميل الملف منه؛ استبدل عنوان .example.

file.mimetypestringمطلوب

نوع MIME المطابق للملف، مثل image/jpeg أو application/pdf.

captionstringاختياري

وصف أو نص مرافق للملف.

إرسال الوسائط يعتمد على الميزات المفعّلة لحسابك؛ تواصل مع الفريق إذا لم يكن متاحًا. لا ترسل رابط صفحة HTML أو ملف يحتاج تسجيل دخول. حدود الحجم تعتمد على إعدادات الخدمة.

curl --request POST "${BASE_URL}/api/sendImage" \
  --header "X-Api-Key: ${API_KEY}" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{
    "session": "${SESSION}",
    "chatId": "201000000000@c.us",
    "file": {
        "mimetype": "image/jpeg",
        "url": "https://your-store.example/products/item.jpg"
    },
    "caption": "صورة المنتج الذي طلبته"
}
JSON

مثال استجابة مختصر201

{
    "id": "true_201000000000@c.us_EXAMPLE_IMAGE_ID",
    "fromMe": true,
    "hasMedia": true
}

الرسائل

إرسال مستند#

شارك فاتورة PDF أو مستندًا من رابط مباشر. ضع نوع الملف واسمه داخل file. يتطلب هذا الطلب تفعيل إرسال الوسائط على حسابك.

POST/api/sendFileAPI KEY

بيانات الطلب

sessionstringمطلوب

اسم الجلسة المخصص لحسابك. default قيمة توضيحية.

chatIdstringمطلوب

معرّف المحادثة؛ رقم دولي متبوع بـ @c.us للمحادثات الفردية.

file.urlstringمطلوب

رابط مباشر يمكن للخدمة تحميل الملف منه؛ استبدل عنوان .example.

file.mimetypestringمطلوب

نوع MIME المطابق للملف، مثل image/jpeg أو application/pdf.

file.filenamestringاختياري

اسم الملف المعروض للمستلم، مثل invoice-1042.pdf.

captionstringاختياري

وصف أو نص مرافق للملف.

المثال يستخدم file.url. لإرسال المحتوى مباشرة، استبدل url بحقل file.data يحتوي على Base64، مع الإبقاء على mimetype وfilename. تواصل مع الفريق لتأكيد تفعيل الوسائط وحدود الملفات.

curl --request POST "${BASE_URL}/api/sendFile" \
  --header "X-Api-Key: ${API_KEY}" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{
    "session": "${SESSION}",
    "chatId": "201000000000@c.us",
    "file": {
        "mimetype": "application/pdf",
        "filename": "invoice-1042.pdf",
        "url": "https://your-store.example/invoices/1042.pdf"
    },
    "caption": "فاتورة طلبك #1042"
}
JSON

مثال استجابة مختصر201

{
    "id": "true_201000000000@c.us_EXAMPLE_FILE_ID",
    "fromMe": true,
    "hasMedia": true
}

الأحداث

استقبال الأحداث · Webhooks#

اضبط config.webhooks للجلسة لاستقبال الرسائل وحالة الاتصال على خادمك. استخرج الإعدادات الحالية من GET /api/sessions/{session} أولًا، واحتفظ بباقي قيم config عند التعديل.

PUT/api/sessions/{session}API KEY

بيانات الطلب

sessionpath · stringمطلوب

اسم الجلسة المرسل عند التفعيل؛ استبدل default باسم جلستك.

config.webhooksarrayمطلوب

قائمة وجهات استقبال الأحداث؛ المثال يوضح وجهة واحدة.

config.webhooks[].urlstringمطلوب

رابط HTTPS على خادمك يقبل POST مع JSON.

config.webhooks[].eventsarrayمطلوب

الأحداث المطلوبة، مثل message وmessage.ack وsession.status.

config.webhooks[].customHeadersarrayاختياري

ترويسات للتحقق من مصدر الطلب، كل عنصر يحتوي name وvalue.

PUT يستبدل إعدادات config ويعيد تشغيل الجلسة إذا كانت تعمل؛ المثال يوضح webhooks فقط، فادمج باقي إعداداتك قبل تنفيذه. في خادم الاستقبال، تحقق من X-Webhook-Secret، ثم أعد 200 بسرعة وتجنب تكرار معالجة الحدث باستخدام id الخاص بالحدث.

curl --request PUT "${BASE_URL}/api/sessions/${SESSION}" \
  --header "X-Api-Key: ${API_KEY}" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{
    "config": {
        "webhooks": [
            {
                "url": "https://your-app.example/webhooks/whatsflow",
                "events": [
                    "message",
                    "message.ack",
                    "session.status"
                ],
                "customHeaders": [
                    {
                        "name": "X-Webhook-Secret",
                        "value": "YOUR_WEBHOOK_SECRET"
                    }
                ]
            }
        ]
    }
}
JSON

مثال استجابة مختصر200

{
    "name": "default",
    "status": "STARTING"
}

أهم الأحداث

الحدث عند الاشتراك	متى يصل؟
`message`	عند وصول رسالة جديدة؛ اقرأ `payload.from` و`payload.body` للرسائل النصية.
`message.ack`	عند تحديث حالة الرسالة؛ مثل `DEVICE` للتسليم أو `READ` للقراءة في `payload.ackName` عند توفرها.
`session.status`	عند تغيّر الاتصال؛ اقرأ الحالة من `payload.status`.

كيف يبدو حدث رسالة واردة؟

مثال مختصر لحدث message. يحتوي payload على بيانات الرسالة وتختلف بنيته حسب الحدث. معرّف الحدث id الخارجي يختلف عن معرّف الرسالة payload.id.

{
    "id": "evt_EXAMPLE_EVENT_ID",
    "event": "message",
    "session": "default",
    "payload": {
        "id": "false_201000000000@c.us_EXAMPLE_INCOMING_ID",
        "from": "201000000000@c.us",
        "fromMe": false,
        "body": "متى يصل طلبي؟",
        "hasMedia": false
    }
}

لربط أكثر استقرارًا

افهم الاستجابة، وحدد خطوتك التالية

افحص رمز HTTP ونص الخطأ معًا. قد تختلف تفاصيل الخطأ بحسب الطلب وإعدادات الخدمة.

الرمز	المعنى	ما الذي تراجعه؟
`200 / 201`	نجاح الطلب	اقرأ البيانات؛ نجاح طلب إرسال لا يؤكد التسليم.
`400`	بيانات غير صحيحة	راجع الحقول المطلوبة وصيغة الرقم ونوع الملف.
`401`	فشل المصادقة	تأكد من قيمة ترويسة `X-Api-Key`.
`403`	وصول غير مسموح	راجع صلاحية المفتاح للجلسة المطلوبة.
`404`	المورد غير موجود	تحقق من عنوان الخدمة، المسار، واسم الجلسة.
`422`	الجلسة غير جاهزة أو الطلب غير قابل للتنفيذ	راجع تفاصيل الخطأ وحالة الجلسة؛ إرسال الرسائل يحتاج `WORKING`.
`501`	الميزة غير متاحة	تواصل مع الفريق لتأكيد تفعيل الميزة المطلوبة على حسابك.
`429`	تجاوز معدل الطلبات، إن كان مفعّلًا	قلّل المعدل واحترم `Retry-After` إذا أعادته الخدمة.
`5xx`	خطأ في الخدمة	تحقق من الاتصال، واحتفظ بتفاصيل الطلب لإرسالها للدعم دون مفاتيح سرية.

إرسال منظم

استخدم طابورًا للرسائل والتزم بحدود حسابك. لا تكرر طلب إرسال تلقائيًا بعد انقطاع الرد؛ تحقق أولًا لتجنب إرسال الرسالة مرتين.

محادثات متوقعة

أرسل لمن وافق على التواصل معك، واحترم طلبات إيقاف الرسائل. ابدأ برقم اختبار قبل تشغيل الإرسال للعملاء.

دليل Whatsflow API.

من الصفر إلى أول رسالة

جهّز بيانات الربط

اربط رقمك

أرسل أول رسالة

مفتاح واحد لطلباتك

بدء الجلسة#

بيانات الطلب

ربط رقم واتساب#

بيانات الطلب

حالة الاتصال#

بيانات الطلب

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

بيانات الطلب

إرسال صورة#

بيانات الطلب

إرسال مستند#

بيانات الطلب

استقبال الأحداث · Webhooks#

بيانات الطلب

أهم الأحداث

افهم الاستجابة، وحدد خطوتك التالية

إرسال منظم

محادثات متوقعة

تطبيقك جاهز للخطوة التالية؟