جمع‌آوری و مدیریت مخاطبین در Google Chat

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

برنامه Chat را در عمل ببینید:

  • فرم تماس از فرمان خط مورب.
    شکل ۱. برنامه «گپ» به فرمان خط مورب /about با پیامک و دکمه‌ای که فرم مخاطب را باز می‌کند پاسخ می‌دهد.
  • فرم تماس در کادر گفتگو.
    شکل ۲. برنامه Chat کادر گفتگویی را باز می‌کند که در آن کاربران می‌توانند اطلاعات مربوط به مخاطب را وارد کنند.
  • کادر گفتگوی تأیید و مرور.
    شکل ۳. برنامه Chat گفتگویی برای تأیید برمی‌گرداند تا کاربران بتوانند اطلاعات را قبل‌از ارسال کردن مرور و تأیید کنند.
  • پیامکی که مخاطب جدید را تأیید می‌کند.
    شکل ۴. پس‌از اینکه کاربر فرم را ارسال کرد، برنامه Chat پیامک خصوصی‌ای برای تأیید ارسال می‌فرستد.
  • فرم تماس از پیام کارت.
    شکل ۵. برنامه Chat همچنین از کاربران می‌خواهد که مخاطبی را از کارتی در پیام اضافه کنند.

پیش‌نیازها

اهداف

معماری

برنامه Chat در Google Apps Script (به‌عنوان برافزای Google Workspace که Google Chat را گسترش می‌دهد) ساخته شده است و به تعاملات کاربر (onMessage، onAppCommand، و کلیک‌های دکمه‌ای که openInitialDialog، openConfirmationDialog، و submitForm را فرا می‌خوانند) پاسخ می‌دهد تا کاربران Chat را پردازش و به آن‌ها پاسخ دهد.

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

  1. کاربری پیام مستقیمی را با برنامه Chat باز می‌کند، یا برنامه Chat را به فضای موجودی اضافه می‌کند.

  2. برنامه Chat از کاربر می‌خواهد که با ساختن و نمایش فرم مخاطب به‌عنوان card شیء، مخاطب اضافه کند. برای ارائه فرم تماس، برنامه Chat به روش‌های زیر به کاربران پاسخ می‌دهد:

    • به @نامبری‌ها و پیام‌های مستقیم (onMessage) با پیام کارت حاوی فرم تماس پاسخ می‌دهد.
    • با باز کردن کادر گفتگویی با فرم مخاطب، به فرمان خط مورب /addContact (onAppCommand) پاسخ می‌دهد.
    • به فرمان خط مورب /about (onAppCommand) با پیامک پاسخ می‌دهد که دکمه افزودن مخاطب دارد و کاربران می‌توانند روی آن کلیک کنند تا openInitialDialog را فراخوانی کنند و کادر گفتگویی با فرم مخاطب باز کنند.

  3. وقتی فرم تماس به کاربر ارائه می‌شود، کاربر اطلاعات تماس را در فیلدها و ابزارک‌های زیر وارد می‌کند:

    • نام و نام خانوادگی: a textInput ابزاره‌ای که رشته‌ها را می‌پذیرد.
    • تاریخ تولد: a dateTimePicker ابزاره‌ای که فقط تاریخ می‌پذیرد.
    • نوع مخاطب: a selectionInput ابزارک دکمه‌های رادیویی که به کاربران امکان می‌دهد مقدار رشته‌ای واحدی (یا Personal یا Work) را انتخاب و ارسال کنند.
    • دکمه مرور و ارسال: a buttonList آرایه‌ای با button ابزارک که کاربر برای ارسال مقادیر واردشده روی آن کلیک می‌کند.

  4. برنامه Google Chat openConfirmationDialog را برای پردازش مقادیر ورودی کاربر فرا می‌خواند و مقادیر را در کارت تأیید نمایش می‌دهد.

  5. کاربر کارت تأیید را مرور می‌کند و روی دکمه ارسال کلیک می‌کند تا submitForm را فراخوانی کند و اطلاعات تماس را نهایی کند.

  6. برنامه Google Chat پیامک خصوصی‌ای ارسال می‌کند که ارسال را تأیید می‌کند.

