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

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

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

الردود التلقائية على الويب للشريك والوكيل

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

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

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

ضبط ردّ تلقائي على الويب مخصَّص لوكيل

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

افتح Business Communications Developer Console وسجِّل الدخول باستخدام حسابك على Google الخاص بشريك RBM.
انقر على الوكيل.
انقر على عمليات الدمج.
بالنسبة إلى Webhook، انقر على ضبط.
بالنسبة إلى عنوان URL لنقطة نهاية الرد التلقائي على الويب، أدخِل عنوان URL للرد التلقائي على الويب يبدأ بـ "https://‎".
دوِّن قيمة clientToken. تحتاج إلى هذا الرقم للتأكّد من أنّ الرسائل التي تتلقّاها واردة من Google.
اضبط إعدادات الرد التلقائي على الويب لقبول طلب POST يتضمّن المَعلمة clientToken المحدّدة وإرسال رد 200 OK يتضمّن قيمة نصية عادية للمَعلمة secret كجزء من نص الرد.

على سبيل المثال، إذا تلقّى خطاف الويب طلب POST يتضمّن محتوى النص الأساسي التالي
```
{
  "clientToken":"SJENCPGJESMGUFPY",
  "secret":"1234567890"
}
```
يجب أن يؤكّد الرد التلقائي على الويب قيمة clientToken، وإذا كانت clientToken صحيحة، يجب أن يعرض الرد 200 OK مع 1234567890 كنص الرد:
```
// clientToken from Configure
const myClientToken = "SJENCPGJESMGUFPY";

// Example endpoint
app.post("/rbm-webhook", (req, res) => {
  const msg = req.body;
  if (msg.clientToken === myClientToken) {
      res.status(200).send(msg.secret);
      return;
  }
  res.send(400);
});
```
في Developer Console، انقر على تأكيد. عندما يتحقّق RBM من رمز Webhook، سيتم إغلاق مربّع الحوار.

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

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

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

استخرِج عنوان X-Goog-Signature للرسالة. هذه نسخة مجزأة ومشفّرة بترميز base64 من حمولة نص الرسالة.
فك ترميز حمولة RBM باستخدام Base64 في العنصر message.body من الطلب.
باستخدام الرمز المميز للعميل الخاص بخطاف الويب (الذي حدّدته عند إعداد خطاف الويب)، أنشئ رمز SHA512 HMAC من وحدات البايت الخاصة بحمولة الرسالة التي تم فك ترميزها باستخدام base-64، ثم أعد ترميز النتيجة باستخدام base64.
قارِن قيمة التجزئة 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
    let userEventString = Buffer.from(requestBody.message.data, 'base64');
    let hmac = crypto.createHmac('sha512', CLIENT_TOKEN);
    let data = hmac.update(userEventString);
    let genHash = data.digest('base64');
    let headerHash = req.header('X-Goog-Signature');

    if (headerHash === genHash) {
      let userEvent = JSON.parse(userEventString);

      console.log('userEventString: ' + userEventString);
      handleMessage(userEvent);
    } else {
      console.log('hash mismatch - ignoring message');
    }
  }

  res.sendStatus(200);

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

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

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

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

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

معالجة خطاف الويب غير المتزامنة

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

معالجة Webhook المتزامنة

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

تستخدم RBM آلية التراجع وإعادة المحاولة عندما تتلقّى ردًا غير 200 OK من طلب webhook. ستزيد خدمة "إدارة الأجهزة الجوّالة للمؤسسات" الوقت الذي تنتظره بين محاولات إعادة الاتصال إلى 600 ثانية كحدّ أقصى. ستستمر عمليات إعادة المحاولة لمدة 7 أيام، وبعد ذلك سيتم تجاهل الرسالة.

تأثيرات الردود التلقائية على الويب على مستوى الوكيل

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

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

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

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

Dialogflow