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

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

注意：在 Google Chat 中，插件会作为 Google Chat 应用显示给用户。您还可以使用 Google Chat API 互动事件来构建 Chat 应用。如需了解详情，请参阅扩展 Google Chat 概览。

图 1：一个聊天应用，可打开对话框来收集联系信息。

聊天应用会向用户请求信息，以便在 Chat 内或 Chat 外执行操作，包括以下方式：

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

前提条件

HTTP

扩展 Google Chat 的 Google Workspace 加载项。如需构建一个，请完成 HTTP 快速入门。

注意：本指南中的代码示例旨在作为 Google Cloud Run 函数在 Node.js 中运行。

Apps 脚本

扩展 Google Chat 的 Google Workspace 加载项。如需构建一个，请完成 Apps 脚本快速入门。

使用卡片构建表单

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

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

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

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

  • 用于输入自由格式文本或建议文本的文本输入 (textInput)。

  • 选择输入源 (selectionInput) 是可选择的界面元素，例如复选框、单选按钮和下拉菜单。选择输入 widget 还可以根据 Google Workspace 数据（例如 Chat 聊天室）或动态数据源填充和建议项目。如需了解详情，请参阅以下部分：添加下拉菜单和添加多选菜单。

  • 用于输入日期和时间的日期时间选择器 (dateTimePicker)。

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

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

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

添加下拉菜单

如需自定义选择项或让用户从动态数据源中选择单个项，Chat 应用可以使用下拉菜单，这是一种 SelectionInput widget。例如，以下卡片显示了一个下拉菜单，用户可以从联系人列表中动态选择联系人：

您可以通过以下数据源填充下拉菜单的项：

• Google Workspace 数据，包括用户或 Chat 聊天室。
• 外部数据源，例如关系型数据库。

从 Google Workspace 数据源填充内容

如需填充来自 Google Workspace 数据源（例如 Google Workspace 用户）的项，请在 DataSourceConfig 对象中指定 platformDataSource 字段。与其他选择输入类型不同，您需要省略 SelectionItem 对象，因为这些选择项是从 Google Workspace 动态获取的。

以下代码显示了 Google Workspace 用户的下拉菜单：

JSON

{
  "sections": [
    {
      "header": "Section Header",
      "widgets": [
        {
          "selectionInput": {
            "name": "contacts",
            "type": "DROPDOWN",
            "label": "Select contact from organization",
            "data_source_configs": [
              {
                "platformDataSource": {
                  "commonDataSource": "USER"
                },
                "min_characters_trigger": 1
              }
            ]
          }
        }
      ]
    }
  ]
}

从外部数据源填充商品

下拉菜单还可以从第三方或外部数据源填充项。如需使用外部数据源，您可以在 DataSourceConfig 对象中指定 remoteDataSource 字段，该对象包含用于查询数据源并从中返回项的函数。

为了减少对外部数据源的请求，您可以在用户在菜单中输入内容之前，在下拉菜单中添加建议的商品。如需从外部数据源填充建议项，请指定静态 SelectionItem 对象。

以下代码展示了一个下拉菜单，该菜单会查询外部数据源并填充其中的项：

JSON

{
  "sections": [
    {
      "header": "Section Header",
      "widgets": [
        {
          "selectionInput": {
            "name": "crm_leads",
            "type": "DROPDOWN",
            "label": "Select CRM Lead",
            "data_source_configs": [
              {
                "remoteDataSource": {
                  "function": "getCrmLeads"
                },
                "min_characters_trigger": 2
              }
            ],
            "items": [
              {
                "text": "Suggested Lead 1",
                "value": "lead-1"
              }
            ]
          }
        }
      ]
    }
  ]
}

如需查看展示如何返回建议项的完整示例，请参阅建议选择项部分。

添加多选菜单

如需自定义选择项或让用户从动态数据源中选择项，Chat 应用可以使用多选菜单，这是一种 SelectionInput widget。例如，以下卡片显示了一个多选菜单，用户可以从联系人列表中动态选择：

您可以从以下数据源填充多选菜单的项：

• Google Workspace 数据，包括用户所属的用户或聊天室。该菜单仅填充来自同一 Google Workspace 组织的项。
• 外部数据源，例如关系型数据库。 例如，您可以使用多选菜单帮助用户从客户关系管理 (CRM) 系统的销售线索列表中进行选择。

从 Google Workspace 数据源填充内容

如需使用 Google Workspace 数据源，请在 SelectionInput widget 中指定 platformDataSource 字段。与其他选择输入类型不同，您需要省略 SelectionItem 对象，因为这些选择项是从 Google Workspace 动态获取的。

