このページは Cloud Translation API によって翻訳されました。

Google Chat アプリ操作イベントの種類

このページでは、Google Chat アプリが Google Chat から受信できるインタラクションイベントの種類について説明します。

インタラクションイベントを受信するように Chat アプリを構成するには、Chat アプリのインタラクションを受信して応答するをご覧ください。

インタラクションイベントの形式

ユーザーはさまざまな方法で Chat アプリを操作できます。Google Chat は、インタラクションのタイプごとに、さまざまな種類のインタラクションイベントを送信します。

メッセージ: ユーザーが Chat アプリにメッセージを送信するか、スペースで Chat アプリを呼び出します。
スペースに追加済み: ユーザーが Chat アプリをスペースに追加します。
スペースから削除: ユーザーがスペースから Chat アプリを削除しました。
クリックされたカード: Chat アプリから送信されたインタラクティブなカードまたはダイアログをユーザーがクリックします。
アプリのホームメッセージ: ユーザーが Chat アプリでダイレクトメッセージを開くと、Chat アプリのホームメッセージが表示されます。
フォームを送信: ユーザーが Chat アプリのホームメッセージからフォーム情報を送信します。

ユーザーが Chat アプリを操作するたびに、Google Chat はリクエスト本文（操作を表す JSON ペイロード）を使用してインタラクションイベントを送信します。このイベントペイロードには、すべてのタイプのインタラクションイベントに共通する要素と、そのイベントタイプに固有の要素が含まれます。

インタラクションイベントのフィールドの詳細については、Google Chat API の Event リファレンスドキュメントをご覧ください。

共通フィールド

インタラクションイベントのペイロードには、次のフィールドが常に提供されます。

項目	説明
`type`	Chat アプリが受信するイベントのタイプ（`MESSAGE`、`ADDED_TO_SPACE` など）。
`eventTime`	イベントがディスパッチされたタイミングを示すタイムスタンプ。
`common`	言語 / 地域やプラットフォームなど、ユーザーのクライアントに関する情報を表します。

インタラクションイベントタイプ別のフィールド

イベントタイプによっては、ペイロードに次の追加フィールドが含まれる場合があります。

項目	説明	イベントタイプ
`message`	イベントに関連するメッセージ。	`MESSAGE`、`ADDED_TO_SPACE`、`CARD_CLICKED`。
`space`	イベントに関連するスペース。	`MESSAGE`、`ADDED_TO_SPACE`、`REMOVED_FROM_SPACE`、`CARD_CLICKED`。
`user`	イベントに関連したユーザー。ユーザーは常に人です（Chat アプリではありません）。	`MESSAGE`、`ADDED_TO_SPACE`、`REMOVED_FROM_SPACE`、`CARD_CLICKED`。
`action`	ユーザーがインタラクティブなカードまたはダイアログをクリックしたときにトリガーされる関数。	`CARD_CLICKED`.

イベントペイロードの例

このセクションでは、インタラクションイベントをトリガーする要因について説明し、次の各イベントタイプの JSON ペイロードの例を示します。

メッセージ（MESSAGE）
スペースに追加しました（ADDED_TO_SPACE）
スペースから削除しました（REMOVED_FROM_SPACE）
クリックされたカード（CARD_CLICKED）

メッセージ

このインタラクションイベントは、ユーザーが Chat アプリに次のようなメッセージを送信したときを表します。

Chat アプリを使用しているダイレクトメッセージ（DM）スペース内のメッセージ。
複数ユーザーによるスペースでのメッセージで、ユーザーが Chat アプリに @メンションするか、スラッシュコマンドのいずれかを使用する。
Chat アプリのリンクプレビューを構成している場合、構成した URL パターンに一致するリンクを含むメッセージをユーザーが投稿します。

次の JSON の例は、複数のユーザーがいるスペースでユーザーが Chat アプリに名前リンクを付ける MESSAGE インタラクションイベントを示しています。

