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

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

در این صفحه نحوه انجام کارهای زیر توضیح داده شده است:

• برنامه چت خود را برای دریافت رویدادهای تعامل پیکربندی کنید.
• رویداد تعامل را در زیرساخت خود پردازش کنید.
• در صورت لزوم، به رویدادهای تعامل پاسخ دهید.

پیش نیازها

یک برنامه Google Chat که برای ویژگی‌های تعاملی فعال است. برای ایجاد یک برنامه چت تعاملی، یکی از شروع سریع زیر را بر اساس معماری برنامه ای که می خواهید استفاده کنید، انجام دهید:

• سرویس HTTP با توابع Google Cloud
• اسکریپت Google Apps
• Google Cloud Dialogflow CX
• Google Cloud Pub/Sub

انواع رویدادهای تعاملی

رویداد تعامل برنامه گپ Google نشان‌دهنده هر اقدامی است که کاربر برای فراخوانی یا تعامل با یک برنامه Chat انجام می‌دهد، مانند @ نام بردن از یک برنامه Chat یا افزودن آن به یک فضا.

هنگامی که کاربران با یک برنامه گپ تعامل می کنند، Google Chat یک رویداد تعاملی را به برنامه Chat ارسال می کند که به عنوان یک نوع Event در Chat API نشان داده می شود. برنامه چت می تواند از رویداد برای پردازش تعامل استفاده کند و به صورت اختیاری، با یک پیام پاسخ دهد.

برای هر نوع تعامل کاربر، Google Chat نوع متفاوتی از رویداد تعاملی را ارسال می‌کند که به برنامه چت شما کمک می‌کند تا هر نوع رویداد را مطابق با آن مدیریت کند. نوع رویداد تعامل با استفاده از شی eventType نشان داده می شود.

به عنوان مثال، Google Chat از نوع رویداد ADDED_TO_SPACE برای هر تعاملی استفاده می‌کند که در آن کاربر برنامه Chat را به یک فضا اضافه می‌کند، به طوری که برنامه Chat می‌تواند بلافاصله با یک پیام خوش‌آمدگویی در فضا پاسخ دهد .

شکل 1 : هنگامی که یک کاربر یک برنامه چت را به یک فضا اضافه می کند، برنامه Chat یک رویداد تعاملی ADDED_TO_SPACE را دریافت می کند که برنامه Chat برای ارسال پیام خوشامدگویی در فضا مدیریت می کند.

جدول زیر تعاملات متداول کاربر، نوع رویداد تعاملی که برنامه‌های گپ دریافت می‌کنند و نحوه پاسخگویی معمولاً برنامه‌های چت را نشان می‌دهد:

تعامل کاربر	eventType	پاسخ معمولی از یک برنامه چت
یک کاربر یک برنامه چت را با ذکر @ یا با استفاده از دستور اسلش فراخوانی می کند.	MESSAGE	برنامه چت بر اساس محتوای پیام پاسخ می دهد. به عنوان مثال، یک برنامه Chat با پیامی به دستور /about پاسخ می دهد که وظایفی را که برنامه Chat می تواند انجام دهد را توضیح می دهد.
کاربر یک برنامه چت را به یک فضا اضافه می کند.	ADDED_TO_SPACE	برنامه چت پیامی ارسال می کند که توضیح می دهد چه کاری انجام می دهد و چگونه کاربران در فضا می توانند با آن تعامل داشته باشند.
کاربر یک برنامه چت را از یک فضا حذف می کند.	REMOVED_FROM_SPACE	برنامه Chat هر گونه اعلان های ورودی را که برای فضا پیکربندی شده اند (مانند حذف یک هوک ) حذف می کند و حافظه داخلی را پاک می کند.
کاربر روی یک کارت از پیام، گفتگو یا صفحه اصلی برنامه چت، روی یک دکمه کلیک می کند.	CARD_CLICKED	برنامه چت یا هر داده ای را که کاربر ارسال کرده است پردازش و ذخیره می کند یا کارت دیگری را برمی گرداند.
یک کاربر صفحه اصلی برنامه چت را با کلیک کردن بر روی برگه صفحه اصلی در یک پیام 1:1 باز می کند.	APP_HOME	برنامه چت یک کارت استاتیک یا تعاملی را از صفحه اصلی برمی‌گرداند.
یک کاربر فرمی را از صفحه اصلی برنامه چت ارسال می کند.	SUBMIT_FORM	برنامه چت یا هر داده ای را که کاربر ارسال کرده است پردازش و ذخیره می کند یا کارت دیگری را برمی گرداند.