以下代码显示了 Google Workspace 用户的多选菜单。 为了填充用户，选择输入将 commonDataSource 设置为 USER：

JSON

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "commonDataSource": "USER"
    }
  }
}

以下代码显示了聊天室的多选菜单。如需填充空间，选择输入会指定 hostAppDataSource 字段。多选菜单还会将 defaultToCurrentSpace 设置为 true，这会使当前空间成为菜单中的默认选择：

JSON

{
  "selectionInput": {
    "name": "spaces",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "hostAppDataSource": {
        "chatDataSource": {
          "spaceDataSource": {
            "defaultToCurrentSpace": true
          }
        }
      }
    }
  }
}

从外部数据源填充商品

多选菜单还可以从第三方或外部数据源填充项。如需使用外部数据源，您需要在 SelectionInput widget 中指定 externalDataSource 字段，该字段包含用于查询数据源并从中返回项的函数。

为了减少对外部数据源的请求，您可以在用户在多选菜单中输入内容之前，先在菜单中显示建议的项目。例如，您可以为用户填充最近搜索过的联系人。如需从外部数据源填充建议项，请指定静态 SelectionItem 对象。

以下代码示例展示了一个多选菜单，该菜单会查询外部数据源并从中填充项：

Node.js

node/chat/selection-input/index.js

在 GitHub 上查看

selectionInput: {
  name: "contacts",
  type: "MULTI_SELECT",
  label: "Selected contacts",
  multiSelectMaxSelectedItems: 3,
  multiSelectMinQueryLength: 1,
  externalDataSource: { function: FUNCTION_URL },
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  items: [getSuggestedContact("3")]
}

将 FUNCTION_URL 替换为用于查询外部数据源的 HTTP 端点。

Python

python/chat/selection-input/main.py

在 GitHub 上查看

'selectionInput': {
  'name': "contacts",
  'type': "MULTI_SELECT",
  'label': "Selected contacts",
  'multiSelectMaxSelectedItems': 3,
  'multiSelectMinQueryLength': 1,
  'externalDataSource': { 'function': FUNCTION_URL },
  # Suggested items loaded by default.
  # The list is static here but it could be dynamic.
  'items': [get_suggested_contact("3")]
}

将 FUNCTION_URL 替换为用于查询外部数据源的 HTTP 端点。

Java

java/chat/selection-input/src/main/java/com/google/chat/selectionInput/App.java

在 GitHub 上查看

.setSelectionInput(new GoogleAppsCardV1SelectionInput()
  .setName("contacts")
  .setType("MULTI_SELECT")
  .setLabel("Selected contacts")
  .setMultiSelectMaxSelectedItems(3)
  .setMultiSelectMinQueryLength(1)
  .setExternalDataSource(new GoogleAppsCardV1Action().setFunction(FUNCTION_URL))
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  .setItems(List.of(getSuggestedContact("3")))))))))));

将 FUNCTION_URL 替换为用于查询外部数据源的 HTTP 端点。

Apps 脚本

此示例通过返回 card JSON 来发送卡片消息。您还可以使用 Apps 脚本卡片服务。

apps-script/chat/selection-input/selection-input.gs

在 GitHub 上查看

selectionInput: {
  name: "contacts",
  type: "MULTI_SELECT",
  label: "Selected contacts",
  multiSelectMaxSelectedItems: 3,
  multiSelectMinQueryLength: 1,
  externalDataSource: { function: "queryContacts" },
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  items: [getSuggestedContact("3")]
}

如需查看展示如何返回建议项的完整示例，请参阅建议选择项部分。

从互动微件接收数据

每当用户点击按钮时，系统都会触发其 Chat 应用操作，并提供有关互动的相关信息。在事件载荷的 commonEventObject 中，formInputs 对象包含用户输入的所有值。

您可以从对象 commonEventObject.formInputs.WIDGET_NAME 中检索值，其中 WIDGET_NAME 是您为 widget 指定的 name 字段。这些值会以 widget 的特定数据类型返回。

以下内容展示了事件对象的一部分，其中用户为每个 widget 输入了值：

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

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

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

Chat 应用收到数据后，可以执行以下任一操作：

• 对于包含多选菜单的卡片，根据用户在菜单中输入的内容填充或建议项目。
• 将数据转移到另一张卡片，以便用户查看自己的信息或继续填写表单的下一部分。
• 回复用户，确认用户已成功填写表单。

建议选择项

如果卡片包含一个多选菜单或一个从外部数据源填充项的下拉菜单，Chat 扩展应用可以根据用户在菜单中输入的内容返回建议项。例如，如果用户开始输入 Atl 以显示美国城市填充的菜单，那么在用户完成输入之前，您的 Chat 应用可以自动建议 Atlanta。Chat 应用最多可建议 100 项。

