收集和处理 Google Chat 用户的信息

本指南介绍了 Google Chat 应用如何通过在卡片式界面中构建表单输入来收集和处理用户信息。

图 1：Chat 应用示例，用于打开对话框以收集联系信息。

Chat 应用会向用户请求信息，以便在 Chat 中或之外执行操作，包括通过以下方式：

• 配置设置。例如，让用户自定义通知设置，或配置并将 Chat 应用添加到一个或多个聊天室。
• 在其他 Google Workspace 应用中创建或更新信息。例如，允许用户创建 Google 日历活动。
• 允许用户访问和更新其他应用或 Web 服务中的资源。例如，Chat 应用可以帮助用户直接在 Chat 聊天室中更新支持服务工单的状态。

前提条件

Node.js

启用了交互功能的 Google Chat 应用。如需使用 HTTP 服务创建交互式 Chat 应用，请完成此快速入门。

Python

启用了交互功能的 Google Chat 应用。如需使用 HTTP 服务创建交互式 Chat 应用，请完成此快速入门。

Java

一款已启用互动功能的 Google Chat 应用。如需使用 HTTP 服务创建交互式 Chat 应用，请完成此快速入门。

Apps 脚本

一款已启用互动功能的 Google Chat 应用。如需使用 Apps 脚本创建交互式 Chat 应用，请完成此快速入门。

使用卡片构建表单

为了收集信息，Chat 应用会设计表单及其输入内容，并将其内置到卡片中。为了向用户显示卡片，Chat 应用可以使用以下 Chat 界面：

• 包含一个或多个卡片的消息。
• 首页：一个卡片，显示在与 Chat 应用的私信首页标签页中。
• 对话框：即从消息和首页在新窗口中打开的卡片。

聊天应用可以使用以下 widget 来构建卡片：

• 用于向用户请求信息的表单输入 widget。（可选）您可以添加验证以形成输入 widget，以确保用户正确输入信息并设置格式。聊天应用可以使用以下表单输入 widget：

  • 文本输入 (textInput)，用于输入自由格式文本或建议文本。
  • 选择输入 (selectionInput) 是可选择的界面元素，例如复选框、单选按钮和下拉菜单。选择输入 widget 还可以从静态或动态数据源填充项。例如，用户可以从他们加入的 Chat 聊天室列表中进行选择。
  • 日期时间选择器 (dateTimePicker)，用于日期和时间条目。

• 一个按钮 widget，让用户可以提交他们在卡片中输入的值。用户点击该按钮后，Chat 应用就可以处理其收到的信息。

在以下示例中，卡片使用文本输入框、日期时间选择器和选择输入微件收集联系信息：

Node.js

node/contact-form-app/index.js

在 GitHub 上查看

