このページでは、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.workspace.chat.spaces.v1.updated）。 - メンバーシップ イベントを受信するには、ユーザーがスペースの直接的なメンバーである必要があります。Google グループを介して間接的にスペースに追加、更新、削除された場合、サブスクリプションはこれらのメンバーシップ イベントを受信しません。Google グループのメンバーの仕組みについては、Google グループをスペースに追加するをご覧ください。
関連トピック
- Google Workspace Events API の概要
- 定期購入の作成
- Google Chat スペースのイベントの詳細を取得する
- Google Chat スペースのイベントを一覧表示する
- イベントの使用方法の例については、Gemini AI Chat アプリで Chat の会話に基づいて質問に回答するのチュートリアルをご覧ください。