在 Google Chat 中收集和管理联系人

本教程介绍了如何构建 Google Chat 应用，以帮助 Google Chat 用户管理其个人和业务联系人。为了收集信息，Chat 应用会提示用户在卡片消息和对话框中填写联系表单。

查看 Chat 应用的实际应用：

• 

  图 1. 聊天应用会通过一条文本消息和用于打开联系表单的按钮来响应斜杠命令 /about。

• 
  图 2. Chat 应用会打开一个对话框，供用户输入联系人信息。
• 
  图 3. 聊天应用会返回一个确认对话框，以便用户在提交之前查看并确认信息。
• 
  图 4. 用户提交表单后，Chat 应用会发送一条私信来确认提交。
• 
  图 5.Chat 应用还会提示用户从消息中的卡片添加联系人。

前提条件

• 拥有 Google Workspace 商务版或企业版账号，且有权访问 Google Chat。

目标

• 将设计和构建的用户界面 (UI) 作为 card 对象，并在消息和对话框中显示这些界面。
• 接收并处理用户通过表单输入 widget 提交的信息。
• 使用包含文字、卡片和配件 widget 的消息响应命令。

架构

该 Chat 应用基于 Google Apps 脚本构建，并使用互动事件来处理 Chat 用户并做出响应。

以下内容展示了用户通常如何与 Chat 应用互动：

1. 用户打开与 Chat 应用的私信对话，或将 Chat 应用添加到现有聊天室。

2. Chat 应用会通过构建并显示联系人表单（以 card 对象的形式）来提示用户添加联系人。为了显示联系表单，Chat 应用会以以下方式响应用户：

   • 通过包含联系表单的卡片消息来响应 @提及和私信。
   • 通过打开包含联系表单的对话框来响应斜杠命令 /addContact。
   • 使用包含添加联系人按钮的文本消息来响应斜杠命令 /about，用户可以点击该按钮打开包含联系人表单的对话框。

3. 当用户看到联系表单时，会在以下字段和 widget 中输入联系信息：

   • 名字和姓氏：接受字符串的 textInput widget。
   • 出生日期：仅接受日期的 dateTimePicker widget。
   • 联系类型：一个包含单选按钮的 selectionInput widget，可让用户选择并提交单个字符串值（Personal 或 Work）。
   • “查看并提交”按钮：一个包含 button widget 的 buttonList 数组，用户点击该 widget 可提交其输入的值。

4. Google Chat 应用会处理 CARD_CLICKED 互动事件，以处理用户输入的值，并在确认卡片中显示这些值。

5. 用户查看确认卡片，然后点击提交按钮以最终确定联系信息。

6. Google Chat 应用会发送一条私密短信，确认提交成功。

准备环境

本部分介绍如何为 Chat 应用创建和配置 Google Cloud 项目。

创建 Google Cloud 项目

Google Cloud 控制台

1. 在 Google Cloud 控制台中，依次前往菜单 > IAM 和管理 > 创建项目。

   前往“创建项目”

2. 在 Project Name 字段中，输入项目的描述性名称。

   可选：如需修改项目 ID，请点击修改。项目创建后，项目 ID 便无法更改，因此请选择满足项目生命周期需求的 ID。

3. 在位置字段中，点击浏览以显示项目的潜在位置。然后，点击选择。
   注意：找不到您的 Google Workspace 组织？
   这意味着您未登录 Google Workspace 账号。Google Workspace 开发者文档中描述的部分功能仅适用于与组织关联的项目。
4. 点击创建。Google Cloud 控制台会转到“信息中心”页面，您的项目会在几分钟内创建完毕。

gcloud CLI

在以下任一开发环境中，访问 Google Cloud CLI (gcloud)：

• Cloud Shell：如需使用已设置 gcloud CLI 的在线终端，请激活 Cloud Shell。
  激活 Cloud Shell
• 本地 shell：如需使用本地开发环境，请安装并初始化 gcloud CLI。
  如需创建 Cloud 项目，请使用 gcloud projects create 命令：

  gcloud projects create PROJECT_ID

  通过设置要创建的项目的 ID 来替换 PROJECT_ID。

设置身份验证和授权

Google Chat 应用要求您配置 OAuth 权限请求页面，以便用户可以在 Google Workspace 应用（包括 Google Chat）中授权您的应用。

