الردّ التلقائي على الويب

عنوان URL يحدّده الشريك وتنشر فيه منصة RCS for Business الرسائل والأحداث. يعمل عنوان URL هذا كنقطة نهاية تتلقّى طلبات HTTPS POST تحتوي على بيانات حول الأحداث. وهذا يعني أنّه يتم إرسال البيانات إلى تطبيقك بشكل آمن عبر HTTPS.

قد يبدو رابط ويب هوك على النحو التالي: https://[your company name].com/api/rbm-events. بعد ضبط webhook، يمكنك البدء في تلقّي الرسائل والأحداث.

تحذير: يُرجى العِلم أنّ ميزة "الرسائل من الشركات من RCS" تضع الرسائل في قائمة انتظار واحدة للشريك. قد يؤدي تعذُّر تنفيذ webhook لأحد الوكلاء (عدم عرض الرمز 200) إلى التأثير في تنفيذ جميع webhooks للوكلاء الآخرين في حساب الشريك نفسه. لمزيد من المعلومات، راجِع تأثيرات الويب هوك على مستوى الوكيل.

الويب هوك الخاص بالشريك والويب هوك الخاص بالوكيل

يمكنك ضبط الويب هوك إمّا على مستوى الشريك أو على مستوى الوكيل.

• ينطبق خطاف الويب الخاص بالشريك على كل وكيل تحتفظ به. إذا كان لدى وكلائك سلوك مشابه، أو إذا كان لديك وكيل واحد فقط، استخدِم رابط ويب الخاص بالشريك.
• تنطبق الويب هوك الخاصة بالوكيل على وكلاء فرديين. إذا كنت تشغّل عدة برامج وكيل ذات سلوك مختلف، يمكنك ضبط رابط ويب مختلف لكل برنامج وكيل.

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

ضبط الويب هوك الخاص بالوكيل

ملاحظة: لإنشاء عملية دمج باستخدام ويب هوك من خلال RBM Management API، يُرجى الرجوع إلى مستندات إنشاء عملية دمج باستخدام ويب هوك.

تتلقّى الرسائل المُرسَلة إلى موظّف الدعم في ويب هوك الشريك. إذا كنت تريد أن تصل رسائل وكيل معيّن إلى ويب هوك مختلف، عليك ضبط ويب هوك للوكيل.

1. افتح RCS for Business Developer Console وسجِّل الدخول باستخدام حساب Google الخاص بشريك RCS for Business.
2. انقر على الوكيل.
3. انقر على عمليات الدمج.

4. في قسم Webhook، انقر على ضبط.

   1. في نقطة نهاية الويب هوك، أدخِل رابط ويب هوك الذي يبدأ بـ "https://‎".
   2. في رمز العميل المميز، حدِّد قيمة clientToken. تحتاج إلى هذا الرقم لإثبات أنّ الرسائل التي تتلقّاها صادرة من Google.
   ملاحظة: لا يمكن عرض الرمز المميّز الحالي للعميل لأسباب تتعلّق بالأمان. لإنشاء رمز مميّز جديد للعميل، أدخِل قيمة في الحقل المعنيّ أو انقر على إعادة التحميل لإنشاء قيمة عشوائية.

5. اضبط خطاف الويب لقبول طلبات POST مع حمولة JSON تتضمّن المَعلمتَين clientToken وsecret.

   {
     "clientToken":"YOURCLIENTTOKEN",
     "secret":"YOURSECRET"
   }
   

   لإثبات صحة الطلب، يجب أن تعرض نقطة النهاية رمز الحالة 200 OK الخاص ببروتوكول HTTP مع قيمة السلسلة الأولية للمَعلمة secret في نص الاستجابة.

   مثال على إعداد الويب هوك

   على سبيل المثال، إذا تلقّى تطبيق الويب الخاص بك طلب POST يتضمّن محتوى النص التالي:

     {
     "clientToken":"YOURCLIENTTOKEN",
     "secret":"YOURSECRET"
     }
     

   بعد ذلك، يجب أن يؤكّد الويب هوك قيمة clientToken، وإذا كانت clientToken صحيحة، يجب أن يعرض الرد 200 OK مع YOURSECRET كنص الرد:

     // clientToken from Configure
     const myClientToken = "YOURCLIENTTOKEN";
   
     // Example endpoint
     app.post("/rbm-webhook", (req, res) => {
       // Use the X-Goog-Webhook-Type header to route requests
       const webhookType = req.header('X-Goog-Webhook-Type');
   
       if (webhookType === 'verification') {
         const msg = req.body;
         if (msg.clientToken === myClientToken) {
             res.status(200).send(msg.secret);
             return;
         }
       }
       res.send(400);
       // Handle other webhook types
     });
     

