‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

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

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

برای ساختن میاناهای تعاملی برای برنامه‌های Chat، از عناصر زیر استفاده می‌کنید:

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

برنامه Chat شیء رویدادی را از راه‌انداز «افزوده‌شده به فضا» دریافت می‌کند — **شکل ۱**: وقتی کاربری برنامه Chat را به فضایی اضافه می‌کند، راه‌انداز **به فضا اضافه شد** فعال می‌شود و شیء رویدادی را ارسال می‌کند. برای پاسخ دادن با پیام، برنامه Chat شیء رویداد را مدیریت می‌کند و کنشی را برمی‌گرداند که پیام را ایجاد می‌کند.

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

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

پیش‌نیازها

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

نحوه عملکرد تعامل‌های کاربر

وقتی کاربر با برنامه Chat تعامل برقرار می‌کند، Google Chat راه‌انداز پیکربندی‌شده‌ای را فرا می‌خواند و شیء رویداد را به نقطه پایانی یا تابع برنامه Chat شما ارسال می‌کند. برنامه Chat شما شیء رویداد را پردازش می‌کند و می‌تواند یا کنش را به‌صورت هم‌زمان برگرداند در ۳۰ ثانیه یا بااستفاده از Chat API به‌صورت ناهم‌زمان پاسخ دهد.

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

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

راه‌اندازها

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

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

راه‌انداز	شرح	پاسخ معمول
به فضا اضافه شد	کاربری برنامه Chat را به فضا اضافه می‌کند، یا سرپرست Google Workspace برنامه Chat را در فضاهای پیام مستقیم برای کاربران سازمانش نصب می‌کند. برای آشنایی با برنامه‌های Chat نصب‌شده توسط سرپرستان، نصب برنامه‌های Marketplace در دامنه‌تان را در مستندات «راهنمای سرپرست Google Workspace» ببینید.	برنامه Chat پیام آماده‌سازی ارسال می‌کند که توضیح می‌دهد چه کاری انجام می‌دهد و کاربران فضا چگونه می‌توانند با آن تعامل داشته باشند.
ارسال پیام	کاربر به یکی از روش‌های زیر با برنامه Chat در پیامی تعامل برقرار می‌کند: پیامی را در فضای پیام مستقیم (DM) با برنامه Chat ارسال می‌کند. برنامه Chat را در هر نوع فضایی @نامبری می‌کند. پیامی ارسال می‌کند که حاوی پیوندی است که با الگوی نشانی وب برای پیش‌نمایش‌های پیوند مطابقت دارد. نوشتار را در منو چندانتخابی `selectionInput` ابزاره تایپ می‌کند.	برنامه Chat براساس محتوای پیام پاسخ می‌دهد. برای مثال، برنامه Chat با پیامی پاسخ می‌دهد، کارت پیش‌نمایش پیوندی را پیوست می‌کند، یا مواردی را در منو چندانتخابی پیشنهاد می‌دهد.
از فضا برداشته شد	کاربری برنامه Chat را از فضایی بردارد، یا سرپرست Google Workspace برنامه Chat را برای کاربری در سازمانش لغو نصب کند. کاربران نمی‌توانند برنامه‌های Chat را که سرپرستشان نصب کرده است بردارند. اگر کاربری قبلاً برنامه Chat را نصب کرده باشد، برنامه Chat صرف‌نظر از اینکه سرپرست Google Workspace بخواهد آن را حذف نصب کند یا نه، نصب‌شده باقی می‌ماند.	برنامه Chat همه اعلان‌های ورودی پیکربندی‌شده برای فضا (مثل حذف وب‌قلاب) را برمی‌دارد و فضای ذخیره‌سازی داخلی را پاک می‌کند. برنامه‌های گپ نمی‌توانند با پیام به این راه‌انداز پاسخ دهند زیرا دیگر عضو فضا نیستند.
فرمان برنامه	کاربر فرمان برنامه Chat (مثل فرمان خط مورب، فرمان سریع، یا کنش پیام) را فرا می‌خواند.	برنامه Chat به این فرمان پاسخ می‌دهد. برای مثال، با پیامی پاسخ می‌دهد یا کادر گفتگویی را باز می‌کند.
صفحه اصلی برنامه	کاربری برگه صفحه اصلی را در فضای پیام مستقیم یک‌به‌یک (DM) با برنامه Chat باز می‌کند، یا با ابزاره‌ای در کارت صفحه اصلی تعامل برقرار می‌کند.	برنامه Chat شیء `RenderActions` را برمی‌گرداند که کارت صفحه اصلی را (`pushCard`) ارسال می‌کند یا کارت صفحه اصلی نمایش‌داده‌شده را (`updateCard`) به‌روز می‌کند.

