دریافت و پاسخ دادن به تعاملات کاربر

این صفحه شرح می‌دهد که برنامه Google Chat شما چگونه می‌تواند تعاملات کاربر را در Google Chat دریافت کند و به آن‌ها پاسخ دهد.

برای ساختن میاناهای تعاملی برای برنامه‌های Chat، از مؤلفه‌های زیر استفاده می‌کنید:

  • راه‌اندازها: روش‌هایی که کاربران Google Chat می‌توانند برنامه Chat را فراخوانی کنند، مثل افزودن آن به فضا یا ارسال پیام به آن.
  • اشیاء رویداد: داده‌هایی که برنامه‌های Chat از راه‌اندازها یا تعامل‌های میانای کاربر دریافت می‌کنند.
  • کنش‌ها: روش‌هایی که برنامه‌های Chat می‌توانند به تعاملات پاسخ دهند، مانند ارسال پیام یا برگرداندن میانای کاربر مبتنی بر کارت.
برنامه Chat شیء رویدادی را از راه‌انداز «افزوده‌شده به فضا» دریافت می‌کند
شکل ۱: وقتی کاربر برنامه Chat را به فضایی اضافه می‌کند، راه‌انداز افزوده‌شده به فضا فعال می‌شود و شیء رویداد ارسال می‌کند. برای پاسخ دادن با پیام، برنامه Chat شیء رویداد را مدیریت می‌کند و کنشی را برمی‌گرداند که پیام را ایجاد می‌کند.

برنامه‌های Chat می‌توانند به روش‌های زیر میاناهای مختلفی بسازند و نمایش دهند:

  • پیام‌هایی که می‌توانند حاوی نوشتار، کارت‌های ایستا یا تعاملی، و دکمه‌های جانبی باشند.
  • صفحه‌های اصلی (صفحه اصلی برنامه) که در برگه صفحه اصلی پیام‌های مستقیم دونفره با برنامه Chat نشان داده می‌شود.
  • چارگوش‌های گفتگو که کارت‌هایی هستند که در پنجره جدیدی باز می‌شوند و معمولاً از کاربران می‌خواهند اطلاعاتی را ارسال کنند.
  • پیش‌نمایش‌های پیوند که کارت‌هایی هستند که اطلاعات مربوط به سرویس خارجی را پیش‌نمایش می‌کنند.

پیش‌نیازها

نحوه عملکرد تعامل‌های کاربر

وقتی کاربر با برنامه Chat تعامل برقرار می‌کند، Google Chat راه‌انداز پیکربندی‌شده‌ای را فرامی‌خواند و شیء رویدادی را به نقطه پایانی یا تابع برنامه Chat شما ارسال می‌کند. برنامه Chat شما شیء رویداد را پردازش می‌کند و می‌تواند کنش را به‌طور هم‌زمان ظرف ۳۰ ثانیه برگرداند یا بااستفاده از Chat API به‌طور ناهم‌زمان پاسخ دهد.

نمودار زیر نشان می‌دهد که برنامه‌های Google Chat چگونه تعاملات کاربر را پردازش می‌کنند و به آن‌ها پاسخ می‌دهند:

معماری نحوه پردازش تعامل‌های کاربر توسط برنامه‌های Google Chat.

راه‌اندازها

راه‌اندازها روش‌های خاصی هستند که کاربران بااستفاده از میانای کاربر Chat، مثلاً بااستفاده از نامبری با @یا فرمان‌های برنامه، برنامه Chat را فرامی‌خوانند.

جدول زیر راه‌اندازهای Chat، شرح، و نحوه پاسخ معمول برنامه‌های Chat را نشان می‌دهد:

راه‌انداز شرح پاسخ معمول
به فضا اضافه شد

کاربری برنامه Chat را به فضایی اضافه می‌کند، یا سرپرست Google Workspace برنامه Chat را در فضاهای پیام مستقیم برای کاربران سازمانش نصب می‌کند. برای آشنایی با برنامه‌های Chat نصب‌شده توسط سرپرستان، به نصب برنامه‌های Marketplace در دامنه‌تان در سند «راهنمای سرپرست Google Workspace» مراجعه کنید.

برنامه Chat پیام آماده‌سازی ارسال می‌کند که توضیح می‌دهد چه کاری انجام می‌دهد و کاربران در فضا چگونه می‌توانند با آن تعامل داشته باشند.
ارسال پیام

کاربر به یکی از روش‌های زیر با برنامه Chat در پیام تعامل می‌کند:

  • پیامی را در فضای پیام مستقیم (DM) با برنامه Chat ارسال می‌کند.
  • برنامه Chat را در هر نوع فضایی با @ نام می‌برد.
  • پیامی ارسال می‌کند که حاوی پیوندی است که با الگوی نشانی وب برای پیش‌نمایش‌های پیوند مطابقت دارد.
  • نوشتار را در منو چندانتخابی selectionInput ابزاره تایپ می‌کند.