6. في Developer Console، انقر على تأكيد. بعد النقر على إثبات صحة المعلومات، ترسل Google طلب POST إلى ويب هوك يتضمّن clientToken وsecret كمَعلمتَين ضمن نص الطلب. عندما تتحقّق خدمة RCS for Business من صحة عنوان URL الخاص بخطاف الويب، يتم إغلاق مربّع الحوار.

تحديد أنواع الطلبات

لتحديد نوع جميع الطلبات الواردة إلى نقطة نهاية "ويب هوك" لديك، يُرجى استخدام الرأس X-Goog-Webhook-Type.

يمكن أن يتضمّن العنوان القيم التالية:

• verification: يُستخدَم هذا النوع في عملية التحقّق الأولية من نقطة النهاية.
• message_callback: تُستخدَم للأحداث ذات الصلة بالرسائل، مثل إشعارات الكتابة أو التسليم والرسائل الواردة من المستخدمين.
• agent_callback: تُستخدَم للأحداث الإدارية الخاصة بالوكيل، مثل تغييرات حالة تشغيل الوكيل.

التحقّق من الرسائل الواردة

بما أنّ خطافات الويب يمكنها تلقّي رسائل من أي مرسل، عليك التأكّد من أنّ Google هي من أرسل الرسائل الواردة قبل معالجة محتوى الرسالة.

للتأكّد من أنّ Google أرسل الرسالة التي تلقّيتها، اتّبِع الخطوات التالية:

1. استخرِج عنوان X-Goog-Signature للرسالة. هذه نسخة مجزأة ومشفرة باستخدام base64 من حمولة نص الرسالة.
2. فك ترميز حمولة RCS for Business باستخدام Base64 في العنصر message.body من الطلب.
3. باستخدام الرمز المميز للعميل الخاص بخطاف الويب (الذي حدّدته عند إعداد خطاف الويب)، أنشئ رمز HMAC SHA512 من وحدات البايت الخاصة بحِمل الرسالة الذي تم فك ترميزه باستخدام base64، ثم أعد ترميز النتيجة باستخدام base64.
4. قارِن قيمة التجزئة X-Goog-Signature بقيمة التجزئة التي أنشأتها.
   • في حال تطابُق التجزئات، يعني ذلك أنّك تأكّدت من أنّ Google هي التي أرسلت الرسالة.

   • في حال عدم تطابق التجزئات، تحقَّق من عملية التجزئة على رسالة معروفة.

     إذا كانت عملية التجزئة تعمل بشكل صحيح وتلقّيت رسالة تعتقد أنّها أُرسلت إليك بشكل احتيالي، يُرجى التواصل معنا.

Node.js

  if ((requestBody.hasOwnProperty('message')) && (requestBody.message.hasOwnProperty('data'))) {
    // Validate the received hash to ensure the message came from Google RBM
    const headerHash = req.header('X-Goog-Signature');
    const userEventString = Buffer.from(requestBody.message.data, 'base64');
    const hmac = crypto.createHmac('sha512', myClientToken);
    const genHash = hmac.update(userEventString).digest('base64');

    if (headerHash === genHash) {
      const userEvent = JSON.parse(userEventString);
      const webhookType = req.header('X-Goog-Webhook-Type');

      // Route based on the header type
      if (webhookType === 'message_callback') {
        handleMessage(userEvent);
      } else if (webhookType === 'agent_callback') {
        handleAgentEvent(userEvent);
      }
    } else {
      console.log('Hash mismatch - ignoring message');
      res.sendStatus(401);
      return;
    }
  }

  res.sendStatus(200);
  

التعامل مع الرسائل

يُعدّ إرجاع أي قيمة أخرى غير 200 OK من الويب هوك فشلاً في التسليم.

على المطوّرين الانتباه إلى أنّ إرسال الرسائل بمعدلات عالية سيؤدي إلى إنشاء إشعارات webhook بمعدلات عالية، وعليهم تصميم الرمز البرمجي للتعامل مع الإشعارات بالمعدل المتوقّع. من المهم أن يأخذ المطوّرون في الاعتبار الحالات التي قد تؤدي إلى ظهور ردود تعذّر التنفيذ، بما في ذلك ردود 500 من الحاوية على الويب أو انتهاء المهلة أو حدوث أخطاء في المصدر. تشمل الأمور التي يجب أخذها في الاعتبار ما يلي:

• تأكَّد من ضبط إعدادات الحماية من هجمات حجب الخدمة الموزّعة (DDoS) للتعامل مع المعدّل المتوقّع لإشعارات خطاف الويب.
• تأكَّد من عدم نفاد الموارد، مثل مجموعات ربط قواعد البيانات، ومن عدم حدوث مهلات أو ظهور استجابات 500.

على المطوّرين تصميم أنظمتهم بطريقة تتم فيها معالجة أحداث RBM بشكل غير متزامن، ولا تمنع Webhook من عرض 200 OK.

من المهم عدم معالجة حدث RBM داخل خطاف الويب نفسه. قد يؤثر أي خطأ أو تأخير أثناء المعالجة في رمز الإرجاع الخاص بخطاف الويب:

السلوك في حال تعذّر التسليم

إذا كان رمز حالة Webhook يعرض أي شيء آخر غير 200 OK، تستخدم منصة RCS for Business آلية إعادة المحاولة والتراجع لإعادة تسليم البيانات. وهذا يعني أنّ النظام يزيد تدريجيًا التأخير بين كل محاولة تسليم، إلى أن يصل في النهاية إلى الحد الأقصى للتكرار وهو محاولة واحدة كل 10 دقائق لكل رسالة معلّقة. تستمر دورة إعادة المحاولة لمدة سبعة أيام، وبعد ذلك يتم حذف الرسالة نهائيًا.

تأثيرات الويب هوك على مستوى الوكيل

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

يمكن أن يؤدي عدم تلقّي إقرار استلام عدة رسائل إلى حدوث ارتفاع كبير في أحداث إعادة المحاولة. على سبيل المثال، إذا لم يقرّ وكيل باستلام 1,600 إيصال تسليم، وبلغت وتيرة إعادة المحاولة الحدّ الأقصى البالغ 10 دقائق، يمكن أن يؤدي ذلك إلى حدوث حوالي 230,000 خطأ محتمل في اليوم:

1,600 رسالة × 6 محاولات إعادة إرسال في الساعة × 24 ساعة في اليوم = حوالي 230,000 خطأ في اليوم

يمكن أن يؤدي هذا العدد الكبير من عمليات إعادة المحاولة إلى حظر قائمة انتظار Pub/Sub المشترَكة والتسبّب في تأخيرات كبيرة في تلقّي أحداث المستخدمين لجميع حملات أحد الشركاء.

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

لضمان موثوقية عدد الزيارات في مرحلة الإنتاج وتجنُّب المشاكل التي تعيق تقدّم الطلبات في قائمة الانتظار، اتّبِع أفضل الممارسات التالية:

• إرجاع الرمز 200 OK على الفور: يجب أن يتلقّى برنامج ربط التطبيقات الرسالة ويخزّنها في قائمة انتظار محلية، ثم يعرض الرد 200 OK في أقل من خمس ثوانٍ.
• فصل المعالجة: استخدِم المنفِّذين المنفصلين في الخلفية لمعالجة منطق المراسلة من الصفّ المحلي.
• مراقبة الوكلاء التجريبيين: يجب التعامل مع وكلاء التطوير على أنّهم وكلاء إنتاج، لأنّهم قد يحظرون أيضًا قائمة انتظار الشريك المشتركة في حال حدوث خطأ.
• حسابات مخصّصة للاختبار: يُفضّل استخدام حساب مطوِّر واحد لبرامج الإنتاج وحساب مطوِّر مخصّص لبرامج الاختبار.
• التحقّق من زيارات Google: استخدِم نظام أسماء النطاقات العكسي أو العنوان X-Goog-Signature بدلاً من القائمة البيضاء الثابتة لعناوين IP، لأنّ Google يستخدم عناوين IP ديناميكية من نوع anycast. للحصول على مزيد من المعلومات حول عملية التحقّق اليدوي وتحديد نطاقات IP الخاصة بمحرك بحث Google، يُرجى الاطّلاع على مستند التحقّق من طلبات Google، وتحديدًا ملفات JSON الخاصة ببرامج الجلب التي يشغّلها المستخدم وبرامج الجلب التي يشغّلها المستخدم من Google.

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

بعد ضبط webhook، سيتمكّن الوكيل من تلقّي الرسائل من أجهزة الاختبار. أرسِل رسالة للتحقّق من صحة عملية الإعداد.