Thu thập và quản lý danh bạ trong Google Chat

Hướng dẫn này cho biết cách tạo một ứng dụng Google Chat giúp người dùng Google Chat quản lý danh bạ cá nhân và doanh nghiệp của họ. Để thu thập thông tin, ứng dụng Chat sẽ nhắc người dùng hoàn tất biểu mẫu liên hệ trong tin nhắn dạng thẻ và hộp thoại.

Xem cách hoạt động của ứng dụng Chat:

  • Biểu mẫu liên hệ từ lệnh dấu gạch chéo.
    Hình 1. Ứng dụng Chat phản hồi lệnh dấu gạch chéo /about bằng một tin nhắn văn bản và nút mở biểu mẫu liên hệ.
  • Biểu mẫu liên hệ trong hộp thoại.
    Hình 2. Ứng dụng Chat sẽ mở một hộp thoại để người dùng có thể nhập thông tin về một người liên hệ.
  • Hộp thoại xác nhận và xem lại.
    Hình 3. Ứng dụng Chat sẽ trả về một hộp thoại xác nhận để người dùng có thể xem xét và xác nhận thông tin trước khi gửi.
  • Một tin nhắn văn bản xác nhận người liên hệ mới.
    Hình 4. Sau khi người dùng gửi biểu mẫu, ứng dụng Chat sẽ gửi một tin nhắn văn bản riêng tư để xác nhận việc gửi.
  • Biểu mẫu liên hệ trong tin nhắn trên thẻ.
    Hình 5. Ứng dụng Chat cũng nhắc người dùng thêm người liên hệ từ thẻ trong tin nhắn.

Điều kiện tiên quyết

Mục tiêu

Kiến trúc

Ứng dụng Chat được tạo bằng Google Apps Script (dưới dạng một tiện ích bổ sung của Google Workspace giúp mở rộng Google Chat) và phản hồi tương tác của người dùng (onMessage, onAppCommand và các lượt nhấp vào nút sẽ gọi openInitialDialog, openConfirmationDialog và submitForm) để xử lý và phản hồi người dùng Chat.

Sau đây là cách người dùng thường tương tác với ứng dụng Chat:

  1. Người dùng mở một tin nhắn trực tiếp bằng ứng dụng Chat hoặc thêm ứng dụng Chat vào một không gian hiện có.

  2. Ứng dụng Chat nhắc người dùng thêm người liên hệ bằng cách tạo và hiển thị biểu mẫu liên hệ dưới dạng đối tượng card. Để trình bày biểu mẫu liên hệ, ứng dụng Chat sẽ phản hồi người dùng theo những cách sau:

    • Phản hồi các lượt đề cập bằng ký tự @và tin nhắn trực tiếp (onMessage) bằng một thông báo dạng thẻ có biểu mẫu liên hệ.
    • Phản hồi lệnh dấu gạch chéo /addContact (onAppCommand) bằng cách mở một hộp thoại có biểu mẫu liên hệ.
    • Phản hồi lệnh dấu gạch chéo /about (onAppCommand) bằng một tin nhắn văn bản có nút Thêm người liên hệ mà người dùng có thể nhấp vào để gọi openInitialDialog và mở một hộp thoại có biểu mẫu liên hệ.

  3. Khi thấy biểu mẫu liên hệ, người dùng sẽ nhập thông tin liên hệ vào các trường và tiện ích sau:

    • Họ và tên: một tiện ích textInput chấp nhận các chuỗi.
    • Ngày sinh: một tiện ích dateTimePicker chỉ chấp nhận ngày.
    • Loại liên hệ: một tiện ích selectionInput gồm các nút chọn cho phép người dùng chọn và gửi một giá trị chuỗi duy nhất (Personal hoặc Work).
    • Nút Xem lại và gửi: một mảng buttonList có tiện ích button mà người dùng nhấp vào để gửi các giá trị mà họ nhập.

  4. Ứng dụng Google Chat gọi openConfirmationDialog để xử lý các giá trị mà người dùng nhập và hiển thị các giá trị đó trong thẻ xác nhận.

  5. Người dùng xem xét thẻ xác nhận rồi nhấp vào nút Gửi để gọi submitForm và hoàn tất thông tin liên hệ.

  6. Ứng dụng Google Chat sẽ gửi một tin nhắn văn bản riêng tư để xác nhận việc gửi.

Chuẩn bị môi trường

Phần này hướng dẫn cách định cấu hình một dự án trên đám mây của Google cho ứng dụng Chat.

Mở dự án trên đám mây trong Google API Console

