تعرف على كيفية إعداد الويب هوك (Webhooks) في Wawp للاستماع لأحداث واتساب اللحظية، والاستفادة من مراقب أحداث النظام لاستكشاف الأخطاء، مع أمثلة عملية لمنصات Zapier و n8n و Make و Pipedream.
6 دقائق للقراءة·تم التحديث في ١٨ يونيو ٢٠٢٦
مقدمة عن الويب هوك (Webhooks)
الويب هوك (Webhook) هو آلية لإرسال رسائل أو بيانات فورية وتلقائية من Wawp إلى خوادمك الخاصة أو التطبيقات الخارجية التي تستخدمها بمجرد وقوع حدث ما. بدلاً من قيام خادمك بفحص الـ API الخاص بـ Wawp بشكل مستمر وطلب البيانات (وهو ما يستهلك موارد الخادم ويتسبب في تأخير وصول البيانات)، تقوم منصة Wawp بإرسال البيانات فوراً إلى رابط URL محدد تقوم بتعيينه مسبقاً.
على سبيل المثال، بمجرد أن يقوم عميل بإرسال رسالة واتساب إلى رقمك، تلتقط Wawp هذا الحدث في نفس اللحظة وترسل طلباً من نوع HTTP POST يحتوي على بيانات الرسالة مباشرة إلى رابط الويب هوك الخاص بك.
ما هو مراقب أحداث النظام (System Event Monitor)؟
مراقب أحداث النظام هو لوحة تحكم مدمجة في Wawp مخصصة لتسجيل وتشخيص الاتصالات والأحداث الصادرة من حسابك. يعمل مثل "الصندوق الأسود" لتسجيل حركة الويب هوك وتدفق البيانات.
الفوائد الرئيسية لمراقب الأحداث:
شفافية لحظية: تتبع عمليات إرسال الويب هوك فور حدوثها، مع عرض رابط الاستلام المستهدف، وتاريخ الإرسال، وسرعة الاستجابة.
تتبع الأخطاء وأكواد الاستجابة: يتيح لك معرفة ما إذا كانت خوادم الاستلام لديك تفشل في معالجة الطلبات (مثل إرجاع خطأ 500 Internal Server Error أو 404 Not Found).
فحص هيكل البيانات (Payload): يمكنك الاطلاع بدقة على ملف الـ JSON الذي تم إرساله بواسطة Wawp، ومراجعة تفاصيل الرد الذي أرجعه سيرفرك.
إعادة إرسال الأحداث الفاشلة (Retry): في حال تعطل خادم الاستقبال لديك مؤقتاً، فلن تفقد رسائلك؛ حيث يتيح لك مراقب الأحداث إعادة إرسال الويب هوك الفاشل بضغطة زر واحدة بمجرد عودة خادمك للعمل.
دورة حياة حالة الرسالة وفائدتها في التحليل
فهم وتتبع حالة كل رسالة يساعدك في مراقبة سلامة اتصالاتك البرمجية مع عملائك:
❌ فشلت (Failed): لم يتم إرسال الرسالة بنجاح (على سبيل المثال: الرقم المستهدف غير مسجل في واتساب، أو هناك مشكلة في إعدادات الاتصال).
📩 وصلت (Delivered): وصلت الرسالة إلى هاتف المستلم (تظهر كعلامتي صح باللون الرمادي على واتساب).
👁️ قرئت (Read): قام المستلم بفتح وقراءة الرسالة (تظهر كعلامتي صح باللون الأزرق).
لماذا يعتبر تتبع هذه الحالات في غاية الأهمية لعملك؟
تحليلات التسليم والقراءة: معرفة نسب فتح وقراءة الرسائل بدقة لتقييم مدى تفاعل عملائك مع حملاتك الإعلانية أو التنبيهات.
تنظيف وتصفية قوائم الاتصال: التعرف الفوري على الأرقام غير الفعالة أو الخاطئة (التي تظهر بحالة Failed) وإزالتها تلقائياً لتوفير التكاليف وحماية الرقم من الحظر.
مسارات الأتمتة الذكية: يمكنك بناء منطق ذكي في n8n أو Zapier يعتمد على التفاعل. على سبيل المثال: يمكنك برمجة النظام لينتظر ساعتين ويرسل رسالة تذكيرية فقط إذا كانت حالة الرسالة الأولى وصلت (Delivered) ولكنها لم تصبح بعد قرئت (Read).
كيفية إعداد ويب هوك في منصة Wawp
اتبع هذه الخطوات البسيطة لربط أول مستمع للأحداث (Webhook Trigger):
1
الحصول على الرابط قم بإنشاء أو نسخ رابط الويب هوك (Webhook URL) من منصة الأتمتة التي تستخدمها (مثل n8n، أو Zapier، أو Make، أو خادمك الخاص).
2
التوجه للإعدادات سجل الدخول إلى لوحة تحكم Wawp، وافتح إعدادات جلسة الواتساب المستهدفة، ثم اختر تبويب Webhooks.
3
الحفظ والاشتراك أدخل رابط URL في المكان المخصص، وقم بتفعيل الأحداث التي ترغب في الاستماع إليها (مثل الرسائل المستلمة، وتغير حالة الاتصال للجلسة)، ثم انقر على "Save Configuration".
التوثيق البرمجي للويب هوك
🔗 للمزيد من المعلومات والتفاصيل البرمجية الشاملة حول هياكل البيانات وأحداث الويب هوك، راجع توثيق المطورين الخاص بنا: دليل الويب هوك
أمثلة عملية للربط والتكامل عبر المنصات المختلفة
يمكنك إعادة توجيه أحداث Wawp إلى أي نظام برمجي أو منصة أتمتة عبر الإنترنت. إليك طرق التهيئة لـ 5 من أشهر المنصات:
1. تكامل n8n (يوصى به بشدة)
تعد منصة n8n أداة قوية لأتمتة سير العمل وتتكامل بشكل مثالي مع Wawp.
مشغل الأحداث: في n8n، يمكنك تثبيت العقدة الرسمية للمجتمع من خلال تنزيل حزمة @wawp/n8n-nodes-wawp.
المشغل: أنشئ سير عمل جديد، واختر "HTTP / Webhook" كمصدر للأحداث، وحدد استقبال طلبات HTTP POST.
الإعداد: ستوفر لك Pipedream رابط استقبال. انسخه والصقه في Wawp. يمكنك كتابة أكواد برمجية بلغة Node.js أو Python لمعالجة وفحص النص الوارد فوراً.
مثال للرابط:https://eoxxx12345.m.pipedream.net
5. خادم خاص (Node.js Express / Webhook.site)
للتطوير البرمجي المخصص، يمكنك بناء خادم محلي لاستقبال طلبات الويب هوك، أو استخدام خدمة Webhook.site للاختبار الفوري السريع.
مثال برمجى بلغة Node.js (Express):
مثال خادم Express (Node.js)
1const express = require('express');
2const app = express();
3app.use(express.json());
4
5app.post('/whatsapp-webhook', (req, res) => {
6const { event, data } = req.body;
7 console.log(`Received event: ${event}`);
8 console.log(`Message: ${data.body} from ${data.from}`);
9 res.status(200).send('Event processed');
10});
11
12app.listen(3000, () => console.log('Webhook server listening on port 3000'));
javascript sample
Ln 12, Col 1
الأحداث المدعومة وبنية البيانات المرسلة (Payload)
ترسل منصة Wawp بيانات أحداث محددة بناءً على الإجراءات الجارية. إليك أبرز الأحداث التي يمكنك الاشتراك بها وفهم تفاصيلها:
1. استقبال رسالة جديدة (message)
يتم إطلاق هذا الحدث فوراً عندما يقوم جهة اتصال بإرسال رسالة نصية، صورة، ملف، أو صوت إلى رقم الواتساب المربوط بحسابك.
التأثير: تفعيل الردود الآلية للبوت، تسجيل المحادثة في نظام إدارة علاقات العملاء (CRM)، أو تنبيه فريق المبيعات والدعم.
مثال لهيكل البيانات:
بيانات حدث استقبال رسالة جديدة
1{
2"event": "message",
3"instanceId": "wawp-instance-5582",
4"timestamp": 1781752669,
5"data": {
6"id": "true_1234567890@c.us_ABCDE12345",
7"from": "1234567890@c.us",
8"to": "0987654321@c.us",
9"body": "مرحباً Wawp! أريد الاستفسار عن طلبي.",
10"type": "chat",
11"fromMe": false
12 }
13}
json sample
Ln 13, Col 1
2. تغير حالة الجلسة (session.status)
يتم إطلاق هذا الحدث عند حدوث أي تغير في حالة الاتصال لجهازك (مثل تسجيل خروج، فقدان الإنترنت، أو بدء التشغيل).
التأثير: إرسال إشعارات طوارئ للمطورين أو تعديل مؤشر الاتصال داخل نظامك الخاص لإظهار حالة الجلسة.
مثال لهيكل البيانات:
بيانات حدث تغير حالة الاتصال للجلسة
1{
2"event": "session.status",
3"instanceId": "wawp-instance-5582",
4"timestamp": 1781753000,
5"data": {
6"status": "DISCONNECTED",
7"reason": "Device logged out by phone",
8"timestamp": "2026-06-18T05:20:00.000Z"
9 }
10}
json sample
Ln 10, Col 1
3. توليد رمز QR جديد (session.qr)
يتم إطلاقه عندما يولد الخادم رمز استجابة سريعة (QR Code) جديداً للتطبيق السحابي الخاص بجهازك.
التأثير: إرسال رمز الـ QR مباشرة إلى واجهة برمجية مخصصة أو نظام خارجي، مما يسمح للموظفين أو العملاء بمسح الرمز وتفعيل الرقم دون الدخول للوحة تحكم Wawp.
مثال لهيكل البيانات:
بيانات حدث توليد رمز QR جديد
1{
2"event": "session.qr",
3"instanceId": "wawp-instance-5582",
4"timestamp": 1781753100,
5"data": {
6"qr": "1@aBcdEfGh...IjKlMnOpQr",
7"timeoutMs": 20000
8 }
9}
json sample
Ln 9, Col 1
من خلال الاشتراك في هذه الأحداث، ستمتلك تحكماً برمجياً كاملاً وشاملاً لقناة تواصل الواتساب الخاصة بنشاطك التجاري، مما يفتح آفاقاً واسعة من عمليات الأتمتة المبتكرة والسريعة.
