برای جلوگیری از تغییر زمینه وقتی کاربران پیوندی را در Google Chat همرسانی میکنند، برنامه Chat شما میتواند با پیوست کردن کارت به پیامشان، پیوند را پیشنمایش کند. این کارت اطلاعات بیشتری ارائه میدهد و به افراد امکان میدهد مستقیماً از Google Chat اقدام کنند.
برای مثال، فضای Google Chat را تصور کنید که شامل همه نمایندگان خدمات مشتری شرکت و همچنین برنامه Chat بهنام Case-y است. کارگزاران اغلب پیوندهای پروندههای خدمات مشتری را در فضای Chat همرسانی میکنند، و هر بار که این کار را میکنند همکارانشان باید پیوند پرونده را باز کنند تا جزئیاتی مثل گیرنده تکلیف، وضعیت، و موضوع را ببینند. بههمین ترتیب، اگر کسی بخواهد مالکیت پروندهای را برعهده بگیرد یا وضعیت آن را تغییر دهد، باید پیوند را باز کند.
پیشنمایش پیوند به برنامه Chat ساکن فضا، Case-y، امکان میدهد هرگاه کسی پیوند پروندهای را همرسانی میکند، کارتی حاوی موضوع، وضعیت، و فرد واگذارشده را پیوست کند. دکمههای روی کارت به نمایندگان امکان میدهد مالکیت پرونده را بپذیرند و وضعیت را مستقیماً از جاریسازی گپ تغییر دهند.
نحوه عملکرد پیشنمایش پیوند
وقتی فردی پیوندی را به پیامش اضافه میکند، تراشهای ظاهر میشود که به او اطلاع میدهد برنامه Chat ممکن است پیوند را پیشنمایش کند.

پساز ارسال پیام، پیوند به برنامه Chat ارسال میشود، که سپس کارت را تولید و به پیام کاربر پیوست میکند.

کارت در کنار پیوند، اطلاعات بیشتری درباره پیوند ارائه میدهد، ازجمله عناصر تعاملی مانند دکمهها. برنامه Chat شما میتواند کارت پیوستشده را در پاسخ به تعاملات کاربر، مانند کلیک روی دکمه، بهروز کند.
اگر کسی نمیخواهد برنامه Chat پیوند او را با پیوست کردن کارت به پیامش پیشنمایش کند، میتواند با کلیک کردن روی در تراشه پیشنمایش از پیشنمایش جلوگیری کند. کاربران میتوانند کارت پیوستشده را در هر زمانی با کلیک کردن روی برداشتن پیشنمایش بردارند.
پیشنیازها
HTTP
برنامه Google Chat که تعاملات کاربر را دریافت و به آنها پاسخ میدهد. برای ساختن آن، شروع سریع HTTP را تکمیل کنید.
Apps Script
برنامه Google Chat که تعاملات کاربر را دریافت و به آنها پاسخ میدهد. برای ساختن یکی از آنها، راهاندازی سریع Apps Script را تکمیل کنید.
پیکربندی پیشنمایشهای پیوند
پیوندهای خاص - مانند example.com، support.example.com، و
support.example.com/cases/ - را بهعنوان الگوهای نشانی وب در صفحه پیکربندی برنامه Chat در کنسول Google Cloud ثبت کنید تا برنامه Chat بتواند پیشنمایش آنها را نشان دهد.

