این صفحه شرح می‌دهد که برنامه Google Chat شما چگونه می‌تواند تعاملات کاربر را در Google Chat دریافت کند و به آن‌ها پاسخ دهد.
برای ساختن میاناهای تعاملی برای برنامه‌های Chat، از مؤلفه‌های زیر استفاده می‌کنید:
- راه‌اندازها: روش‌هایی که کاربران Google Chat می‌توانند یک برنامه Chat را فراخوانی کنند، مانند افزودن آن به یک فضا یا ارسال پیام به آن.
- اشیاء رویداد: داده‌هایی که برنامه‌های Chat از راه‌اندازها یا تعامل‌های میانای کاربر دریافت می‌کنند.
- کنش‌ها: روش‌هایی که برنامه‌های Chat می‌توانند به تعاملات پاسخ دهند، مانند ارسال پیام یا برگرداندن میانای کاربر مبتنی بر کارت.
برنامه‌های Chat می‌توانند به روش‌های زیر میاناهای کاربری را بسازند و نمایش دهند:
- پیام‌هایی که می‌توانند حاوی نوشتار، کارت‌های ثابت یا تعاملی، و دکمه‌های جانبی باشند.
- صفحه‌های اصلی (صفحه اصلی برنامه) که در برگه صفحه اصلی پیام‌های مستقیم دونفره با برنامه Chat نشان داده می‌شود.
- چارگوش‌های گفتگو که کارت‌هایی هستند که در پنجره جدیدی باز می‌شوند و معمولاً از کاربران می‌خواهند اطلاعاتی را ارسال کنند.
- پیش‌نمایش پیوند که کارت‌هایی هستند که اطلاعات مربوط به سرویس خارجی را پیش‌نمایش می‌کنند.
پیش‌نیازها
- حساب Google Workspace «کسب‌وکار» یا «سازمان» با دسترسی به Google Chat.
- پروژه Google Cloud ایجاد کنید.
- صفحه کسب رضایت OAuth را پیکربندی کنید.
- Google Chat API را فعال و پیکربندی کنید.
نحوه عملکرد تعامل‌های کاربر
وقتی کاربر با برنامه Chat تعامل برقرار می‌کند، Google Chat راه‌انداز پیکربندی‌شده را فرامی‌خواند و شیء رویداد را به نقطه پایانی یا تابع برنامه Chat شما ارسال می‌کند. برنامه Chat شما شیء رویداد را پردازش می‌کند و می‌تواند کنش را به‌صورت هم‌زمان ظرف ۳۰ ثانیه برگرداند یا بااستفاده از Chat API به‌صورت ناهم‌زمان پاسخ دهد.
نمودار زیر نشان می‌دهد که برنامه‌های Google Chat چگونه تعاملات کاربر را پردازش می‌کنند و به آن‌ها پاسخ می‌دهند:
راه‌اندازها
راه‌اندازها روش‌های خاصی هستند که کاربران بااستفاده از واسط کاربر Chat، مثلاً بااستفاده از نامبری با @یا فرمان‌های برنامه، برنامه Chat را فرامی‌خوانند.
جدول زیر راه‌اندازهای Chat، شرح، و نحوه پاسخ معمول برنامه‌های Chat را نشان می‌دهد:
| راه‌انداز | شرح | پاسخ معمول |
|---|---|---|
| به فضا اضافه شد |
کاربری برنامه Chat را به فضایی اضافه می‌کند، یا سرپرست Google Workspace برنامه Chat را در فضاهای پیام مستقیم برای کاربران سازمانش نصب می‌کند. برای آشنایی با برنامه‌های Chat نصب‌شده توسط سرپرستان، به نصب برنامه‌های Marketplace در دامنه‌تان در سند «راهنمای سرپرست Google Workspace» مراجعه کنید. |
برنامه Chat پیام آماده‌سازی ارسال می‌کند که توضیح می‌دهد چه کاری انجام می‌دهد و کاربران در فضا چگونه می‌توانند با آن تعامل داشته باشند. |
| ارسال پیام |
کاربر به یکی از روش‌های زیر با برنامه Chat در پیام تعامل می‌کند:
|
برنامه Chat براساس محتوای پیام پاسخ می‌دهد. برای مثال، برنامه Chat با پیامی پاسخ می‌دهد، کارت پیش‌نمایش پیوند را پیوست می‌کند، یا مواردی را در منو چندانتخابی پیشنهاد می‌دهد. |
| از فضا برداشته شد |
کاربری برنامه Chat را از فضایی برمی‌دارد، یا سرپرست Google Workspace برنامه Chat را برای کاربری در سازمانش حذف نصب می‌کند. کاربران نمی‌توانند برنامه‌های Chat را که سرپرستشان نصب کرده است بردارند. اگر کاربری قبلاً برنامه Chat را نصب کرده باشد، برنامه Chat بدون توجه به اینکه سرپرست Google Workspace سعی در حذف نصب آن داشته باشد یا نه، نصب‌شده باقی می‌ماند. |
برنامه Chat همه اعلان‌های ورودی پیکربندی‌شده برای فضا را برمی‌دارد (مثلاً با حذف کردن وب‌قلاب) و همه حافظه داخلی را پاک می‌کند. برنامه‌های Chat نمی‌توانند با پیام به این راه‌انداز پاسخ دهند چون دیگر عضو این فضا نیستند. |
| فرمان برنامه |
کاربر فرمان برنامه Chat (مانند فرمان خط مورب، فرمان سریع، یا کنش پیام) را فراخوانی می‌کند. |
برنامه Chat به فرمان پاسخ می‌دهد. برای مثال، با پیامی پاسخ می‌دهد یا کادر گفتگویی را باز می‌کند. |
| صفحه اصلی برنامه |
کاربر برگه صفحه اصلی را در فضای پیام مستقیم یک‌به‌یک با برنامه Chat باز می‌کند یا با ابزاره‌ای در کارت صفحه اصلی تعامل برقرار می‌کند. |
برنامه Chat یک شیء
RenderActions برمی‌گرداند که کارت صفحه اصلی را ارسال می‌کند
(pushCard) یا کارت صفحه اصلی نمایش‌داده‌شده را به‌روز می‌کند
(updateCard).
|
شما نقاط پایانی یا توابع بازخوانی را برای این راه‌اندازها در کنسول Google Cloud در صفحه پیکربندی Chat API پیکربندی می‌کنید. برای دستورالعمل‌های گام‌به‌گام، پیکربندی Google Chat API را ببینید.
پیکربندی پیام‌واره‌های آغازگر
پیام‌واره‌های آغازگر به کاربران کمک می‌کنند تا وقتی پیام مستقیم یک‌به‌یک خالی با برنامه شما باز می‌کنند، عملکرد برنامه Chat شما را کشف کنند. می‌توانید تا سه پیام‌واره آغازگر را پیکربندی کنید.
برای افزودن و پیکربندی پیام‌واره‌های آغازگر:
در کنسول Google Cloud، به صفحه پیکربندی Chat API بروید:
در بخش ویژگی‌های تعاملی، پیام‌واره‌های آغازگر را پیدا کنید و روی افزودن پیام‌واره کلیک کنید.
در فیلد رتبه (۱-۳)، عددی از
1تا3وارد کنید تا ترتیب نمایش را مشخص کنید.در بخش انتخاب نوع، نحوه رفتار پیام‌واره را انتخاب کنید:
- پیام‌واره نوشتاری: وقتی کاربر روی تراشه پیام‌واره کلیک می‌کند، نوار نوشتن را با نوشتار ازپیش‌تعریف‌شده پر می‌کند.
- فرمان خط مورب: با کلیک کردن روی آن، فرمان خط مورب یا فرمان سریع ثبت‌شده‌ای اجرا می‌شود. فرمان‌هایی که به آرگومان‌های اضافی نیاز دارند قابل‌انتخاب نیستند.
پیام‌واره را براساس نوع انتخابی‌تان پیکربندی کنید:
اگر «پیام‌واره نوشتاری» را انتخاب کرده‌اید:
- در عنوان، عنوان پیام‌واره‌ای را که در تراشه نمایش داده می‌شود وارد کنید (حداکثر ۳۰ نویسه).
- در نوشتار پیام‌واره، نوشتاری را که در نوار نوشتن پر شده است وارد کنید (حداکثر ۶۰ نویسه).
- اختیاری: عنوان‌ها و نوشتار بومی‌سازی‌شده را برای کاربران به زبان‌های دیگر اضافه کنید:
- در بخش پیام‌واره‌های بومی‌سازی‌شده، روی افزودن زبان کلیک کنید.
- در زبان، یکی از زبان‌های پشتیبانی‌شده را از منو کرکره‌ای انتخاب کنید.
- در عنوان بومی‌سازی‌شده، عنوان بومی‌سازی‌شده را وارد کنید (حداکثر ۳۰ نویسه).
- در نوشتار پیام‌واره بومی‌سازی‌شده، نوشتار پیام‌واره بومی‌سازی‌شده را وارد کنید (حداکثر ۶۰ نویسه).
- درصورت نیاز، این مراحل را برای افزودن زبان‌های بیشتر تکرار کنید.
اگر «خط فرمان» را انتخاب کردید:
- در فرمان خط مورب / فرمان سریع، فرمان را از منو کرکره‌ای انتخاب کنید.
روی تمام کلیک کنید، و سپس روی ذخیره در پایین صفحه کلیک کنید.
رسیدگی به تلاش‌های مجدد تماس HTTP به سرویس شما
اگر درخواست HTTPS به سرویس شما ناموفق باشد (مثلاً به‌دلیل اتمام مهلت، قطعی موقت شبکه، یا کد وضعیت HTTPS غیر 2xx)، ممکن است Google Chat چند بار در عرض چند دقیقه ارسال را تکرار کند (اما این تضمین‌شده نیست). درنتیجه، ممکن است برنامه Chat در برخی شرایط یک رویداد را چند بار دریافت کند. اگر درخواست باموفقیت تکمیل شود اما بار داده پاسخ نامعتبر برگرداند، Google Chat درخواست را تکرار نمی‌کند.
اشیای رویداد
وقتی راه‌انداز Chat اجرا می‌شود یا وقتی کاربران Chat با میانای کاربر برنامه Chat تعامل برقرار می‌کنند (مثلاً روی دکمه‌ای کلیک می‌کنند یا کادر گفتگویی را ارسال می‌کنند)، برنامه‌های Chat شیء رویداد دریافت می‌کنند. شیء رویداد به شما امکان می‌دهد از داده‌های تعامل برای پاسخ دادن یا به‌روزرسانی واسط کاربر استفاده کنید.
در سال ۲۰۲۵، برنامه‌های Google Chat برای پشتیبانی از رویدادهای برافزاها گسترش یافتند و این از ژوئیه ۲۰۲۵ برای برنامه‌های Chat جدید پیش‌فرض بوده است. در سراسر اسناد Chat، رویدادهای برافزا نوع رویداد استانداردی است که در راهنماها و نمونه‌های کد نشان داده می‌شود. اسناد مربوط به رویدادهای Chat (برای برنامه‌های Chat که برافزاهای Google Workspace نیستند) به بخش‌های جمع‌شده تقسیم شده‌اند (برای مثال، برنامه‌های Chat که برافزا نیستند: دریافت و پاسخ به رویدادهای تعامل).
تعیین انواع رویداد و پاسخ
وقتی برنامه Chat شما شیء رویدادی را دریافت می‌کند، ساختار بار و نحوه پاسخ دادن شما به این بستگی دارد که آیا برنامه Chat شما به‌عنوان برافزای Google Workspace پیکربندی شده است یا نه.
برای تأیید اینکه برنامه‌تان چه نوع شیء رویدادی دریافت می‌کند و چگونه باید پاسخ دهد، پیکربندی برنامه‌تان را بااستفاده از جدول زیر بررسی کنید:
| نوع برنامه | رویدادهای برافزاها را دریافت می‌کند (پیش‌فرض برای برنامه‌های جدید ایجادشده پس‌از ژوئیه ۲۰۲۵) |
رویدادهای Chat را دریافت می‌کند (پیش‌فرض قبلی، پیش‌از ژوئیه ۲۰۲۵) |
|---|---|---|
| برنامه‌های Apps Script فایل مانیفست ( appsscript.json) را
بررسی کنید |
شیء chat در addOns پیکربندی شده است:
|
شیء chat در ریشه مانیفست پیکربندی شده است:
|
| برنامه‌های دیگر صفحه پیکربندی Google Chat API را بررسی کنید |
چارگوش انتخاب «ساختن این برنامه 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 باید ظرف ۳۰ ثانیه پاسخ دهد و پاسخ باید برای فضایی که تعامل در آن رخ داده است اعمال شود. این پاسخ‌های همگام به اصالت‌سنجی نیاز ندارند. اگر برنامه Chat شما به بیش‌از ۳۰ ثانیه زمان نیاز دارد یا باید خارج از فضا عمل کند، اصالت‌سنجی را راه‌اندازی کنید و بااستفاده از 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
در Apps Script بسازند.
| پاسخ برنامه Chat | کنش الزامی برای بازگشت (JSON) | کنش الزامی برای بازگشت (Apps Script) |
|---|---|---|
| پیامی ارسال کنید یا پیامی را به‌روز کنید. | 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 با @نام می‌برند یا به آن پیام مستقیم ارسال می‌کنند.
- افزوده‌شده به راه‌اندازهای فضا، مثلاً وقتی کاربران برنامه Chat را از Google Workspace Marketplace نصب می‌کنند یا آن را به فضایی اضافه می‌کنند.
- راه‌اندازهای فرمان برنامه، مثلاً وقتی کاربران فرمان خط مورب یا فرمان سریع را فراخوانی می‌کنند.
- کلیک‌های دکمه از کارت‌ها در پیام‌ها یا کادرهای گفتگو. برای مثال، وقتی کاربران اطلاعاتی را وارد می‌کنند و روی ارسال کلیک می‌کنند.
برنامه‌های 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();
}
}
Apps Script
/**
* 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 API را فراخوانی کنند تا هرکدام از کارهای زیر را انجام دهند:
- پاسخ دادن به تعامل پس‌از ۳۰ ثانیه (مثلاً پس‌از تکمیل کردن یک تکلیف طولانی‌مدت).
- ارسال پیام طبق زمان‌بندی، یا ارسال اعلان درباره تغییرات منابع خارجی.
- انجام تکالیف خارج از فضایی که تعامل در آن صورت گرفته است.
- تکالیفی را در Chat انجام دهید که به‌عنوان کنش‌های همگام دردسترس نیستند، مثل فهرست کردن فضاها یا افزودن اعضا به فضا.
- انجام تکالیف ازطرف کاربر Chat (که به اصالت‌سنجی کاربر نیاز دارد).
هنگام پاسخ دادن به تعامل پس‌از ۳۰ ثانیه، برای جلوگیری از نمایش پیام خطای سَمت کاربر مبنی بر اینکه برنامه Chat شما پاسخ نمی‌دهد، باید دریافت شیء رویداد را ظرف ۳۰ ثانیه با برگرداندن پاسخ خالی تأیید کنید:
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 "{}";
}
Apps Script
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 نیستند، به‌جای
اشیاء رویداد برافزای Google Workspace (EventObject)،
رویدادهای تعامل Chat API (Event)
دریافت می‌کنند و با برگرداندن منبع
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 به فرمان درباره با پیامی پاسخ می‌دهد که کارهایی را که برنامه Chat می‌تواند انجام دهد توضیح می‌دهد. |
برای دیدن همه رویدادهای تعامل پشتیبانی‌شده و نمونه‌های بار JSON،
انواع رویدادهای تعامل برنامه Chat
و
EventType سند مرجع را ببینید.
رویدادهای تعاملی از کادرهای گفتگو
اگر برنامه Chat شما که برافزا نیست کادرهای گفتگو را باز می‌کند، رویداد تعامل حاوی اطلاعات اضافی زیر است که می‌توانید از آن برای پردازش پاسخ استفاده کنید:
- فیلد
isDialogEventرویtrueتنظیم شده است. DialogEventType(REQUEST_DIALOG،SUBMIT_DIALOG، یاCANCEL_DIALOG) مشخص می‌کند که آیا تعامل باعث باز شدن کادر گفتگو می‌شود، اطلاعاتی را از کادر گفتگو ارسال می‌کند، یا کادر گفتگو را می‌بندد.
پیکربندی برنامه Chat که برافزا نیست برای دریافت رویدادهای تعاملی
در کنسول Google Cloud، به صفحه پیکربندی Chat API بروید:
در بخش ویژگی‌های تعاملی، ساخت این برنامه Chat به‌عنوان برافزای Google Workspace را پاک کنید و عملکرد، یک نقطه پایانی تنظیمات اتصال (نشانی وب نقطه پایانی HTTP، Apps Script، نام موضوع 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();
}
}
}
Apps Script
/**
* 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`.'
};
}