在本教程中，您将部署一个仅用于测试和内部使用的聊天应用，因此可以在意见征求屏幕上使用占位信息。在发布聊天应用之前，请将所有占位信息替换为真实信息。

1. 在 Google Cloud 控制台中，依次前往“菜单”图标 > > 品牌推广。

   前往“品牌推广”

2. 如果您已配置，则可以在品牌推广、受众群体和数据访问权限中配置以下 OAuth 权限请求页面设置。 如果您看到一条消息，提示 尚未配置，请点击开始：

   1. 在应用信息下的应用名称中，输入 Contact Manager。
   2. 在用户支持电子邮件地址中，选择您的电子邮件地址或合适的 Google 群组。
   3. 点击下一步。
   4. 在受众群体下，选择内部。如果您无法选择内部，请选择外部。
   5. 点击下一步。
   6. 在联系信息下，输入一个电子邮件地址，以便您接收有关项目变更的通知。
   7. 点击下一步。
   8. 在完成下，查看 Google API 服务用户数据政策，如果您同意该政策，请选择我同意《Google API 服务：用户数据政策》。
   9. 点击继续。
   10. 点击创建。
   11. 如果您为用户类型选择了外部，请添加测试用户：
       1. 点击受众群体。
       2. 在测试用户下，点击添加用户。
       3. 输入您的电子邮件地址和任何其他已获授权的测试用户，然后点击保存。

创建和部署聊天应用

在下一部分中，您将复制并更新一个完整的 Apps 脚本项目，其中包含 Chat 应用所需的所有应用代码，因此无需复制并粘贴每个文件。

您也可以在 GitHub 上查看整个项目。

在 GitHub 上查看

下面简要介绍一下每个文件：

main.gs

处理所有应用逻辑，包括有关用户何时向 Chat 应用发送消息、点击 Chat 应用消息中的按钮或打开和关闭对话框的互动事件。

查看 main.gs 代码

apps-script/contact-form-app/main.gs

在 GitHub 上查看

