الـ Webhooks

رسالة واردة

يتم تفعيل هذا الحدث عند استلام رسالة جديدة بواسطة مثيل واتساب الخاص بك.

توصيات

  • أضف تأخيرات عشوائية بين الرسائل لمحاكاة السلوك البشري.

  • تحقق من أرقام الهواتف قبل الإرسال لضمان التسليم.

الوحدة الذرية للمحادثة: تحليل عميق لويب هوك الرسائل

في هندسة أي تطبيق محادثة، تعد الرسالة الواردة هي الوحدة الأساسية للقيمة. فهي الإشارة الرئيسية التي تطلق سير عمل الأعمال، وتفعل الذكاء الاصطناعي، وتقود تفاعل العملاء. يعد ويب هوك [message] الحدث الأكثر أهمية وتكراراً في منصة Wawp، حيث يعمل كجسر في الوقت الفعلي بين نية المستخدم واستجابة نظامك.

🏗️ الفلسفة المعمارية: تشريح "النية"

رسالة واتساب هي كائن بيانات غني يحتوي على الهوية، المصدر، الحالة، والبيانات الوصفية للوسائط.

1. استراتيجية العزل السياقي (fromMe و source)

لتجنب "حلقة التغذية الراجعة اللانهائية" (حيث يرد البوت على نفسه)، يوفر Wawp خاصيتين حاسمتين:

  • القيمة المنطقية fromMe: تخبرك فوراً إذا كانت الرسالة مرسلة من مثيلك الخاص (true) أو من جهة اتصال خارجية (false). يجب أن تقوم التكاملات الاحترافية دائمًا بفلترة fromMe === false كخطوة أولى.
  • **حقل المصدر source: يحدد ما إذا كانت الرسالة أُرسلت عبر واجهة Wawp (api) أو يدوياً بواسطة شخص يحمل الهاتف (phone). إذا كان المصدر phone، يمكن للبوت "التنحي" وترك المجال للمحادثة البشرية.

2. تحديد هوية المصدر (JIDs)

يسمح حقل [from] لنظامك بتحديد سياق المحادثة فوراً:

  • الدردشات الفردية (@c.us): محادثات خاصة بين شخصين.
  • الدردشات الجماعية (@g.us): محادثات جماعية، وهنا يصبح حقل [author] حاسماً لتحديد الفرد الذي أرسل الرسالة داخل المجموعة.
  • القنوات (@newsletter): رسائل من القنوات العامة أو النشرات الإخبارية.

🚀 حالات الاستخدام الاستراتيجي

1. الفرز المعزز بالذكاء الاصطناعي

بمجرد وصول الرسالة، يمكن لنظامك تحليل المحتوى (Sentiment Analysis). إذا تم رصد "إحباط شديد" من العميل، يمكن للنظام تخطي البوت وتنبيه وكيل بشري رفيع المستوى فوراً.

2. مسار الأدلة البصرية

عندما تكون قيمة hasMedia هي true، يتحول التفاعل إلى "إثبات بصري". يوفر ويب هوك Wawp رابطاً مؤقتاً للوسائط. يمكن لنظامك تحميلها وتنسيقها فوراً وتضمينها في تذكرة الدعم الفني، مما يوفر سياقاً بصرياً فورياً للوكيل البشري.

🛡️ أفضل الممارسات التشغيلية والهندسية

  • استراتيجية "الاستيعاب الخفيف" (Thin Ingestion): لا تقم بأعمال ثقيلة (مثل استدعاء ذكاء اصطناعي) داخل دورة الويب هوك. قم باستلام الرسالة، وضعها في طابور مهام سريع مثل (Redis)، وأرسل رد 200 OK فوراً لـ Wawp. ثم دع "العمال" (Workers) يعالجون المنطق برمجياً بشكل منفصل.
  • إدارة التكرار (Idempotency): تحقق دائماً من المعرف الفريد id للرسالة الواردة مقابل ذاكرة مؤقتة للرسائل "المستلمة مؤخراً". قد تتسبب تقلبات الشبكة في توصيل نفس الويب هوك مرتين.
  • الوعي بأنواع الوسائط: لا تكتفِ بالتحقق من وجود وسائط، بل تحقق من media.mimetype. فمعالجة مستند PDF بحجم 50 ميجابايت تختلف تماماً عن معالجة صورة JPEG بحجم 10 كيلوبايت.

الردود المتوقعة

استكشف كافة الردود والنتائج المحتملة من الخادم. قمنا بتوثيق كل كود حالة (Status Code) مع أمثلة للبيانات لتسهيل معالجة الأخطاء والنجاح.

Webhook Payload Example
application/json
string *
number *
string *
object *
string *
string *
object *
object *

Example

{
"id": "evt_01aaaaaaaaaaaaaaaaaaaaaaaa",
"timestamp": 1634567890123,
"session": "default",
"metadata": {
  "user.id": "123",
  "user.email": "email@example.com"
  },
"engine": "WEBJS",
"event": "message",
"payload": {
  "id": "false_11111111111@c.us_AAAAAAAAAAAAAAAAAAAA",
  "timestamp": 1666943582,
  "from": "11111111111@c.us",
  "fromMe": true,
  "source": "api",
  "to": "11111111111@c.us",
  "participant": null,
  "body": "Hello, world!",
  "hasMedia": true,
  "media": {
    "url": "https://api.wawp.net/api/files/example.oga",
    "mimetype": "audio/ogg",
    "filename": "example.oga",
    "s3": {
      "Bucket": "my-bucket",
      "Key": "default/example.oga"
      },
    "error": null
    },
  "ack": -1,
  "ackName": "PENDING",
  "author": "11111111111@c.us",
  "location": {
    "description": "London, UK",
    "latitude": "51.5074",
    "longitude": "0.1278"
    },
  "vCards": {
    "0": "BEGIN:VCARD..."
    },
  "_data": {
    },
  "replyTo": {
    "id": "AAAAAAAAAAAAAAAAAAAA",
    "participant": "11111111111@c.us",
    "body": "Hello!",
    "_data": {
      }
    }
  },
"me": {
  "id": "11111111111@c.us",
  "lid": "123123@lid",
  "pushName": "Wawp Instance"
  }
}
الموضوع السابقتغير حالة الجلسة
الموضوع التاليتفاعل مع الرسالة

Command Palette

Search for a command to run...