تلقّي أحداث التفاعل والردّ عليها

توضّح هذه الصفحة كيف يمكن لتطبيق Google Chat تلقّي تفاعلات المستخدمين والردّ عليها، والمعروفة أيضًا باسم أحداث التفاعل مع تطبيق Google Chat.

توضّح هذه الصفحة كيفية تنفيذ ما يلي:

• اضبط تطبيق Chat لتلقّي أحداث التفاعل.
• عالِج حدث التفاعل على بنيتك الأساسية.
• الردّ على أحداث التفاعل عند الاقتضاء

ملاحظة: يوضّح هذا الدليل كيفية إنشاء تطبيق Chat تفاعلي باستخدام أحداث التفاعل في Chat API. يمكنك أيضًا إنشاء تطبيق Chat كإضافة في Google Workspace. لمعرفة المزيد حول إطار العمل الذي يجب استخدامه، يمكنك الاطّلاع على إنشاء تطبيق تفاعلي على Google Chat.

المتطلبات الأساسية

• حساب Google Workspace من إصدار Business أو Enterprise مع إذن الوصول إلى Google Chat
• أنشئ مشروعًا على Google Cloud.
• ضبط شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth
• تفعيل واجهة برمجة تطبيقات Google Chat

أنواع أحداث التفاعل

يمثّل حدث التفاعل مع تطبيق Google Chat أي إجراء يتّخذه مستخدم لاستدعاء تطبيق Chat أو التفاعل معه، مثل الإشارة إلى تطبيق Chat باستخدام @أو إضافته إلى مساحة.

عندما يتفاعل المستخدمون مع تطبيق Chat، يرسل Google Chat إلى تطبيق Chat حدث تفاعل، ويتم تمثيله كنوع Event في Chat API. يمكن لتطبيق Chat استخدام الحدث لمعالجة التفاعل، ويمكنه أيضًا الرد برسالة.

بالنسبة إلى كل نوع من تفاعلات المستخدمين، يرسل Google Chat نوعًا مختلفًا من أحداث التفاعل التي تساعد تطبيق Chat في التعامل مع كل نوع من الأحداث بشكل مناسب. يتم تمثيل نوع حدث التفاعل باستخدام الكائن eventType.

على سبيل المثال، يستخدم Google Chat نوع الحدث ADDED_TO_SPACE لأي تفاعل يضيف فيه المستخدم تطبيق Chat إلى مساحة، وذلك حتى يتمكّن تطبيق Chat من الردّ فورًا برسالة ترحيب في المساحة.

الشكل 1: عندما يضيف مستخدم تطبيق Chat إلى مساحة، يتلقّى تطبيق Chat حدث تفاعل ADDED_TO_SPACE يتعامل معه تطبيق Chat لإرسال رسالة ترحيب في المساحة.

يوضّح الجدول التالي تفاعلات المستخدمين الشائعة ونوع حدث التفاعل الذي تتلقّاه تطبيقات Chat وطريقة استجابة تطبيقات Chat عادةً:

تفاعل المستخدم	eventType	الردّ المعتاد من تطبيق Chat
يرسل مستخدم رسالة إلى تطبيق Chat، مثلاً، يشير إلى تطبيق Chat باستخدام علامة @ أو يستخدم أمرًا يبدأ بشرطة مائلة.	MESSAGE	يردّ تطبيق Chat استنادًا إلى محتوى الرسالة. على سبيل المثال، يردّ تطبيق Chat على الأمر /about الذي يبدأ بشرطة مائلة برسالة توضّح المهام التي يمكن أن ينفّذها تطبيق Chat.
يضيف مستخدم تطبيق Chat إلى مساحة.	ADDED_TO_SPACE	يرسل تطبيق Chat رسالة إعداد توضّح وظيفة التطبيق وكيفية تفاعل المستخدمين في المساحة معه.
يزيل مستخدم تطبيق Chat من مساحة.	REMOVED_FROM_SPACE	يزيل تطبيق Chat أي إشعارات واردة تم ضبطها للمساحة (مثل حذف خطاف ويب) ويمحو أي مساحة تخزين داخلية.
ينقر المستخدم على زر في بطاقة من رسالة تطبيق Chat أو مربّع حوار أو الصفحة الرئيسية.	CARD_CLICKED	يعالج تطبيق Chat ويخزّن أي بيانات أرسلها المستخدم، أو يعرض بطاقة أخرى.
يفتح المستخدم الصفحة الرئيسية لتطبيق Chat من خلال النقر على علامة التبويب الصفحة الرئيسية في رسالة محادثة بين شخصين.	APP_HOME	يعرض تطبيق Chat بطاقة ثابتة أو تفاعلية من الصفحة الرئيسية.
يرسل مستخدم نموذجًا من الصفحة الرئيسية لتطبيق Chat.	SUBMIT_FORM	يعالج تطبيق Chat ويخزّن أي بيانات أرسلها المستخدم، أو يعرض بطاقة أخرى.
يستدعي المستخدم أمرًا باستخدام أمر سريع.	APP_COMMAND	يردّ تطبيق Chat استنادًا إلى الأمر الذي تم تنفيذه. على سبيل المثال، يردّ تطبيق Chat على الأمر حول برسالة توضّح المهام التي يمكن أن ينفّذها تطبيق Chat.

للاطّلاع على جميع أحداث التفاعل المتوافقة، راجِع مستنداتEventType المرجع.

أحداث التفاعل من مربّعات الحوار

إذا كان تطبيق Chat يفتح مربّعات حوار، يتضمّن حدث التفاعل المعلومات الإضافية التالية التي يمكنك استخدامها لمعالجة الردّ:

• تم ضبط قيمة isDialogEvent على true.
• توضّح DialogEventType ما إذا كان التفاعل يؤدي إلى فتح مربّع حوار أو إرسال معلومات من مربّع حوار أو إغلاق مربّع حوار.

يعرض الجدول التالي التفاعلات الشائعة مع مربّعات الحوار وأنواع أحداث مربّعات الحوار المقابلة ووصفًا لطريقة استجابة تطبيقات المحادثة عادةً:

تفاعل المستخدم مع مربّع حوار	نوع حدث مربّع الحوار	الردّ النموذجي
يبدأ المستخدم طلب مربع حوار. على سبيل المثال، يستخدمون أمرًا يبدأ بشرطة مائلة أو ينقرون على زر من رسالة.	REQUEST_DIALOG	يفتح تطبيق Chat مربّع الحوار.
يرسل المستخدم معلومات في مربّع الحوار من خلال النقر على زر.	SUBMIT_DIALOG	ينتقِل تطبيق Chat إلى مربّع حوار آخر أو يغلق مربّع الحوار لإكمال التفاعل.
يخرج المستخدم من مربّع الحوار أو يغلقه قبل إرسال المعلومات.	CANCEL_DIALOG	يمكن لتطبيق Chat اختياريًا الرد برسالة جديدة أو تعديل الرسالة أو البطاقة التي فتح منها المستخدم مربّع الحوار.

لمزيد من المعلومات، يُرجى الاطّلاع على فتح مربّعات حوار تفاعلية.

تلقّي أحداث التفاعل مع تطبيق Chat

يوضّح هذا القسم كيفية تلقّي أحداث التفاعل ومعالجتها في تطبيق الدردشة.

ضبط تطبيق Chat لتلقّي أحداث التفاعل

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

بالنسبة إلى كل ميزة تفاعلية تريد إنشاءها، عليك تعديل إعداداتك في Chat API ليتمكّن Google Chat من إرسال أحداث التفاعل ذات الصلة إلى تطبيق Chat:

1. في وحدة تحكّم Google Cloud، انتقِل إلى صفحة Chat API وانقر على صفحة الإعدادات:

   الانتقال إلى صفحة "إعدادات واجهة برمجة تطبيقات Chat"