- کنسول Google Cloud را باز کنید.
- در کنار «Google Cloud»، روی «پیکان روبه پایین» کلیک کنید و پروژه برنامه Chat را باز کنید.
- در فیلد جستجو،
Google Chat APIرا تایپ کنید و روی Google Chat API کلیک کنید. - روی مدیریت > پیکربندی کلیک کنید.
- در بخش «پیشنمایشهای پیوند»، الگوی نشانی وبی را اضافه یا ویرایش کنید.
- برای پیکربندی پیشنمایش پیوند برای الگوی نشانی وب جدید، روی افزودن الگوی نشانی وب کلیک کنید.
- برای ویرایش پیکربندی الگوی نشانی وب موجود، روی «کلید پایینبر» کلیک کنید.
در فیلد الگوی میزبان، دامنه الگوی نشانی وب را وارد کنید. برنامه Chat پیوندهای این دامنه را پیشدید خواهد کرد.
برای اینکه برنامه Chat پیوندهای یک زیردامنه خاص، مثل
subdomain.example.com، را پیشدید کند، زیردامنه را اضافه کنید.برای اینکه برنامه Chat پیوندهای کل دامنه را پیشدید کند، نویسه عامی را با ستاره (*) بهعنوان زیردامنه مشخص کنید. برای مثال،
*.example.comباsubdomain.example.comوany.number.of.subdomains.example.comمطابقت دارد.در فیلد پیشوند مسیر، مسیری را وارد کنید تا به دامنه الگوی میزبان پیوست شود.
برای مطابقت دادن همه نشانیهای وب در دامنه الگوی میزبان، پیشوند مسیر را خالی بگذارید.
برای مثال، اگر الگوی «میزبان»
support.example.comاست، برای مطابقت دادن نشانیهای وب موارد میزبانیشده درsupport.example.com/cases/،cases/را وارد کنید.روی تمام کلیک کنید.
روی ذخیره کلیک کنید.
اکنون، هرگاه کسی پیوندی را که با الگوی نشانی وب پیشنمایش پیوند مطابقت دارد به پیامی در فضای Chat که شامل برنامه Chat شما است اضافه کند، برنامه شما پیوند را پیشنمایش میکند.
پیشنمایش پیوند
پساز پیکربندی پیشنمایش پیوند برای پیوندی معین، برنامه Chat شما میتواند پیوند را با پیوست کردن اطلاعات بیشتر به آن تشخیص دهد و پیشنمایش کند.
در فضاهای Chat که شامل برنامه Chat شما میشود، وقتی پیام کسی حاوی پیوندی باشد که با الگوی نشانی وب پیشنمای پیوند مطابقت داشته باشد، برنامه Chat شما شیء رویدادی با MessagePayload دریافت میکند.
در محتوای پیام، شیء
message.matchedUrl
(chat.messagePayload.message.matchedUrl.url) حاوی پیوندی است که
کاربر در پیام قرار داده است:
(قالب) JSON
message: {
matchedUrl: {
url: "https://support.example.com/cases/case123"
},
... // other message attributes redacted
}
با بررسی وجود فیلد matchedUrl در بار پیام رویداد MESSAGE (chat.messagePayload.message.matchedUrl.url)، برنامه Chat شما میتواند اطلاعاتی را به پیام با پیوند پیشنمایششده اضافه کند. برنامه Chat شما میتواند با پیام نوشتاری ساده پاسخ دهد یا کارت پیوست کند.
پاسخ دادن با پیامک
برای پاسخهای ساده، برنامه Chat شما میتواند پیوندی را با پاسخ دادن با پیامک ساده به پیوند پیشدید کند. این مثال پیامی را پیوست میکند که نشانی وب پیوندی را که با الگوی نشانی وب پیشنمایش پیوند مطابقت دارد تکرار میکند.
Node.js
FUNCTION_URL را با نقطه پایان HTTP که کلیکهای دکمه را مدیریت میکند جایگزین کنید.
Python
FUNCTION_URL را با نقطه پایان HTTP که کلیکهای دکمه را مدیریت میکند جایگزین کنید.
جاوا
FUNCTION_URL را با نقطه پایانی HTTP که کلیکهای دکمه را مدیریت میکند جایگزین کنید.
Apps Script
کارتی را که پیشنمایش پیوند است پیوست کنید
برای پیوست کردن کارت به پیوند پیشنمایششده،
کنش DataActions را با
شیء ChatDataActionMarkup از نوع
UpdateInlinePreviewAction برگردانید.
در مثال زیر، برنامه Chat کارت پیشنمایشی
به پیامهایی که حاوی الگوی نشانی وب support.example.com هستند اضافه میکند.

