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

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

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

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

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

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

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

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

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

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

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

عندما يتفاعل مستخدم مع تطبيق 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 عند فتح رسالة مباشرة فارغة بين شخصين باستخدام تطبيقك. يمكنك ضبط ما يصل إلى ثلاثة طلبات أولية.

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

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

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

معالجة عمليات إعادة محاولة إجراء طلبات 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 API
كيفية الردّ	عرض إجراء، مثل `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 وتطبيقات 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 ليس إضافة لتلقّي أحداث التفاعل

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

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

الرد برسالة في تطبيق 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`.'
  };
}

تلقّي تفاعلات المستخدمين والاستجابة لها تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

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

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

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

عناصر الحدث

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

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

تقديم ردّ

الرد برسالة

Node.js

Python

جافا

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

تعديل رسالة

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

Node.js

Python

جافا

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

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

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

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

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

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

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

Node.js

Python

جافا

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

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