如需在选择输入中建议并动态填充项，卡片上的 SelectionInput widget 必须指定一个查询外部数据源的函数。对于多选菜单，您需要指定 externalDataSource 字段。对于下拉菜单，您可以在 DataSourceConfig 对象内指定 remoteDataSource 字段。

您还可以配置用户在菜单返回建议之前输入的字符数。对于多选菜单，请设置 multiSelectMinQueryLength 字段。对于下拉菜单，请在 DataSourceConfig 中设置 min_characters_trigger 字段。

如需返回建议的项目，该函数必须执行以下操作：

1. 处理 event 对象，当用户在菜单中输入内容时，Chat 应用会收到该对象。
2. 从事件对象中获取用户输入的值，该值在 event.commonEventObject.parameters["autocomplete_widget_query"] 字段中表示。
3. 使用用户输入的值查询数据源，以获取一个或多个 SelectionItems 来向用户提供建议。
4. 通过返回包含 modifyCard 对象的 RenderActions 操作来返回建议的商品。

以下代码示例展示了 Chat 应用如何在卡片上的多选菜单中动态建议项。当用户在菜单中输入内容时，widget 的 externalDataSource 字段中提供的函数或端点会查询外部数据源，并建议用户可以选择的项。

Node.js

node/chat/selection-input/index.js

在 GitHub 上查看

/**
 * Web app that responds to events sent from a Google Chat space.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
app.post('/', async (req, res) => {
  // Stores the Google Chat event
  const chatEvent = req.body.chat;

  // Handle user interaction with multiselect.
  if(chatEvent.widgetUpdatedPayload) {
    return res.json(queryContacts(req.body));
  }

  // Replies with a card that contains the multiselect menu.
  return res.json({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: FUNCTION_URL },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact("3")]
        }
      }]}]}
    }]
  }}}}});
});

/**
 * Get contact suggestions based on text typed by users.
 *
 * @param {Object} event the event object that contains the user's query
 * @return {Object} suggestions
 */
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
  // Only return items based on the query from the user.
  ].filter(e => !query || e.text.includes(query)) }}}]}};
}

/**
 * Generate a suggested contact given an ID.
 *
 * @param {String} id The ID of the contact to return.
 * @return {Object} The contact formatted as a selection item in the menu.
 */
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

将 FUNCTION_URL 替换为用于查询外部数据源的 HTTP 端点。

Python

python/chat/selection-input/main.py

在 GitHub 上查看

@app.route('/', methods=['POST'])
def post() -> Mapping[str, Any]:
  """Handle requests from Google Chat

  Returns:
      Mapping[str, Any]: The response
  """
  # Stores the Google Chat event
  chatEvent = request.get_json().get('chat')

  # Handle user interaction with multiselect.
  if chatEvent.get('widgetUpdatedPayload') is not None:
    return json.jsonify(query_contacts(request.get_json()))

  # Replies with a card that contains the multiselect menu.
  return json.jsonify({ 'hostAppDataAction': { 'chatDataAction': { 'createMessageAction': {
    'message': { 'cardsV2': [{
      'cardId': "contactSelector",
      'card': { 'sections':[{ 'widgets': [{
        'selectionInput': {
          'name': "contacts",
          'type': "MULTI_SELECT",
          'label': "Selected contacts",
          'multiSelectMaxSelectedItems': 3,
          'multiSelectMinQueryLength': 1,
          'externalDataSource': { 'function': FUNCTION_URL },
          # Suggested items loaded by default.
          # The list is static here but it could be dynamic.
          'items': [get_suggested_contact("3")]
        }
      }]}]}
    }]}
  }}}})


def query_contacts(event: dict) -> dict:
  """Get contact suggestions based on text typed by users.

  Args:
      event (Mapping[str, Any]): The event object that contains the user's query

  Returns:
      Mapping[str, Any]: The response with contact suggestions.
  """
  query = event.get("commonEventObject").get("parameters").get("autocomplete_widget_query")
  return { 'action': { 'modifyOperations': [{ 'updateWidget': { 'selectionInputWidgetSuggestions': { 'suggestions': list(
    filter(lambda e: query is None or query in e["text"], [
      # The list is static here but it could be dynamic.
      get_suggested_contact("1"), get_suggested_contact("2"), get_suggested_contact("3"), get_suggested_contact("4"), get_suggested_contact("5")
    # Only return items based on the query from the user
    ])
  )}}}]}}