/**
 * 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

包含从用户那里接收表单数据的 widget。这些表单输入 widget 显示在消息和对话框中显示的卡片中。

查看 contactForm.gs 代码

apps-script/contact-form-app/contactForm.gs

在 GitHub 上查看

/**
 * 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

用于为 Chat 应用定义和配置 Apps 脚本项目的 Apps 脚本清单。

查看 appsscript.json 代码

apps-script/contact-form-app/appsscript.json

在 GitHub 上查看

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "chat": {}
}

查找您的 Cloud 项目编号和 ID

1. 在 Google Cloud 控制台中，前往您的 Cloud 项目。

   转到 Google Cloud 控制台

2. 依次点击“设置和实用程序”图标 > 项目设置。

3. 记下项目编号和项目 ID 字段中的值。您将在后续部分中使用它们。

创建 Apps 脚本项目

如需创建 Apps 脚本项目并将其与您的 Cloud 项目相关联，请执行以下操作：

1. 点击以下按钮，打开 Manage contacts in Google Chat Apps 脚本项目。
   打开项目
2. 点击 概览。
3. 在概览页面上，点击 复制。

4. 为复制的 Apps 脚本项目命名：

   1. 点击在 Google Chat 中管理联系人的副本。

   2. 在项目名称中，输入 Contact Manager - Google Chat app

   3. 点击重命名。

设置 Apps 脚本项目的 Cloud 项目

1. 在 Apps 脚本项目中，点击 项目设置。
2. 在 Google Cloud Platform (GCP) 项目下，点击更改项目。
3. 在 GCP 项目编号中，粘贴您的 Cloud 项目的编号。
4. 点击设置项目。Cloud 项目和 Apps 脚本项目现已关联。

创建 Apps 脚本部署

现在，所有代码都已就绪，接下来请部署 Apps 脚本项目。在 Google Cloud 中配置 Chat 应用时，您需要使用部署 ID。

1. 在 Apps 脚本中，打开 Chat 应用的项目。

   前往 Apps 脚本

2. 依次点击部署 > 新部署。

3. 如果插件尚未选中，请点击选择类型旁边的部署类型图标 ，然后选择插件。

4. 在说明中，输入此版本的说明，例如 Test of Contact Manager。

5. 点击部署。Apps 脚本会报告部署成功并提供部署 ID。

6. 点击 Copy 复制部署 ID，然后点击 Done。

在 Google Cloud 控制台中配置 Chat 应用

本部分将介绍如何在 Google Cloud 控制台中配置 Google Chat API，其中包含有关 Chat 应用的信息，包括您刚刚从 Apps 脚本项目创建的部署的 ID。

1. 在 Google Cloud 控制台中，依次点击菜单 > 更多产品 > Google Workspace > 产品库 > 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 脚本。

8. 在部署 ID 中，粘贴您在上一部分中创建 Apps 脚本部署时复制的 Apps 脚本部署 ID。

9. 在命令下，设置斜杠命令 /about 和 /addContact：

   1. 点击添加斜杠命令以设置第一个斜杠命令。
   2. 在名称中，输入 About。
   3. 在命令 ID 中，输入 1。
   4. 在说明中，输入 Learn how to use this Chat app to manage your contacts。
   5. 在命令类型下，选择 Slash command。
   6. 在斜杠命令名称中，输入 /about。
   7. 选择打开对话框。
   8. 点击完成。
   9. 点击添加命令以设置其他斜杠命令。
   10. 在名称中，输入 Add a contact。
   11. 在命令 ID 中，输入 2。
   12. 在说明中，输入 Submit information about a contact。
   13. 在命令类型下，选择 Slash command。
   14. 在斜杠命令名称中，输入 /addContact。
   15. 选择打开对话框。
   16. 点击完成。

10. 在公开范围下方，选中面向 YOUR DOMAIN 中的特定人员和群组提供此 Chat 扩展应用复选框，然后输入您的电子邮件地址。

11. 在日志下，选择将错误记录到 Logging。

12. 点击保存。系统会显示一条“配置已保存”消息。

Chat 应用已准备就绪，可在 Chat 中安装和测试。

测试 Chat 应用

如需测试 Chat 应用，请打开与该应用的私信对话，然后发送消息：

1. 使用您在添加自己为可信测试人员时提供的 Google Workspace 账号打开 Google Chat。

   前往 Google Chat

2. 点击 发起新聊天。
3. 在添加 1 位或多位用户字段中，输入您的 Chat 应用的名称。

4. 从结果中选择您的 Chat 应用。系统会打开私信对话。

   注意：如果您在结果列表中没有看到自己的 Chat 应用，请确保您已在 Google Cloud 控制台的 Chat API 配置页面中将您的 Google Workspace 账号纳入公开范围设置。

1. 在与 Chat 应用的新私信对话中，输入 /addContact 并按 Enter 键。

2. 在随即打开的对话框中，输入联系信息：

   1. 在名字和姓氏文本字段中，输入一个名称。
   2. 在出生日期日期选择器中，选择一个日期。
   3. 在联系类型下，选择工作或个人单选按钮。

3. 点击查看并提交。

4. 在确认对话框中，查看您提交的信息，然后点击提交。Chat 应用会回复一条文本消息，内容为 ✅ CONTACT NAME has been added to your contacts.。

5. 您还可以选择通过以下方式测试并提交联系表单：

   • 使用 /about 斜杠命令。聊天应用会回复一条文本消息和一个显示 Add a contact 的配件 widget 按钮。您可以点击该按钮打开包含联系表单的对话框。
   • 向 Chat 应用发送不含斜杠命令的私信，例如 Hello。Chat 应用会回复一条包含联系表单的文本和卡片。

清理

为避免系统因本教程中使用的资源向您的 Google Cloud 账号收取费用，我们建议您删除 Cloud 项目。

警告：删除项目会产生以下影响：

• 项目中的所有内容都会被删除。如果您在本教程使用现有项目，则删除该项目后，还将删除您已在该项目中完成的其他所有工作。
• 自定义项目 ID 会丢失。创建此项目时，您可能创建了要在将来使用的自定义项目 ID。如需保留使用该项目 ID 的网址（例如 appspot.com 上的网址），请删除项目内的所选资源，而不是删除整个项目。

如果您打算浏览多个教程和快速入门，重复使用项目可以帮助您避免超出项目配额上限。

1. 在 Google Cloud 控制台中，前往管理资源页面。依次点击 菜单 > IAM 和管理 > 管理资源。

   前往资源管理器

2. 在项目列表中，选择要删除的项目，然后点击删除 。
3. 在对话框中输入项目 ID，然后点击关停以删除项目。

相关主题

• 响应命令
• 收集和处理 Google Chat 用户的信息
• 打开互动式对话框
• 探索其他 Google Chat 应用示例