التكاملات و Webhooks

ربط الخدمات الخارجية لمعالجة الرسائل الواردة برمجياً

ما هي التكاملات؟

تتيح لك التكاملات إعادة توجيه رسائل واتساب الواردة إلى رابط webhook خارجي في الوقت الفعلي. هذا مفيد للاتصال بـ N8N أو أنظمة CRM أو أي خدمة خارجية.

حالات الاستخدام الشائعة

• الاتصال بـ N8N لأتمتة سير العمل المعقد
• إرسال الرسائل إلى نظام CRM للتسجيل
• بناء روبوتات محادثة مخصصة بمنطق الذكاء الاصطناعي الخاص بك
• إعادة توجيه الرسائل إلى قناة Slack أو دردشة الفريق
• معالجة الطلبات والمدفوعات من خلال نظام خارجي

إنشاء تكامل

لإنشاء تكامل جديد، اتبع هذه الخطوات:

1. انتقل إلى التكاملات — اذهب إلى علامة التبويب 'التكاملات' في الشريط الجانبي
2. انقر على إضافة تكامل — زر إضافة تكامل يفتح نموذج الإنشاء
3. أدخل اسماً — اسم وصفي لتحديد هذا التكامل
4. اختر المزود — اختر Webhook أو N8N أو Custom
5. أدخل رابط Webhook — الرابط الذي سيستقبل طلبات POST مع بيانات الرسالة
6. تكوين الإعدادات — تعيين وضع الرد، إضافة مفتاح سري لتوقيع HMAC، تصفية حسب JID أو الجلسات
7. تفعيل التكامل — قم بتفعيل التكامل لبدء استقبال مكالمات webhook

حقول التكوين

حمولة Webhook

عندما تشغل رسالة تكاملاً، يرسل النظام طلب HTTP POST إلى رابط webhook الخاص بك مع بنية الحمولة التالية:

POST /your-webhook-url
Content-Type: application/json
X-Baileys-Signature: <hmac-sha256-signature> (only if secret is set)

{
  "event": "messages.upsert",
  "sessionId": "abc123...",
  "instanceId": "inst_abc...",
  "data": {
    "remoteJid": "201234567890@s.whatsapp.net",
    "text": "Hello, I want to order a pizza",
    "fromMe": false,
    "timestamp": 1718000000
  }
}

حقول الحمولة

أوضاع معالجة الرد

وضع الإرسال والنسيان

في وضع الإرسال والنسيان، يرسل النظام طلب webhook ولا ينتظر رداً. مناسب لـ:

• تسجيل الرسائل في أنظمة خارجية
• تشغيل سير العمل الذي لا يحتاج للرد على العميل
• إعادة توجيه البيانات لمنصات التحليلات أو CRM

وضع الرد

في وضع الرد، ينتظر النظام حتى 10 ثوانٍ لاستجابة webhook. مناسبة لـ:

• بناء روبوتات محادثة مخصصة ترد في الوقت الفعلي
• التكامل مع سير عمل N8N التي تولد ردوداً
• الاتصال بخدمات الذكاء الاصطناعي لردود ذكية

إذا لم يستجب webhook خلال 10 ثوانٍ، ينتهي الوقت ولا يتم الرد على الرسالة.

الرد المتوقع

HTTP 200 OK
Content-Type: application/json

{
  "reply": "Your message here",
  "text": "Your message here",
  "message": "Your message here"
}

حقول reply أو text أو message جميعها مقبولة. يتم استخدام أول قيمة غير فارغة كنص الرد.

الأمان والتحقق

توقيع HMAC

عند تعيين مفتاح سري لتكامل، يتضمن كل طلب webhook رأس X-Baileys-Signature.

• تأكد من أن الطلب جاء من وارِد وليس منتحلاً
• تحقق من عدم العبث بالحمولة أثناء النقل
• مصادقة طلبات webhook دون الحاجة إلى رموز API

مثال التحقق

// Verify HMAC-SHA256 signature
const crypto = require('crypto')

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}

خيارات التصفية

تصفية JID (لـ JID فقط)

يمكنك تقييد التكامل ليعمل فقط لرسائل من شخص معين على واتساب.

• أدخل JID كاملاً (مثال: 201234567890@s.whatsapp.net)
• أو أدخل جزءاً لاحقة يطابق عدة جهات اتصال

تعيين الجلسات

افتراضياً، ينطبق التكامل على جميع جلسات واتساب في نسختك. يمكنك اختيار جلسات محددة.

اختبار التكامل

قبل توجيه التكامل إلى نقطة نهاية إنتاج، يمكنك اختباره باستخدام أداة اختبار Webhook المدمجة.

زر صفحة توثيق أداة اختبار Webhook للتفاصيل:

حل المشاكل

• Webhook لا يعمل — تحقق من أن التكامل نشط. تأكد من اتصال الجلسة. تحقق من أن triggerOn يتضمن messages.upsert
• وضع الرد لا يعمل — تأكد من أن webhook يعيد استجابة JSON مع حقل reply أو text أو message خلال 10 ثوانٍ
• توقيع HMAC غير متطابق — تحقق من أن المفتاح السري في التكامل يطابق المفتاح المستخدم في HMAC. تأكد من استخدام SHA256 مع نص الطلب الخام
• تم الوصول إلى حد التكاملات — تحقق من خطة اشتراكك. قد تحتاج إلى ترقية لإضافة المزيد من التكاملات
• الرسائل لا ترسل إلى webhook — استخدم أداة اختبار Webhook للتحقق من إمكانية الوصول إلى نقطة النهاية