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

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

این صفحه نحوه انجام موارد زیر را شرح می‌دهد:

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

توجه: این راهنما نحوه ساخت یک برنامه چت تعاملی با استفاده از رویدادهای تعاملی API چت را توضیح می‌دهد. همچنین می‌توانید برنامه چت خود را به عنوان یک افزونه Google Workspace بسازید. برای کسب اطلاعات در مورد اینکه از کدام چارچوب استفاده کنید، به بخش ساخت یک برنامه چت تعاملی Google مراجعه کنید.

پیش‌نیازها

• یک حساب کاربری تجاری یا سازمانی Google Workspace با دسترسی به Google Chat .
• یک پروژه گوگل کلود ایجاد کنید .
• صفحه رضایت OAuth را پیکربندی کنید .
• فعال کردن API چت گوگل

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

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

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

برای هر نوع تعامل کاربر، گوگل چت نوع متفاوتی از رویداد تعامل را ارسال می‌کند که به برنامه چت شما کمک می‌کند تا هر نوع رویداد را متناسب با آن مدیریت کند. نوع رویداد تعامل با استفاده از شیء eventType نمایش داده می‌شود.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1. در کنسول گوگل کلود، به صفحه Chat API بروید و روی صفحه Configuration کلیک کنید:

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

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

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

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

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

مدیریت تلاش مجدد برای فراخوانی HTTP به سرویس شما

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

نود جی اس

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

پایتون

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

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

پاسخ ناهمزمان

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

برای ایجاد پیام با استفاده از Chat API، به بخش «ایجاد پیام» مراجعه کنید. برای راهنمایی در مورد استفاده از متدهای اضافی Chat API، به بخش «مرور کلی Chat API» مراجعه کنید.

مباحث مرتبط

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