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

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

لإنشاء واجهات تفاعلية لتطبيقات Chat، يمكنك استخدام المكوّنات التالية:

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

يمكن لتطبيقات Chat إنشاء الواجهات وعرضها بالطرق التالية:

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

آلية عمل تفاعلات المستخدمين

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

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

بنية كيفية معالجة تطبيقات Google Chat لتفاعلات المستخدمين

العوامل التي تؤدي إلى الظهور

العوامل التي تؤدي إلى الظهور هي الطرق المحدّدة التي يستدعي بها المستخدمون تطبيق Chat باستخدام واجهة مستخدم Chat، مثل استخدام الإشارات باستخدام @أو أوامر التطبيق.

يعرض الجدول التالي عوامل تشغيل Chat ووصفًا لها وكيفية استجابة تطبيقات Chat عادةً:

Trigger الوصف الردّ المعتاد
تمت الإضافة إلى المساحة

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

يرسل تطبيق Chat رسالة ترحيبية توضّح وظيفته وكيفية تفاعل المستخدمين في المساحة معه.
رسالة

يتفاعل المستخدم مع تطبيق Chat في رسالة بإحدى الطرق التالية:

  • يرسل رسالة في مساحة رسالة مباشرة (DM) باستخدام تطبيق Chat.
  • يشير إلى تطبيق Chat باستخدام @ في أي نوع من المساحات.
  • يرسل رسالة تحتوي على رابط يتطابق مع نمط عنوان URL لمعاينات الروابط.
  • يكتب نصًا في قائمة الاختيار المتعدّد في تطبيق مصغّر من النوع selectionInput.
يستجيب تطبيق Chat استنادًا إلى محتوى الرسالة. على سبيل المثال، يردّ تطبيق Chat برسالة أو يرفق بطاقة معاينة رابط أو يقترح عناصر في قائمة متعددة الاختيارات.
تمت إزالته من المساحة

يزيل المستخدم تطبيق Chat من مساحة، أو يلغي مشرف حسابات Google Workspace تثبيت تطبيق Chat لمستخدم في مؤسسته.

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

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

يستدعي المستخدم أمرًا في تطبيق Chat (مثل أمر يبدأ بشرطة مائلة أو أمر سريع أو إجراء رسالة).

يستجيب تطبيق Chat للأمر. على سبيل المثال، يردّ برسالة أو يفتح مربّع حوار.
الصفحة الرئيسية للتطبيق

يفتح المستخدم علامة التبويب الصفحة الرئيسية في مساحة رسالة مباشرة على الخاص (DM) مع تطبيق Chat، أو يتفاعل مع تطبيق مصغّر في بطاقة الصفحة الرئيسية.

يعرض تطبيق Chat عنصر RenderActions الذي يرسل بطاقة الصفحة الرئيسية (pushCard) أو يعدّل بطاقة الصفحة الرئيسية المعروضة (updateCard).

يمكنك ضبط نقاط النهاية أو دوال رد الاتصال لهذه المشغّلات في Google Cloud Console ضمن صفحة الإعدادات في Chat API. للحصول على تعليمات مفصّلة، يُرجى الاطّلاع على مقالة ضبط Google Chat API.

ضبط الطلبات الأولية

تساعد الطلبات الأولية المستخدمين في اكتشاف وظائف تطبيق Chat عند فتح رسالة مباشرة على الخاص فارغة باستخدام تطبيقك. يمكنك ضبط ما يصل إلى ثلاثة طلبات أولية.

