このページでは、Google Chat アプリが Google Chat 内のイベントを受信して応答する方法について説明します。
Google Chat イベントは、スペースでの新しいメッセージなど、Chat のアクティビティまたは変更を表します。Chat アプリは、イベントを使用して何が起こったかを理解し、ユーザーにとって有意義な方法でアクションや応答を行うことができます。
イベントの使い方の例を次に示します。
- キーワードやフレーズを確認するなど、スペース内の新しいメッセージをモニタリングして対応できます。
- スペースに参加するユーザーにウェルカム メッセージを送信して、スペースのガイドラインを説明したり、Chat アプリを効果的に使用するためのヒントを共有したりします。
- Chat のアクティビティを追跡、分析する。たとえば、新しいメンバーや、リアクションや返信が最も多いメッセージに関する月次レポートを送信する場合などです。
- 複数のメッセージング プラットフォーム間でのコミュニケーション。たとえば、ユーザーは Chat を離れることなく、別のメッセージング プラットフォームでユーザーとメッセージを送受信できます。
イベントの仕組み
Google Chat で何かが発生するたびに、Google Chat API リソースが作成、更新、削除されます。Chat はイベントを使用して、発生したアクティビティの種類と影響を受けた Chat API リソースに関する情報を Chat アプリに配信します。
Message リソースが作成されます。その後、新しいメッセージに関するデータを含むイベントが作成されます。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 API の spaces.spaceEvents.list() メソッドが Chat アプリから呼び出され、新規、更新、削除されたメンバーシップ イベントに対してクエリをフィルタしています。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 アプリのインクルーシブ ヘルプ機能をご覧ください。