Google Chat のイベントに登録する

このページでは、Google Workspace Events API を使用して Chat アプリが登録できる Chat イベントについて説明します。必要なイベントの種類を決定したら、サブスクリプションを作成して、Chat からのイベントの受信を開始します。

イベントのサブスクライブに加えて、Google Chat API を呼び出してイベントのクエリを実行することもできます。Chat API を呼び出すと、イベントを定期的に取得したり、停止によりサブスクリプションから見逃した可能性のあるイベントをキャッチアップしたりできます。Chat イベントを受信して応答する方法については、Chat ドキュメントの Chat のイベントを操作するをご覧ください。

サポートされている Chat イベント

Google Workspace サブスクリプションを使用すると、Chat で行われた次の種類の変更に関するイベントを受信できます。

イベントをモニタリングできるリソース

イベントを受信するには、モニタリングする Chat リソースを指定します。これは、サブスクリプションのターゲット リソースと呼ばれます。

Google Workspace Events API は、Chat の次のターゲット リソースをサポートしています。

ターゲット リソース 形式 制限事項
スペース

//chat.googleapis.com/spaces/SPACE

ここで、SPACE は Chat API の space リソースの リソース名の ID です。ID は、スペースの URL から取得するか、 spaces.list() メソッドを使用して取得できます。

 サブスクリプションを承認する Chat ユーザーまたは Chat 用アプリは、Google Workspace アカウントまたは Google アカウントを通じてスペースのメンバーである必要があります。サポート:
ユーザーのすべてのスペース

//chat.googleapis.com/spaces/-

 サブスクリプションは、ユーザーが Google Workspace または Google アカウントを通じてメンバーになっているスペースのイベントのみを受信します。ユーザー認証のみをサポートします。
ユーザー

//cloudidentity.googleapis.com/users/USER

ここで、USER は Chat API の user リソースの リソース名の ID です。詳しくは、Google Chat ユーザーを特定して指定するをご覧ください。

サブスクリプションは、サブスクリプションを承認したユーザーに関するイベントのみを受信します。ユーザーは、他のユーザーに代わってサブスクリプションを承認することはできません。ユーザー認証のみをサポートします。
お客様 （ デベロッパー プレビュー）

//admin.googleapis.com/customers/CUSTOMER

ここで、CUSTOMER は顧客 ID です。Chat 用アプリの顧客ドメインに my_customer エイリアスを使用することもできます。

サブスクリプションは、顧客ドメインで管理されているすべてのスペースとユーザーのイベントを受信します。管理者による承認を必要とするアプリ認証のみをサポートします。

サブスクリプション作成のイベントタイプ

サブスクリプションを作成するときに、eventTypes[] フィールドを使用して、受信するイベントのタイプを指定します。イベントタイプは、google.workspace.APPLICATION.RESOURCE.VERSION.ACTION などの CloudEvents 仕様に従ってフォーマットされます。

たとえば、ユーザーが Chat スペースに参加したときのイベントを受信するには、スペースをターゲット リソースとして指定し、イベントタイプを google.workspace.chat.membership.v1.created として指定します。特定のユーザーが任意のスペースに参加したことに関するイベントを受信するには、ユーザーをターゲット リソースとして指定し、イベントタイプを google.workspace.chat.membership.v1.created として指定します。イベントの仕組みについては、Google Workspace イベントの構造をご覧ください。

次の表に、スペースのサブスクリプションとユーザーのサブスクリプションでサポートされているイベントタイプを示します。イベントをトリガーする例外については、制限事項をご覧ください。

イベント タイプ 形式 リソースデータ
スペースのサブスクリプション  
メッセージが投稿された。

google.workspace.chat.message.v1.created

space.message
メッセージが更新された。

google.workspace.chat.message.v1.updated

space.message
メッセージが削除されます。

google.workspace.chat.message.v1.deleted

space.message
リアクションが作成されます。

google.workspace.chat.reaction.v1.created

space.message.reaction
リアクションが削除されます。

google.workspace.chat.reaction.v1.deleted

space.message.reaction
メンバーがスペースに追加されます。

google.workspace.chat.membership.v1.created

space.membership
スペース内のメンバーが更新されます。