لإضافة الطلبات الأولية وضبطها:

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

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

  2. ضمن الميزات التفاعلية، ابحث عن الطلبات الأولية وانقر على إضافة طلب.

  3. في حقل الترتيب (1-3)، أدخِل رقمًا من 1 إلى 3 لتحديد ترتيب العرض.

  4. ضمن اختيار النوع، اختَر سلوك الطلب:

    • الطلب النصي: يملأ خانة إدخال المحتوى بنص محدّد مسبقًا عندما ينقر المستخدم على شريحة الطلب.
    • أمر يبدأ بشرطة مائلة: لتشغيل أمر يبدأ بشرطة مائلة مسجَّل أو أمر سريع عند النقر عليه. لا يمكن اختيار الأوامر التي تتطلّب وسيطات إضافية.
  5. اضبط الطلب استنادًا إلى اختيارك للنوع:

    • إذا اخترت "طلب نصي":

      1. في العنوان، أدخِل عنوان الطلب المعروض على الشريحة (ما يصل إلى 30 حرفًا).
      2. في نص الطلب، أدخِل النص الذي يظهر في خانة إدخال المحتوى (ما يصل إلى 60 حرفًا).
      3. اختياري: أضِف عناوين ونصوصًا مترجَمة للمستخدمين بلغات أخرى:
      4. ضمن الطلبات المترجَمة، انقر على إضافة لغة.
      5. في قسم اللغة، اختَر لغة متوافقة من القائمة المنسدلة.
      6. في حقل العنوان المترجَم، أدخِل العنوان المترجَم (ما يصل إلى 30 حرفًا).
      7. في حقل نص الطلب المترجَم، أدخِل نص الطلب المترجَم (ما يصل إلى 60 حرفًا).
      8. كرِّر الخطوات لإضافة المزيد من اللغات حسب الحاجة.
    • إذا اخترت "موجّه الأوامر":

      1. في الأمر الذي يبدأ بشرطة مائلة / الأمر السريع، اختَر الأمر من القائمة المنسدلة.
  6. انقر على تم، ثم على حفظ في أسفل الصفحة.

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

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

كائنات الأحداث

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

في عام 2025، تم توسيع نطاق تطبيقات Google Chat لتتوافق مع أحداث الإضافات، وأصبح هذا هو الإعداد التلقائي لتطبيقات Chat الجديدة منذ يوليو 2025. في مستندات Chat، تُعدّ أحداث الإضافات هي نوع الأحداث العادي المعروض في الأدلة وعيّنات التعليمات البرمجية. يتم فصل مستندات أحداث Chat (لتطبيقات Chat التي ليست إضافات Google Workspace) إلى أقسام مصغّرة (على سبيل المثال، تطبيقات Chat التي ليست إضافات: تلقّي أحداث التفاعل والرد عليها).

تحديد أنواع الأحداث والاستجابات

عندما يتلقّى تطبيق Chat كائن حدث، تعتمد بنية الحمولة وطريقة الردّ على ما إذا تم إعداد تطبيق Chat كإضافة في Google Workspace.

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

نوع التطبيق تلقّي أحداث الإضافات
(الإعداد التلقائي للتطبيقات الجديدة التي تم إنشاؤها بعد يوليو 2025)
تلقّي أحداث Chat
(الإعداد التلقائي السابق، قبل يوليو 2025)
تطبيقات "برمجة تطبيقات Google"
يُرجى مراجعة ملف البيان (appsscript.json)
يتم ضبط عنصر chat داخل addOns:
{
  "addOns": {
    "chat": {}
  }
}
يتم ضبط عنصر chat في جذر ملف البيان:
{
  "chat": {}
}
التطبيقات الأخرى
يُرجى الاطّلاع على صفحة إعدادات واجهة برمجة تطبيقات Google Chat
تم وضع علامة في مربّع الاختيار "إنشاء تطبيق Chat هذا كإضافة في Google Workspace" . لم يتم وضع علامة في مربّع الاختيار "إنشاء تطبيق Chat هذا كإضافة في Google Workspace".
أين يمكن العثور على المستندات؟ في الأدلة وعينات التعليمات البرمجية

مستندات مرجعية للأحداث: كائنات أحداث الإضافات
الأقسام المصغّرة (على سبيل المثال، تطبيقات Chat التي ليست إضافات: تلقّي أحداث التفاعل والردّ عليها)

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

حمولة كائن الحدث

