پیام‌های چت Google را ارسال کنید

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

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

  • فرم تماس از دستور اسلش.
    شکل 1. یک برنامه چت با یک پیام متنی و دکمه به دستور اسلش پاسخ می دهد.
  • فرم تماس در یک گفتگو.
    شکل 2. یک برنامه چت گفتگویی را باز می کند که در آن کاربران می توانند اطلاعات را وارد کنند.
  • پیام کارت با ویجت های ورودی فرم.
    شکل 5. یک برنامه چت پیامی با متن و یک کارت تعاملی ارسال می کند.

پیش نیازها

Node.js

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

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

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

پیام را طراحی کنید

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

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

برای آشنایی با طراحی پیام‌ها، به مستندات Google Chat API زیر مراجعه کنید:

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

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

  • محرک‌های پیام ، مانند زمانی که کاربران از یک برنامه چت @ نام می‌برند یا پیام مستقیم می‌دهند.
  • به محرک‌های فضا اضافه شده است ، مانند زمانی که کاربران برنامه Chat را از Google Workspace Marketplace نصب می‌کنند یا آن را به یک فضا اضافه می‌کنند.
  • کلیک دکمه ها از کارت ها در پیام ها یا گفتگوها. به عنوان مثال، زمانی که کاربران اطلاعات را وارد کرده و روی ارسال کلیک می کنند.

در غیر این صورت، برنامه‌های گپ می‌توانند با تماس با Google Chat API به صورت فعال پیام ارسال کنند.

برای پاسخ دادن با یک پیام، عمل DataActions را با یک شی CreateMessageAction برگردانید:

{ "hostAppDataAction": { "chatDataAction": { "createMessageAction": {
  "message": MESSAGE
}}}

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

در مثال زیر، یک برنامه چت هر زمان که به فضایی اضافه شود پیام متنی ایجاد کرده و ارسال می کند. برای ارسال پیام نوشتاری هنگامی که کاربر برنامه چت شما را به یک فضا اضافه می‌کند، برنامه چت شما با برگرداندن عملکرد DataActions به محرک Added to space پاسخ می‌دهد:

Node.js 

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The request object from Google Workspace Add-on.
 * @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.cymbalApp = function cymbalApp(req, res) {
  const chatEvent = req.body.chat;
  // Send an onboarding message when added to a Chat space
  if (chatEvent.addedToSpacePayload) {
    res.json({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
      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 onAddedToSpace(event) {
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    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`.'
  }}}}};
}

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

نمونه پیام ورود.

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

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

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

برای به‌روزرسانی پیام برنامه Chat، عمل DataActions با UpdateMessageAction برگردانید، همانطور که در مثال زیر نشان داده شده است:

{ "hostAppDataAction": { "chatDataAction": { "updateMessageAction": {
  "message": MESSAGE
}}}}

MESSAGE با یک منبع Message از Chat API جایگزین کنید.

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

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

با استفاده از Google Chat API به تعاملات پاسخ دهید یا پیام‌های فعال ارسال کنید

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

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

برای ارسال پیام با استفاده از Chat API، باید احراز هویت را تنظیم کنید و متد create() را در منبع Message فراخوانی کنید. برای مراحل، به ارسال پیام با استفاده از Google Chat API مراجعه کنید.