このページでは、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"
}
}
}
関連トピック
インタラクション イベントのペイロードを処理してレスポンスを返す方法については、次のガイドをご覧ください。
- カード メッセージを送信する
- テキスト メッセージを送信する
- アプリのホームカード メッセージを送信する
- インタラクティブなダイアログを開く
- プレビュー リンク
- ユーザーがカード上で入力したフォームデータを読み取る
- スラッシュ コマンドを設定する