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

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

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

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

إنشاء تطبيق Chat تفاعلي كإضافة في Google Workspace

إصدار المطوّر: يتوفّر كجزء من برنامج إصدار المطوّر في Google Workspace، الذي يتيح الوصول المبكر إلى ميزات معيّنة.

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

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

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

• خدمة HTTP باستخدام Google Cloud Functions
• Google Apps Script
• 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 إلى مساحة.	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