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

این صفحه نمای کلی از نحوه ایجاد رابط های کاربری (UI) برای افزونه های Google Workspace که گپ Google را گسترش می دهند، ارائه می دهد.

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

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

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

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

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

محرک ها

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

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

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

ماشه توضیحات پاسخ معمولی
به فضا اضافه شد

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

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

یک کاربر با برنامه چت از طریق پیام به یکی از روش های زیر تعامل برقرار می کند:

  • پیامی را در فضای پیام مستقیم (DM) با برنامه چت ارسال می کند.
  • @در هر فضایی از برنامه Chat نام می برد.
  • پیامی ارسال می‌کند که حاوی پیوندی است که با الگوی URL برای پیش‌نمایش پیوند مطابقت دارد.
  • متن را در منوی چند انتخابی ویجت selectionInput تایپ می کند.
 برنامه چت بر اساس محتوای پیام پاسخ می دهد. به عنوان مثال، یک برنامه Chat با پیامی به دستور /about پاسخ می دهد که وظایفی را که برنامه Chat می تواند انجام دهد را توضیح می دهد.
از فضا حذف شد

یک کاربر برنامه Chat را از یک فضا حذف می‌کند، یا یک سرپرست Google Workspace، برنامه Chat را برای کاربر در سازمانش حذف نصب می‌کند.

کاربران نمی‌توانند برنامه‌های چت را که توسط سرپرستشان نصب شده است حذف کنند. اگر کاربری قبلاً برنامه Chat را نصب کرده باشد، برنامه Chat بدون در نظر گرفتن اینکه آیا سرپرست Google Workspace سعی در حذف نصب داشته باشد، همچنان نصب می‌شود.

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

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

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

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

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

اشیاء رویداد

این بخش تمام عناصر اشیاء رویداد Chat را تعریف و توضیح می دهد. برای کسب اطلاعات بیشتر، اشیاء رویداد را ببینید.

شی رویداد
commonEventObject object ( CommonEventObject )
یک شی حاوی اطلاعات مشترک برای همه اشیاء رویداد، صرف نظر از برنامه میزبان.
chat object ( Chat )
یک شی حاوی تمام اطلاعات در مورد تعاملات چت.

چت کنید

چت کنید
chat.user object ( User )
کاربر چت که با برنامه چت تعامل داشت.
chat.space object ( Space )
فضای چت که در آن کاربر با برنامه چت تعامل داشت.
chat.eventTime

string ( Timestamp format)

زمانی که تعامل رخ داد.

payload میدان اتحادیه

payload می تواند تنها یکی از موارد زیر باشد:

chat.messagePayload

object ( MessagePayload )

باری که برنامه‌های چت از راه‌انداز پیام دریافت می‌کنند.

chat.addedToSpacePayload

object ( AddedToSpacePayload )

محموله‌ای که برنامه‌های چت از یک راه‌انداز اضافه شده به فضا دریافت می‌کنند.

chat.removedFromSpacePayload

object ( RemovedFromSpacePayload )

محموله‌ای که برنامه‌های چت از راه‌انداز Removed from space دریافت می‌کنند.

chat.buttonClickedPayload

object ( ButtonClickedPayload )

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

chat.widgetUpdatedPayload

object ( WidgetUpdatedPayload )

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

شی CommonEventObject.parameters['autocomplete_widget_query'] حاوی مقدار رشته ای است که کاربر در منو تایپ می کند.

chat.appCommandPayload

object ( AppCommandPayload )

زمانی که کاربر از دستوری از برنامه چت استفاده می‌کند، برنامه‌های چت دریافت می‌کنند.

بار

بسته به نوع تعامل، رویداد حاوی یک بار با یک یا چند منبع Chat API است.

MessagePayload
chat.messagePayload.message object ( Message )
پیام Chat که رویداد را آغاز کرد.
chat.messagePayload.space object ( Space )
فضای چت که در آن کاربر پیامی را ارسال می کند که برنامه چت را فراخوانی می کند.

AddedToSpacePayload
chat.addedToSpacePayload.space object ( Space )
فضای چت که کاربر برنامه چت را به آن اضافه یا نصب کرده است.

وقتی سرپرستان برنامه‌های چت را نصب می‌کنند، قسمت space.adminInstalled روی true تنظیم می‌شود.

