تلقّي التفاعلات مع تطبيق Google Chat والردّ عليها

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

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

على سبيل المثال، تستخدِم تطبيقات Chat أحداث التفاعل لتنفيذ أيّ ممّا يلي:

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

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

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

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

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

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

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

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

إذا أنشأت تطبيق Chat تفاعليًا، عليك إعداد Google Chat API ليتمكّن تطبيق Google Chat من إرسال أحداث التفاعل إليك:

  1. في Google Cloud Console، افتح صفحة Google Chat API:

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

  2. انقر على علامة التبويب الإعدادات.
  3. في قسم الميزات التفاعلية، انقر على زرّ التبديل تفعيل الميزات التفاعلية لتفعيل الميزة.
  4. في الوظائف، ضَع علامة في أحد مربّعَي الاختيار التاليَين أو كليهما:
    1. تلقّي رسائل بين شخصَين: يسمح هذا الخيار للمستخدمين بالتفاعل مع تطبيقك على Chat في مساحات الرسائل المباشرة. يتلقّى تطبيق Chat أحداث التفاعل في أي وقت يرسل فيه مستخدم رسالة في المساحة المباشرة.
    2. الانضمام إلى المساحات والمحادثات الجماعية: يسمح هذا الخيار للمستخدمين بإضافة تطبيقك في Chat وإزالته إلى المساحات التي تضم أكثر من مستخدم واحد. يتلقّى تطبيق Chat أحداث التفاعل كلما تمت إضافته أو إزالته من مساحة، وعندما يشير المستخدمون باستخدام @أو يستخدمون أمرًا شرطة مائلة في المساحة.
  5. في إعدادات الربط، حدِّد المكان الذي يرسل فيه Google Chat أحداث التفاعل مع تطبيق Chat.
  6. اختياري: في الأوامر التي تبدأ بشرطة مائلة، يمكنك إضافة وضبط واحد أو أكثر من الأوامر التي تبدأ بشرطة مائلة. لمزيد من المعلومات، يُرجى الاطّلاع على إعداد الأوامر التي تبدأ بشرطة مائلة.
  7. اختياري: في معاينات الروابط، يمكنك إضافة نمط واحد أو أكثر من أنماط عناوين URL التي يعاينها تطبيق Chat وإعدادها. لمزيد من المعلومات، يُرجى الاطّلاع على روابط المعاينة.
  8. انقر على حفظ.

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

التعامل مع عمليات إعادة محاولة استدعاء HTTP إلى خدمتك

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

معالجة أحداث التفاعل أو الاستجابة لها

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

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

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

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

بنية لكيفية معالجة تطبيقات Google Chat لأحداث التفاعل

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

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

لإنشاء استجابات متزامنة لأحداث التفاعل، راجِع الأدلة التالية:

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

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

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

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