برای مشاهده همه رویدادهای تعامل پشتیبانی شده، به مستندات مرجع EventType مراجعه کنید.

رویدادهای تعامل از دیالوگ ها

اگر برنامه گپ شما گفتگوها را باز می کند، رویداد تعامل حاوی اطلاعات اضافی زیر است که می توانید برای پردازش پاسخ از آنها استفاده کنید:

• isDialogEvent روی true تنظیم شده است.
• DialogEventType روشن می کند که آیا تعامل باعث باز شدن یک گفتگو می شود، اطلاعات را از یک گفتگو ارسال می کند یا یک گفتگو را می بندد.

جدول زیر تعاملات رایج با دیالوگ‌ها، انواع رویداد گفتگوی مربوطه، و توضیحی در مورد نحوه پاسخگویی معمولاً برنامه‌های چت را نشان می‌دهد:

تعامل کاربر با دیالوگ	نوع رویداد گفتگو	پاسخ معمولی
یک کاربر یک درخواست گفتگو را راه اندازی می کند. به عنوان مثال، آنها از یک دستور اسلش استفاده می کنند یا روی دکمه ای از یک پیام کلیک می کنند.	REQUEST_DIALOG	برنامه چت گفتگو را باز می کند.
کاربر با کلیک بر روی یک دکمه اطلاعات را در کادر گفتگو ارسال می کند.	SUBMIT_DIALOG	برنامه چت یا به گفتگوی دیگری می رود یا برای تکمیل تعامل، گفتگو را می بندد.
یک کاربر قبل از ارسال اطلاعات از گفتگو خارج می شود یا می بندد.	CANCEL_DIALOG	در صورت تمایل، برنامه چت می‌تواند با یک پیام جدید پاسخ دهد، یا پیام یا کارتی را که کاربر گفتگو را از آن باز کرده است، به‌روزرسانی کند.

برای اطلاعات بیشتر، باز کردن گفتگوهای تعاملی را ببینید.

رویدادهای تعامل برنامه چت را دریافت کنید

این بخش نحوه دریافت و پردازش رویدادهای تعاملی را برای برنامه چت شما شرح می دهد.

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

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

برای هر یک از ویژگی‌های تعاملی که می‌خواهید بسازید، باید پیکربندی خود را در Chat API به‌روزرسانی کنید تا Google Chat بتواند رویدادهای تعاملی مرتبط را به برنامه Chat شما ارسال کند:

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

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

2. در بخش ویژگی‌های تعاملی ، تنظیمات را مرور کنید و براساس ویژگی‌هایی که می‌خواهید بسازید، به‌روزرسانی کنید:

   میدان	توضیحات
   کارکرد	مورد نیاز. مجموعه‌ای از فیلدها که نحوه تعامل برنامه چت با کاربران را تعیین می‌کند: دریافت پیام‌های ۱:۱ : کاربران می‌توانند برنامه چت را مستقیماً در چت Google پیدا کنند و پیام دهند. پیوستن به فضاها و مکالمات گروهی : کاربران می توانند برنامه چت را به فضاها و مکالمات گروهی اضافه کنند.
   تنظیمات اتصال	مورد نیاز. نقطه پایانی برای برنامه Chat که یکی از موارد زیر است: URL نقطه پایانی HTTP : یک نقطه پایانی HTTPS که میزبان اجرای برنامه چت است. Apps Script : شناسه استقرار برای پروژه Apps Script که یک برنامه Chat را پیاده سازی می کند. نام موضوع Cloud Pub/Sub : یک موضوع Pub/Sub که برنامه Chat به عنوان نقطه پایانی در آن مشترک شده است. Dialogflow : برنامه Chat را با یکپارچه سازی Dialogflow ثبت می کند. برای اطلاعات بیشتر، به ساخت برنامه گفتگوی Google Chat که زبان طبیعی را می‌فهمد، مراجعه کنید.
   دستورات اسلش	اختیاری. دستوراتی که می توانند برای کاربران در چت Google ظاهر شوند. به کاربران اجازه می‌دهد تا عملکردهای اصلی برنامه چت شما را در Google Chat ببینند و اقدام خاصی را که می‌خواهند با آن تعامل داشته باشند انتخاب کنند. برای اطلاعات بیشتر، پاسخ به دستورات اسلش را به‌عنوان برنامه چت ببینید.
   پیش نمایش پیوندها	اختیاری. الگوهای نشانی وب که برنامه چت می شناسد و محتوای اضافی را برای زمانی که کاربران پیوند می فرستند ارائه می کند. برای اطلاعات بیشتر، پیش‌نمایش پیوندها را ببینید.
   دید	اختیاری. حداکثر پنج نفر یا یک یا چند گروه Google که می‌توانند برنامه چت شما را مشاهده و نصب کنند. از این فیلد برای آزمایش برنامه چت یا اشتراک گذاری برنامه چت با تیم خود استفاده کنید. برای اطلاعات بیشتر، تست ویژگی‌های تعاملی را ببینید.

