ユーザーが入力した情報を処理する

このガイドでは、ユーザーがカード メッセージダイアログに入力した情報を受け取り、確認する方法について説明します。ユーザーは、Chat アプリが受信、読み取り、応答するデータを入力できます。ユーザーが情報を入力できるウィジェットには次のものがあります。

  • TextInput: 候補もサポートする自由形式のテキスト入力用。
  • SelectionInput: リストアイテムとメニュー(チェックボックス、ラジオボタン、プルダウン メニューなど)用。
  • DateTimePicker: 日付と時刻のエントリ。


カードビルダーでカードをデザインしてプレビューする。

カードビルダーを開く

ユーザーからデータ入力を受け取ると、Chat アプリは次の処理を実行できます。

  • カスタマー サービスのケースを更新する。
  • 作業指示を作成する。
  • ウェブサービスで認証する。

データの受信の仕組み

Chat アプリは、情報をダイアログまたはカード メッセージとしてユーザーに提示します。この例では、ユーザーに TextInput ウィジェットと SelectionInput ウィジェットを使用して連絡先に関する情報を入力するように求めるダイアログが表示されています。

さまざまなウィジェットを表示するダイアログ。

完了すると、Chat アプリは、ユーザーがダイアログに入力した JSON 形式のデータとインタラクション イベントを受け取ります。

ユーザーが入力した内容に関するデータを取得するには、イベント ペイロードの Event.common.formInputs フィールドを使用します。formInputs フィールドはマップです。キーは各ウィジェットに割り当てられた文字列 ID で、値は各ウィジェットのユーザー入力を表します。さまざまなオブジェクトが異なる入力データ型を表します。たとえば、Event.common.formInputs.stringInputs は文字列入力を表します。

アプリは event.common.formInputs.NAME.stringInputs.value[0] で最初にユーザーが入力した値にアクセスできます。ここで、NAMETextInput ウィジェットの 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 Script

/**
 * 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 UI にエラー メッセージが表示されないにもかかわらず、Chat アプリまたはカードから予期しない結果(カード メッセージが表示されないなど)が発生することがあります。

Chat の UI にエラー メッセージが表示されない場合もありますが、Chat アプリのエラーロギングがオンになっている場合は、エラー メッセージとログデータを使用してエラーを修正できます。エラーの表示、デバッグ、修正については、Google Chat のエラーのトラブルシューティングと修正をご覧ください。