def get_suggested_contact(id: str) -> dict:
  """Generate a suggested contact given an ID.

  Args:
      id (str): The ID of the contact to return.

  Returns:
      Mapping[str, Any]: The contact formatted as a selection item in the menu.
  """
  return {
    'value': id,
    'startIconUri': "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    'text': "Contact " + id
  }

将 FUNCTION_URL 替换为用于查询外部数据源的 HTTP 端点。

Java

java/chat/selection-input/src/main/java/com/google/chat/selectionInput/App.java

在 GitHub 上查看

@SpringBootApplication
@RestController
// Web app that responds to events sent from a Google Chat space.
public class App {
  private static final String FUNCTION_URL = "your-function-url";

  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /**
   * Handle requests from Google Chat
   * 
   * @param event the event object sent by Google Chat
   * @return The response to be sent back to Google Chat
   */
  @PostMapping("/")
  @ResponseBody
  public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
    // Stores the Google Chat event
    JsonNode chatEvent = event.at("/chat");

    // Handle user interaction with multiselect.
    if (!chatEvent.at("/widgetUpdatedPayload").isEmpty()) {
      return queryContacts(event);
    }

    // Replies with a card that contains the multiselect menu.
    Message message = new Message().setCardsV2(List.of(new CardWithId()
      .setCardId("contactSelector")
      .setCard(new GoogleAppsCardV1Card()
        .setSections(List.of(new GoogleAppsCardV1Section().setWidgets(List.of(new GoogleAppsCardV1Widget()
          .setSelectionInput(new GoogleAppsCardV1SelectionInput()
            .setName("contacts")
            .setType("MULTI_SELECT")
            .setLabel("Selected contacts")
            .setMultiSelectMaxSelectedItems(3)
            .setMultiSelectMinQueryLength(1)
            .setExternalDataSource(new GoogleAppsCardV1Action().setFunction(FUNCTION_URL))
            // Suggested items loaded by default.
            // The list is static here but it could be dynamic.
            .setItems(List.of(getSuggestedContact("3")))))))))));

    return new GenericJson() {{
      put("hostAppDataAction", new GenericJson() {{
        put("chatDataAction", new GenericJson() {{
          put("createMessageAction", new GenericJson() {{
            put("message", message);
          }});
        }});
      }});
    }};
  }

  /**
   * Get contact suggestions based on text typed by users.
   *
   * @param event the event object that contains the user's query.
   * @return The response with contact suggestions.
   */
  GenericJson queryContacts(JsonNode event) throws Exception {
    String query = event.at("/commonEventObject/parameters/autocomplete_widget_query").asText();
    List<GoogleAppsCardV1SelectionItem> suggestions = List.of(
      // The list is static here but it could be dynamic.
      getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
    // Only return items based on the query from the user
    ).stream().filter(e -> query == null || e.getText().indexOf(query) > -1).toList();

    return new GenericJson() {{
      put("action", new GenericJson() {{
        put("modifyOperations", List.of(new GenericJson() {{
          put("updateWidget", new GenericJson() {{
            put("selectionInputWidgetSuggestions", new GenericJson() {{
              put("suggestions", suggestions);
            }});
          }});
        }}));
      }});
    }};
  }

  /**
   * Generate a suggested contact given an ID.
   * 
   * @param id The ID of the contact to return.
   * @return The contact formatted as a selection item in the menu.
   */
  GoogleAppsCardV1SelectionItem getSuggestedContact(String id) {
    return new GoogleAppsCardV1SelectionItem()
      .setValue(id)
      .setStartIconUri("https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png")
      .setText("Contact " + id);
  }
}

将 FUNCTION_URL 替换为用于查询外部数据源的 HTTP 端点。

Apps 脚本

此示例通过返回 card JSON 来发送卡片消息。您还可以使用 Apps 脚本卡片服务。

apps-script/chat/selection-input/selection-input.gs

在 GitHub 上查看

/**
* Responds to a Message trigger in Google Chat.
*
* @param {Object} event the event object from Google Chat
* @return {Object} Response from the Chat app.
*/
function onMessage(event) {
  // Replies with a card that contains the multiselect menu.
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: "queryContacts" },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact("3")]
        }
      }]}]}
    }]
  }}}}};
}

/**
* Get contact suggestions based on text typed by users.
*
* @param {Object} event the event object that contains the user's query
* @return {Object} suggestions
*/
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
  // Only return items based on the query from the user.
  ].filter(e => !query || e.text.includes(query)) }}}]}};
}

/**
* Generate a suggested contact given an ID.
*
* @param {String} id The ID of the contact to return.
* @return {Object} The contact formatted as a selection item in the menu.
*/
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

将数据转移到另一张卡

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