google.workspace.chat.membership.v1.updated

space.membership
メンバーがスペースから削除されます。

google.workspace.chat.membership.v1.deleted

space.membership
スペースが更新されます。

google.workspace.chat.space.v1.updated

space
スペースが削除されます。

google.workspace.chat.space.v1.deleted

space
ユーザーへのサブスクリプション  
ユーザーがスペースのメンバーになります。

すべての新規メンバーがイベントをトリガーするわけではありません。詳細については、制限事項をご覧ください。

google.workspace.chat.membership.v1.created

space.membership
ユーザーのスペース メンバーシップが更新されます。

google.workspace.chat.membership.v1.updated

space.membership
ユーザーはスペースの直接のメンバーから削除されます。

google.workspace.chat.membership.v1.deleted

space.membership
ユーザーのスペースの既読状態が更新されます。

google.workspace.chat.spaceReadState.v1.updated

spaceReadState
ユーザーのスレッドの既読状態が更新されます。

google.workspace.chat.threadReadState.v1.updated

threadReadState
顧客への定期購入 （ デベロッパー プレビュー）  
Google Workspace 組織内のスペース、メッセージ、リアクション、メンバーシップ、ユーザーの既読ステータスでイベントが発生します。

スペースとユーザーのサブスクリプションに記載されているすべてのイベントタイプをサポートします。

イベントタイプ（space、space.message、space.membership、spaceReadState など）によって異なります。

バッチ イベントタイプ（出力のみ）

Chat 用アプリは、登録したイベントタイプに加えて、バッチイベントを受信することもあります。バッチ イベントは、短期間に発生する同じタイプの多くのイベントを表すイベントです。バッチイベントのペイロードには、変更されたすべてのリソースのリストが含まれています。

たとえば、ユーザーが 20 人のユーザーを同時にスペースに追加すると、Chat 用アプリはバッチ イベント（google.workspace.chat.membership.v1.batchCreated）を受信する可能性があります。イベント ペイロードには、ユーザーがメンバーをスペースに追加したときに作成された新しい Membership リソースのリストが含まれています。

登録したイベントタイプのバッチイベントが送信されるため、サブスクリプションの作成時にバッチイベントを指定する必要はありません。たとえば、新しいリアクション（google.workspace.chat.reaction.v1.created）を登録すると、Chat 用アプリはバッチ リアクション イベント（google.workspace.chat.reaction.v1.batchCreated）を受信するように自動的に構成されます。

次の表に、サブスクリプションで発生する可能性のあるバッチイベントを示します。

バッチ イベントタイプ 形式
複数のメッセージが投稿されます。

google.workspace.chat.message.v1.batchCreated
複数のメッセージが更新されます。

google.workspace.chat.message.v1.batchUpdated
複数のメッセージが削除されます。

google.workspace.chat.message.v1.batchDeleted
複数のリアクションが作成されます。

google.workspace.chat.reaction.v1.batchCreated
複数のリアクションが削除されます。

google.workspace.chat.reaction.v1.batchDeleted
複数のメンバーが登録済みスペースに追加された場合、または登録済みユーザーが複数のスペースに追加された場合。

google.workspace.chat.membership.v1.batchCreated
複数のメンバーシップが、登録されたスペースまたは登録されたユーザーに対して更新されます。

google.workspace.chat.membership.v1.batchUpdated
複数のメンバーが登録しているスペースから削除された場合、または登録しているユーザーが複数のスペースから削除された場合。

google.workspace.chat.membership.v1.batchDeleted
スペースに複数の更新情報があります。

google.workspace.chat.space.v1.batchUpdated
登録ユーザーの複数のスペースの既読状態が更新されます。

google.workspace.chat.spaceReadState.v1.batchUpdated
登録ユーザーの複数のスレッドの既読状態が更新されます。

google.workspace.chat.threadReadState.v1.batchUpdated

イベントデータ

このセクションでは、Chat のイベントのイベントデータとペイロードの例について説明します。

Google Workspace サブスクリプションが Chat からイベントを受信すると、data フィールドにイベントのペイロードが含まれます。このペイロードには、変更された Google Workspace リソースに関する情報が含まれています。たとえば、スペースのメンバーシップ イベントを購読している場合、これらのイベントのペイロードには、変更された spaces.membership リソースに関する情報が含まれます。