/**
 * 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
        }
      ]
    }
  }
];

Python

python/contact-form-app/main.py

在 GitHub 上查看

# 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
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
        }
      ]
    }
  }
]

Java

java/contact-form-app/src/main/java/com/google/chat/contact/App.java

在 GitHub 上查看

// 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
final static private List<GoogleAppsCardV1Widget> CONTACT_FORM_WIDGETS = List.of(
  new GoogleAppsCardV1Widget().setTextInput(new GoogleAppsCardV1TextInput()
    .setName("contactName")
    .setLabel("First and last name")
    .setType("SINGLE_LINE")),
  new GoogleAppsCardV1Widget().setDateTimePicker(new GoogleAppsCardV1DateTimePicker()
    .setName("contactBirthdate")
    .setLabel("Birthdate")
    .setType("DATE_ONLY")),
  new GoogleAppsCardV1Widget().setSelectionInput(new GoogleAppsCardV1SelectionInput()
    .setName("contactType")
    .setLabel("Contact type")
    .setType("RADIO_BUTTON")
    .setItems(List.of(
      new GoogleAppsCardV1SelectionItem()
        .setText("Work")
        .setValue("Work")
        .setSelected(false),
      new GoogleAppsCardV1SelectionItem()
        .setText("Personal")
        .setValue("Personal")
        .setSelected(false)))));

Apps 脚本

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

在 GitHub 上查看

/**
 * 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
        }
      ]
    }
  }
];

如需查看更多可用于收集信息的交互式 widget 示例，请参阅设计交互式卡片或对话框。

接收来自互动 widget 的数据

如需查看更多示例，请参阅 Google Chat 应用示例。

每当用户点击按钮时，Chat 应用都会收到 CARD_CLICKED 互动事件，其中包含有关互动的信息。CARD_CLICKED 互动事件的载荷包含一个 common.formInputs 对象，该对象包含用户输入的任何值。

您可以从对象 common.formInputs.WIDGET_NAME 检索值，其中 WIDGET_NAME 是您为该 widget 指定的 name 字段。这些值会以 widget 的特定数据类型（表示为 Inputs 对象）的形式返回。

下面显示了 CARD_CLICKED 互动事件的一部分，其中用户为每个 widget 输入了值：

HTTP

{
  "type": "CARD_CLICKED",
  "common": { "formInputs": {
    "contactName": { "stringInputs": {
      "value": ["Kai 0"]
    }},
    "contactBirthdate": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }},
    "contactType": { "stringInputs": {
      "value": ["Personal"]
    }}
  }}
}

Apps 脚本

{
  "type": "CARD_CLICKED",
  "common": { "formInputs": {
    "contactName": { "": { "stringInputs": {
      "value": ["Kai 0"]
    }}},
    "contactBirthdate": { "": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }}},
      "contactType": { "": { "stringInputs": {
      "value": ["Personal"]
    }}}
  }}
}

为了接收数据，您的 Chat 应用会处理互动事件，以获取用户在 widget 中输入的值。下表展示了如何获取给定表单输入 widget 的值。对于每个微件，该表都会显示微件接受的数据类型，其值存储在互动事件中的位置，以及示例值。

重要提示：如果您的 Chat 应用是使用 Apps Script 构建的，您必须在微件名称后面添加 [""]，例如 formInputs.contactName[""].stringInputs.value[0]。

表单输入微件	输入数据类型	输入来自互动事件的值	示例值
textInput	stringInputs	event.common.formInputs.contactName.stringInputs.value[0]	Kai O
selectionInput	stringInputs	如需获取第一个或唯一值，请使用 event.common.formInputs.contactType.stringInputs.value[0]	Personal
仅接受日期的 dateTimePicker。	dateInput	event.common.formInputs.contactBirthdate.dateInput.msSinceEpoch。	1000425600000

将数据转移到其他卡

用户提交卡片信息后，您可能需要返回其他卡片才能执行以下任一操作：

• 通过创建不同的部分，帮助用户填写较长的表单。
• 让用户预览并确认初始卡片中的信息，以便在提交之前检查答案。
• 动态填充表单的其余部分。例如，如需提示用户创建预约，Chat 应用可以显示一张初始卡片，用于请求预约的原因，然后填充另一个根据预约类型提供空闲时间的卡片。

如需从初始卡片传输数据输入，您可以使用 actionParameters 构建 button widget，其中包含 widget 的 name 和用户输入的值，如以下示例所示：

Node.js

node/contact-form-app/index.js

在 GitHub 上查看

buttonList: { buttons: [{
  text: "Submit",
  onClick: { action: {
    function: "submitForm",
    parameters: [{
      key: "contactName", value: name }, {
      key: "contactBirthdate", value: birthdate }, {
      key: "contactType", value: type
    }]
  }}
}]}

Python

python/contact-form-app/main.py

在 GitHub 上查看

'buttonList': { 'buttons': [{
  'text': "Submit",
  'onClick': { 'action': {
    'function': "submitForm",
    'parameters': [{
      'key': "contactName", 'value': name }, {
      'key': "contactBirthdate", 'value': birthdate }, {
      'key': "contactType", 'value': type
    }]
  }}
}]}

Java

java/contact-form-app/src/main/java/com/google/chat/contact/App.java

在 GitHub 上查看

new GoogleAppsCardV1Widget().setButtonList(new GoogleAppsCardV1ButtonList().setButtons(List.of(new GoogleAppsCardV1Button()
  .setText("Submit")
  .setOnClick(new GoogleAppsCardV1OnClick().setAction(new GoogleAppsCardV1Action()
    .setFunction("submitForm")
    .setParameters(List.of(
      new GoogleAppsCardV1ActionParameter().setKey("contactName").setValue(name),
      new GoogleAppsCardV1ActionParameter().setKey("contactBirthdate").setValue(birthdate),
      new GoogleAppsCardV1ActionParameter().setKey("contactType").setValue(type))))))))));

Apps 脚本

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

在 GitHub 上查看

buttonList: { buttons: [{
  text: "Submit",
  onClick: { action: {
    function: "submitForm",
    parameters: [{
      key: "contactName", value: name }, {
      key: "contactBirthdate", value: birthdate }, {
      key: "contactType", value: type
    }]
  }}
}]}

当用户点击该按钮时，您的 Chat 应用会收到 CARD_CLICKED 互动事件，您可以从中接收数据。

回复表单提交内容

从卡片消息或对话框收到数据后，Chat 应用会通过确认收到或返回错误来响应。

在以下示例中，Chat 应用发送一条短信，确认已成功收到通过对话框或卡片消息提交的表单。

Node.js

node/contact-form-app/index.js

在 GitHub 上查看

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.
if (!contactName) {
  const errorMessage = "Don't forget to name your new contact!";
  if (event.dialogEventType === "SUBMIT_DIALOG") {
    return { actionResponse: {
      type: "DIALOG",
      dialogAction: { actionStatus: {
        statusCode: "INVALID_ARGUMENT",
        userFacingMessage: errorMessage
      }}
    }};
  } else {
    return {
      privateMessageViewer: event.user,
      text: errorMessage
    };
  }
}

Python

python/contact-form-app/main.py

在 GitHub 上查看

contact_name = event.get('common').get('parameters')["contactName"]
# Checks to make sure the user entered a contact name.
# If no name value detected, returns an error message.
if contact_name == "":
  error_message = "Don't forget to name your new contact!"
  if "SUBMIT_DIALOG" == event.get('dialogEventType'):
    return { 'actionResponse': {
      'type': "DIALOG",
      'dialogAction': { 'actionStatus': {
        'statusCode': "INVALID_ARGUMENT",
        'userFacingMessage': error_message
      }}
    }}
  else:
    return {
      'privateMessageViewer': event.get('user'),
      'text': error_message
    }

Java

java/contact-form-app/src/main/java/com/google/chat/contact/App.java

在 GitHub 上查看

String contactName = event.at("/common/parameters/contactName").asText();
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
if (contactName.isEmpty()) {
  String errorMessage = "Don't forget to name your new contact!";
  if (event.at("/dialogEventType") != null && "SUBMIT_DIALOG".equals(event.at("/dialogEventType").asText())) {
    return new Message().setActionResponse(new ActionResponse()
      .setType("DIALOG")
      .setDialogAction(new DialogAction().setActionStatus(new ActionStatus()
        .setStatusCode("INVALID_ARGUMENT")
        .setUserFacingMessage(errorMessage))));
  } else {
    return new Message()
      .setPrivateMessageViewer(new User().setName(event.at("/user/name").asText()))
      .setText(errorMessage);
  }
}

Apps 脚本

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

在 GitHub 上查看

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.
if (!contactName) {
  const errorMessage = "Don't forget to name your new contact!";
  if (event.dialogEventType === "SUBMIT_DIALOG") {
    return { actionResponse: {
      type: "DIALOG",
      dialogAction: { actionStatus: {
        statusCode: "INVALID_ARGUMENT",
        userFacingMessage: errorMessage
      }}
    }};
  } else {
    return {
      privateMessageViewer: event.user,
      text: errorMessage
    };
  }
}

如需处理并关闭对话框，您需要返回一个 ActionResponse 对象，用于指定您是想要发送确认消息、更新原始消息或卡片，还是仅关闭对话框。如需了解相关步骤，请参阅关闭对话框。

问题排查

当 Google Chat 应用或卡片返回错误时，Chat 界面会显示“出了点问题”消息。或“无法处理您的请求”。有时，Chat 界面不显示任何错误消息，但 Chat 应用或卡片会产生意外结果；例如，卡片消息可能不会显示。

虽然 Chat 界面中可能未显示错误消息，但当为 Chat 应用启用错误日志记录功能时，系统会显示描述性错误消息和日志数据，帮助您修复错误。如需查看、调试和修正错误方面的帮助，请参阅排查和修正 Google Chat 错误。

相关主题

• 查看联系人管理器示例，这是一款 Chat 应用，可通过卡片消息和对话框提示用户填写联系表单。
• 打开互动式对话框