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

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

さまざまなウィジェットを表示するダイアログ。
図 1: ダイアログを開いて連絡先情報を収集するサンプルの Chat アプリ。

Chat アプリは、Google Chat でアクションを実行するために、 次のような操作を行えます。

  • 設定を構成します。たとえば、ユーザーが通知設定をカスタマイズできるようにするには、 Chat 用アプリを 1 つまたは複数のコンテナに できます。
  • 他の Google Workspace アプリケーションで情報を作成または更新する。たとえば、ユーザーが Google カレンダーの予定を作成できるようにします。
  • ユーザーが他のアプリやウェブサービス内のリソースにアクセスして更新できるようにします。対象 たとえば、Chat 用アプリで、ユーザーが サポート チケットのステータスを Chat スペースから直接取得する方法を学びました。

前提条件

インタラクティブ機能を有効にする Google Chat アプリ。新しい 次のいずれかのクイックスタートを完了してください。 使用するアプリ アーキテクチャ:

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

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

  • 1 つ以上のカードを含むメッセージ。
  • ホームページ これは、[ホーム] タブから直接表示されるカードです。 やり取りできます。
  • ダイアログ: メッセージやホームページから新しいウィンドウで開くカードです。

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

  • ユーザーに情報を要求するフォーム入力ウィジェット。必要に応じて、 検証を追加 ユーザーが情報の入力と書式設定を行えるように、入力ウィジェットを形成する 確認します。Chat アプリでは、次のフォーム入力ウィジェットを使用できます。

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

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

次に、3 種類の異なる日時入力で構成されるカードを示します。

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

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

ユーザーがボタンをクリックするたびに、Chat アプリはインタラクションに関する情報を含む CARD_CLICKED インタラクション イベントを受信します。Pod のペイロード CARD_CLICKED インタラクション イベントに common.formInputs が含まれています ユーザーが入力した値を含むオブジェクトが作成されます。

値はオブジェクト common.formInputs.WIDGET_NAME から取得できます。ここで、WIDGET_NAME はウィジェットに指定した name フィールドです。値はウィジェットの特定のデータ型（ Inputs オブジェクト）。 次の例では、カードがテキスト入力、日時選択ツール、選択入力ウィジェットを使用して連絡先情報を収集します。

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

インタラクション イベントを処理する

ユーザーがカードまたはダイアログにデータを入力すると、Chat アプリは、ユーザーが入力した値を含む Chat アプリの CARD_CLICKED インタラクション イベントを受信します。

以下は、CARD_CLICKED インタラクション イベントの一部を示しています。 ユーザーがウィジェットごとに入力した値:

HTTP

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

Apps Script

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

データを受信するため、Chat アプリは ユーザーがウィジェットに入力した値を取得するために使用できます。次の 表に、特定のフォーム入力ウィジェットの値を取得する方法を示します。表には、各ウィジェットが受け入れるデータ型、インタラクション イベントに値が保存される場所、値の例が表示されます。

フォーム入力ウィジェット 入力データのタイプ インタラクション イベントからの入力値 値の例
textInput stringInputs events.common.formInputs.contactName.stringInputs.value[0] Kai O
selectionInput stringInputs 最初の値または唯一の値を取得するには、events.common.formInputs.contactType.stringInputs.value[0] を使用します。 Personal
日付のみを許可する dateTimePicker。 dateInput events.common.formInputs.contactBirthdate.dateInput.msSinceEpoch。 1000425600000

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

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

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

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

{
  "buttonList": {
    "buttons": [{
      "text": "Submit",
      "onClick": {
        "action": {
          "function": "openNextCard",
          "parameters": [{
            "key": "WIDGET_NAME",
            "value": "USER_INPUT_VALUE"
          }]
        }
      }
    }]
  }
}

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

ユーザーがボタンをクリックすると、Chat アプリは CARD_CLICKED インタラクション イベントを受け取ります。値を取得するには、 event.common.parameters 渡されます。

以下は、ユーザーを含むパラメータを渡す方法の例を示しています。 次のカードを開く関数に入力データを渡します。

Node.js

// Respond to button clicks on cards or dialogs
if (event.type === "CARD_CLICKED") {

  // Open another card.
  if (event.common.invokedFunction === "openNextCard") {
    const parameters = event.common.parameters;
    openNextCard(event);
  }
}

Python

  # Respond to button clicks on cards or dialogs
  if request.get('type') == 'CARD_CLICKED':
    if invoked_function := request.get('common', dict()).get('invokedFunction'):
      if invoked_function == 'open_next_card':
        parameters = request.get('common', dict()).get('parameters'),
        return open_next_card(parameters)

Apps Script

// Respond to button clicks on cards or dialogs
function onCardClick(event) {
  if (event.common.invokedFunction === "openNextCard") {
    const parameters = event.common.parameters;
    return openNextCard(parameters);
  }
}

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

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

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

Apps Script

function submitCardForm(contactName, contactBirthdate, contactType) {
    return {
      "text": "You entered the following contact information:\n\n" +
      "*Name:* " + contactName + "\n" +
      "*Birthdate:* " + contactBirthdate + "\n" +
      "*Type:* " + contactType
      }
}

ダイアログを処理して閉じるには、 ActionResponse 確認メッセージ、更新メッセージのどちらを送信するかを指定する ダイアログを閉じることもできます手順については、以下をご覧ください。 ダイアログを閉じる。

トラブルシューティング

Google Chat アプリまたは card がエラーを返した場合、 Chat のインターフェースに「エラーが発生しました」というメッセージが表示されている。 または「リクエストを処理できません」というメッセージが表示されます。場合によっては、Chat の UI が エラー メッセージは表示されませんが、Chat 用アプリまたは 予期しない結果が生じた場合たとえば、カード メッセージに 表示されます。

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