نقطه‌های پایانی یا توابع برگشتی را برای این راه‌اندازها در کنسول Google Cloud در صفحه پیکربندی «میانای برنامه‌سازی کاربردی Chat» پیکربندی می‌کنید. برای دریافت دستورالعمل‌های گام‌به‌گام، پیکربندی Google Chat API را ببینید.

پیکربندی پیام‌واره‌های آغازگر

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

برای افزودن و پیکربندی پیام‌واره‌های آغازگر:

در کنسول Google Cloud، به صفحه پیکربندی Chat API بروید:

رفتن به صفحه «پیکربندی Chat API»
در بخش ویژگی‌های تعاملی، پیام‌واره‌های آغازگر را پیدا کنید و روی افزودن پیام‌واره کلیک کنید.
در فیلد رتبه (۱ تا ۳)، عددی از 1 تا 3 وارد کنید تا ترتیب نمایش را مشخص کنید.
در بخش انتخاب نوع، انتخاب کنید پیام‌واره چگونه عمل کند:
- پیام‌واره نوشتاری: وقتی کاربر روی تراشه پیام‌واره کلیک می‌کند، نوار نوشتن را با نوشتار پیش‌تعریف‌شده پر می‌کند.
- پیام‌واره فرمان: با کلیک کردن، فرمان ثبت‌شده خط مورب یا فرمان سریع را اجرا می‌کند. فرمان‌هایی که به آرگومان‌های اضافی نیاز دارند نمی‌توانند انتخاب شوند.
پیام‌واره را براساس نوع انتخابتان پیکربندی کنید:
- اگر «پیام‌واره نوشتاری» را انتخاب کردید:
  1. در عنوان، عنوان پیام‌واره نمایش‌داده‌شده در تراشه را وارد کنید (حداکثر ۳۰ نویسه).
  2. در نوشتار پیام‌واره، نوشتار تکمیل‌شده در نوار نوشتن (حداکثر ۶۰ نویسه) را وارد کنید.
  3. اختیاری: افزودن عنوان‌ها و نوشتار بومی‌سازی‌شده برای کاربران به زبان‌های دیگر:
  4. در بخش پیام‌واره‌های بومی‌سازی‌شده، روی افزودن زبان کلیک کنید.
  5. در زبان، زبانی پشتیبانی‌شده را از منو کرکره‌ای انتخاب کنید.
  6. در عنوان بومی‌سازی‌شده، عنوان بومی‌سازی‌شده (حداکثر ۳۰ نویسه) را وارد کنید.
  7. در نوشتار پیام‌واره بومی‌سازی‌شده، نوشتار پیام‌واره بومی‌سازی‌شده (حداکثر ۶۰ نویسه) را وارد کنید.
  8. برای افزودن زبان‌های بیشتر درصورت نیاز، تکرار کنید.
- اگر «پیام‌واره فرمان» را انتخاب کرده‌اید:
  1. در فرمان خط مورب / فرمان سریع، فرمان را از منو کرکره‌ای انتخاب کنید.
روی تمام و سپس روی ذخیره در پایین صفحه کلیک کنید.

مدیریت کردن تلاش‌های مجدد برای تماس HTTP با سرویس شما

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

اشیای رویداد

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

بار داده‌های شیء رویداد

هر شیء رویداد «گپ» شامل commonEventObject با جزئیات میزبان و پلاتفرم (hostApp: "CHAT"،‏ clientPlatform، userLocale،‏ userTimezone،‏ parameters، و formInputs) و شیء chat حاوی بافت ویژه «گپ» است:

برای راه‌انداز صفحه اصلی برنامه (وقتی کاربر زبانه صفحه اصلی را در پیام مستقیم 1:1 با برنامه Chat باز می‌کند)، شیء chat حاوی chat.user و chat.eventTime بدون فیلد payload اتحادیه است. وقتی کاربری روی دکمه‌ای در کارت صفحه اصلی کلیک می‌کند، شیء رویداد شامل chat.buttonClickedPayload به‌همراه commonEventObject.parameters (و commonEventObject.formInputs اگر کارت حاوی ورودی‌های فرم باشد) می‌شود.
برای تعاملات فضا و پیام (افزوده‌شده به فضا، پیام، برداشته‌شده از فضا، فرمان برنامه، یا تعاملات دکمه و ابزارک)، chat شیء شامل chat.user، chat.space، chat.eventTime، و بار تعامل مربوطه است:
- ‫messagePayload: حاوی space، message، و configCompleteRedirectUri هنگام ارسال پیام توسط کاربر.
- addedToSpacePayload: وقتی برنامه Chat به فضایی اضافه می‌شود، حاوی space، interactionAdd، و configCompleteRedirectUri است.
- removedFromSpacePayload: وقتی برنامه Chat از فضایی برداشته می‌شود، space را دربرمی‌گیرد.
- ‫buttonClickedPayload: وقتی کاربر روی دکمه‌ای در کارت یا کادر گفتگویی کلیک می‌کند، حاوی space،‏ message،‏ isDialogEvent، و dialogEventType است.
- widgetUpdatedPayload: وقتی کاربر با ابزاره‌ای تعامل برقرار می‌کند، مثل تایپ کردن در منو چندانتخابی با منبع داده خارجی، space را دربرمی‌گیرد.
- ‫appCommandPayload: حاوی space، message، appCommandMetadata، isDialogEvent، dialogEventType، و configCompleteRedirectUri است وقتی کاربر فرمان برنامه‌ای را فرا می‌خواند.

