用户输入信息

本指南介绍了如何接收和阅读用户在卡片消息对话框中输入的信息。 用户可以输入 Chat 应用接收、读取和响应的数据。允许用户输入信息的微件包括:

  • TextInput,用于输入同样支持建议的自由格式文本。
  • SelectionInput:用于列表项和菜单,例如复选框、单选按钮和下拉菜单。
  • DateTimePicker,用于日期和时间条目。


使用卡片制作工具设计和预览卡片。

打开卡片制作工具

接收用户输入的数据可让 Chat 应用执行以下操作:

  • 更新客户服务请求。
  • 创建工作订单。
  • 使用网络服务进行身份验证。

接收数据的运作方式

Chat 应用以对话框或卡片消息的形式向用户呈现信息。在此示例中,对话框会要求用户使用 TextInputSelectionInput widget 输入联系人的相关信息:

包含各种不同 widget 的对话框。

完成后,Chat 应用会收到用户在对话框中输入的 JSON 格式数据和互动事件,其中:

如需获取与用户输入的内容相关的数据,请使用事件载荷中的 Event.common.formInputs 字段。formInputs 字段是一个映射,其中的键是分配给每个 widget 的字符串 ID,值表示每个 widget 的用户输入。不同的对象代表不同的输入数据类型。例如,Event.common.formInputs.stringInputs 表示字符串输入。

应用可以访问 event.common.formInputs.NAME.stringInputs.value[0] 处的第一个用户输入的值,其中 NAMETextInput widget 的 name 字段。

接收来自卡片的数据

当用户在卡片消息中输入数据时,您的 Chat 应用会收到 Chat 应用互动事件,例如以下示例:

JSON

{
  "type": enum (EventType),
  "eventTime": string,
  "threadKey": string,
  "message": {
    object (Message)
  },
  "user": {
    object (User)
  },
  "space": {
    object (Space)
  },
  "action": {
    object (FormAction)
  },
  "configCompleteRedirectUrl": string,
  "common": {

    // Represents user data entered in a card.
    "formInputs": {

      // Represents user data entered for a specific field in a card.
      "NAME": {

        // Represents string data entered in a card, like text input fields
        // and check boxes.
        "stringInputs": {

          // An array of strings entered by the user in a card.
          "value": [
            string
          ]
        }
      }
    },
    "parameters": {
      string: string,
      ...
    },
    "invokedFunction": string
  }
}

从对话框中接收数据

当用户在对话框中提交数据时,您的 Chat 应用会收到另一个 Chat 应用互动事件,例如以下示例:

JSON

{
  "type": enum (EventType),
  "eventTime": string,
  "threadKey": string,
  "message": {
    object (Message)
  },
  "user": {
    object (User)
  },
  "space": {
    object (Space)
  },
  "action": {
    object (FormAction)
  },
  "configCompleteRedirectUrl": string,

  // Indicates that this event is dialog-related.
  "isDialogEvent": true,

  // Indicates that a user clicked a button, and all data
  // they entered in the dialog is included in Event.common.formInputs.
  "dialogEventType": "SUBMIT_DIALOG",
  "common": {
    "userLocale": string,
    "hostApp": enum (HostApp),
    "platform": enum (Platform),
    "timeZone": {
      object (TimeZone)
    },

    // Represents user data entered in a dialog.
    "formInputs": {

      // Represents user data entered for a specific field in a dialog.
      "NAME": {

        // Represents string data entered in a dialog, like text input fields
        // and check boxes.
        "stringInputs": {

          // An array of strings entered by the user in a dialog.
          "value": [
            string
          ]
        }
      }
    },
    "parameters": {
      string: string,
      ...
    },
    "invokedFunction": string
  }
}

响应从卡片消息或对话框中收集的数据

从卡片消息或对话框接收数据后,Chat 应用会通过确认收到或返回错误来进行响应,这两项操作都是通过返回 ActionResponse 来完成的:

  • 如需确认接收成功,请使用包含 "actionStatus": "OK"ActionResponse 参数进行响应。
  • 如需返回错误,请使用包含 "actionStatus": "ERROR MESSAGE"ActionResponse 参数进行响应。

示例

以下示例检查是否存在 name 值。如果不存在,应用会返回错误。如果存在,应用会确认已收到表单数据并关闭对话框。

Node.js

/**
 * Checks for a form input error, the absence of
 * a "name" value, and returns an error if absent.
 * Otherwise, confirms successful receipt of a dialog.
 *
 * Confirms successful receipt of a dialog.
 *
 * @param {Object} event the event object from Chat API.
 *
 * @return {object} open a Dialog in Google Chat.
 */
function receiveDialog(event) {

  // Checks to make sure the user entered a name
  // in a dialog. If no name value detected, returns
  // an error message.
  if (event.common.formInputs.WIDGET_NAME.stringInputs.value[0] == "") {
    res.json({
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "Don't forget to name your new contact!"
        }
      }
    });

  // Otherwise the app indicates that it received
  // form data from the dialog. Any value other than "OK"
  // gets returned as an error. "OK" is interpreted as
  // code 200, and the dialog closes.
  } else {
    res.json({
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "OK"
        }
      }
    });
  }
}

Apps 脚本

/**
 * Checks for a form input error, the absence of
 * a "name" value, and returns an error if absent.
 * Otherwise, confirms successful receipt of a dialog.
 *
 * Confirms successful receipt of a dialog.
 *
 * @param {Object} event the event object from Chat API.
 *
 * @return {object} open a Dialog in Google Chat.
 */
function receiveDialog(event) {

  // Checks to make sure the user entered a name
  // in a dialog. If no name value detected, returns
  // an error message.
  if (event.common.formInputs.WIDGET_NAME[""].stringInputs.value[0] == "") {
    return {
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "Don't forget to name your new contact!"
        }
      }
    };

  // Otherwise the app indicates that it received
  // form data from the dialog. Any value other than "OK"
  // gets returned as an error. "OK" is interpreted as
  // code 200, and the dialog closes.
  } else {
    return {
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "OK"
        }
      }
    };
  }
}

Python

def receive_dialog(event: Mapping[str, Any]) -> Mapping[str, Any]:
  """Checks for a form input error, the absence of a "name" value, and returns
     an error if absent. Otherwise, confirms successful receipt of a dialog.

  Args:
      event (Mapping[str, Any]): the event object from Chat API.

  Returns:
      Mapping[str, Any]: the response.
  """

  if common := event.get('common'):
    if form_inputs := common.get('formInputs'):
      if contact_name := form_inputs.get('WIDGET_NAME'):
        if string_inputs := contact_name.get('stringInputs'):
          if name := string_inputs.get('value')[0]:
            return {
              'actionResponse': {
                'type': 'DIALOG',
                'dialogAction': {
                  'actionStatus': 'OK'
                }
              }
            }
          else:
            return {
              'actionResponse': {
                'type': 'DIALOG',
                'dialogAction': {
                  'actionStatus': 'Don\'t forget to name your new contact!'
                }
              }
            }

问题排查

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

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