آماده کردن محیط

این بخش نحوه پیکربندی پروژه Google Cloud را برای برنامه Chat نشان می‌دهد.

پروژه Cloud خود را در «کنسول Google API» باز کنید

اگر ازقبل باز نیست، «پروژه ابری» موردنظرتان را برای استفاده در این نمونه باز کنید:

  1. در «کنسول Google API»، به صفحه انتخاب پروژه بروید.

    انتخاب پروژه Cloud

  2. پروژه Google Cloud موردنظرتان را برای استفاده انتخاب کنید. یا روی ایجاد پروژه کلیک کنید و دستورالعمل‌های روی صفحه را دنبال کنید. اگر پروژه Google Cloud ایجاد کنید، ممکن است لازم باشد صورت‌حساب را برای پروژه روشن کنید.

راه‌اندازی اصالت‌سنجی و مجوز

برنامه‌های Google Chat از شما می‌خواهند که صفحه موافقت OAuth را پیکربندی کنید تا کاربران بتوانند برنامه شما را در برنامه‌های Google Workspace، ازجمله Google Chat، مجاز کنند.

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

  1. در «کنسول Google API»، به «منو» > پلاتفرم Google Auth > نمانام‌سازی بروید.

    رفتن به نمانام‌سازی

  2. اگر قبلاً پلاتفرم Google Auth را پیکربندی کرده‌اید، می‌توانید تنظیمات «صفحه رضایت OAuth» زیر را در نمانام‌سازی، مخاطب، و دسترسی به داده‌ها پیکربندی کنید. اگر پیامی با این مضمون دیدید: پلاتفرم «احراز هویت Google» هنوز پیکربندی نشده است، روی شروع به کار کلیک کنید:

    1. در بخش اطلاعات برنامه، در نام برنامه، Contact Manager را تایپ کنید.
    2. در ایمیل پشتیبانی کاربر، نشانی ایمیل خودتان یا گروه Google مناسبی را انتخاب کنید.
    3. روی بعدی کلیک کنید.
    4. در بخش مخاطبان، داخلی را انتخاب کنید. اگر نمی‌توانید داخلی را انتخاب کنید، خارجی را انتخاب کنید.
    5. روی بعدی کلیک کنید.
    6. در بخش اطلاعات تماس، نشانی ایمیلی وارد کنید که ازطریق آن بتوانید از هرگونه تغییر در پروژه‌تان مطلع شوید.
    7. روی بعدی کلیک کنید.
    8. در بخش تکمیل، خط‌مشی داده‌های کاربر سرویس‌های Google API را مرور کنید و درصورت موافقت، با «خط‌مشی داده‌های کاربر سرویس‌های Google API» موافقم را انتخاب کنید.
    9. روی ادامه کلیک کنید.
    10. روی ایجاد کردن کلیک کنید.
    11. اگر خارجی را برای نوع کاربر انتخاب کردید، کاربران آزمایش را اضافه کنید:
      1. روی مخاطبان کلیک کنید.
      2. در بخش کاربران آزمایش، روی افزودن کاربران کلیک کنید.
      3. نشانی ایمیل خود و سایر کاربران آزمایش مجاز را وارد کنید، سپس روی ذخیره کلیک کنید.

ایجاد و استقرار برنامه Chat

در بخش زیر، پروژه Apps Script را با کد برنامه (Code.gs و appsscript.json) برای برنامه Chat خود ایجاد و به‌روزرسانی می‌کنید.

درصورت تمایل، می‌توانید کل پروژه را در GitHub مشاهده کنید.

مشاهده در GitHub

در اینجا نمای کلی هر فایل آورده شده است:

Code.gs

همه منطق برنامه، ازجمله تعاملات کاربر (onMessage، onAppCommand، openInitialDialog، openConfirmationDialog، و submitForm) و ابزارک‌های ورودی فرم نمایش‌داده‌شده در کارت‌های پیام‌ها و کادرهای گفتگو را مدیریت می‌کند.

مشاهده Code.gs کد

apps-script/chat/contact-form-app/Code.gs
/**
 * Copyright 2025 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * Responds to a message in Google Chat.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} response that handles dialogs.
 */