يتضمّن كل كائن حدث في الإضافات commonEventObject مع تفاصيل المضيف والمنصة (hostApp: "CHAT" وclientPlatform وuserLocale وuserTimezone وparameters وformInputs) و كائن chat يحتوي على سياق خاص بـ Chat:

  • بالنسبة إلى عامل تشغيل الصفحة الرئيسية للتطبيق (عندما يفتح المستخدم علامة التبويب الصفحة الرئيسية في رسالة مباشرة بين شخصين باستخدام تطبيق Chat)، يحتوي العنصر chat على chat.user وchat.eventTime بدون حقل الاتحاد payload. عندما ينقر المستخدم على زر في بطاقة الصفحة الرئيسية، يتضمن كائن الحدث chat.buttonClickedPayload مع commonEventObject.parameters (و commonEventObject.formInputs إذا كانت البطاقة تحتوي على مدخلات النموذج).
  • بالنسبة إلى التفاعلات مع المساحات والرسائل (تمت الإضافة إلى المساحة أو الرسالة أو تمت الإزالة من المساحة أو أمر التطبيق أو التفاعلات مع الأزرار والتطبيقات المصغّرة)، يتضمّن الكائن chat كلاً من chat.user وchat.space وchat.eventTime وحمولة التفاعل المقابلة:
    • ‫messagePayload: يحتوي على space وmessage وconfigCompleteRedirectUri عندما يرسل المستخدم رسالة.
    • ‫addedToSpacePayload: يحتوي على space وinteractionAdd وconfigCompleteRedirectUri عند إضافة تطبيق Chat إلى مساحة.
    • ‫removedFromSpacePayload: يحتوي على space عند إزالة تطبيق Chat من مساحة.
    • ‫buttonClickedPayload: يحتوي على space وmessage وisDialogEvent وdialogEventType عندما ينقر المستخدم على زر في بطاقة أو مربّع حوار.
    • ‫widgetUpdatedPayload: يحتوي على space عندما يتفاعل المستخدم مع تطبيق مصغّر، مثل الكتابة في قائمة متعددة الاختيارات باستخدام مصدر بيانات خارجي.
    • ‫appCommandPayload: يحتوي على space وmessage وappCommandMetadata وisDialogEvent وdialogEventType وconfigCompleteRedirectUri عندما يستدعي المستخدم أمرًا في التطبيق.

عند تفعيل جلسات المحادثات في مساحة رسائل مباشرة على الخاص مع تطبيق Chat، يتضمّن العنصر space في حمولة التفاعل (مثل chat.messagePayload.space أو chat.addedToSpacePayload.space أو chat.buttonClickedPayload.space أو chat.widgetUpdatedPayload.space أو chat.appCommandPayload.space) السمة sessionState (المضبوطة على THREAD) والسمة sessionEnableTime، ويحدّد العنصر thread (chat.messagePayload.message.thread أو chat.buttonClickedPayload.message.thread أو chat.appCommandPayload.message.thread أو chat.appCommandPayload.thread) سلسلة محادثات الجلسة (spaces/{space}/threads/{thread}).

للتعرّف على كائنات أحداث الإضافات في Chat وتطبيقات Google Workspace الأخرى، يُرجى الاطّلاع على كائنات الأحداث.

تقديم ردّ

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

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

للردّ على تفاعلات المستخدمين بشكل متزامن، يعالج تطبيق Chat كائن الحدث الوارد ويعرض أحد كائنات JSON التالية:

  • DataActions: ينشئ رسائل محادثة (CreateMessageAction وUpdateMessageAction) أو يعدّلها أو يرفق معاينات الروابط (UpdateInlinePreviewAction) باستخدام chatDataActionMarkup.
  • RenderActions: لإنشاء صفحة رئيسية أو مربّع حوار (pushCard، updateCard، endNavigation: "CLOSE_DIALOG") أو تعديلهما أو إغلاقهما، أو تقديم اقتراحات إدخال ديناميكية لقائمة الاختيار المتعدد (modifyCard).
  • AuthorizationError: تطلب من المستخدمين تسجيل الدخول أو المصادقة على خدمة خارجية باستخدام بطاقة تفويض أساسية (basic_authorization_prompt).

يوضّح الجدول التالي كيف يمكن لتطبيقات Chat الردّ من خلال الإجراءات. يمكن لتطبيقات Chat عرض عناصر JSON مباشرةً أو إنشاء الردّ باستخدام AddOnResponseService وCardService في "برمجة تطبيقات Google".