Nếu chưa mở, hãy mở dự án trên đám mây mà bạn dự định dùng cho mẫu này:

  1. Trong Google API Console, hãy chuyển đến trang Chọn một dự án.

    Chọn một dự án trên đám mây

  2. Chọn dự án trên Google Cloud mà bạn muốn sử dụng. Hoặc nhấp vào Tạo dự án rồi làm theo hướng dẫn trên màn hình. Nếu tạo một dự án trên Google Cloud, bạn có thể cần phải bật tính năng thanh toán cho dự án trên đám mây.

Thiết lập tính năng xác thực và uỷ quyền

Các ứng dụng Google Chat yêu cầu bạn định cấu hình một màn hình xin phép bằng OAuth để người dùng có thể uỷ quyền cho ứng dụng của bạn trong các ứng dụng Google Workspace, bao gồm cả Google Chat.

Trong hướng dẫn này, bạn sẽ triển khai một ứng dụng trò chuyện chỉ dành cho mục đích thử nghiệm và sử dụng nội bộ, vì vậy, bạn có thể sử dụng thông tin giữ chỗ cho màn hình đồng ý. Trước khi xuất bản ứng dụng Chat, hãy thay thế mọi thông tin giữ chỗ bằng thông tin thực.

  1. Trong Google API Console, hãy chuyển đến Trình đơn > Nền tảng xác thực của Google > Thương hiệu.

    Chuyển đến phần Xây dựng thương hiệu

  2. Nếu đã định cấu hình nền tảng Google Auth, bạn có thể định cấu hình các chế độ cài đặt sau đây cho Màn hình xin phép bằng OAuth trong phần Thương hiệu, Đối tượng và Quyền truy cập dữ liệu. Nếu bạn thấy thông báo cho biết Nền tảng Google Auth chưa được định cấu hình, hãy nhấp vào Bắt đầu:

    1. Trong phần App Information (Thông tin ứng dụng), trong phần App name (Tên ứng dụng), hãy nhập Contact Manager.
    2. Trong phần Email hỗ trợ người dùng, hãy chọn địa chỉ email của bạn hoặc một nhóm thích hợp trên Google Groups.
    3. Nhấp vào Tiếp theo.
    4. Trong phần Đối tượng, hãy chọn Nội bộ. Nếu bạn không thể chọn Nội bộ, hãy chọn Bên ngoài.
    5. Nhấp vào Tiếp theo.
    6. Trong phần Thông tin liên hệ, hãy nhập Địa chỉ email mà bạn có thể nhận thông báo về mọi thay đổi đối với dự án của mình.
    7. Nhấp vào Tiếp theo.
    8. Trong phần Hoàn tất, hãy xem Chính sách dữ liệu người dùng của các dịch vụ API của Google. Nếu bạn đồng ý, hãy chọn Tôi đồng ý với Chính sách dữ liệu người dùng của các dịch vụ API của Google.
    9. Nhấp vào Tiếp tục.
    10. Nhấp vào Tạo.
    11. Nếu bạn chọn Bên ngoài cho loại người dùng, hãy thêm người dùng thử nghiệm:
      1. Nhấp vào Đối tượng.
      2. Trong phần Người dùng kiểm thử, hãy nhấp vào Thêm người dùng.
      3. Nhập địa chỉ email của bạn và mọi người dùng kiểm thử được uỷ quyền khác, sau đó nhấp vào Lưu.

Tạo và triển khai ứng dụng Chat

Trong phần sau, bạn sẽ tạo và cập nhật một dự án Apps Script bằng mã xử lý ứng dụng (Code.gs và appsscript.json) cho ứng dụng Chat của mình.

Bạn có thể xem toàn bộ dự án trên GitHub (nếu muốn).

Xem trên GitHub

Sau đây là thông tin tổng quan về từng tệp:

Code.gs

Xử lý mọi logic của ứng dụng, bao gồm cả các hoạt động tương tác của người dùng (onMessage, onAppCommand, openInitialDialog, openConfirmationDialog và submitForm) cũng như các tiện ích nhập biểu mẫu xuất hiện trong thẻ trong tin nhắn và hộp thoại.

Xem Code.gs mã

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

Tệp kê khai Apps Script xác định và định cấu hình dự án Apps Script cho ứng dụng Chat.

Xem appsscript.json mã

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

Tạo dự án Apps Script

Cách tạo một dự án Apps Script từ các tệp Code.gs và appsscript.json:

  1. Truy cập vào Google Apps Script rồi nhấp vào Dự án mới.

  2. Đặt tên cho dự án Apps Script của bạn:

    1. Nhấp vào Dự án chưa có tiêu đề.

    2. Trong Project title (Tên dự án), hãy nhập Contact Manager - Google Chat app.

    3. Nhấp vào Đổi tên.

  3. Thay thế nội dung của Code.gs bằng mã mẫu Code.gs ở trên.

  4. Nhấp vào Project Settings (Cài đặt dự án) Biểu tượng cho phần cài đặt dự án rồi chọn Show "appsscript.json" manifest file in editor (Hiện tệp kê khai "appsscript.json" trong trình chỉnh sửa).

  5. Quay lại Trình chỉnh sửa và thay thế nội dung của appsscript.json bằng mã appsscript.json trong tệp kê khai ở trên, sau đó lưu dự án của bạn.