برنامه 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 شما باز می‌کنند، عملکرد آن را کشف کنند. می‌توانید تا سه پیام‌واره آغازگر پیکربندی کنید.

برای افزودن و پیکربندی پیام‌واره‌های آغازگر:

  1. در کنسول Google Cloud، به صفحه پیکربندی Chat API بروید:

    رفتن به صفحه پیکربندی Chat API

  2. در بخش ویژگی‌های تعاملی، پیام‌واره‌های آغازگر را پیدا کنید و روی افزودن پیام‌واره یا فرمان پیش‌فرض کلیک کنید.

  3. در فیلد رتبه (۱-۳)، عددی از 1 تا 3 وارد کنید تا ترتیب نمایش را مشخص کنید. هر پیام‌واره پیکربندی‌شده باید رتبه یکتایی داشته باشد.

  4. در بخش انتخاب نوع، نحوه رفتار پیام‌واره را انتخاب کنید:

    • پیام‌واره نوشتاری: وقتی کاربر روی تراشه پیام‌واره‌دهی کلیک می‌کند، نوار نوشتن را با نوشتار ازپیش‌تعریف‌شده پر می‌کند.
    • فرمان: فرمان خط مورب یا فرمان سریع ثبت‌شده‌ای را هنگام کلیک کردن اجرا می‌کند. کنش‌های پیام را نمی‌توان به پیام‌واره‌های آغازگر نگاشت کرد.
  5. پیام‌واره را براساس نوع انتخابتان پیکربندی کنید:

    • اگر «پیام‌واره نوشتاری» را انتخاب کرده‌اید:

      1. در عنوان، عنوان پیام‌واره نمایش‌داده‌شده در تراشه را وارد کنید (حداکثر ۳۰ نویسه). عنوان نمی‌تواند حاوی کج‌خط یا واکج‌خط باشد.
      2. در نوشتار پیام‌واره، نوشتاری را که در نوار نوشتن پر شده است وارد کنید (حداکثر ۶۰ نویسه). نوشتار پیام‌واره نباید حاوی کج‌خط یا واکج‌خط باشد.
      3. اختیاری: عنوان‌ها و نوشتار بومی‌سازی‌شده را برای کاربران به زبان‌های دیگر اضافه کنید:
      4. در بخش پیام‌واره‌های بومی‌سازی‌شده، روی افزودن زبان کلیک کنید.
      5. در بخش زبان، یکی از زبان‌های پشتیبانی‌شده را از منو انتخاب کنید.
      6. در عنوان بومی‌سازی‌شده، عنوان بومی‌سازی‌شده را تا ۳۰ نویسه وارد کنید.
      7. در نوشتار بومی‌سازی‌شده، نوشتار پیام‌واره بومی‌سازی‌شده را تا ۶۰ نویسه وارد کنید.
      8. درصورت نیاز، این مراحل را برای افزودن زبان‌های بیشتر تکرار کنید.
    • اگر «فرمان» را انتخاب کردید:

      1. در شناسه فرمان، فرمان را از منو انتخاب کنید.
  6. روی تمام کلیک کنید، و سپس روی ذخیره در پایین صفحه کلیک کنید.

رسیدگی به تلاش‌های مجدد تماس 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 پیکربندی شده است:
{
  "addOns": {
    "chat": {}
  }
}
شیء chat در ریشه مانیفست پیکربندی شده است:
{
  "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 شما فعال باشد، شیء 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 باید ظرف ۳۰ ثانیه پاسخ دهد و پاسخ باید برای فضایی که تعامل در آن رخ داده است اعمال شود. این پاسخ‌های همگام به اصالت‌سنجی نیاز ندارند. اگر برنامه 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 را ببینید.

برنامه‌های 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 که برافزا نیست فعال باشد، فیلد سطح بالای space رویداد تعامل شامل space.sessionState (تنظیم‌شده روی THREAD) و space.sessionEnableTime می‌شود، و message.thread یا thread رشته جلسه را شناسایی می‌کند.

پیکربندی برنامه Chat که برافزا نیست برای دریافت رویدادهای تعاملی

  1. در کنسول Google Cloud، به صفحه پیکربندی Chat API بروید:

    رفتن به صفحه پیکربندی Chat API

  2. در بخش ویژگی‌های تعاملی، ساخت این برنامه Chat به‌عنوان برافزای Google Workspace را پاک کنید و عملکرد، یک نقطه پایانی تنظیمات اتصال (نشانی وب نقطه پایانی HTTP،‏ Apps Script، نام موضوع 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();
    }
  }
}

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