Node.js
FUNCTION_URL را با نقطه پایانی HTTP که کلیکهای دکمه را مدیریت میکند جایگزین کنید.
Python
FUNCTION_URL را با نقطه پایان HTTP که کلیکهای دکمه را مدیریت میکند جایگزین کنید.
جاوا
FUNCTION_URL را با نقطه پایان HTTP که کلیکهای دکمه را مدیریت میکند جایگزین کنید.
Apps Script
بهروزرسانی کارت پیشنمایش پیوند
وقتی کاربران با کارت پیشنمایش پیوند تعامل برقرار میکنند، مثلاً روی دکمهای در کارت کلیک میکنند، برنامه Chat شما میتواند کارت پیشنمایش پیوند را بهروز کند.
برای بهروزرسانی کارت، برنامه Chat شما باید
کنش DataActions را با
یکی از اشیاء ChatDataActionMarkup زیر برگرداند:
- اگر کاربر پیام را ارسال کرده است،
UpdateMessageActionشیء را برگردانید. - اگر برنامه Chat پیام را ارسال کرده است،
UpdateInlinePreviewActionشیء را برگردانید.
برای تعیین اینکه چه کسی پیام را ارسال کرده است، از محتوای رویداد
(buttonClickedPayload)
استفاده کنید تا بررسی کنید که آیا فرستنده (message.sender.type) روی HUMAN (کاربر) یا
BOT (برنامه Chat) تنظیم شده است یا نه.
مثال زیر نشان میدهد که چگونه برنامه Chat هرگاه کاربری روی دکمه Assign to Me (به من واگذار شود) کلیک میکند، پیشنمایش پیوند را با بهروزرسانی فیلد Assignee (گیرنده واگذاری) کارت و غیرفعال کردن دکمه بهروز میکند.

