このページでは、Google Chat アプリが Google Chat のイベントを受信して応答する方法について説明します。
Google Chat イベントは、スペース内の新しいメッセージなど、Chat でのアクティビティや変更を表します。Chat アプリでは、イベントを使用して何が起こったのかを把握し、ユーザーにとって有意義な方法でアクションを実行したり、応答したりできます。
イベントの使用例をいくつか示します。
- スペース内の新しいメッセージをモニタリングして返信する（キーワードやフレーズを確認するなど）。
- ユーザーがスペースに参加したときにウェルカム メッセージを送信して、スペースのガイドラインを説明したり、Chat アプリを効果的に使用する方法に関するヒントを共有したりします。
- Chat のアクティビティを追跡、分析します。たとえば、新規メンバーや、高評価や返信が最も多かったメッセージに関する月次レポートを送信できます。
- メッセージング プラットフォーム間でコミュニケーションをとる。たとえば、ユーザーは Chat を離れることなく、別のメッセージ プラットフォームのユーザーとメッセージを送受信できます。
イベントの仕組み
Google Chat で何かが発生するたびに、Google Chat API リソースが作成、更新、削除されます。Chat はイベントを使用して、発生したアクティビティの種類と影響を受けた Chat API リソースに関する情報を Chat アプリに提供します。
Message リソースが作成されます。Chat は、新しいメッセージに関するデータを含むイベントを作成します。Chat では、イベントがタイプ別に分類されます。イベントタイプを使用すると、必要な種類の情報のみをフィルタして取得し、類似するアクティビティを同じ方法で処理できます。
次の表に、Chat でのアクティビティが関連する Chat API リソースに与える影響と、Chat アプリが受信するイベントの種類を示します。
| アクティビティ | Chat API リソース | イベントの種類 |
|---|---|---|
| ユーザーが Chat スペースにメッセージを投稿します | Message リソースが作成されます。 |
新しいメッセージ |
| ユーザーがスペースの管理者になります。 | Membership リソースが更新されます。 |
メンバーシップを更新しました |
| ユーザーがメッセージにリアクションします。 | Reaction リソースが作成されます。 |
リアクションを受信しました |
| ユーザーがスペースから退出する。 | Membership リソースが削除されます。 |
メンバーシップを削除しました |
Google Chat からイベントを受信する
Chat アプリは、次のいずれかの方法でイベントを受信できます。
- Google Workspace Events API を使用してイベントに登録し、イベントが発生するたびに受信します。
- Chat API を呼び出して、最近のイベントをクエリします。
次の表に、イベントのクエリとサブスクリプションの違いと理由を示します。
| イベントに登録する | イベントをクエリする | |
|---|---|---|
| ユースケース |
|
|
| API | Google Workspace Events API | Chat API |
| イベントのソース | スペースとユーザー | スペースのみ |
| サポートされるイベント |
サポートされているイベントタイプの一覧については、Google Workspace Events API ドキュメントの 定期購入の作成に使用するイベントタイプをご覧ください。 |
サポートされているイベントタイプの一覧については、Chat API リファレンス ドキュメントの spaceEvents リソースをご覧ください。
|
| イベントの形式 | CloudEvent 仕様に従ってフォーマットされた Google Cloud Pub/Sub メッセージ。詳しくは、Google Workspace イベントの構造をご覧ください。 |
Chat API リソース（
spaces.spaceEvent） |
| イベントデータ | リソースデータの有無にかかわらず Base64 でエンコードされた文字列。ペイロードの例については、イベントデータをご覧ください。 | リソースデータを含む JSON ペイロード。イベントタイプによっては、特定のリソース フィールドのみが含まれます。ペイロードの例については、 リファレンス ドキュメントをご覧ください。 |
例: スペースのメンバーシップに関するイベントをクエリまたはサブスクライブする
この例では、Chat アプリが Chat スペースのメンバーの変更に関する情報を受信します。スペースでは、次のメンバーシップ アクティビティが発生します。
- ユーザーがスペースに参加すると、
Membershipリソースが作成され、新しいメンバー イベントがトリガーされます。 - ユーザーがスペースの管理者になると、ユーザーの
Membershipリソースが更新され、更新されたメンバー イベントがトリガーされます。 - ユーザーがスペースを離れると、ユーザーの
Membershipリソースが削除され、メンバー削除イベントがトリガーされます。
メンバーシップ イベントに登録する
イベントをリアルタイムで受信するため、Chat アプリは Google Workspace Events API の subscriptions.create() メソッドを呼び出して、すべてのタイプのメンバーシップ イベントのスペースをサブスクライブします。サブスクリプションを作成すると、Chat アプリはメンバーシップ イベントの受信を開始できます。
図 2 では、Chat アプリはスペースに有効な定期購入があるため、スペースのメンバーシップが変更されるたびにイベントを受信します。これにより、Chat アプリは、スペースに参加したメンバーに非公開のウェルカム メッセージを投稿するなど、あらゆるアクティビティをリアルタイムで処理または応答できます。
Google Workspace Events API を使用してサブスクリプションを作成する方法については、Google Workspace Events API のドキュメントをご覧ください。
最近のメンバーシップ イベントをクエリする
Chat アプリは、メンバーシップ イベントが発生したときに受信するのではなく、Chat API を呼び出して、メンバーシップ アクティビティに関連する最近のスペース イベントを一覧表示できます。
図 3 の Chat アプリは、すべてのメンバーシップ アクティビティが発生した後に Chat API の spaces.spaceEvents.list() メソッドを呼び出し、新しいメンバーシップ イベント、更新されたメンバーシップ イベント、削除されたメンバーシップ イベントをクエリでフィルタします。Chat API は、各メンバーシップの変更を表す spaceEvent リソースのリストを返します。Chat アプリは、最近のアクティビティに基づいて処理または応答できます。たとえば、過去 7 日間のスペースのメンバーシップ アクティビティの概要を含む週次メッセージを投稿できます。
Chat API を使用してイベントをクエリするには、Google Chat スペースのイベントを一覧表示するをご覧ください。
制限事項
-
ユーザーの定期購入の場合、ダイレクト メッセージまたは名前のないグループ チャット（
google.workspace.chat.membership.v1.created）の新しいメンバーに関するイベントは、最初のメッセージが投稿された後にのみトリガーされます。 - メンバーシップ イベントを受信するには、ユーザーがスペースの直接的なメンバーである必要があります。Google グループを介してスペースにユーザーが間接的に追加、更新、削除された場合、サブスクリプションにはそれらのメンバーシップ イベントは送信されません。Google グループのメンバーシップの仕組みについては、スペースに Google グループを追加するをご覧ください。
関連トピック
- Google Workspace Events API の概要
- 定期購入の作成
- Google Chat スペースのイベントの詳細を取得する
- Google Chat スペースのイベントを一覧表示する
- イベントの使用例については、Gemini AI Chat アプリで Chat の会話に基づいて質問に回答するのチュートリアル、または Codelab Gemini 対応の Google Chat アプリを作成するの課題管理 Chat アプリの包括性に関するヘルプ機能を参照してください。