このページでは、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 用アプリのインクルーシビティ ヘルプ機能をご覧ください。