Trong tương lai, nếu muốn sử dụng một số API của Google hoặc xuất bản ứng dụng, bạn phải liên kết dự án trên đám mây với dự án Apps Script. Đối với hướng dẫn này, bạn không cần làm như vậy. Để tìm hiểu thêm, hãy xem hướng dẫn về dự án trên Google Cloud.

Tạo một bản triển khai Apps Script

Giờ đây, khi tất cả mã đã được đặt đúng vị trí, hãy triển khai dự án Apps Script. Bạn sử dụng mã nhận dạng triển khai khi định cấu hình ứng dụng Chat trong Google Cloud.

  1. Trong Apps Script, hãy mở dự án của ứng dụng Chat.

    Chuyển đến Apps Script

  2. Nhấp vào Triển khai > Triển khai mới.

  3. Nếu bạn chưa chọn Tiện ích bổ sung, thì bên cạnh Chọn loại, hãy nhấp vào các loại triển khai Biểu tượng cho phần cài đặt dự án rồi chọn Tiện ích bổ sung.

  4. Trong phần Nội dung mô tả, hãy nhập nội dung mô tả cho phiên bản này, chẳng hạn như Test of Contact Manager.

  5. Nhấp vào Triển khai. Apps Script báo cáo việc triển khai thành công và cung cấp một mã nhận dạng triển khai.

  6. Nhấp vào Sao chép để sao chép mã nhận dạng lượt triển khai, rồi nhấp vào Xong.

Định cấu hình ứng dụng Chat trong Google API Console

Phần này trình bày cách định cấu hình Google Chat API trong Google API Console bằng thông tin về ứng dụng Chat của bạn, bao gồm cả mã nhận dạng của bản triển khai mà bạn vừa tạo từ dự án Apps Script.

  1. Trong Google API Console, hãy nhấp vào Trình đơn > API và Dịch vụ > API và Dịch vụ đã bật > Google Chat API > Cấu hình.

    Chuyển đến phần Cấu hình Chat API

  2. Trong phần Tên ứng dụng, hãy nhập Contact Manager.

  3. Trong phần URL của hình đại diện, hãy nhập https://developers.google.com/chat/images/contact-icon.png.

  4. Trong mục Nội dung mô tả, hãy nhập Manage your personal and business contacts.

  5. Nhấp để gạt nút Bật tính năng tương tác sang vị trí bật.

  6. Trong phần Chức năng, hãy chọn Tham gia không gian và cuộc trò chuyện nhóm.

  7. Trong phần Cài đặt kết nối, hãy chọn Apps Script.

  8. Trong Mã nhận dạng lượt triển khai, hãy dán Mã nhận dạng lượt triển khai Apps Script mà bạn đã sao chép trong phần trước khi tạo lượt triển khai Apps Script.

  9. Trong mục Triggers (Điều kiện kích hoạt), hãy định cấu hình các hàm phản hồi hoạt động tương tác của người dùng:

    • Đối với điều kiện kích hoạt Tin nhắn, hãy nhập onMessage.
    • Đối với điều kiện kích hoạt Lệnh ứng dụng, hãy nhập onAppCommand.

  10. Trong phần Lệnh, hãy thiết lập các lệnh dấu gạch chéo /about và /addContact:

    1. Nhấp vào Thêm lệnh để thiết lập lệnh dấu gạch chéo đầu tiên.
    2. Trong Command ID (Mã lệnh), hãy nhập 1.
    3. Trong phần Nội dung mô tả, hãy nhập Learn how to use this Chat app to manage your contacts.
    4. Trong mục Loại lệnh, hãy chọn Slash command.
    5. Trong Slash command name (Tên lệnh dấu gạch chéo), hãy nhập /about.
    6. Nhấp vào Xong.
    7. Nhấp vào Thêm lệnh để thiết lập một lệnh dấu gạch chéo khác.
    8. Trong Command ID (Mã lệnh), hãy nhập 2.
    9. Trong phần Nội dung mô tả, hãy nhập Submit information about a contact.
    10. Trong mục Loại lệnh, hãy chọn Slash command.
    11. Trong Tên lệnh dấu gạch chéo, hãy nhập /addContact.
    12. Chọn Mở hộp thoại.
    13. Nhấp vào Xong.

  11. Trong phần Chế độ hiển thị, hãy chọn hộp đánh dấu Cho phép một số người và nhóm cụ thể sử dụng ứng dụng Chat này trong YOUR DOMAIN rồi nhập địa chỉ email của bạn.

  12. Trong phần Nhật ký, hãy chọn Ghi lỗi vào Nhật ký.

  13. Nhấp vào Lưu. Một thông báo Đã lưu cấu hình sẽ xuất hiện.