function onMessage(event) {
  // Reply with a message that contains a button to open the initial dialog
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "To add a contact, use the `ADD CONTACT` button below.",
    accessoryWidgets: [
      { buttonList: { buttons: [{
        text: "ADD CONTACT",
        onClick: { action: {
          function: "openInitialDialog",
          interaction: "OPEN_DIALOG"
        }}
      }]}}
    ]
  }}}}};
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} open the dialog.
 */
function openInitialDialog(event) {
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [
    { textInput: {
      name: "contactName",
      label: "First and last name",
      type: "SINGLE_LINE"
    }},
    { dateTimePicker: {
      name: "contactBirthdate",
      label: "Birthdate",
      type: "DATE_ONLY"
    }},
    { selectionInput: {
      name: "contactType",
      label: "Contact type",
      type: "RADIO_BUTTON",
      items: [
        { text: "Work", value: "Work", selected: false },
        { text: "Personal", value: "Personal", selected: false }
      ]
    }},
    { buttonList: { buttons: [{
      text: "NEXT",
      onClick: { action: { function : "openConfirmationDialog" }}
    }]}}
  ]}]}}]}};
}

/**
 * Opens the second step of the dialog that lets users confirm details.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} update the dialog.
 */
function openConfirmationDialog(event) {
  // Retrieve the form input values
  const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
  const birthdate = event.commonEventObject.formInputs["contactBirthdate"].dateInput.msSinceEpoch;
  const type = event.commonEventObject.formInputs["contactType"].stringInputs.value[0];
  // Display the input values for confirmation
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [
    { textParagraph: { text: "Confirm contact information and submit:" }},
    { textParagraph: { text: "<b>Name:</b> " + name }},
    { textParagraph: { text: "<b>Birthday:</b> " + new Date(birthdate) }},
    { textParagraph: { text: "<b>Type:</b> " + type }},
    { buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        function: "submitDialog",
        // Pass input values as parameters for last dialog step (submission)
        parameters: [
          { key: "contactName", value: name },
          { key: "contactBirthdate", value: birthdate },
          { key: "contactType", value: type }
        ]
      }}
    }]}}
  ]}]}}]}};
}