2. ضمن الميزات التفاعلية، راجِع الإعدادات وعدِّلها استنادًا إلى الميزات التي تريد إنشاءها:

   الحقل	الوصف
   الوظائف	مطلوب. مجموعة من الحقول التي تحدّد كيفية تفاعل تطبيق Chat مع المستخدمين. بشكلٍ تلقائي، يمكن للمستخدمين العثور على تطبيق Chat وإرسال رسائل إليه مباشرةً في Google Chat. الانضمام إلى المساحات والمحادثات الجماعية: يمكن للمستخدمين إضافة تطبيق Chat إلى المساحات والمحادثات الجماعية.
   إعدادات الاتصال	مطلوب. نقطة نهاية تطبيق Chat، وهي إحدى القيم التالية: عنوان URL لنقطة نهاية HTTP: نقطة نهاية HTTPS تستضيف تنفيذ تطبيق Chat. برمجة التطبيقات: رقم تعريف نشر لمشروع "برمجة التطبيقات" ينفّذ تطبيق Chat. اسم موضوع Cloud Pub/Sub: موضوع Pub/Sub يشترك فيه تطبيق Chat كنقطة نهاية. ‫Dialogflow: يسجّل تطبيق Chat من خلال عملية دمج مع Dialogflow. لمزيد من المعلومات، راجِع إنشاء تطبيق Dialogflow Google Chat يفهم اللغة الطبيعية.
   الطلبات الصوتية	اختيارية: الأوامر التي تبدأ بشرطة مائلة والأوامر السريعة لتطبيق Chat، وهي تتيح للمستخدمين طلب تنفيذ إجراء أو استخدام ميزة معيّنة في تطبيق Chat. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة الردّ على أوامر تطبيق Google Chat.
   معاينات الروابط	اختيارية: أنماط عناوين URL التي يتعرّف عليها تطبيق Chat ويقدّم محتوًى إضافيًا لها عندما يرسل المستخدمون روابط لمزيد من المعلومات، يُرجى الاطّلاع على معاينة الروابط.
   مستوى الرؤية	اختيارية: ما يصل إلى خمسة أفراد، أو مجموعة واحدة أو أكثر من "مجموعات Google" يمكنها عرض تطبيق Chat وتثبيته. استخدِم هذا الحقل لاختبار تطبيق Chat أو لمشاركته مع فريقك. لمزيد من المعلومات، يُرجى الاطّلاع على تجربة الميزات التفاعلية.

3. انقر على حفظ. عند حفظ إعدادات تطبيق Chat، يصبح تطبيق Chat متاحًا للمستخدمين المحدّدين في مؤسستك على Google Workspace.

تم الآن إعداد تطبيق Chat لتلقّي أحداث التفاعل من Google Chat.

التعامل مع عمليات إعادة محاولة طلبات HTTP إلى خدمتك

إذا تعذّر إرسال طلب HTTPS إلى خدمتك (مثل انتهاء المهلة أو حدوث عطل مؤقت في الشبكة أو ظهور رمز حالة HTTPS غير 2xx)، قد يعيد Google Chat محاولة التسليم عدة مرات في غضون بضع دقائق (ولكن لا يمكن ضمان ذلك). ونتيجةً لذلك، قد يتلقّى تطبيق دردشة الرسالة نفسها عدة مرات في حالات معيّنة. إذا اكتمل الطلب بنجاح ولكن تم عرض حمولة رسالة غير صالحة، لن يعيد Google Chat محاولة إرسال الطلب.

معالجة أحداث التفاعل أو الردّ عليها

يوضّح هذا القسم كيف يمكن لتطبيقات Google Chat معالجة أحداث التفاعل والردّ عليها.

بعد أن يتلقّى تطبيق Chat حدث تفاعل من Google Chat، يمكنه الردّ بطرق عديدة. في كثير من الحالات، تردّ تطبيقات Chat التفاعلية على المستخدم برسالة. يمكن لتطبيق Google Chat أيضًا البحث عن بعض المعلومات من مصدر بيانات، أو تسجيل معلومات حدث التفاعل، أو أي شيء آخر تقريبًا. هذا السلوك في المعالجة هو ما يحدّد بشكل أساسي تطبيق Google Chat.

للرد بشكل متزامن، يجب أن يرد تطبيق Chat في غضون 30 ثانية، ويجب نشر الرد في المساحة التي حدث فيها التفاعل. بخلاف ذلك، يمكن لتطبيق Chat الرد بشكل غير متزامن.

