كتلة الويب هوك - استقبال استدعاءات HTTP الواردة في تدفق روبوت المحادثة

أوقف تدفق روبوت المحادثة في ChatMaxima مؤقتاً وانتظر استدعاء HTTP خارجياً. استقبل الحمولات واستأنف التدفق وأرسل استجابات HTTP مخصصة إلى المتصل.

نظرة عامة

تتيح كتلة الويب هوك لنظام خارجي استدعاء روبوت المحادثة الخاص بك عبر HTTP. يمكن استخدامها بطريقتين: كـ الكتلة الأولى من تدفق (الويب هوك نفسه يبدأ المحادثة)، أو ككتلة في منتصف التدفق توقف المحادثة مؤقتاً وتنتظر استدعاءً خارجياً لاستئنافها. في كلتا الحالتين، تُحلَّل الحمولة الواردة وتُتاح للكتل اللاحقة كمتغيرات. يمكنك اختيارياً إرسال استجابة HTTP مخصصة إلى المتصل باستخدام كتلة استجابة الويب هوك.

هذا عكس كتلة API. ترسل كتلة API طلبات صادرة. تستمع كتلة الويب هوك للطلبات الواردة. تشمل حالات الاستخدام النموذجية بدء محادثة جديدة من حدث خارجي (إرسال نموذج، إنشاء سجل في نظام إدارة علاقات العملاء، مُشغّل iPaaS مثل n8n أو Zapier)، أو انتظار استدعاء بوابة دفع، أو استقبال تأكيد تسليم كلمة مرور لمرة واحدة من مزود رسائل نصية تابع لجهة خارجية، أو الإشعار عند اكتمال مهمة واجهة خلفية طويلة الأمد، أو قبول تحديثات غير متزامنة من تطبيق خارجي.

كتلة الويب هوك مقابل كتلة API

الجانب	كتلة API	كتلة الويب هوك
الاتجاه	صادر (الروبوت يستدعي API)	وارد (نظام خارجي يستدعي الروبوت)
المُشغّل	تلقائي عند وصول التدفق إلى الكتلة	استدعاء HTTP POST خارجي يبدأ التدفق أو يستأنفه
الموضع	في منتصف التدفق فقط	الكتلة الأولى أو في منتصف التدفق
سلوك الانتظار	متزامن، مهلة 30 ثانية	يبدأ التدفق عند الوصول، أو يوقف التدفق مؤقتاً حتى يصل الاستدعاء
الاستخدام النموذجي	البحث عن البيانات، دفع التحديثات	بدء المحادثات من أحداث خارجية، انتظار الاستدعاءات غير المتزامنة
معالجة الاستجابة	يحلّل محتوى الاستجابة إلى متغيرات	تصبح الحمولة الواردة متغيرات

أين تجدها

افتح روبوت المحادثة الخاص بك في Studio
اسحب كتلة الويب هوك من الشريط الجانبي الأيسر إلى اللوحة
ضعها كـ الكتلة الأولى من تدفقك (لبدء محادثة من حدث خارجي) أو اربطها بعد أي كتلة سابقة (للإيقاف المؤقت وانتظار استدعاء في منتصف التدفق)
انقر نقراً مزدوجاً على الكتلة لتهيئتها

لإرسال استجابة HTTP مخصصة إلى المتصل، أضف كتلة استجابة الويب هوك مباشرةً بعد كتلة الويب هوك.

الويب هوك كالكتلة الأولى

عندما تكون كتلة الويب هوك هي الكتلة الأولى من التدفق، لا توجد محادثة نشطة بعد. ينشئ طلب POST الخارجي المحادثة، ويحلّل الحمولة إلى متغيرات، ويبدأ التدفق من البداية تماماً. هذا هو النمط الذي يُستخدم عندما:

يُنشأ عميل محتمل جديد في نظام إدارة علاقات العملاء الخاص بك وتريد أن يتواصل الروبوت
يُرسل نموذج على موقعك الإلكتروني وتريد أن يتابع الروبوت
يُشغّل سير عمل n8n أو Zapier أو Make جلسة دردشة جديدة
يجب أن يبدأ حدث في الواجهة الخلفية (طلب مُقدَّم، تذكرة دعم مفتوحة) محادثة روبوت

الويب هوك في منتصف التدفق

عندما توضع كتلة الويب هوك بعد كتلة أخرى، يتوقف التدفق مؤقتاً عند تلك النقطة حتى يصل طلب POST الخارجي. هذا هو النمط الذي يُستخدم عندما تحتاج إلى التحويل إلى نظام خارجي، وانتظار استجابته غير المتزامنة، ثم متابعة التدفق بناءً على ما أعاده.

