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

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

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

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

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

تطبيق Google Chat مفعَّل للميزات التفاعلية لإنشاء تطبيق Chat تفاعلي، أكمِل إحدى خطوات البدء السريعة التالية استنادًا إلى بنية التطبيق التي تريد استخدامها:

• خدمة HTTP باستخدام Google Cloud Functions
• برمجة تطبيقات Google
• Google Cloud Dialogflow CX
• Google Cloud Pub/Sub

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

يمثّل حدث التفاعل مع تطبيق 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 وكيفية تفاعلها عادةً:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   الانتقال إلى صفحة إعدادات Chat API

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

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

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

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

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

إذا تعذّر إرسال طلب HTTPS إلى خدمتك (مثل انتهاء المهلة أو تعطُّل مؤقت في الشبكة أو رمز حالة HTTPS الذي لا ينتمي إلى 2xx)، قد يعيد Google Chat محاولة التسليم بضع مرات خلال بضع دقائق (ولكن ذلك ليس مضمونًا). ونتيجةً لذلك، قد يتلقّى تطبيق 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، اطّلِع على مقالة إنشاء رسالة. للحصول على أدلة حول استخدام methods إضافية في Chat API، يُرجى الاطّلاع على نظرة عامة على Chat API.

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

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