3. روی ذخیره کلیک کنید. وقتی پیکربندی برنامه گپ را ذخیره می‌کنید، برنامه گپ شما برای کاربران مشخص‌شده در سازمان Google Workspace شما در دسترس است.

برنامه چت شما اکنون برای دریافت رویدادهای تعاملی از گپ Google پیکربندی شده است.

کنترل مجدد تماس HTTP برای سرویس شما

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

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

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

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

برای پاسخگویی همزمان، یک برنامه چت باید ظرف 30 ثانیه پاسخ دهد و پاسخ باید در فضایی که تعامل رخ داده است پست شود. در غیر این صورت، برنامه چت می تواند به صورت ناهمزمان پاسخ دهد.

برای هر رویداد تعاملی، برنامه‌های گپ یک بدنه درخواست دریافت می‌کنند که بار JSON است که رویداد را نشان می‌دهد. می توانید از اطلاعات برای پردازش پاسخ استفاده کنید. برای نمونه‌هایی از بارهای رویداد، به انواع رویدادهای تعامل برنامه گپ مراجعه کنید.

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

در زمان واقعی پاسخ دهید

رویدادهای تعاملی به برنامه‌های چت اجازه می‌دهند به صورت هم‌زمان یا هم‌زمان پاسخ دهند. پاسخ های همزمان نیازی به احراز هویت ندارند.

برای پاسخگویی در زمان واقعی، برنامه چت باید یک شیء Message برگرداند. برای پاسخ دادن با یک پیام در فضای خالی، شی Message می‌تواند شامل text ، cardsV2 و اشیاء accessoryWidgets باشد. برای استفاده با انواع دیگر پاسخ ها، راهنماهای زیر را ببینید:

• گفتگوهای تعاملی را باز کنید
• پیش نمایش لینک ها
• اطلاعات پردازش ارسال شده توسط کاربران

توجه: برای رویدادهای تعامل REMOVED_FROM_SPACE ، برنامه‌های گپ نمی‌توانند با شی Message پاسخ دهند زیرا دیگر در فضا نیستند.

با پیام پاسخ دهید

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

برای ارسال پیام نوشتاری هنگامی که کاربر برنامه چت شما را به یک فضا اضافه می‌کند، برنامه چت شما به یک رویداد تعاملی ADDED_TO_SPACE پاسخ می‌دهد. برای پاسخ دادن به رویدادهای تعامل 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. An onboarding message that
 * introduces the app and helps people get started with it.
 */
exports.onMessage = function onMessage(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send(
      'Hello! This function is meant to be used in a Google Chat space.');
  }

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

اسکریپت برنامه ها

/**
 * 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. An onboarding message that
 * introduces the app and helps people get started with it.
 */
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`.'
  }
}

نمونه کد پیام متنی زیر را برمی گرداند:

به صورت ناهمزمان پاسخ دهید

گاهی اوقات برنامه‌های چت باید پس از 30 ثانیه به یک رویداد تعاملی پاسخ دهند یا کارهایی را خارج از فضایی که رویداد تعاملی ایجاد شده است انجام دهند. به عنوان مثال، یک برنامه چت ممکن است نیاز داشته باشد پس از انجام یک کار طولانی مدت به کاربر پاسخ دهد. در این حالت، برنامه‌های چت می‌توانند با تماس با Google Chat API به صورت ناهمزمان پاسخ دهند.

برای ایجاد پیام با استفاده از Chat API، به ایجاد پیام مراجعه کنید. برای راهنمایی در مورد استفاده از روش‌های دیگر Chat API، به نمای کلی Chat API مراجعه کنید.

موضوعات مرتبط

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