بالنسبة إلى كل حدث تفاعلي، تتلقّى تطبيقات Chat نص طلب، وهو حِمل JSON الذي يمثّل الحدث. يمكنك استخدام المعلومات لمعالجة الرد. للاطّلاع على أمثلة على حمولات الأحداث، راجِع أنواع أحداث التفاعل مع تطبيق Chat.

يوضّح الرسم البياني التالي الطريقة التي يعالج بها تطبيق Google Chat عادةً أنواعًا مختلفة من أحداث التفاعل أو يستجيب لها:

الردّ في الوقت الفعلي

تتيح أحداث التفاعل لتطبيقات Chat الاستجابة في الوقت الفعلي أو بشكل متزامن. لا تتطلّب الردود المتزامنة إجراء مصادقة.

للرد في الوقت الفعلي، يجب أن يعرض تطبيق Chat عنصر Message. للرد برسالة في المساحة، يمكن أن يحتوي العنصر Message على العناصر text وcardsV2 وaccessoryWidgets. للاستخدام مع أنواع أخرى من الردود، راجِع الأدلة التالية:

• فتح مربّعات الحوار التفاعلية
• معاينة الروابط
• معالجة المعلومات التي يقدّمها المستخدمون

ملاحظة: بالنسبة إلى أحداث التفاعل REMOVED_FROM_SPACE، لا يمكن لتطبيقات Chat الرد باستخدام عنصر Message لأنّها لم تعُد في المساحة.

الرد برسالة

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

لإرسال رسالة نصية عندما يضيف مستخدم تطبيق Chat إلى مساحة، سيردّ تطبيق Chat على ADDED_TO_SPACE حدث تفاعلي. للردّ على أحداث التفاعل ADDED_TO_SPACE برسالة نصية، استخدِم الرمز التالي:

Node.js

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The event object from Chat API.
 * @param {Object} res The response object from the Chat app. An onboarding message that
 * introduces the app and helps people get started with it.
 */
exports.onMessage = function onMessage(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send(
      'Hello! This function is meant to be used in a Google Chat space.');
  }

  // Send an onboarding message when added to a Chat space
  if (req.body.type === 'ADDED_TO_SPACE') {
    res.json({
      'text': 'Hi, Cymbal at your service. I help you manage your calendar
      from Google Chat. Take a look at your schedule today by typing
      `/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To
      learn what else I can do, type `/help`.'
    });
  }
};

برمجة تطبيقات

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app. An onboarding message that
 * introduces the app and helps people get started with it.
 */
function onAddToSpace(event) {

  return {
    'text': 'Hi, Cymbal at your service. I help you manage your calendar
    from Google Chat. Take a look at your schedule today by typing
    `/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn
    what else I can do, type `/help`.'
  }
}

تعرض عيّنة الرمز البرمجي الرسالة النصية التالية:

الردّ بشكل غير متزامن

في بعض الأحيان، يجب أن تستجيب تطبيقات Chat لحدث تفاعل بعد 30 ثانية أو أن تنفّذ مهامًا خارج المساحة التي تم إنشاء حدث التفاعل فيها. على سبيل المثال، قد يحتاج تطبيق Chat إلى الرد على المستخدم بعد إكمال مهمة تستغرق وقتًا طويلاً. في هذه الحالة، يمكن لتطبيقات Chat الرد بشكل غير متزامن من خلال استدعاء واجهة برمجة التطبيقات Google Chat API.

لإنشاء رسالة باستخدام Chat API، يُرجى الاطّلاع على مقالة إنشاء رسالة. للحصول على أدلة حول استخدام طرق إضافية في Chat API، يُرجى الاطّلاع على نظرة عامة على Chat API.

مواضيع ذات صلة

• إرسال رسالة
• فتح مربّعات الحوار التفاعلية
• معاينة الروابط
• قراءة بيانات النماذج التي أدخلها المستخدمون على البطاقات
• الردّ على الأوامر
• إنشاء صفحة رئيسية لتطبيق Chat
• التحقّق من الطلبات الواردة من Chat
• اختبار الميزات التفاعلية لتطبيقات Google Chat