رابط های چت گوگل بسازید

این صفحه مروری بر نحوه ساخت رابط‌های کاربری (UI) برای افزونه‌های Google Workspace که Google Chat را توسعه می‌دهند، ارائه می‌دهد.

برای ساخت رابط کاربری برای برنامه‌های چت، از اجزای افزونه زیر استفاده می‌کنید:

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

برنامه‌های چت می‌توانند کارت‌ها را در رابط‌های کاربری زیر ایجاد و نمایش دهند:

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

محرک‌ها

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

تریگرها روش‌های خاصی هستند که کاربران با استفاده از رابط کاربری چت، یک برنامه چت را فراخوانی می‌کنند، مانند استفاده از @mentions یا دستورات برنامه.

جدول زیر محرک‌های چت، توضیحات و نحوه‌ی واکنش معمول برنامه‌های چت را نشان می‌دهد:

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

برای پاسخ به یک تریگر، به راهنماهای زیر مراجعه کنید:

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

اشیاء رویداد

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

برای آشنایی با نحوه‌ی مدیریت اشیاء رویداد، به راهنماهای زیر مراجعه کنید:

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

برای کسب اطلاعات بیشتر در مورد اشیاء رویداد افزونه در Chat و سایر برنامه‌های Google Workspace، به اشیاء رویداد مراجعه کنید.

اقدامات چت

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

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

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

برای پاسخ به تعاملات کاربر، برنامه‌های چت باید شیء رویداد مربوطه را مدیریت کرده و یکی از اشیاء JSON زیر را برگردانند:

• DataActions : داده‌های Google Workspace را ایجاد یا به‌روزرسانی می‌کند. برای ارسال یا به‌روزرسانی پیام‌های چت ، شیء باید حاوی نشانه‌گذاری باشد که تغییرات داده‌های Message را تعریف می‌کند و به صورت chatDataActionMarkup نمایش داده می‌شود.
• RenderActions : یک کادر محاوره‌ای ایجاد یا به‌روزرسانی می‌کند یا پیشنهادهای ورودی برای یک منوی چندگزینه‌ای ارائه می‌دهد.
• AuthorizationError : به کاربرانی که کارت مجوز دارند، دستور می‌دهد تا وارد سیستم شوند یا در سرویسی که خارج از گوگل است، احراز هویت شوند. در چت، فقط کارت مجوز پایه پشتیبانی می‌شود.

با استفاده از API چت گوگل پاسخ دهید

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

• بعد از 30 ثانیه به یک تعامل پاسخ دهید.
• وظایفی را خارج از فضایی که تعامل در آن رخ داده است، انجام دهید.
• انجام کارهایی در چت که به عنوان اقدامات افزونه در دسترس نیستند. به عنوان مثال، فهرست کردن فضاهایی که یک کاربر یا برنامه چت عضو آن است، یا اضافه کردن کاربران به فضا.
• انجام وظایف از طرف کاربر چت (که نیاز به احراز هویت کاربر دارد).

هنگام پاسخ دادن به یک رویداد تعاملی پس از 30 ثانیه، برای جلوگیری از نمایش پیام خطای کاربر مبنی بر عدم پاسخگویی برنامه چت، باید دریافت رویداد تعاملی را ظرف 30 ثانیه با ارسال یک پاسخ خالی، همانطور که در اینجا نشان داده شده است، تأیید کنید:

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({});
};

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، به نمای کلی Chat API مراجعه کنید.

مباحث مرتبط

• محرک‌های افزونه‌های Google Workspace
• پیکربندی برنامه چت گوگل
• اشیاء رویداد
• اقدامات افزونه
• ارسال پیام‌های گوگل چت
• باز کردن پنجره‌های محاوره‌ای تعاملی
• پیش‌نمایش لینک‌ها در پیام‌های گوگل چت
• مرور کلی API چت