برای آشنایی با اشیای رویداد برافزا در Chat و دیگر برنامه‌های Google Workspace، اشیای رویداد را ببینید.

ارائه پاسخ

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

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

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

DataActions: پیام‌های «گپ» (CreateMessageAction، UpdateMessageAction) را ایجاد یا به‌روزرسانی می‌کند یا پیش‌نمایش پیوند (UpdateInlinePreviewAction) را بااستفاده از chatDataActionMarkup پیوست می‌کند.
RenderActions: صفحه اصلی یا کادر گفتگویی (pushCard، updateCard، endNavigation: "CLOSE_DIALOG") را ایجاد، به‌روزرسانی، یا می‌بندد، یا پیشنهادهای ورودی پویا برای منو چندانتخابی (modifyCard) ارائه می‌دهد.
AuthorizationError: کاربران را با کارت مجوز پایه (basic_authorization_prompt) برای ورود به سیستم یا اصالت‌سنجی در سرویس خارجی ترغیب می‌کند.

جدول زیر نشان می‌دهد برنامه‌های Chat چگونه می‌توانند با کنش‌ها پاسخ دهند. برنامه‌های گپ می‌توانند مستقیماً اشیای JSON را برگردانند یا پاسخ را بااستفاده از AddOnResponseService و CardService در Apps Script بسازند.

پاسخ برنامه گپ	کنش لازم برای برگرداندن (JSON)	اقدام لازم برای برگشتن (Apps Script)
ارسال پیام یا به‌روزرسانی پیام.	‫`DataActions` (`createMessageAction` یا `updateMessageAction`)	`DataActionsResponse`
پیش‌نمایش پیوندها در پیام‌هایی که کاربران Chat در فضا ارسال می‌کنند.	‫`DataActions`‏ (`updateInlinePreviewAction`)	`DataActionsResponse`
در برگه صفحه اصلی پیام مستقیم، صفحه اصلی را پرداز یا به‌روزرسانی کنید.	‫`RenderActions` (`pushCard` یا `updateCard`)	`ActionResponse`
کادر گفتگو را باز، به‌روز، یا بسته می‌کند.	‫`RenderActions` (`pushCard`،‏ `updateCard`، یا `endNavigation: "CLOSE_DIALOG"`)	`ActionResponse`
برای جمع‌آوری اطلاعات از کارت یا کادر گفتگو، براساس آنچه کاربران در منو چندانتخابی تایپ می‌کنند، موارد انتخابی را پیشنهاد دهید.	‫`RenderActions`‏ (`modifyCard`)	`ActionResponse`
درخواست پیکربندی یا مجوز برای سرویس خارجی.	‫`AuthorizationError`‏ (`basic_authorization_prompt`)	`AuthorizationException`

پاسخ با پیام

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

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

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

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

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

{
  "hostAppDataAction": {
    "chatDataAction": {
      "createMessageAction": {
        "message": <var>MESSAGE</var>
      }
    }
  }
}

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

در مثال زیر، برنامه Chat هربار که با پاسخ دادن به راه‌انداز افزوده‌شده به فضا با DataActions به فضایی اضافه می‌شود، پیامک آماده‌سازی ایجاد و ارسال می‌کند:

Node.js

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The request object from Google Chat.
 * @param {Object} res The response object from the Chat app.
 */
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`.'
    }}}}});
  }
};

Python

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.
  """
  chat_event = request.get_json()["chat"]
  if "addedToSpacePayload" in chat_event:
    return json.jsonify({ "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`.'
      }}
    }}})

جاوا