{
  "type": "MESSAGE",
  "eventTime": {
      "seconds": 1691187414,
      "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "displayName": "Customer Support Superstars",
    "spaceType": "SPACE"
  },
  "message": {
    "name": "spaces/AAAAAAAAAAA/messages/CCCCCCCCCCC",
    "sender": {
      "name": "users/12345678901234567890",
      "displayName": "Izumi",
      "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
      "email": "izumi@example.com"
    },
    "createTime": {
      "seconds": 1691187386,
      "nanos": 954319000
    },
    "text": "@TestBot Create ticket.",
    "argumentText": " Create ticket.",
    "thread": {
      "name": "spaces/AAAAAAAAAAA/threads/BBBBBBBBBBB",
      "threadKey": "custom-thread-ID"
    },
    "annotations": [
      {
        "length": 8,
        "startIndex": 0,
        "userMention": {
          "type": "MENTION",
          "user": {
            "avatarUrl": "https://.../avatar.png",
            "displayName": "TestBot",
            "name": "users/1234567890987654321",
            "type": "BOT"
          }
        },
        "type": "USER_MENTION"
      }
    ],
    "attachment": [
      {
        "name": "spaces/5o6pDgAAAAE/messages/Ohu1LlUVcS8.Ohu1LlUVcS8/attachments/AATUf-Iz7d8kySEdRRZd-dznqBk3",
        "content_name": "solar.png",
        "content_type": "image/png",
        "drive_data_ref": {
          "drive_file_id": "H1HqaqRuH2Pfd_TOa1fF2_ltwDlV_yKRrr"
        },
        "source": "DRIVE_FILE"
      }
    ]
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

スペースに追加しました

このインタラクションイベントは、Chat アプリがスペースに追加されたことを示します。アプリは通常、このインタラクションイベントに応答して、スペースの新しいスレッドにウェルカムメッセージを投稿します。

次の JSON の例は、ユーザーがスペースに Chat アプリを追加したときの ADDED_TO_SPACE インタラクションイベントのリクエストの本文を示しています。

{
  "type": "ADDED_TO_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "displayName": "Customer Support Superstars",
    "spaceType": "SPACE",
    "adminInstalled": "false"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

Google Workspace 管理者がインストール

ADDED_TO_SPACE インタラクションイベントは、Google Workspace 管理者が組織内のユーザー用に Chat アプリをインストールしたことを示す場合もあります。

管理者は、Chat アプリとユーザー間のダイレクトメッセージにのみ Chat アプリをインストールできます。インストール済みのアプリがユーザーのダイレクトメッセージパネルに表示されます。管理者が Chat アプリをインストールした場合、ユーザーがアンインストールすることはできません。管理者がインストールした Chat アプリの詳細については、Google Workspace 管理者用ヘルプのドキュメントのドメイン内に Marketplace アプリをインストールするをご覧ください。

次の JSON の例は、Google Workspace 管理者がユーザーに Chat アプリをインストールしたときの ADDED_TO_SPACE インタラクションイベントのリクエストの本文を示しています。管理者が Chat アプリをインストールしているため、adminInstalled は true に設定されています。

{
  "type": "ADDED_TO_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "displayName": "Customer Support Superstars",
    "spaceType": "DIRECT_MESSAGE",
    "adminInstalled": "true"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

スペースから削除しました

このインタラクションイベントは、Chat アプリがスペースから削除されたことを示します。チャットアプリはすでに削除されているため、このイベントに対するメッセージでは応答しません。

次の JSON の例は、ユーザーがスペースから Chat アプリを削除したときの REMOVED_FROM_SPACE インタラクションイベントのリクエストの本文を示しています。

{
  "type": "REMOVED_FROM_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "spaceType": "SPACE",
    "adminInstalled": "false"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

Google Workspace 管理者によってアンインストールされました

REMOVED_FROM_SPACE インタラクションイベントは、Google Workspace 管理者が組織内のユーザーの Chat アプリをアンインストールしたことを示している場合もあります。アンインストールすると、Chat アプリはユーザーのダイレクトメッセージパネルに表示されなくなります。

管理者より前に Chat アプリをインストールしていた場合は、そのユーザーの Chat アプリはインストールされたままになります。この場合、Chat アプリはまだインストールされているため、Chat アプリは REMOVED_FROM_SPACE インタラクションイベントを受信しません。

次の JSON の例は、Google Workspace 管理者がユーザーの Chat アプリをアンインストールしたときの REMOVED_FROM_SPACE インタラクションイベントのリクエストの本文を示しています。Chat アプリは管理者によってアンインストールされているため、adminInstalled は true に設定されています。

{
  "type": "REMOVED_FROM_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "spaceType": "DIRECT_MESSAGE",
    "adminInstalled": "true"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

カードがクリックされました

このインタラクションイベントは、ユーザーがカードメッセージまたはダイアログ内のボタンをクリックしたことを示します。

インタラクションイベントを受信するには、そのボタンで Chat アプリとの別のインタラクションをトリガーする必要があります。たとえば、ユーザーがウェブサイトへのリンクを開くボタンをクリックした場合、Chat アプリは CARD_CLICKED インタラクションイベントを受信しませんが、次の例ではインタラクションイベントを受信します。

ユーザーがカードの Send feedback ボタンをクリックすると、情報を入力するためのダイアログが開きます。
ユーザーがカードまたはダイアログに情報を入力した後、Submit ボタンをクリックします。

次の JSON の例は、受信サポートチケットをユーザーが割り当てるカードメッセージのボタンをユーザーがクリックしたときの、CARD_CLICKED インタラクションイベントのリクエスト本文を示しています。

{
  "type": "CARD_CLICKED",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "common": {
    "userLocale": "en",
    "hostApp": "CHAT",
    "invokedFunction": "doAssignTicket",
    "timeZone": {
      "offset": -25200000,
      "id": "America/Los_Angeles"
    }
  },
  "action": {
    "actionMethodName": "doAssignTicket"
  },
  "message": {
    "cards": [
      {
        "header": {
          "title": "Incoming support ticket."
        },
        "sections": [
          {
            "widgets": [
              {
                "textParagraph": {
                  "text": "Incoming support ticket #12345 is unassigned and needs your attention."
                }
              },
              {
                "buttons": [
                  {
                    "textButton": {
                      "onClick": {
                        "action": {
                          "actionMethodName": "doAssignTicket"
                        }
                      },
                      "text": "Assign to me"
                    }
                  }
                ]
              }
            ]
          }
        ]
      }
    ],
    "sender": {
      "avatarUrl": "https://www.example.com/images/chat-app-icon.png",
      "displayName": "Support Chat app",
      "name": "users/98765432109876543210",
      "type": "BOT"
    },
    "createTime": {
      "seconds": 1691187386,
      "nanos": 954319000
    },
    "retentionSettings": {
      "state": "PERMANENT"
    },
    "name": "spaces/AAAAAAAAAAA/messages/CCCCCCCCCCC",
    "thread": {
      "retentionSettings": {
        "state": "PERMANENT"
      },
      "name": "spaces/AAAAAAAAAAA/threads/BBBBBBBBBBB"
    },
    "messageHistoryState": "HISTORY_ON",
    "space": {
      "spaceThreadingState": "GROUPED_MESSAGES",
      "spaceType": "SPACE",
      "displayName": "Customer Support Superstars",
      "name": "spaces/AAAAAAAAAAA",
      "spaceHistoryState": "HISTORY_ON",
      "type": "ROOM",
      "threaded": true
    }
  },
  "user": {
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "displayName": "Izumi",
    "name": "users/12345678901234567890",
    "type": "HUMAN",
    "email": "izumi@example.com",
    "domainId": "ABCDEFG"
  },
  "space": {
    "spaceThreadingState": "GROUPED_MESSAGES",
    "spaceType": "SPACE",
    "displayName": "Customer Support Superstars",
    "name": "spaces/AAAAAAAAAAA",
    "spaceHistoryState": "HISTORY_ON",
    "type": "ROOM",
    "threaded": true
  }
}

ダイアログのカードのクリック

ユーザーがダイアログを操作すると、CARD_CLICKED インタラクションイベントのペイロードに次の追加フィールドが含まれます。

isDialogEvent: ダイアログを含むインタラクションイベントの場合は true に設定します。
DialogEventType: ダイアログの操作の種類（ユーザーがダイアログを開いた、送信、キャンセルしたかどうかなど）。

次の JSON の例は、CARD_CLICKED インタラクションイベントのリクエスト本文の一部を示しています。この例では、Chat アプリに情報を送信するダイアログのボタンをユーザーがクリックしています。

{
  "type": "CARD_CLICKED",
  ...
  "isDialogEvent": true,
  "dialogEventType": "SUBMIT_DIALOG",
}

アプリのホームメッセージ

このインタラクションイベントは、ユーザーが Chat アプリでダイレクトメッセージを開き、Chat アプリのホームメッセージを受け取ったことを示します。

次の JSON の例は、APP_HOME インタラクションイベントのリクエスト本文を示しています。

{
  "chat": {
    "type": "APP_HOME",
    "user": {
      "name": "users/12345678901234567890",
      "type": "HUMAN",
      "email": "izumi@example.com",
      "domainId": "ABCDEFG"
    },
    "space": {
      "name": "spaces/AAAAAAAAAAA",
      "singleUserBotDm": true,
      "spaceType": "DIRECT_MESSAGE"
    }
  },
  "commonEventObject": {
    "invokedFunction": "onAppHome",
    "userLocale": "en",
    "hostApp": "CHAT"
  }
}

アプリのホームメッセージでフォームを送信する

このインタラクションイベントは、ユーザーが Chat アプリのホームメッセージを介してフォーム情報を送信したことを示します。

次の JSON の例は、SUBMIT_FORM インタラクションイベントのリクエスト本文を示しています。

{
  "commonEventObject": {
    "userLocale": "en",
    "invokedFunction": "onSubmitFunction",
    "formInputs": {
      "username": {
        "": {
          "stringInputs": {
            "value": [
              "Ira"
            ]
          }
        }
      }
    },
    "hostApp": "CHAT"
  },
  "chat": {
    "type": "SUBMIT_FORM",
    "space": {
      "name": "spaces/AAAAAAAAAAA",
      "spaceType": "DIRECT_MESSAGE",
      "singleUserBotDm": true
    },
    "user": {
      "type": "HUMAN",
      "name": "123456789"
    }
  }
}