دعم Webhook و& API - الأسئلة الشائعة
الأسئلة الشائعة حول استخدام واجهات Chakra Chat API وخطافات الويب للرسائل الواردة.
يتناول هذا القسم خطافات الويب لأحداث الرسائل الواردة (بصيغة المرور المباشر وبصيغة Chakra)، وتوقيع HMAC، واستعادة سجل الرسائل، والتعايش، وضمان عدم تكرار عمليات الإرسال.
1. السلوك العام لخطافات الويب
هل يدعم خطاف الويب إعادة المحاولة أو وضع الأحداث في قائمة انتظار أو تجميعها؟ ما المهلة المطلوبة للاستجابة، وما محتواها للإقرار بالاستلام بنجاح؟
لا توجد سياسة لإعادة المحاولة أو وضع الأحداث في قائمة انتظار، سواءً في خطافات الويب للمرور المباشر أو Chakra. يكون الإقرار الناجح باستجابة HTTP 200، ولا يلزم إرسال محتوى في الاستجابة، ويجب إرجاعها خلال أقل من 200 ms. المرجع: مستندات خطاف ويب الأحداث الواردة
هل يمكن تجميع أحداث خطاف الويب أو تكرارها أو تسليمها بترتيب غير صحيح؟ هل تكون عمليات التسليم المكررة متطابقة على مستوى البايتات، وهل يتم توقيع كل عملية تسليم بشكل مستقل باستخدام HMAC؟
لا ندعم تجميع الأحداث، وقد تصل بترتيب غير صحيح. المرجع: خطاف ويب الأحداث الواردة — قسم التحقق من HMAC
ما حدود حجم محتوى خطاف الويب، وحجم الدفعة، والتزامن، ومعدل التسليم؟
لم تُنشر أي حدود. يُتوقع الاستخدام العادل.
ما زمن انتقال أحداث خطاف الويب عند الاشتراك فيها؟
يبلغ زمن الانتقال التاريخي المقاس بين وصول حدث من Meta إلى Chakra Webhook ومحاولة إرسال الحدث إلى حوالي 10-50 ms.
2. استعادة الأحداث الفائتة
إذا فاتنا حدث من خطاف الويب، فما نقطة النهاية التي تتيح تعداد الرسائل الواردة وحالات التسليم وأصداء تطبيق الأعمال الفائتة؟
لا توجد نقطة نهاية مخصصة لـ «الأحداث الفائتة». يمكن استعادة الرسائل الواردة الفائتة من خلال واجهات API لسجل المحادثات، مع إمكانية التصفية حسب معرّف المكوّن الإضافي ومعرّف رقم هاتف WhatsApp. ولا تتناول الوثائق المنشورة طريقة بحث مكافئة لحالات التسليم أو أصداء تطبيق الأعمال، ولا فترات الاحتفاظ أو أرقام التأخير في الاتساق؛ لذا ينبغي اعتبار هذه الإمكانية غير متاحة حاليًا إلى حين التأكيد داخليًا. المرجع: قائمة المحادثات | قائمة رسائل المحادثة | قائمة الرسائل السابقة لرقم هاتف
3. الحمولات والتعرّف على الأحداث
أين يمكنني العثور على حمولات حالية كاملة ومنقّحة لكل من message, status, message_echoو smb_message_echo، بما في ذلك حالة فشل تتضمن جميع حقول الخطأ؟
تتوفر أمثلة للحمولات في مرجع خطاف ويب الأحداث الواردة. المرجع: خطاف ويب الأحداث الواردة — أمثلة الحمولات
بالنسبة إلى أحداث status, message_echoو smb_message_echo ، ما الحقول التي تحدد المكوّن الإضافي وWABA ورقم هاتف النشاط التجاري المستقبِل عندما يكون للحساب عدة أرقام؟
في أحداث المرور المباشر/بصيغة Meta، يظهر رقم الهاتف المستقبِل في value.metadata.phone_number_id / display_phone_number، ويظهر معرّف WABA في entry[].id.
- مثال لحدث رسالة نصية واردة: apidocs.chakrahq.com/doc-919167#sample-inbound-text-message-event
- بنية كائن الحدث الوارد: apidocs.chakrahq.com/doc-919167#inbound-event-object-structure
المرجع: خطاف ويب الأحداث الواردة
ما رسائل تطبيق الأعمال التي تُنشئ أحداث smb_message_echo، وهل توجد أنواع غير مدعومة أو أجهزة مرافقة؟
تُنشئ جميع الرسائل النصية ورسائل الوسائط في تطبيق الأعمال أحداث smb_message_echo . أنواع الرسائل غير المدعومة هي:
- استطلاعات الرأي
- الرسائل المؤقتة
- الرسائل المحذوفة
ما الأحداث التي اشترك فيها حساب WABA الخاص بنا؟
الأحداث التالية مشترَك بها ومتاحة عبر خطاف الويب للمرور المباشر
يُعلمك خطاف الويب account_alerts بالتغييرات التي تطرأ على حد المراسلة, والملف التجاري، وحالة الحساب التجاري الرسمي لرقم هاتف النشاط التجاري. | |
يُعلمك خطاف الويب account_review_update عند مراجعة حساب WhatsApp Business وفقًا لإرشادات السياسات لدينا. | |
يُعلمك خطاف الويب account_update بالتغييرات التي تطرأ على طلب التحقق من النشاط التجاري بقيادة الشريك لحساب WhatsApp Business، أو أهلية معدل المصادقة الدولي ، أو الموقع الأساسي للنشاط التجاري عند مشاركته مع Solution Partner, أو بانتهاكات السياسات أو الشروط، أو إلغاء الإعداد، أو إعادة الاتصال، أو حذف الحساب. | |
يُعلمك خطاف الويب automatic_events عند اكتشاف عملية شراء أو حدث عميل محتمل في سلسلة محادثات بينك وبين مستخدم WhatsApp راسلك عبر إعلانك «انقر للمراسلة على WhatsApp»، إذا كنت قد اشتركت في إعداد تقارير الأحداث التلقائية . | |
يُعلمك خطاف الويب business_capability_update بالتغييرات التي تطرأ على إمكانات حساب WhatsApp Business أو محفظة الأعمال (مثلحدود المراسلة, وحدود أرقام الهواتف، وغيرها). | |
يُعلمك خطاف الويب calls بأحداث المكالمات المتعلقة بـ المكالمات التي يبدأها المستخدم و المكالمات التي يبدأها النشاط التجاري، مثل اتصال المكالمة أو إنهائها. | |
يُستخدم خطاف الويب history لمزامنة سجل محادثات تطبيق WhatsApp Business الخاص بعميل تجاري سجّله مزوّد حلول. | |
يُعلمك خطاف الويب message_template_components_update بالتغييرات التي تطرأ على مكوّنات القالب. | |
يُخطرك خطاف الويب message_template_quality_update بالتغييرات التي تطرأ على درجة جودة. | |
يُخطرك خطاف الويب message_template_status_update بالتغييرات التي تطرأ على حالة قالب موجود. | |
يصف خطاف الويب messages الرسائل المرسلة من مستخدم WhatsApp إلى نشاط تجاري، وحالة الرسائل التي يرسلها نشاط تجاري إلى مستخدم WhatsApp. | |
يصف خطاف الويب partner_solutions webhook التغييرات التي تطرأ على حالة حل الشركاء المتعددين. | |
يُخطرك خطاف الويب payment_configuration_update بالتغييرات التي تطرأ على إعدادات الدفع الخاصة بـ Payments API India و Payments API Brazil. | |
يُخطرك خطاف الويب phone_number_name_update بنتائج التحقق من اسم العرض لرقم هاتف النشاط التجاري. | |
يُخطرك خطاف الويب phone_number_quality_update بالتغييرات التي تطرأ على مستوى معدل نقل البيانات. | |
يُخطرك خطاف الويب security بالتغييرات التي تطرأ على إعدادات الأمان لرقم هاتف النشاط التجاري. | |
يُستخدم خطاف الويب smb_app_state_sync لمزامنة جهات اتصال مستخدمي تطبيق WhatsApp Business الذين تم ضمهم من خلال موفر حلول. | |
يُخطرك خطاف الويب smb_message_echoes بالرسائل التي يرسلها عميل نشاط تجاري عبر تطبيق WhatsApp Business أو جهاز مرافق («مرتبط») ، بعد أن تم ضمّه إلى Cloud API من خلال موفر حلول. | |
يُخطرك خطاف الويب template_category_update بالتغييرات التي تطرأ على فئة. | |
يُخطرك خطاف الويب user_preferences بالتغييرات التي تطرأ على تفضيلات الرسائل التسويقية. |
4. عناصر التحكم في الرسائل الصادرة
هل يتضمن حسابنا خطافات ويب لتمرير البيانات، وخطافات ويب مخصصة، وHMAC، ورسائل صدى التعايش؟
يدعم كل حساب في Chakra Chat خطافات ويب لتمرير البيانات، وخطافات ويب مخصصة، وHMAC، ورسائل صدى التعايش.
5. سر HMAC وتدويره
هل نوفر سر HMAC أم تنشئه Chakra؟
أنت من يوفّره، ويمكنك تعيينه ضمن Admin > Team > Secrets. مرجع: خطاف ويب للأحداث الواردة — التحقق من HMAC
يؤدي إنشاء سر HMAC جديد للفريق إلى إبطال السر السابق فورًا. ما الإجراء الانتقالي الذي يمنع فقدان خطافات الويب أثناء التدوير، وهل يمكن تداخل التوقيعات القديمة والجديدة مؤقتًا؟ تم توثيق آلية التدوير (يُعيّن السر ضمن Admin > Team > Secrets، ويُرسل عبر ترويسة X-Chakra-Signature-256 )، لكن لا يتوفر إجراء انتقالي أو فترة لتداخل التوقيعات. مرجع: خطاف ويب للأحداث الواردة — التحقق من HMAC
هل يمكن لعنوان رد الاتصال والسر نفسيهما استلام رسائل تمرير البيانات والحالات وأحداث message_echoو smb_message_echo ؟
تستخدم جميع الأحداث بتنسيق Chakra وأحداث تمرير البيانات (message, status, message_echo, smb_message_echo) عنوان URL واحدًا لرد الاتصال وسر HMAC واحدًا. ويستخدم تدفق تمرير البيانات من Meta عنوان URL منفصلًا، ولا تتوفر وثائق حول توقيع HMAC لهذا التدفق تحديدًا. مرجع: خطاف ويب للأحداث الواردة
6. إعداد عنوان URL لرد الاتصال
أين نُعد عنوان URL لرد الاتصال الخاص بخطاف الويب — في لوحة المعلومات أم عبر API؟ في لوحة معلومات Chakra: صفحة WhatsApp Setup ← علامة التبويب "More" ← الحقل "Pass-through webhook url" (بتنسيق Meta) والحقل "Chakra webhook url" (بتنسيق Chakra).
يمكن أيضًا تعيينه برمجيًا من خلال API لإعدادات الإضافة: apidocs.chakrahq.com/api-33925592
المرجع: خطاف ويب الأحداث الواردة
هل يكون عنوان رد الاتصال على مستوى الفريق بأكمله، أم على مستوى WABA/الإضافة، أم مخصصًا لكل رقم هاتف؟
لكل إضافة. لكل مثيل من إضافات WhatsApp Setup حقوله الخاصة لعناوين URL لخطافَي الويب، Chakra وتمرير البيانات — ولا يوجد خطاف ويب على مستوى الفريق. ويمكن إعداد خطافات ويب خاصة بـ WABA/رقم الهاتف ضمن الإضافة نفسها. مرجع: خطاف ويب للأحداث الواردة
7. ضمان عدم تكرار طلبات API
هل تدعم أي نقطة نهاية للإرسال مفتاحًا لضمان عدم التكرار يحدده العميل أو آلية لمنع التكرار؟ بعد انتهاء المهلة، كيف يمكننا التأكد بشكل قاطع من قبول الرسالة؟
لا تدعم نقاط نهاية الإرسال أي معلمة لمفتاح ضمان عدم التكرار. عند نجاح الإرسال، يُعاد معرّف رسالة WhatsApp (wamid) بشكل متزامن في نص الاستجابة. والإجراء الموثق بعد انتهاء المهلة هو الاستعلام عن سجل المحادثة/الرسائل ومطابقة النتيجة مع wamid — فلا توجد آلية لمفتاح ضمان عدم التكرار أو لمنع تكرار الإرسال نفسه. مرجع: إرسال رسالة جلسة WhatsApp | عرض رسائل المحادثة
8. قطع الاتصال بالتعايش
ما اتفاقية مستوى الخدمة (SLA) المتعلقة بتحرير الاتصال والتصعيد من جانب موفر الخدمة عند قطع الاتصال بالتعايش، بما في ذلك ارتباطات الشريك/الفوترة المتبقية؟
يقدم العميل تفاصيل الفوترة الخاصة به مباشرةً إلى Meta، لذا لا يمكن أن تنشأ أي مشكلة فوترة متبقية. مرجع: قطع اتصال حساب WABA | إلغاء تسجيل رقم هاتف WhatsApp Business