Ứng dụng Chat đã sẵn sàng để cài đặt và kiểm thử trong Chat.

Kiểm thử ứng dụng Chat

Để kiểm thử ứng dụng Chat, hãy mở một không gian nhắn tin trực tiếp có ứng dụng Chat rồi gửi một tin nhắn:

  1. Mở Google Chat bằng tài khoản Google Workspace mà bạn đã cung cấp khi thêm chính mình làm người thử nghiệm đáng tin cậy.

    Chuyển đến Google Chat

  2. Nhấp vào biểu tượng Cuộc trò chuyện mới.
  3. Trong trường Thêm một hoặc nhiều người, hãy nhập tên ứng dụng Chat của bạn.

  4. Chọn ứng dụng Chat trong kết quả. Một tin nhắn trực tiếp sẽ mở ra.

  1. Trong tin nhắn trực tiếp mới với ứng dụng Chat, hãy nhập /addContact rồi nhấn enter.

  2. Trong hộp thoại mở ra, hãy nhập thông tin liên hệ:

    1. Trong trường văn bản Họ và tên, hãy nhập tên.
    2. Trong bộ chọn ngày Ngày sinh, hãy chọn một ngày.
    3. Trong phần Loại người liên hệ, hãy chọn nút chọn Công việc hoặc Cá nhân.

  3. Nhấp vào Xem lại và gửi.

  4. Trong hộp thoại xác nhận, hãy xem lại thông tin bạn đã gửi rồi nhấp vào Gửi. Ứng dụng Chat sẽ trả lời bằng một tin nhắn văn bản có nội dung ✅ CONTACT NAME has been added to your contacts..

  5. Ngoài ra, bạn cũng có thể kiểm thử và gửi biểu mẫu liên hệ theo những cách sau:

    • Sử dụng lệnh dấu gạch chéo /about. Ứng dụng nhắn tin trả lời bằng một tin nhắn văn bản và một nút tiện ích bổ sung có nội dung Add a contact. Bạn có thể nhấp vào nút này để mở một hộp thoại có biểu mẫu liên hệ.
    • Gửi tin nhắn trực tiếp cho ứng dụng Chat mà không cần dùng lệnh dấu gạch chéo, chẳng hạn như Hello. Ứng dụng Chat sẽ trả lời bằng một văn bản và thẻ chứa biểu mẫu liên hệ.

Dọn dẹp

Để tránh phát sinh phí cho tài khoản Google Cloud của bạn đối với các tài nguyên được dùng trong hướng dẫn này, bạn nên xoá dự án trên đám mây.

  1. Trong Google API Console, hãy chuyển đến trang Quản lý tài nguyên. Nhấp vào Trình đơn > IAM và Quản trị > Quản lý tài nguyên.

    Chuyển đến Resource Manager

  2. Trong danh sách dự án, hãy chọn dự án bạn muốn xoá rồi nhấp vào biểu tượng Xoá .
  3. Trong hộp thoại, hãy nhập mã dự án rồi nhấp vào Tắt để xoá dự án.

Các ứng dụng Chat không phải là tiện ích bổ sung: Quản lý người liên hệ trong Google Chat

Các hướng dẫn và mã mẫu sau đây áp dụng cho một ứng dụng Chat không phải là tiện ích bổ sung của Google Workspace (Xem trên GitHub).

Tệp Apps Script

main.gs

Xử lý mọi logic của ứng dụng, bao gồm cả các sự kiện tương tác về thời điểm người dùng gửi tin nhắn đến ứng dụng Chat, nhấp vào các nút trong tin nhắn của ứng dụng Chat hoặc mở và đóng hộp thoại.

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

Chứa các tiện ích nhận dữ liệu biểu mẫu từ người dùng. Các tiện ích đầu vào biểu mẫu này xuất hiện trong các thẻ xuất hiện trong tin nhắn và hộp thoại.

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

Tệp kê khai Apps Script xác định và định cấu hình dự án Apps Script cho ứng dụng Chat không phải là tiện ích bổ sung.

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

Tạo và định cấu hình dự án Apps Script

  1. Mở dự án Apps Script Quản lý người liên hệ trong Google Chat cho một ứng dụng Chat không phải là tiện ích bổ sung rồi sao chép dự án đó.
  2. Khi định cấu hình Chat API trong Google API Console: Xoá Tạo ứng dụng Chat này dưới dạng một tiện ích bổ sung của Google Workspace. Một hộp thoại sẽ mở ra và yêu cầu bạn xác nhận. Trong hộp thoại, hãy nhấp vào Tắt.