/**
 * Handles submission and closes the dialog.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} close the dialog with a status in text notification or message.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: { action: "CLOSE_DIALOG"}}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "✅ " + event.commonEventObject.parameters["contactName"] + " has been added to your contacts."
  }}}}};
}
appsscript.json

مانیفست Apps Script که پروژه Apps Script را برای برنامه Chat تعریف و پیکربندی می‌کند.

مشاهده appsscript.json کد

apps-script/chat/contact-form-app/appsscript.json
{
  "timeZone": "America/Los_Angeles",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Contact Form app",
      "logoUrl": "https://developers.google.com/workspace/add-ons/images/contact-icon.png"
    },
    "chat": {}
  }
}

ایجاد پروژه Apps Script

برای ایجاد پروژه Apps Script از فایل‌های Code.gs و appsscript.json:

  1. به Google Apps Script بروید و روی پروژه جدید کلیک کنید.

  2. پروژه Apps Script خود را نام‌گذاری کنید:

    1. روی پروژه بی‌عنوان کلیک کنید.

    2. در عنوان پروژه، Contact Manager - Google Chat app را تایپ کنید.

    3. روی تغییر نام کلیک کنید.

  3. محتوای Code.gs را با کد نمونه Code.gs در بالا جایگزین کنید.

  4. روی تنظیمات پروژه نماد تنظیمات پروژه کلیک کنید و نمایش فایل مانیفست «appsscript.json» در ویرایشگر را انتخاب کنید.

  5. به ویرایشگر برگردید و محتوای appsscript.json را با کد مانیفست appsscript.json در بالا جایگزین کنید، سپس پروژه‌تان را ذخیره کنید.

در آینده، اگر بخواهید از برخی‌از Google APIs استفاده کنید یا برنامه‌تان را منتشر کنید، باید پروژه Cloud خود را با پروژه Apps Script مرتبط کنید. برای این راهنما، لازم نیست این کار را انجام دهید. برای کسب اطلاعات بیشتر، راهنمای پروژه‌های Google Cloud را ببینید.

ایجاد پیاده‌سازی Apps Script

اکنون که همه کدها در جای خود قرار دارند، پروژه Apps Script را پیاده‌سازی کنید. هنگام پیکربندی برنامه Chat در Google Cloud، از شناسه استقرار استفاده می‌کنید.

  1. در Apps Script، پروژه برنامه Chat را باز کنید.

    رفتن به Apps Script

  2. روی استقرار > استقرار جدید کلیک کنید.

  3. اگر برافزا ازقبل انتخاب نشده است، در کنار انتخاب نوع، روی انواع استقرار نماد تنظیمات پروژه کلیک کنید و برافزا را انتخاب کنید.

  4. در شرح، شرحی برای این نسخه وارد کنید، مثلاً Test of Contact Manager.

  5. روی استقرار کلیک کنید. ‫Apps Script گزارش می‌دهد که پیاده‌سازی موفقیت‌آمیز بوده است و شناسه پیاده‌سازی ارائه می‌دهد.

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

پیکربندی برنامه Chat در «کنسول Google API»

این بخش نحوه پیکربندی Google Chat API را در «کنسول Google API» با اطلاعاتی درباره برنامه Chat شما، ازجمله شناسه استقرار که به‌تازگی از پروژه Apps Script ایجاد کرده‌اید نشان می‌دهد.

  1. در «کنسول Google API»، روی منو > APIs و سرویس‌ها > APIs و سرویس‌های فعال > Google Chat API > پیکربندی کلیک کنید.

    رفتن به پیکربندی Chat API

  2. در نام برنامه، Contact Manager را تایپ کنید.

  3. در نشانی وب چهرک، https://developers.google.com/chat/images/contact-icon.png را تایپ کنید.

  4. در شرح، Manage your personal and business contacts را تایپ کنید.

  5. کلید فعال کردن ویژگی‌های تعاملی را به حالت روشن تغییر دهید.

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

  7. در بخش تنظیمات اتصال، Apps Script را انتخاب کنید.

  8. در شناسه پیاده‌سازی، «شناسه پیاده‌سازی Apps Script» را که در بخش قبلی هنگام ایجاد پیاده‌سازی Apps Script کپی کردید جای‌گذاری کنید.

  9. در بخش راه‌اندازها، عملکردهایی را که به تعاملات کاربر پاسخ می‌دهند پیکربندی کنید:

    • برای راه‌انداز پیام، onMessage را وارد کنید.
    • برای راه‌انداز فرمان برنامه، onAppCommand را وارد کنید.

  10. در بخش فرمان‌ها، فرمان‌های خط مورب /about و /addContact را راه‌اندازی کنید:

    1. برای تنظیم اولین فرمان خط مورب، روی افزودن فرمان کلیک کنید.
    2. در شناسه فرمان، 1 را تایپ کنید.
    3. در شرح، Learn how to use this Chat app to manage your contacts را تایپ کنید.
    4. در بخش نوع فرمان، Slash command را انتخاب کنید.
    5. در نام فرمان خط مورب، /about را تایپ کنید.
    6. روی تمام کلیک کنید.
    7. برای تنظیم فرمان خط مورب دیگر، روی افزودن فرمان کلیک کنید.
    8. در شناسه فرمان، 2 را تایپ کنید.
    9. در شرح، Submit information about a contact را تایپ کنید.
    10. در بخش نوع فرمان، Slash command را انتخاب کنید.
    11. در نام فرمان خط مورب، /addContact را تایپ کنید.
    12. باز کردن کادر گفتگو را انتخاب کنید.
    13. روی تمام کلیک کنید.

  11. در بخش رؤیت‌پذیری، کادر انتخاب این برنامه Chat را برای افراد و گروه‌های خاصی در YOUR DOMAIN دردسترس قرار دهید را انتخاب کنید و نشانی ایمیلتان را وارد کنید.

  12. در بخش گزارش‌ها، خطاهای گزارش به «گزارش‌گیری» را انتخاب کنید.

  13. روی ذخیره کلیک کنید. پیام ذخیره شدن پیکربندی نشان داده می‌شود.

برنامه Chat برای نصب و آزمایش در Chat آماده است.

آزمایش کردن برنامه Chat

برای آزمایش برنامه Chat، فضای پیام مستقیمی را با برنامه Chat باز کنید و پیامی ارسال کنید:

  1. بااستفاده از حساب Google Workspace که هنگام اضافه کردن خودتان به‌عنوان آزمایش‌کننده معتمد ارائه کردید، Google Chat را باز کنید.

    رفتن به Google Chat

  2. روی گپ جدید کلیک کنید.
  3. در فیلد افزودن ۱ یا چند نفر، نام برنامه Chat خود را تایپ کنید.

  4. برنامه Chat را از نتایج انتخاب کنید. پیام مستقیمی باز می‌شود.

  1. در پیام مستقیم جدید با برنامه Chat، /addContact را تایپ کنید و کلید Enter را فشار دهید.

  2. در کادر گفتگویی که باز می‌شود، اطلاعات تماس را وارد کنید:

    1. در فیلد نوشتاری نام و نام خانوادگی، نامی وارد کنید.
    2. در انتخاب‌گر تاریخ تاریخ تولد، تاریخی را انتخاب کنید.
    3. در بخش نوع مخاطب، دکمه رادیویی کاری یا شخصی را انتخاب کنید.

  3. روی مرور و ارسال کلیک کنید.

  4. در کادر گفتگوی تأیید، اطلاعاتی را که ارسال کرده‌اید مرور کنید و روی ارسال کلیک کنید. برنامه Chat با پیام نوشتاری که می‌گوید ✅ CONTACT NAME has been added to your contacts. پاسخ می‌دهد.

  5. به‌صورت اختیاری، می‌توانید فرم تماس را به روش‌های زیر آزمایش و ارسال کنید:

    • از فرمان خط مورب /about استفاده کنید. برنامه گپ با پیام نوشتاری و دکمه ابزارک جانبی که می‌گوید Add a contact پاسخ می‌دهد. می‌توانید روی دکمه کلیک کنید تا کادر گفتگویی با فرم تماس باز شود.
    • بدون فرمان خط مورب، مثل Hello، به برنامه Chat پیام مستقیم ارسال کنید. برنامه Chat با نوشتار و کارتی که حاوی فرم تماس است پاسخ می‌دهد.

مرتب‌سازی

برای اینکه هزینه منابع استفاده‌شده در این آموزش به حساب Google Cloud شما اضافه نشود، توصیه می‌کنیم پروژه Cloud را حذف کنید.

  1. در «کنسول Google API»، به صفحه مدیریت منابع بروید. روی منو > IAM و سرپرست > مدیریت منابع کلیک کنید.

    به «مدیر منابع» بروید

  2. در فهرست پروژه، پروژه‌ای را که می‌خواهید حذف کنید انتخاب کنید و سپس روی حذف کلیک کنید.
  3. در چارگوش گفتگو، شناسه پروژه را تایپ کنید و سپس روی خاموش کردن کلیک کنید تا پروژه حذف شود.

برنامه‌های گپی که برافزا نیستند: مدیریت مخاطبین از Google Chat

دستورالعمل‌ها و نمونه‌های کد زیر برای برنامه Chat که برافزای Google Workspace نیست اعمال می‌شود (مشاهده در GitHub).

فایل‌های Apps Script

main.gs

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

apps-script/contact-form-app/main.gs
/**
 * Copyright 2024 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * Responds to a MESSAGE interaction event in Google Chat.
 *
 * @param {Object} event the MESSAGE interaction event from Chat API.
 * @return {Object} message response that opens a dialog or sends private
 *                          message with text and card.
 */