• 通过创建不同的部分，帮助用户完成较长的表单。
• 让用户预览并确认初始卡片中的信息，以便他们在提交之前检查自己的回答。
• 动态填充表单的其余部分。例如，为了提示用户创建预约，Chat 应用可以显示一个初始卡片，要求用户提供预约原因，然后填充另一个卡片，其中包含根据预约类型提供的可用时间。

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

Node.js

node/chat/contact-form-app/index.js

在 GitHub 上查看

{ buttonList: { buttons: [{
  text: "SUBMIT",
  onClick: { action: {
    function: FUNCTION_URL,
    parameters: [
      { key: "actionName", value: "submitDialog" },
      // Pass input values as parameters for last dialog step (submission)
      { key: "contactName", value: name },
      { key: "contactBirthdate", value: birthdate },
      { key: "contactType", value: type }
    ]
  }}
}]}}

将 FUNCTION_URL 替换为处理按钮点击的 HTTP 端点。

Python

python/chat/contact-form-app/main.py

在 GitHub 上查看

{ 'buttonList': { 'buttons': [{
  'text': "SUBMIT",
  'onClick': { 'action': {
    'function': FUNCTION_URL,
    'parameters': [
      { 'key': "actionName", 'value': "submitDialog" },
      # Pass input values as parameters for last dialog step (submission)
      { 'key': "contactName", 'value': name },
      { 'key': "contactBirthdate", 'value': birthdate },
      { 'key': "contactType", 'value': type }
    ]
  }}
}]}}

将 FUNCTION_URL 替换为处理按钮点击的 HTTP 端点。

Java

java/chat/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(FUNCTION_URL)
      .setParameters(List.of(
        new GoogleAppsCardV1ActionParameter().setKey("actionName").setValue("submitDialog"),
        // Pass input values as parameters for last dialog step (submission)
        new GoogleAppsCardV1ActionParameter().setKey("contactName").setValue(name),
        new GoogleAppsCardV1ActionParameter().setKey("contactBirthdate").setValue(birthdate),
        new GoogleAppsCardV1ActionParameter().setKey("contactType").setValue(type))))))))))));

将 FUNCTION_URL 替换为处理按钮点击的 HTTP 端点。

Apps 脚本

此示例通过返回 card JSON 来发送卡片消息。您还可以使用 Apps 脚本卡片服务。

apps-script/chat/contact-form-app/Code.gs

在 GitHub 上查看

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

当用户点击该按钮时，您的 Chat 应用会收到一个事件对象，您可以从中接收数据。

回复表单提交

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

在以下示例中，聊天应用发送了一条文本消息，以确认其已成功收到从卡片消息提交的表单。

Node.js

node/chat/contact-form-app/index.js

在 GitHub 上查看

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

Python

python/chat/contact-form-app/main.py

在 GitHub 上查看

return { 'hostAppDataAction': { 'chatDataAction': { 'createMessageAction': { 'message': {
  'text': "✅ " + event.get('commonEventObject').get('parameters')["contactName"] + " has been added to your contacts."
}}}}}

Java

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

在 GitHub 上查看

return new GenericJson() {{
  put("hostAppDataAction", new GenericJson() {{
    put("chatDataAction", new GenericJson() {{
      put("createMessageAction", new GenericJson() {{
        put("message", new Message()
          .setText( "✅ " + event.at("/commonEventObject/parameters/contactName").asText() +
                    " has been added to your contacts."));
      }});
    }});
  }});
}};

Apps 脚本

此示例通过返回 card JSON 来发送卡片消息。您还可以使用 Apps 脚本卡片服务。

apps-script/chat/contact-form-app/Code.gs

在 GitHub 上查看

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

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

问题排查

本部分提供了在聊天中与对话框互动时出现的特定错误代码和运行时行为的问题排查步骤。

对话互动返回“调用插件时出现未指明的错误”

在与对话框互动时，如果您看到错误日志，其中包含“调用插件时出现未指定的错误”消息和代码 13，这通常表示存在内部错误，或者 Chat 应用的 HTTP 端点未能处理请求或返回有效响应。

如需排查此错误，请执行以下操作：

• 检查 HTTP 端点的日志中是否有任何未处理的异常或崩溃。
• 验证您的端点是否能在 30 秒内响应请求。如果端点运行时间超过 30 秒，Chat 将无法处理响应，互动也会失败。如需了解详情，请参阅速率限制和最佳实践。
• 确保您的端点返回有效的响应。对于对话提交，端点必须返回采用正确 JSON 格式的 RenderActions 对象。如果响应格式不正确或不包含必需字段，对话互动可能会失败。

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

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