イベント ペイロードのリソースデータ

サブスクリプションを作成するときに、ペイロードにリソースの詳細を含めるか、リソースの名前のみを含めるかを指定できます。たとえば、Chat スペースのメンバーに関するイベントを受信する場合は、イベント ペイロードで受信するメンバーシップ リソースのフィールドを指定します。

次の表に、Chat スペース spaces/AAAABBBBBB のサブスクリプションの JSON ペイロードの例を示します。サブスクリプションが受信する各イベントのペイロードは、イベントの data フィールドに表示されます。

例 イベント タイプ JSON ペイロード

ユーザーがスペースに「Hello world」というメッセージを投稿します。

google.workspace.chat.message.v1.created

リソースデータが含まれます。

{
    "message":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID",
        "sender":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "createTime": "2023-09-07T21:37:36.260127Z",
        "text": "Hello world",
        "thread":
        {
            "name": "spaces/SPACE_ID/threads/THREAD_ID"
        },
        "space":
        {
            "name": "spaces/SPACE_ID"
        },
        "argumentText": "Hello world"
    }
}

リソースデータを除外します。

{
    "message":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID"
    }
}
ユーザーがスペースの管理者になる。

google.workspace.chat.membership.v1.updated

リソースデータが含まれます。

{
    "membership":
    {
        "name": "spaces/SPACE_ID/members/MEMBER_ID",
        "state": "JOINED",
        "member":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "createTime": "1970-01-01T00:00:00Z",
        "role": "ROLE_MANAGER"
    }
}

リソースデータを除外します。

{
    "membership":
    {
        "name": "spaces/SPACE_ID/members/MEMBER_ID"
    }
}
ユーザーがスペースの説明を「Cymbal Labs の営業チーム」に更新します。 google.workspace.chat.space.v1.updated

リソースデータが含まれます。

{
    "space":
    {
        "name": "spaces/SPACE_ID",
        "displayName": "Cymbal Sales",
        "spaceThreadingState": "THREADED_MESSAGES",
        "spaceType": "SPACE",
        "spaceDetails":
        {
            "description": "Sales team for Cymbal Labs."
        },
        "spaceHistoryState": "HISTORY_ON"
    }
}

リソースデータを除外します。

{
    "space":
    {
        "name": "spaces/SPACE_ID"
    }
}
2 人の Chat ユーザーが同時にスペースに追加されました。 google.workspace.chat.membership.v1.batchCreated

リソースデータが含まれます。

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID",
            "state": "JOINED",
            "member":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        },
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID",
            "state": "JOINED",
            "member":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        }
    ]
}

リソースデータを除外します。

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        },
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        }
    ]
}
ユーザーが 😊 絵文字でメッセージにリアクションしている。 google.workspace.chat.reaction.v1.created

リソースデータが含まれます。

{
    "reaction":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
        "user":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "emoji":
        {
            "unicode": "😊"
        }
    }
}

リソースデータを除外します。

{
    "reaction":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
    }
}
ユーザーが 😊 絵文字と 😸 絵文字でメッセージにリアクションしています。 google.workspace.chat.reaction.v1.batchCreated

リソースデータが含まれます。

{
    "reactions": [
        {
          "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
            "user":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😊"
            }
          }
        },
        {
          "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
            "user":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😸"
            }
          }
        }
    ]
}

リソースデータを除外します。

{
    "reactions": [
      {
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
        },
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
        }
      }
    ]
}
ユーザーが未読のスペースにアクセスすると、スペースの既読状態が更新されます。 google.workspace.chat.spaceReadState.v1.updated

リソースデータが含まれます。

{
  "spaceReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/spaceReadState",
    "lastReadTime": "2026-04-14T14:03:46.431760Z"
  }
}

リソースデータを除外します。

{
  "spaceReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/spaceReadState"
  }
}
ユーザーがスレッド内のメッセージを読むと、スレッドの既読状態が更新されます。 google.workspace.chat.threadReadState.v1.updated

リソースデータが含まれます。