ردّ تطبيق Chat الإجراء المطلوب لإرجاع (JSON) الإجراء المطلوب لإرجاع (برمجة تطبيقات Google)
إرسال رسالة أو تعديل رسالة ‫DataActions (createMessageAction أو updateMessageAction) DataActionsResponse
معاينة الروابط في الرسائل التي يرسلها مستخدمو Chat في مساحة DataActions ‏(updateInlinePreviewAction) DataActionsResponse
عرض صفحة رئيسية أو تعديلها في علامة التبويب الصفحة الرئيسية لرسالة مباشرة ‫RenderActions (pushCard أو updateCard) ActionResponse
فتح مربّع حوار أو تعديله أو إغلاقه RenderActions (pushCard أو updateCard أو endNavigation: "CLOSE_DIALOG") ActionResponse
لجمع المعلومات من بطاقة أو مربّع حوار، يمكنك اقتراح عناصر اختيار استنادًا إلى ما يكتبه المستخدمون في قائمة الاختيار المتعدّد. RenderActions ‏(modifyCard) ActionResponse
طلب الإعداد أو التفويض لخدمة خارجية AuthorizationError ‏(basic_authorization_prompt) AuthorizationException

الرد برسالة

يمكن لتطبيقات Chat الردّ برسالة على أي من العوامل أو التفاعلات التالية:

  • مشغّلات الرسائل، مثل عندما يشير المستخدمون إلى تطبيق Chat باستخدام @أو يرسلون رسالة مباشرة إليه
  • Added to space triggers, such as when users install the Chat app from the Google Workspace Marketplace or add it to a space.
  • مشغّلات أوامر التطبيق، مثل عندما يستدعي المستخدمون أمرًا يبدأ بشرطة مائلة أو أمرًا سريعًا
  • النقرات على الأزرار من البطاقات في الرسائل أو مربّعات الحوار على سبيل المثال، عندما يقوم المستخدمون بإدخال المعلومات والنقر فوق إرسال.

يمكن أن تتضمّن تطبيقات Chat أيًا مما يلي في الرسالة:

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

للردّ برسالة، يمكنك عرض DataActions باستخدام عنصر CreateMessageAction:

{
  "hostAppDataAction": {
    "chatDataAction": {
      "createMessageAction": {
        "message": <var>MESSAGE</var>
      }
    }
  }
}

استبدِل MESSAGE بمورد Message من Chat API.

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

Node.js

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The request object from Google Chat.
 * @param {Object} res The response object from the Chat app.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  const chatEvent = req.body.chat;
  // Send an onboarding message when added to a Chat space
  if (chatEvent.addedToSpacePayload) {
    res.json({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
      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`.'
    }}}}});
  }
};

Python

from flask import Flask, request, json
app = Flask(__name__)

@app.route('/', methods=['POST'])
def cymbal_app():
  """Sends an onboarding message when the Chat app is added to a space.

  Returns:
    Mapping[str, Any]: The response object from the Chat app.
  """
  chat_event = request.get_json()["chat"]
  if "addedToSpacePayload" in chat_event:
    return json.jsonify({ "hostAppDataAction": { "chatDataAction": {
      "createMessageAction": { "message": {
        "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`.'
      }}
    }}})

جافا

@SpringBootApplication
@RestController
public class App {
  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /*
   * Sends an onboarding message when the Chat app is added to a space.
   *
   * @return The response object from the Chat app.
   */
  @PostMapping("/")
  @ResponseBody
  public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
    JsonNode chatEvent = event.at("/chat");
    if (!chatEvent.at("/addedToSpacePayload").isEmpty()) {
      return new GenericJson() { {
        put("hostAppDataAction", new GenericJson() { {
          put("chatDataAction", new GenericJson() { {
            put("createMessageAction", new GenericJson() { {
              put("message", new Message().setText(
                "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`."
              ));
            } });
          } });
        } });
      } };
    }
    return new GenericJson();
  }
}

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

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Google Chat.
 * @return {Object} Response from the Chat app.
 */