Node.js
FUNCTION_URL را با نقطه پایانی HTTP که کلیکهای دکمه را مدیریت میکند جایگزین کنید.
Python
FUNCTION_URL را با نقطه پایان HTTP که کلیکهای دکمه را مدیریت میکند جایگزین کنید.
جاوا
FUNCTION_URL را با نقطه پایانی HTTP که کلیکهای دکمه را مدیریت میکند جایگزین کنید.
Apps Script
محدودیتها و ملاحظات
هنگام پیکربندی پیشنمایش پیوند برای برنامه Chat، این محدودیتها و ملاحظات را درنظر بگیرید:
- هر برنامه Chat از پیشنمایش پیوند برای حداکثر ۵ الگوی نشانی وب پشتیبانی میکند.
- برنامههای Chat یک پیوند در هر پیام را پیشنمایش میکنند. اگر چندین پیوند پیشنمایششدنی در یک پیام وجود داشته باشد، فقط اولین پیوند پیشنمایششدنی پیشنمایش میشود.
- برنامههای گپ فقط پیوندهایی را پیشنمایش میکنند که با
https://شروع میشوند، بنابراینhttps://support.example.com/cases/پیشنمایش میشود، اماsupport.example.com/cases/پیشنمایش نمیشود. - مگر اینکه پیام شامل اطلاعات دیگری باشد که به برنامه Chat ارسال میشود، مانند فرمان خط مورب، فقط نشانی وب پیوند توسط پیشنمایش پیوند به برنامه Chat ارسال میشود.
- اگر کاربری پیوند را پست کند، برنامه Chat فقط درصورتی میتواند کارت پیشنمایش پیوند را بهروز کند که کاربران با کارت تعامل داشته باشند، مثلاً روی دکمه کلیک کنند. نمیتوانید روش
update()«میانای برنامهسازی کاربردی Chat» را در منبعMessageبرای بهروزرسانی ناهمزمان پیام کاربر فراخوانی کنید. - برنامههای Chat باید پیوندها را برای همه افراد در فضا پیشدید کنند، بنابراین
پیام باید فیلد
privateMessageViewerرا حذف کند.
اشکالزدایی پیشنمایشهای پیوند
همزمان با پیادهسازی پیشنمای پیوند، ممکن است لازم باشد با خواندن گزارشهای برنامه، برنامه Chat خود را اشکالزدایی کنید. برای خواندن گزارشها، به کاوشگر گزارشها در کنسول Google Cloud مراجعه کنید.
برنامههای گپ که برافزا نیستند: پیشدید کردن پیوندها
اسناد زیر برای برنامههای Chat که برافزاهای Google Workspace نیستند اعمال میشود. برای انتقال برنامه Chat که برافزا نیست، تبدیل برنامه Google Chat به برافزای Google Workspace را ببینید.
در فضاهای Chat که شامل برنامه Chat است که برافزا نیست، وقتی پیام کسی حاوی پیوندی است که با الگوی نشانی وب پیشنمایش پیوند مطابقت دارد، برنامه Chat رویداد تعامل MESSAGE را دریافت میکند. بار JSON برای رویداد تعامل حاوی فیلد matchedUrl است:
(قالب) JSON
message: {
matchedUrl: {
url: "https://support.example.com/cases/case123"
},
... // other message attributes redacted
}
با بررسی وجود فیلد matchedUrl در بار MESSAGE رویداد، برنامه Chat که برافزا نیست میتواند اطلاعات را به پیام دارای پیوند پیشدیدشده اضافه کند.
پاسخ دادن با پیامک
برای پاسخهای پایه، برنامه Chat که برافزا نیست میتواند با پاسخ دادن با پیامک ساده به پیوند، آن را پیشدید کند. این مثال پیامی را پیوست میکند که نشانی وب پیوندی را که با الگوی نشانی وب پیشنمایش پیوند مطابقت دارد تکرار میکند:
Node.js
Python
جاوا
Apps Script
کارتی را که پیشنمایش پیوند است پیوست کنید
برای پیوست کردن کارت به پیوند پیشدیدشده
در برنامه Chat که
برافزا نیست،
ActionResponse
از نوع UPDATE_USER_MESSAGE_CARDS برگردانید. این مثال کارت سادهای را پیوست میکند:
Node.js
Python
جاوا
Apps Script
این مثال با برگرداندن JSON کارت، پیام کارت ارسال میکند. همچنین میتوانید از خدمات کارت Apps Script استفاده کنید.
بهروزرسانی کارت پیشنمایش پیوند
برای بهروز کردن کارت پیشنمایش پیوند در برنامه Chat که
برافزا نیست،
رویداد تعامل CARD_CLICKED
را مدیریت کنید و براساس اینکه چه کسی پیامی را که حاوی پیشنمایش پیوند است ارسال کرده است،
actionResponse
را برگردانید:
- اگر کاربر پیام را ارسال کرده است،
actionResponse.typeرا رویUPDATE_USER_MESSAGE_CARDSتنظیم کنید. - اگر برنامه Chat پیام را ارسال کرده است،
actionResponse.typeرا رویUPDATE_MESSAGEتنظیم کنید.
برای تعیین اینکه چه کسی پیام را ارسال کرده است، میتوانید از فیلد message.sender.type رویداد تعامل استفاده کنید تا ببینید فرستنده کاربر HUMAN بوده است یا BOT.
مثال زیر نشان میدهد که چگونه یک برنامه Chat که برافزا نیست هرگاه کاربر روی دکمه اختصاص دادن به من کلیک میکند، پیشنمایش پیوند را با بهروز کردن فیلد اختصاصدهنده کارت و غیرفعال کردن دکمه بهروز میکند:
Node.js
Python
جاوا
Apps Script
این مثال با برگرداندن JSON کارت، پیام کارت ارسال میکند. همچنین میتوانید از خدمات کارت Apps Script استفاده کنید.