توضّح هذه الصفحة كيف يمكن لتطبيق Google Chat تلقّي تفاعلات المستخدمين والردّ عليها في Google Chat.
لإنشاء واجهات تفاعلية لتطبيقات Chat، يمكنك استخدام المكوّنات التالية:
- المشغّلات: الطرق التي يمكن لمستخدمي Google Chat من خلالها استدعاء تطبيق Chat، مثل إضافته إلى مساحة أو إرسال رسالة إليه
- كائنات الأحداث: البيانات التي تتلقّاها تطبيقات 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 لتفاعلات المستخدمين والردّ عليها:
العوامل التي تؤدي إلى الظهور
العوامل التي تؤدي إلى الظهور هي الطرق المحدّدة التي يستدعي بها المستخدمون تطبيق Chat باستخدام واجهة مستخدم Chat، مثل استخدام الإشارات باستخدام @أو أوامر التطبيق.
يعرض الجدول التالي عوامل تشغيل Chat ووصفًا لها وكيفية استجابة تطبيقات Chat عادةً:
| Trigger | الوصف | الردّ المعتاد |
|---|---|---|
| تمت الإضافة إلى المساحة |
يضيف المستخدم تطبيق Chat إلى مساحة، أو يثبّت مشرف حسابات Google Workspace تطبيق Chat في مساحات الرسائل المباشرة للمستخدمين في مؤسسته. للتعرّف على تطبيقات Chat التي ثبّتها المشرفون، يُرجى الاطّلاع على مقالة تثبيت تطبيقات Marketplace في نطاقك في مستندات مساعدة مشرفي Google Workspace. |
يرسل تطبيق Chat رسالة ترحيبية توضّح وظيفته وكيفية تفاعل المستخدمين في المساحة معه. |
| رسالة |
يتفاعل المستخدم مع تطبيق Chat في رسالة بإحدى الطرق التالية:
|
يستجيب تطبيق 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:
ضمن الميزات التفاعلية، ابحث عن الطلبات الأولية وانقر على إضافة طلب.
في حقل الترتيب (1-3)، أدخِل رقمًا من
1إلى3لتحديد ترتيب العرض.ضمن اختيار النوع، اختَر سلوك الطلب:
- الطلب النصي: يملأ خانة إدخال المحتوى بنص محدّد مسبقًا عندما ينقر المستخدم على شريحة الطلب.
- أمر يبدأ بشرطة مائلة: لتشغيل أمر يبدأ بشرطة مائلة مسجَّل أو أمر سريع عند النقر عليه. لا يمكن اختيار الأوامر التي تتطلّب وسيطات إضافية.
اضبط الطلب استنادًا إلى اختيارك للنوع:
إذا اخترت "طلب نصي":
- في العنوان، أدخِل عنوان الطلب المعروض على الشريحة (ما يصل إلى 30 حرفًا).
- في نص الطلب، أدخِل النص الذي يظهر في خانة إدخال المحتوى (ما يصل إلى 60 حرفًا).
- اختياري: أضِف عناوين ونصوصًا مترجَمة للمستخدمين بلغات أخرى:
- ضمن الطلبات المترجَمة، انقر على إضافة لغة.
- في قسم اللغة، اختَر لغة متوافقة من القائمة المنسدلة.
- في حقل العنوان المترجَم، أدخِل العنوان المترجَم (ما يصل إلى 30 حرفًا).
- في حقل نص الطلب المترجَم، أدخِل نص الطلب المترجَم (ما يصل إلى 60 حرفًا).
- كرِّر الخطوات لإضافة المزيد من اللغات حسب الحاجة.
إذا اخترت "موجّه الأوامر":
- في الأمر الذي يبدأ بشرطة مائلة / الأمر السريع، اختَر الأمر من القائمة المنسدلة.
انقر على تم، ثم على حفظ في أسفل الصفحة.
التعامل مع عمليات إعادة محاولة إجراء طلبات 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:
|
يتم ضبط عنصر 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.
المواضيع ذات الصلة
- إعداد Google Chat API
- إرسال رسالة
- الردّ على الطلبات
- فتح مربّعات الحوار التفاعلية
- قراءة بيانات النماذج التي يُدخلها المستخدمون في البطاقات
- معاينة الروابط
- إنشاء صفحة رئيسية لتطبيق Chat
- تنظيم المحادثات في جلسات
- التحقّق من الطلبات الواردة من Chat
- اختبار الميزات التفاعلية لتطبيقات Google Chat
تطبيقات 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 ليس إضافة لتلقّي أحداث التفاعل
في وحدة تحكّم Google Cloud، انتقِل إلى صفحة إعدادات 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`.'
};
}