function onAddedToSpace(event) {
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    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 أيضًا تعديل الرسائل التي ترسلها. على سبيل المثال، يمكن لتطبيق Chat تعديل رسالة بعد أن يرسل المستخدم مربّع حوار أو ينقر على زر في بطاقة في رسالة.

لتعديل رسالة تطبيق Chat ردًا على تفاعل، يمكنك عرض DataActions مع UpdateMessageAction:

{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateMessageAction": {
        "message": <var>MESSAGE</var>
      }
    }
  }
}

استبدِل MESSAGE بمورد Message من Chat API.

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

الرد بشكل غير متزامن باستخدام Google Chat API

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

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

عند الردّ على تفاعل بعد 30 ثانية، لتجنُّب ظهور رسالة خطأ موجّهة للمستخدمين تفيد بأنّ تطبيق Chat لا يستجيب، عليك تأكيد استلام كائن الحدث في غضون 30 ثانية من خلال عرض ردّ فارغ:

Node.js

async function onEvent(req, res) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return res.send({});
};

Python

def on_event(event) -> dict:
  # Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return {}

جافا

public String onEvent(JsonNode event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return "{}";
}

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

function onEvent(event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return null;
}

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

تطبيقات Chat التي ليست إضافات: تلقّي تفاعلات المستخدمين والردّ عليها

تتلقّى تطبيقات Chat التي ليست إضافات Google Workspace أحداث تفاعل Chat API (Event) بدلاً من كائنات أحداث إضافات Google Workspace (EventObject)، وتستجيب من خلال عرض مورد Message بدلاً من إجراء.

لترقية تطبيق Chat ليس إضافة إلى إطار عمل إضافات Google Workspace، يُرجى الاطّلاع على تحويل تطبيق Google Chat إلى إضافة Google Workspace.

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

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

تفاعل المستخدم 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 على الأمر لمحة برسالة توضّح المهام التي يمكنه تنفيذها.

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

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

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

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

أحداث التفاعل في المساحات التي تتضمّن جلسات

عند تفعيل جلسات المحادثات في مساحة رسائل مباشرة على الخاص مع تطبيق Chat ليس إضافة، يتضمّن حقل space ذو المستوى الأعلى لحدث التفاعل space.sessionState (تم ضبطه على THREAD) وspace.sessionEnableTime، ويحدّد message.thread أو thread سلسلة المحادثات في الجلسة.

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

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

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

  2. ضمن الميزات التفاعلية، أزِل العلامة من المربّع بجانب إنشاء تطبيق Chat هذا كإضافة في Google Workspace، واضبط الوظيفة، ونقطة نهاية واحدة لـ إعدادات الاتصال (عنوان URL لنقطة نهاية HTTP أو "برمجة تطبيقات Google" أو اسم موضوع Cloud Pub/Sub أو Dialogflow) والطلبات والطلبات الأولية ومعاينات الروابط ومستوى الظهور.

  3. انقر على حفظ.

الرد برسالة في تطبيق Chat ليس إضافة

للرد بشكل متزامن في تطبيق Chat ليس إضافة، يمكنك عرض عنصر Message مباشرةً. يستجيب المثال التالي لحدث تفاعل 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.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  // 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`.'
    });
  }
};

Python

from flask import Flask, request, json
app = Flask(__name__)

@app.route('/', methods=['POST'])
def cymbal_app():
  """Sends an onboarding message when the Chat app is added to a space.

  Returns:
    Mapping[str, Any]: The response object from the Chat app.
  """
  event = request.get_json()
  if event['type'] == 'ADDED_TO_SPACE':
    return json.jsonify({
      '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`.'
    })
  return json.jsonify({})

جافا

@SpringBootApplication
@RestController
public class App {
  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /*
   * Sends an onboarding message when the Chat app is added to a space.
   *
   * @return The response object from the Chat app.
   */
  @PostMapping("/")
  @ResponseBody
  public Message onEvent(@RequestBody JsonNode event) {
    switch (event.get("type").asText()) {
      case "ADDED_TO_SPACE":
        return new Message().setText(
          "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`.");
      default:
        return new Message();
    }
  }
}

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

/**
 * 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.
 */
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`.'
  };
}