chat.addedToSpacePayload.interactionAdd boolean
اینکه آیا کاربر برنامه Chat را با استفاده از یک پیام به یک فضا اضافه می‌کند یا خیر. برای مثال، @ از برنامه Chat نام می برد یا از دستور اسلش استفاده می کند. اگر true ، Chat یک شی رویداد دیگر را با یک messagePayload ارسال می کند که حاوی اطلاعاتی درباره پیام است.

RemovedFromSpacePayload
chat.removedFromSpacePayload.space object ( Space )
فضای چت که کاربر برنامه چت را از آن حذف یا حذف نصب کرد.

وقتی سرپرستان برنامه‌های چت را حذف نصب می‌کنند، قسمت space.adminInstalled روی false تنظیم می‌شود.

ButtonClickedPayload
chat.buttonClickedPayload.message object ( Message )
پیام چت که حاوی دکمه ای است که کاربر روی آن کلیک کرده است.
chat.buttonClickedPayload.space object ( Space )
فضای چت که در آن کاربر روی یک دکمه از پیام برنامه چت کلیک کرد.
chat.buttonClickedPayload.isDialogEvent boolean
آیا کاربر روی دکمه برای تعامل با یک گفتگو کلیک کرده است یا خیر.
chat.buttonClickedPayload.dialogEventType enum ( DialogEventType )
اگر isDialogEvent true باشد، نوع تعامل در یک گفتگو.

Enum DialogEventType .

مقدار dialogEventType می تواند تنها یکی از موارد زیر باشد:

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

WidgetUpdatedPayload
chat.widgetUpdatedPayload.space object ( Space )
فضای چت که در آن تعامل رخ داده است.

AppCommandPayload
chat.appCommandPayload.appCommandMetadata object ( AppCommandMetadata )
فراداده در مورد اینکه کاربر از کدام دستور استفاده کرده است و چگونه فرمان را راه اندازی کرده است.
chat.appCommandPayload.space object ( Space )
فضای چت که در آن کاربر از دستور استفاده کرده است.
chat.appCommandPayload.thread object ( Thread )
اگر تعامل در یک رشته اتفاق افتاده است، موضوع چت که در آن کاربر از دستور استفاده کرده است.
chat.appCommandPayload.message object ( Message )
پیامی که کاربر با دستور اسلش ارسال کرده است.
chat.appCommandPayload.configCompleteRedirectUri string
اگر مجوز یا پیکربندی برای دستور مورد نیاز است، یک URL برای هدایت مجدد کاربر پس از تکمیل فرآیند خارج از Google Chat.
chat.appCommandPayload.isDialogEvent boolean
این که آیا دستور یک گفتگو را باز می کند یا خیر.
chat.appCommandPayload.dialogEventType enum ( DialogEventType )
نوع تعامل با دیالوگ.

Enum DialogEventType .

مقدار dialogEventType می تواند تنها یکی از موارد زیر باشد:

TYPE_UNSPECIFIED مقدار پیش فرض نامشخص
REQUEST_DIALOG کاربر یک گفتگو درخواست می کند. به عنوان مثال، آنها از یک دستور اسلش استفاده می کنند یا روی دکمه ای از یک پیام کلیک می کنند.
SUBMIT_DIALOG کاربر روی یک عنصر تعاملی در یک گفتگو کلیک می کند. به عنوان مثال، یک کاربر اطلاعات را در یک گفتگو پر می کند و برای ارسال اطلاعات روی دکمه ای کلیک می کند.
فراداده فرمان برنامه
AppCommandMetadata
chat.appCommandPayload.appCommandMetadata.appCommandId

string ( int64 format)

شناسه فرمان

chat.appCommandPayload.appCommandMetadata.appCommandType enum ( AppCommandType )
نوع فرمان.

Enum AppCommandType .

مقدار AppCommandType می تواند تنها یکی از موارد زیر باشد:

APP_COMMAND_TYPE_UNSPECIFIED مقدار پیش فرض نامشخص
SLASH_COMMAND کاربر با ارسال پیامی که با علامت اسلش / شروع می شود از دستور استفاده می کند.

اقدامات چت

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

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

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

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

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

با استفاده از Google Chat API پاسخ دهید

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

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

برای آشنایی با احراز هویت و تماس با Chat API، به نمای کلی Chat API مراجعه کنید.