function onMessage(event) {
  if (event.message.slashCommand) {
    switch (event.message.slashCommand.commandId) {
      case 1:
        // If the slash command is "/about", responds with a text message and button
        // that opens a dialog.
        return {
          text: "Manage your personal and business contacts 📇. To add a " +
                  "contact, use the slash command `/addContact`.",
          accessoryWidgets: [{
            buttonList: { buttons: [{
              text: "Add Contact",
              onClick: { action: {
                function: "openInitialDialog",
                interaction: "OPEN_DIALOG"
              }}
            }]}
          }]
        }
      case 2:
        // If the slash command is "/addContact", opens a dialog.
        return openInitialDialog();
    }
  }

  // If user sends the Chat app a message without a slash command, the app responds
  // privately with a text and card to add a contact.
  return {
    privateMessageViewer: event.user,
    text: "To add a contact, try `/addContact` or complete the form below:",
    cardsV2: [{
      cardId: "addContactForm",
      card: {
        header: { title: "Add a contact" },
        sections:[{ widgets: CONTACT_FORM_WIDGETS.concat([{
          buttonList: { buttons: [{
            text: "Review and submit",
            onClick: { action: { function : "openConfirmation" }}
          }]}
        }])}]
      }
    }]
  };
}

/**
 * Responds to CARD_CLICKED interaction events in Google Chat.
 *
 * @param {Object} event the CARD_CLICKED interaction event from Google Chat.
 * @return {Object} message responses specific to the dialog handling.
 */