{
  "threadReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/threads/THREAD_ID/threadReadState",
    "lastReadTime": "2026-04-14T14:03:46.431760Z"
  }
}

リソースデータを除外します。

{
  "threadReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/threads/THREAD_ID/threadReadState"
  }
}
Chat でユーザーが利用可能になった場合。 google.workspace.chat.availability.v1.updated

リソースデータが含まれます。

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "ACTIVE"
    }
}

リソースデータを除外します。

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
Chat でユーザーがアイドル状態になる。 google.workspace.chat.availability.v1.updated

リソースデータが含まれます。

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "IDLE",
    }
}

リソースデータを除外します。

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
ユーザーが Chat でステータスを Away に設定します。 google.workspace.chat.availability.v1.updated

リソースデータが含まれます。

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "AWAY",
    }
}

リソースデータを除外します。

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
ユーザーが Chat でステータスを Do not disturb に設定します。 google.workspace.chat.availability.v1.updated

リソースデータが含まれます。

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "DO_NOT_DISTURB",
        "doNotDisturbMetadata": {
          "expirationTime": "2026-03-24T18:36:31.337Z"
        }
    }
}

リソースデータを除外します。

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
ユーザーが Chat でカスタム ステータスを設定します。 google.workspace.chat.availability.v1.updated

リソースデータが含まれます。

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "ACTIVE",
        "customStatus": {
          "text": "Be right back",
          "emoji": {
            "unicode": "👟"
          },
          "expireTime": "2026-03-24T18:38:05.583655Z"
        }
    }
}

リソースデータを除外します。

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}

制限事項と配信の動作

一般的な制限事項

  • メンバーシップ イベントを受信するには、ユーザーまたは Chat 用アプリがスペースの直接のメンバーである必要があります。Google グループ経由でスペースに間接的に追加、更新、削除された場合、サブスクリプションはこれらのメンバーシップ イベントを受け取りません。Google グループのメンバーシップの仕組みについては、スペースに Google グループを追加するをご覧ください。

ユーザーの登録

  • ユーザーのサブスクリプションの場合、ダイレクト メッセージまたは名前のないグループ チャットの新しいメンバーに関するイベント（google.workspace.chat.membership.v1.created）は、最初のメッセージが投稿された後にのみトリガーされます。

顧客サブスクリプション （ デベロッパー プレビュー）

お客様のサブスクリプションには、次の制限が適用されます。

  • Google Workspace 組織には、少なくとも 1 つの Enterprise SKU ライセンスが必要です。この要件は、デベロッパー プレビュー プログラムの段階では厳格に適用されませんが、今後適用される予定です（別途お知らせします）。
  • Chat 用アプリで作成できる顧客サブスクリプションは、特定の Google Workspace 組織に対して 1 つのみです。Google Workspace 組織では、合計で最大 5 つの顧客サブスクリプション（異なる Chat 用アプリによって作成されたもの）を設定できます。

お客様のサブスクリプションの場合、イベント配信は次の一般的なルールに従います。

  • Space イベント: Google Workspace 組織が管理するスペースでイベントが発生した場合にのみ配信されます。
  • ユーザー イベント: Google Workspace 組織に属するユーザーに対してイベントが発生した場合にのみ配信されます。

これらのルールの唯一の例外は、メンバーシップ イベントです。サブスクリプションは、組織が管理するスペースと外部組織が管理するスペースの両方からメンバーシップ イベントを受信できますが、配信方法はスペースを管理する組織によって異なります。

Google Workspace 組織によって管理されているスペース

Google Workspace 組織が管理するスペースでメンバーシップの変更が発生すると、スペース イベントとして配信されます。

スペース イベントのリソース名の形式は次のとおりです。

spaces/{spaceId}/spaceEvents/{spaceEventId}

外部組織によって管理されているスペース

Google Workspace 組織で管理されているユーザーのメンバーシップが、外部組織で管理されているスペース（外部のユーザーが作成した外部の名前付きスペースやダイレクト メッセージなど）で変更されると、サブスクリプションはこのイベントをユーザー イベントとして受け取ります。

ユーザー イベントのリソース名には次の形式を使用します。

users/{userId}/userEvents/{userEventId}