@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 GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
    JsonNode chatEvent = event.at("/chat");
    if (!chatEvent.at("/addedToSpacePayload").isEmpty()) {
      return new GenericJson() { {
        put("hostAppDataAction", new GenericJson() { {
          put("chatDataAction", new GenericJson() { {
            put("createMessageAction", new GenericJson() { {
              put("message", 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`."
              ));
            } });
          } });
        } });
      } };
    }
    return new GenericJson();
  }
}

Apps Script

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Google Chat.
 * @return {Object} Response from the Chat app.
 */
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 می‌تواند پیامی را پس‌از اینکه کاربر گفتگویی را ارسال می‌کند یا روی دکمه‌ای در کارت پیام کلیک می‌کند به‌روز کند.

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

{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateMessageAction": {
        "message": <var>MESSAGE</var>
      }
    }
  }
}

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

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

بااستفاده از Google Chat API به‌صورت ناهمزمان پاسخ دهید

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

پس‌از ۳۰ ثانیه به تعامل پاسخ دهید (مثلاً پس‌از تکمیل یک کار طولانی‌مدت).
پیام‌ها را طبق زمان‌بندی ارسال کنید یا اعلان‌هایی درباره تغییرات منابع خارجی ارسال کنید.
انجام تکالیف خارج از فضایی که تعامل در آن انجام شده است.
انجام تکالیف در Chat که به‌عنوان کنش‌های هم‌زمان دردسترس نیستند، مثل فهرست کردن فضاها یا افزودن اعضا به فضا.
انجام تکالیف ازطرف کاربر Chat (که نیاز به اصالت‌سنجی کاربر دارد).

هنگام پاسخ دادن به تعامل پس‌از ۳۰ ثانیه، برای جلوگیری از پیام خطای کاربر که می‌گوید برنامه Chat شما پاسخ نمی‌دهد، باید دریافت شیء رویداد را ظرف ۳۰ ثانیه با برگرداندن پاسخ خالی تأیید کنید:

Node.js

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

Python

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 "{}";
}

Apps Script

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، اصالت‌سنجی راه‌اندازی کنید و متد spaces.messages.create را فراخوانی کنید. برای مراحل، به ارسال پیام مراجعه کنید. برای دریافت راهنمایی درباره استفاده از روش‌های اضافی Chat API، نمای کلی Chat API را ببینید.

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

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

برای ارتقا دادن برنامه Chat که برافزا نیست به چارچوب برافزاهای Google Workspace، به تبدیل برنامه Google Chat به برافزای Google Workspace مراجعه کنید.

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

برای هر نوع تعامل کاربر، Google Chat برنامه Chat که برافزا نیست شیء Event را که نوع آن با فیلد eventType نشان داده می‌شود ارسال می‌کند:

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

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

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

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

فیلد isDialogEvent روی true تنظیم شده است.
‫DialogEventType (REQUEST_DIALOG،‏ SUBMIT_DIALOG، یا CANCEL_DIALOG) مشخص می‌کند که آیا تعامل باعث باز شدن کادر گفتگو می‌شود، اطلاعات را از کادر گفتگو ارسال می‌کند، یا کادر گفتگو را می‌بندد.

برنامه Chat را که برافزار نیست پیکربندی کنید تا رویدادهای تعامل را دریافت کند

در کنسول Google Cloud، به صفحه پیکربندی میانای برنامه‌سازی کاربردی Chat بروید:

رفتن به صفحه «پیکربندی Chat API»
در بخش ویژگی‌های تعاملی، ساخت این برنامه Chat به‌عنوان برافزای Google Workspace را لغو انتخاب کنید، و عملکرد، یک نقطه پایانی تنظیمات اتصال (نشانی وب نقطه پایانی HTTP،‏ Apps Script، نام موضوع Cloud Pub/Sub، یا Dialogflow)،‏ فرمان‌ها، پیام‌واره‌های آغازگر، پیش‌نمایش‌های پیوند، و رؤیت‌پذیری را پیکربندی کنید.
روی ذخیره کلیک کنید.

پاسخ دادن با پیام در برنامه Chat که برافزا نیست

برای پاسخ هم‌زمان در برنامه Chat که برافزا نیست، شیء Message را مستقیماً برگردانید. مثال زیر به رویداد تعامل ADDED_TO_SPACE با پیام نوشتاری پاسخ می‌دهد:

Node.js

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

Python

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

Apps Script

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

دریافت و پاسخ دادن به تعاملات کاربر با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

پیش‌نیازها

نحوه عملکرد تعامل‌های کاربر

راه‌اندازها

پیکربندی پیام‌واره‌های آغازگر

مدیریت کردن تلاش‌های مجدد برای تماس HTTP با سرویس شما

اشیای رویداد

بار داده‌های شیء رویداد

ارائه پاسخ

پاسخ با پیام

Node.js

Python

جاوا

Apps Script

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

بااستفاده از Google Chat API به‌صورت ناهمزمان پاسخ دهید

Node.js

Python

جاوا

Apps Script

موضوعات مرتبط

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

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

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

برنامه Chat را که برافزار نیست پیکربندی کنید تا رویدادهای تعامل را دریافت کند

پاسخ دادن با پیام در برنامه Chat که برافزا نیست

Node.js

Python

جاوا

Apps Script

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