function onCardClick(event) {
  // Initial dialog form page
  if (event.common.invokedFunction === "openInitialDialog") {
    return openInitialDialog();
  // Confirmation dialog form page
  } else if (event.common.invokedFunction === "openConfirmation") {
    return openConfirmation(event);
  // Submission dialog form page
  } else if (event.common.invokedFunction === "submitForm") {
    return submitForm(event);
  }
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @return {Object} a message with an action response to open a dialog.
 */
function openInitialDialog() {
  return { actionResponse: {
    type: "DIALOG",
    dialogAction: { dialog: { body: { sections: [{
      header: "Add new contact",
      widgets: CONTACT_FORM_WIDGETS.concat([{
        buttonList: { buttons: [{
          text: "Review and submit",
          onClick: { action: { function: "openConfirmation" }}
        }]}
      }])
    }]}}}
  }};
}

/**
 * Returns the second step as a dialog or card message that lets users confirm details.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} returns a dialog or private card message.
 */
function openConfirmation(event) {
  const name = fetchFormValue(event, "contactName") ?? "";
  const birthdate = fetchFormValue(event, "contactBirthdate") ?? "";
  const type = fetchFormValue(event, "contactType") ?? "";
  const cardConfirmation = {
    header: "Your contact",
    widgets: [{
      textParagraph: { text: "Confirm contact information and submit:" }}, {
      textParagraph: { text: "<b>Name:</b> " + name }}, {
      textParagraph: {
        text: "<b>Birthday:</b> " + convertMillisToDateString(birthdate)
      }}, {
      textParagraph: { text: "<b>Type:</b> " + type }}, {
      buttonList: { buttons: [{
        text: "Submit",
        onClick: { action: {
          function: "submitForm",
          parameters: [{
            key: "contactName", value: name }, {
            key: "contactBirthdate", value: birthdate }, {
            key: "contactType", value: type
          }]
        }}
      }]}
    }]
  };

  // Returns a dialog with contact information that the user input.
  if (event.isDialogEvent) {
    return { action_response: {
      type: "DIALOG",
      dialogAction: { dialog: { body: { sections: [ cardConfirmation ]}}}
    }};
  }

  // Updates existing card message with contact information that the user input.
  return {
    actionResponse: { type: "UPDATE_MESSAGE" },
    privateMessageViewer: event.user,
    cardsV2: [{
      card: { sections: [cardConfirmation]}
    }]
  }
}

/**
  * Validates and submits information from a dialog or card message
  * and notifies status.
  *
  * @param {Object} event the interactive event with parameters.
  * @return {Object} a message response that opens a dialog or posts a private
  *                  message.
  */
function submitForm(event) {
  const contactName = event.common.parameters["contactName"];
  // Checks to make sure the user entered a contact name.
  // If no name value detected, returns an error message.
  const errorMessage = "Don't forget to name your new contact!";
  if (!contactName && event.dialogEventType === "SUBMIT_DIALOG") {
    return { actionResponse: {
      type: "DIALOG",
      dialogAction: { actionStatus: {
        statusCode: "INVALID_ARGUMENT",
        userFacingMessage: errorMessage
      }}
    }};
  }
  if (!contactName) {
    return {
      privateMessageViewer: event.user,
      text: errorMessage
    };
  }

  // The Chat app indicates that it received form data from the dialog or card.
  // Sends private text message that confirms submission.
  const confirmationMessage = "✅ " + contactName + " has been added to your contacts.";
  if (event.dialogEventType === "SUBMIT_DIALOG") {
    return {
      actionResponse: {
        type: "DIALOG",
        dialogAction: { actionStatus: {
          statusCode: "OK",
          userFacingMessage: "Success " + contactName
        }}
      }
    };
  }
  return {
    actionResponse: { type: "NEW_MESSAGE" },
    privateMessageViewer: event.user,
    text: confirmationMessage
  };
}

/**
 * Extracts form input value for a given widget.
 *
 * @param {Object} event the CARD_CLICKED interaction event from Google Chat.
 * @param {String} widgetName a unique ID for the widget, specified in the widget's name field.
 * @returns the value inputted by the user, null if no value can be found.
 */
function fetchFormValue(event, widgetName) {
  const formItem = event.common.formInputs[widgetName][""];
  // For widgets that receive StringInputs data, the value input by the user.
  if (formItem.hasOwnProperty("stringInputs")) {
    const stringInput = event.common.formInputs[widgetName][""].stringInputs.value[0];
    if (stringInput != null) {
      return stringInput;
    }
  // For widgets that receive dateInput data, the value input by the user.
  } else if (formItem.hasOwnProperty("dateInput")) {
    const dateInput = event.common.formInputs[widgetName][""].dateInput.msSinceEpoch;
     if (dateInput != null) {
       return dateInput;
     }
  }

  return null;
}

/**
 * Converts date in milliseconds since epoch to user-friendly string.
 *
 * @param {Object} millis the milliseconds since epoch time.
 * @return {string} Display-friend date (English US).
 */
function convertMillisToDateString(millis) {
  const date = new Date(millis);
  const options = { year: 'numeric', month: 'long', day: 'numeric' };
  return date.toLocaleDateString('en-US', options);
}
contactForm.gs

شامل ابزاره‌هایی است که داده‌های فرم را از کاربران دریافت می‌کنند. این ابزارک‌های ورودی فرم در کارت‌هایی که در پیام‌ها و کادرهای گفتگو ظاهر می‌شوند نمایش داده می‌شوند.

apps-script/contact-form-app/contactForm.gs
/**
 * Copyright 2024 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * The section of the contact card that contains the form input widgets. Used in a dialog and card message.
 * To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
 */
const CONTACT_FORM_WIDGETS = [
  {
    "textInput": {
      "name": "contactName",
      "label": "First and last name",
      "type": "SINGLE_LINE"
    }
  },
  {
    "dateTimePicker": {
      "name": "contactBirthdate",
      "label": "Birthdate",
      "type": "DATE_ONLY"
    }
  },
  {
    "selectionInput": {
      "name": "contactType",
      "label": "Contact type",
      "type": "RADIO_BUTTON",
      "items": [
        {
          "text": "Work",
          "value": "Work",
          "selected": false
        },
        {
          "text": "Personal",
          "value": "Personal",
          "selected": false
        }
      ]
    }
  }
];
appsscript.json

مانیفست Apps Script که پروژه Apps Script را برای برنامه Chat که برافزا نیست تعریف و پیکربندی می‌کند.

apps-script/contact-form-app/appsscript.json
{
  "timeZone": "America/Los_Angeles",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "chat": {}
}

ایجاد و پیکربندی پروژه Apps Script

  1. پروژه Apps Script مربوط به برنامه Chat را که افزونه نیست باز کنید و از آن کپی بگیرید: مدیریت مخاطبین در Google Chat
  2. هنگام پیکربندی Chat API در «کنسول Google API»: ساخت این برنامه Chat به‌عنوان برافزای Google Workspace را لغو انتخاب کنید. کادر گفتگویی باز می‌شود که از شما می‌خواهد تأیید کنید. در چارگوش گفتگو، روی غیرفعال کردن کلیک کنید.