كيف تعمل

وضع الكتلة الأولى

External system POSTs to webhook URL
                 │
                 ▼
   New conversation is created
                 │
                 ▼
   Payload parsed into variables
                 │
                 ▼
   Flow starts from the next block
                 │
                 ▼
   Webhook Response sent (optional)

وضع منتصف التدفق

Bot flow runs ──▶ Reaches Webhook Block ──▶ Flow pauses
                                                  │
                             External system POSTs to webhook URL
                                                  │
                                                  ▼
                            Payload parsed into variables
                                                  │
                                                  ▼
                     Webhook Response sent (optional)
                                                  │
                                                  ▼
                     Flow continues to next block

في وضع منتصف التدفق، يخزّن الروبوت موضع الكتلة الحالي عند الإيقاف المؤقت. عندما يصل طلب POST الخارجي إلى رابط الويب هوك، يطابقه النظام مع المحادثة المتوقفة مؤقتاً، ويستأنف من تلك الكتلة، ويستمر إلى أسفل التدفق.

التهيئة

الخطوة 1: ضع كتلة الويب هوك في التدفق

اسحب الكتلة إلى اللوحة عند النقطة التي يجب أن يبدأ منها التدفق أو ينتظر عندها حدثاً خارجياً. على سبيل المثال:

كـ الكتلة الأولى، للسماح لنظام إدارة علاقات العملاء أو نموذج أو أداة iPaaS ببدء محادثة دردشة جديدة
بعد التقاط تفاصيل الدفع، لانتظار تأكيد بوابة الدفع
بعد تشغيل مهمة واجهة خلفية عبر كتلة API، لانتظار إشعار اكتمال المهمة

الخطوة 2: انسخ رابط الويب هوك

تعرض كل كتلة ويب هوك رابطاً فريداً يظهر في تهيئة الكتلة. التنسيق هو:

https://chatmaxima.com/webhooks/chatbot/<bot_token>/<block_id>/

مرّر هذا الرابط إلى النظام الخارجي كوجهة لطلب POST الخاص به. لأدوات iPaaS (n8n وZapier وMake) تلصقه في خطوة HTTP. لأنظمة إدارة علاقات العملاء ومنشئي النماذج، هيّئه كويب هوك صادر في لوحة التحكم الخاصة بهم. لبوابات الدفع والواجهات الخلفية غير المتزامنة، اضبطه كرابط الاستدعاء عند بدء العمل.

الخطوة 3: صادق على المتصل

يقبل رابط الويب هوك رمز Bearer في ترويسة Authorization. استخدم الرمز المعروض في تهيئة الكتلة بحيث يقبل الويب هوك الاستدعاءات فقط من الأنظمة التي تثق بها.

curl -X POST https://chatmaxima.com/webhooks/chatbot/<bot_token>/<block_id>/ \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_token>' \
  --data '{
    "type": "Conversation",
    "channel": "",
    "account_alias": "",
    "reference_id": "",
    "data": {
      "name": ""
    }
  }'

شكل الحمولة

الحقل	الغرض
`type`	نوع الحدث، عادةً `Conversation` لبدء دردشة أو استئنافها
`channel`	القناة التي يجب أن تستخدمها المحادثة (مثل `whatsapp` أو `website`). اتركه فارغاً لاستخدام الافتراضي
`account_alias`	اسم الفريق المستعار عندما يُشارَك الروبوت عبر حسابات متعددة
`reference_id`	معرّف خارجي يمكنك استخدامه لربط المحادثة بسجل في نظامك
`data`	كائن يحتوي على أي حقول تريد تمريرها كمتغيرات (مثل `name` و`email` و`phone` والحقول المخصصة)

الخطوة 4: الإشارة إلى حقول الحمولة الواردة

عندما يصل طلب POST، يُحلَّل كائن data ويصبح كل حقل متغيراً متاحاً لجميع الكتل اللاحقة.

لحمولة مثل:

{
  "type": "Conversation",
  "channel": "whatsapp",
  "reference_id": "ORDER-9981",
  "data": {
    "name": "Priya",
    "phone": "+919000000000",
    "order_id": "ORDER-9981",
    "customer": {
      "email": "priya@example.com"
    }
  }
}

يمكنك الإشارة إلى:

{name} لـ Priya
{phone} لـ +919000000000
{order_id} لـ ORDER-9981
{customer.email} للحقول المتداخلة
{reference_id} للبيانات الوصفية عالية المستوى

الخطوة 5: الإرسال والحفظ

