Google Chat ユーザーから情報を収集して処理する

このガイドでは、Google Chat アプリがカードベースのインターフェースにフォーム入力を構築して、ユーザーから情報を収集して処理する方法について説明します。

Google Chat では、アドオンは Google Chat アプリとしてユーザーに表示されます。詳細については、Google Chat の拡張機能の概要をご覧ください。

Chat アプリは、Chat 内または Chat 外でアクションを実行するために、ユーザーに情報をリクエストします。たとえば、次の方法でリクエストします。

• 設定を行います。たとえば、ユーザーが通知設定をカスタマイズしたり、Chat アプリを構成して 1 つ以上のスペースに追加したりできるようにします。
• 他の Google Workspace アプリケーションで情報を作成または更新します。たとえば、ユーザーが Google カレンダーの予定を作成できるようにします。
• ユーザーが他のアプリやウェブサービス内のリソースにアクセスして更新できるようにします。たとえば、Chat アプリを使用すると、ユーザーは Chat スペースから直接サポート チケットのステータスを更新できます。

前提条件

カードを使用してフォームを作成する

情報を収集するために、Chat アプリはフォームとその入力を設計し、カードに組み込みます。カードをユーザーに表示するには、Chat アプリで次の Chat インターフェースを使用できます。

• 1 つ以上のカードを含む Chat メッセージ。
• ダイアログ: メッセージやホームページから新しいウィンドウで開くカードです。

Chat アプリでは、次のウィジェットを使用してカードを作成できます。

• ユーザーに情報をリクエストするフォーム入力ウィジェット。必要に応じて、フォーム入力ウィジェットに検証を追加して、ユーザーが情報を正しく入力してフォーマットできるようにします。Chat アプリでは、次のフォーム入力ウィジェットを使用できます。

  • 自由形式または候補テキスト用のテキスト入力（textInput）。
  • 選択入力（selectionInput）は、チェックボックス、ラジオボタン、プルダウン メニューなどの選択可能な UI 要素です。選択入力ウィジェットでは、静的または動的データソースからアイテムを入力することもできます。たとえば、ユーザーは、自分がメンバーである Chat スペースのリストから選択できます。
  • 日時入力用の日時ピッカー（dateTimePicker）。

• ボタン ウィジェット。ユーザーがカードに入力した値を送信できるようにします。ユーザーがボタンをクリックすると、Chat アプリは受信した情報を処理できます。

次の例では、カードがテキスト入力、日時選択ツール、選択入力を使用して連絡先情報を収集します。

情報を収集するために使用できるインタラクティブ ウィジェットの例については、Google Chat API ドキュメントのインタラクティブなカードまたはダイアログを設計するをご覧ください。

インタラクティブなウィジェットからデータを受信する

ユーザーがボタンをクリックするたびに、その Chat アプリのアクションがトリガーされ、インタラクションに関する情報が返されます。イベント ペイロードの commonEventObject で、formInputs オブジェクトにはユーザーが入力した値が含まれます。

値はオブジェクト commonEventObject.formInputs.WIDGET_NAME から取得できます。ここで、WIDGET_NAME はウィジェットに指定した name フィールドです。値は、ウィジェットの特定のデータ型として返されます。

次の例は、ユーザーが各ウィジェットの値を入力したイベント オブジェクトの一部を示しています。

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

データを受け取るには、Chat アプリがイベント オブジェクトを処理して、ユーザーがウィジェットに入力した値を取得します。次の表に、特定のフォーム入力ウィジェットの値を取得する方法を示します。表には、ウィジェットが受け入れるデータ型、イベント オブジェクトに値が保存される場所、値の例が、ウィジェットごとに示されています。

別のカードにデータを移行する

お客様がカードの情報を送信した後、次のいずれかを行うには、追加のカードを返却していただく必要があります。

• 長いフォームを入力する際にユーザーが混乱しないように、個別のセクションを作成します。
• 最初のカードの情報を確認して確認できるようにし、送信する前に回答を確認できるようにします。
• フォームの残りの部分を動的に入力します。たとえば、ユーザーに予約を作成するよう求める Chat アプリでは、予約の理由を尋ねる最初のカードを表示し、予約の種類に基づいて空き時間が表示される別のカードを表示できます。

最初のカードから入力されたデータを転送するには、次の例に示すように、ウィジェットの name とユーザーが入力した値を含む actionParameters を使用して button ウィジェットを作成します。

{
  "buttonList": { "buttons": [{
    "text": "Submit",
    "onClick": { "action": {
      "function": "submitForm",
      "parameters": [
        {
          "key": "WIDGET_NAME",
          "value": "USER_INPUT_VALUE"
        },
        // Can specify multiple parameters
      ]
    }}
  }]}
}

ここで、WIDGET_NAME はウィジェットの name で、USER_INPUT_VALUE はユーザーが入力したものです。たとえば、個人の名前を収集するテキスト入力の場合、ウィジェット名は contactName で、値の例は Kai O です。

ユーザーがボタンをクリックすると、Chat アプリはイベント オブジェクトを受け取ります。このオブジェクトからデータを受け取ることができます。

フォームの送信に応答する

カード メッセージまたはダイアログからデータを受信すると、Chat アプリは受信確認またはエラーの返信によって応答します。

次の例では、Chat アプリがテキスト メッセージを送信して、カード メッセージから送信されたフォームが正常に受信されたことを確認します。

/**
 * Google Cloud Function that handles all Google Workspace Add On events for
 * the contact manager app.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.contactManager = function contactManager(req, res) {
  const chatEvent = req.body.chat;
  const chatMessage = chatEvent.messagePayload.message;

  // Handle MESSAGE events
  if(chatEvent.messagePayload) {
    return res.send(handleMessage(chatMessage, chatEvent.user));
  // Handle CARD_CLICKED events
  } else if(chatEvent.buttonClickedPayload) {
    switch(req.body.commonEventObject.parameters.actionName) {
        case "openDialog":
            return res.send(openDialog());
        case "openNextCard":
            return res.send(openNextCard(req.body));
        case "submitForm":
            return res.send(submitForm(req.body));
    }
  }
};

/**
 * Submits information from a dialog or card message.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} a message response that posts a private message.
 */
function submitForm(event) {
  const chatUser = event.chat.user;
  const contactName = event.commonEventObject.parameters["contactName"];

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    privateMessageViewer: chatUser,
    text: "✅ " + contactName + " has been added to your contacts."
  }}}}};
}

/**
 * Sends private text message that confirms submission.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} a message response that posts a private message.
 */
function submitForm(event) {
  const chatUser = event.chat.user;
  const contactName = event.commonEventObject.parameters["contactName"];

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    privateMessageViewer: chatUser,
    text: "✅ " + contactName + " has been added to your contacts."
  }}}}};
}

ダイアログを処理して閉じるには、確認メッセージを送信するか、元のメッセージまたはカードを更新するか、ダイアログを閉じるかを指定する RenderActions オブジェクトを返します。手順については、ダイアログを閉じるをご覧ください。

トラブルシューティング

Google Chat アプリまたはカードからエラーが返されると、Chat インターフェースに「エラーが発生しました」というメッセージが表示されます。または「リクエストを処理できません」というメッセージが表示されます。Chat UI にエラー メッセージが表示されない場合でも、Chat アプリまたはカードで予期しない結果が生成されることがあります（カード メッセージが表示されないなど）。

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