انقر على إرسال في نافذة الكتلة، ثم احفظ التدفق باستخدام حفظ التغييرات في الشريط العلوي.

كتلة استجابة الويب هوك

اقرن كتلة الويب هوك بـ كتلة استجابة الويب هوك عندما يتوقع المتصل استجابة HTTP محددة. بدون كتلة الاستجابة، يعيد الروبوت 200 OK افتراضياً مع {"status":"success"}.

تتيح لك كتلة استجابة الويب هوك تخصيص رمز الحالة (مثل 201 أو 400 أو 500)، ونوع المحتوى (application/json أو application/xml أو text/plain أو text/html)، ومحتوى الاستجابة المرسل إلى المتصل. يمكنك إدراج متغيرات التدفق بصيغة {variable_name}.

الأنماط الشائعة:

إعادة 201 Created مع {conversation_id} الجديد لأدوات iPaaS
إعادة 400 مع حقل خطأ عندما تكون الحمولة غير صالحة
إعادة text/plain OK لاستدعاءات تسليم الرسائل النصية القصيرة
إعادة XML لتكاملات SOAP القديمة

راجع وثائق كتلة استجابة الويب هوك الكاملة لخيارات التهيئة والأمثلة واستكشاف الأخطاء.

أفضل الممارسات

تحقق دائماً من الحمولات الواردة. استخدم كتلة شرط بعد كتلة الويب هوك للتحقق من حقول مثل status == "success" قبل المتابعة
استخدم كتلة استجابة الويب هوك عندما يتوقع المتصل (بوابة الدفع، مزود الرسائل النصية، إلخ) تنسيق إقرار محدداً. بدونها، يحصل المتصل على 200 OK عام
اضبط مهلة ذات معنى في مكان آخر. لا تنتهي مهلة كتلة الويب هوك نفسها، لذا اجمعها مع مهلة عدم النشاط لتجنّب التدفقات التي تبقى متوقفة إلى أجل غير مسمى
أمّن رابط الويب هوك. الرمز في الرابط فريد لكل محادثة. لا تعرض الرابط علناً أو تسجّله في أنظمة يمكن للمستخدم قراءتها
تعامل مع حالة الفشل. تفرّع التدفق بناءً على الحمولة الواردة. إذا أشار الحدث الخارجي إلى فشل، أرسل رسالة استرداد أو وجّه إلى وكيل

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

عميل محتمل من نظام إدارة علاقات العملاء ينشئ محادثة (الكتلة الأولى)

يُضاف عميل محتمل جديد في نظام إدارة علاقات العملاء الخاص بك، ويفتح الروبوت محادثة WhatsApp لتأهيله.

كتلة الويب هوك (الكتلة الأولى): يرسل نظام إدارة علاقات العملاء حمولة العميل المحتمل مع phone وname وsource
كتلة رسالة: Hi {name}, thanks for your interest!
كتلة سؤال: اطرح أسئلة التأهيل
كتلة API: ادفع البيانات المؤهَّلة مرة أخرى إلى نظام إدارة علاقات العملاء

مُشغّل n8n أو Zapier (الكتلة الأولى)

تُطلق أداة أتمتة ويب هوك عند حدوث حدث معين (طلب Shopify جديد، إرسال Typeform، إلخ)، ويتابع الروبوت مع العميل.

كتلة الويب هوك (الكتلة الأولى): يرسل n8n طلب POST بـ {"phone":"...", "order_id":"..."}
كتلة رسالة: Your order {order_id} has shipped!

استدعاء بوابة الدفع

يبدأ المستخدم الدفع، ويرسله الروبوت إلى صفحة الدفع، ثم ينتظر أن ترسل البوابة النتيجة.

كتلة API: أنشئ جلسة دفع، وخزّن payment_url
كتلة رسالة: أرسل payment_url إلى المستخدم
كتلة الويب هوك: أوقف التدفق مؤقتاً، ومرّر رابط الويب هوك إلى البوابة كرابط الاستدعاء
كتلة شرط: تفرّع على {status} == "success"
كتلة استجابة الويب هوك: أعد {"received":true} إلى البوابة

إشعار مهمة غير متزامنة

يُشغّل الروبوت مهمة توليد تقرير طويلة الأمد، وينتظر الاكتمال، ثم يرسل رابط التقرير إلى المستخدم.

كتلة API: أرسل المهمة، وخزّن job_id، وضمّن رابط الويب هوك كرابط استدعاء
كتلة رسالة: "جارٍ توليد تقريرك، قد يستغرق هذا دقيقة..."
كتلة الويب هوك: انتظر استدعاء اكتمال المهمة
كتلة رسالة: Your report is ready: {report_url}

حالة تسليم كلمة مرور لمرة واحدة من جهة خارجية

يرسل الروبوت كلمة مرور لمرة واحدة عبر مزود رسائل نصية خارجي يستخدم ويب هوك لتأكيد التسليم.

كتلة API: شغّل إرسال كلمة المرور لمرة واحدة، ومرّر رابط الويب هوك
كتلة الويب هوك: انتظر حالة التسليم
كتلة شرط: تفرّع على {delivery_status}
كتلة رسالة: اطلب رمز كلمة المرور لمرة واحدة أو اعتذر عن فشل التسليم

إرسال نموذج خارجي

يجمع تطبيق ويب منفصل معلومات إضافية ويرسلها إلى الروبوت عند انتهاء المستخدم.

كتلة رسالة: أرسل رابط النموذج إلى المستخدم
كتلة الويب هوك: انتظر إرسال النموذج
كتلة رسالة: Thanks, we received your {form_field}

استكشاف الأخطاء وإصلاحها

التدفق عالق على كتلة الويب هوك (منتصف التدفق)

تأكد من أن النظام الخارجي أرسل فعلياً طلب POST إلى رابط الويب هوك. تحقق من سجلات التسليم الخاصة به
تحقق من أن الرابط يمكن الوصول إليه من النظام الخارجي (غير محظور بواسطة جدار حماية أو قائمة IP مسموح بها)
تأكد من أن الرابط يتضمن المسار الكامل والرمز الختامي
اجمع مع مهلة عدم النشاط للإغلاق التلقائي للمحادثات التي لا تستقبل الاستدعاء أبداً

ويب هوك الكتلة الأولى لا يبدأ محادثة

تأكد من أن كتلة الويب هوك هي أول كتلة في التدفق (لا تتصل بها أي كتلة أخرى)
تحقق من أن الحمولة تتضمن معرّف مستلم (هاتف أو بريد إلكتروني أو معرّف زائر) يمكن للروبوت استخدامه لإنشاء المحادثة
تحقق من نشر الروبوت وربط القناة (WhatsApp، أداة الموقع الإلكتروني، إلخ)
افحص حالة الاستجابة المعادة إلى المتصل. تشير حالة 4xx إلى رفض الحمولة

حقول الحمولة الواردة فارغة في الكتل اللاحقة

تأكد من أن Content-Type لطلب POST الوارد هو application/json أو نوع نموذج مدعوم
تحقق من أسماء الحقول الدقيقة في الحمولة. أسماء المتغيرات حساسة لحالة الأحرف
للحقول المتداخلة، استخدم العلامة النقطية: {customer.email}، وليس {customer_email}
افحص الحمولة الواردة الخام في سجل المحادثة لرؤية ما استُلم فعلياً

يحصل المتصل على `200 OK` عام بدلاً من استجابتي المخصصة

تأكد من إضافة كتلة استجابة الويب هوك بعد كتلة الويب هوك
تحقق من أن كتلة الاستجابة يمكن الوصول إليها في مخطط التدفق. قد توجّه كتلة شرط حولها
تحقق مرتين من نقر زر الإرسال وحفظ التدفق

النظام الخارجي يرفض استجابة الويب هوك

تأكد من أن Content-Type يطابق ما يتوقعه المتصل (على سبيل المثال، application/json مقابل text/plain)
تحقق من أن محتوى الاستجابة جيد التكوين. سيؤدي كائن JSON غير مغلق إلى إعادة محاولة المتصلين الصارمين
تحقق من رمز حالة HTTP. يقبل بعض المتصلين 200 فقط، وليس 201 أو 202

تصل طلبات POST متعددة للمحادثة نفسها

تعيد بعض الأنظمة الخارجية محاولة عمليات الويب هوك إذا اعتقدت أن التسليم الأول فشل. رابط الويب هوك خامل (idempotent) لكل محادثة، لذا يستأنف التدفق طلب POST الصالح الأول فقط. تستقبل طلبات POST اللاحقة الاستجابة المهيّأة دون تقدّم التدفق مرة أخرى.

الخطوات التالية

كتلة استجابة الويب هوك - إرسال استجابات HTTP مخصصة إلى المتصل
كتلة API - استدعاء واجهات برمجة التطبيقات الخارجية من التدفق
مهلة عدم النشاط - الإغلاق التلقائي للمحادثات التي تبقى متوقفة لفترة طويلة جداً
كتلة إنهاء المحادثة - إنهاء المحادثات يدوياً بزر إعادة التشغيل
نظرة عامة على Studio - استكشف جميع أنواع الكتل وميزات مُنشئ التدفق