Как подписаться на события Google Chat

На этой странице описаны события Chat, на которые приложение Chat может подписаться с помощью Google Workspace Events API. Определив, какие типы событий вам нужны, создайте подписку, чтобы начать получать события из Chat.

Помимо подписки на события, вы также можете запрашивать события, вызывая Google Chat API. Вызов Chat API позволяет периодически получать события или узнавать о событиях, которые вы могли пропустить из-за сбоя в работе подписки. Подробнее о том, как получать события Chat и отвечать на них…

Поддерживаемые события Chat

Подписки Google Workspace позволяют получать события о следующих типах изменений в Chat:

• Новые, обновленные или удаленные сообщения в чат-группе.
• Добавление или удаление откликов на сообщение.
• Добавление, изменение или удаление участников чат-группы.
• Изменения в чат-группе, на которую вы подписаны, например обновление названия или описания чат-группы.
• Изменения доступности пользователя.
• Изменения в spaceReadState или threadReadState пользователя.

Ресурсы, для которых можно отслеживать события

Чтобы получать события, укажите ресурс Chat, который нужно отслеживать. Он называется целевым ресурсом подписки.

Google Workspace Events API поддерживает следующие целевые ресурсы для Chat:

Типы событий для создания подписок

При создании подписки используйте поле eventTypes[], чтобы указать, какие типы событий вы хотите получать. Типы событий форматируются в соответствии со спецификацией CloudEvents, например google.workspace.APPLICATION.RESOURCE.VERSION.ACTION.

Например, чтобы получать события о пользователях, присоединяющихся к чат-группе, укажите чат-группу в качестве целевого ресурса, а тип события – как google.workspace.chat.membership.v1.created. Чтобы получать события о присоединении определенного пользователя к любому чат-пространству, укажите пользователя в качестве целевого ресурса, а тип события – как google.workspace.chat.membership.v1.created. Подробнее о том, как работают события, рассказывается в статье Структура событий Google Workspace.

В таблице ниже показано, какие типы событий поддерживаются для подписок на чат-группы и пользователей. Исключения, при которых событие не активируется, описаны в разделе Ограничения.

Типы пакетных событий (только вывод)

Помимо событий, на которые вы подписаны, ваше приложение Chat может получать пакетные события. Пакетное событие – это событие, которое представляет собой множество событий одного типа, происходящих за короткий период времени. Полезная нагрузка пакетного события содержит список всех измененных ресурсов.

Например, если пользователь добавляет в чат-группу 20 пользователей одновременно, ваше приложение Chat может получить пакетное событие (google.workspace.chat.membership.v1.batchCreated). Полезная нагрузка события содержит список всех новых ресурсов Membership, которые были созданы, когда пользователь добавил участников в чат-группу.

Вы получаете пакетное событие для любого типа события, на которое вы подписаны, поэтому вам не нужно указывать пакетные события при создании подписки. Например, если вы подпишетесь на новые отклики (google.workspace.chat.reaction.v1.created), ваше приложение Chat будет автоматически настроено на получение событий пакетных откликов (google.workspace.chat.reaction.v1.batchCreated).

В таблице ниже перечислены возможные пакетные события для подписки.

Данные события

В этом разделе описываются данные о событиях и примеры полезной нагрузки для событий в Chat.

Когда ваша подписка Google Workspace получает событие от Chat, поле data содержит полезную нагрузку для события. В этих полезных данных содержится информация об измененном ресурсе Google Workspace. Например, если вы подписались на события, связанные с участниками чат-группы, полезная нагрузка для этих событий содержит информацию об измененном ресурсе spaces.membership.

Данные ресурса в полезной нагрузке события

При создании подписки вы можете указать, должна ли полезная нагрузка включать сведения о ресурсе или только его название. Например, если вы хотите получать события об участниках чат-группы Chat, укажите, какие поля ресурса участника вы хотите получать в полезной нагрузке события.

В таблице ниже приведены примеры полезной нагрузки JSON для подписки на чат-группу Chat spaces/AAAABBBBBB. Для каждого события, полученного подпиской, полезная нагрузка отображается в поле data события:

{
    "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"
    }
}
      

{
    "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"
    }
}
      

{
    "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"
    }
}
      

{
    "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"
          }
        }
    ]
}
      

{
    "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"
    }
}
      

{
    "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",
        }
      }
    ]
}
      

{
  "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"
  }
}
      

{
  "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"
  }
}
      

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

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

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

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

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

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

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

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

{
    "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 должна быть хотя бы одна лицензия Enterprise.
• Приложение Chat может создать только одну подписку клиента для определенной организации Google Workspace. У организации Google Workspace может быть не более пяти подписок клиентов (созданных разными приложениями Chat).

Для подписок клиентов доставка событий выполняется по следующим общим правилам:

• События чат-группы. Доставляются, только если событие происходит в чат-группе, управляемой вашей организацией Google Workspace.
• События пользователей. Доставляются, только если событие происходит для пользователя, который принадлежит к вашей организации Google Workspace.

Единственное исключение из этих правил – события, связанные с членством. Ваша подписка может получать события участия как из чат-групп, управляемых вашей организацией, так и из чат-групп, управляемых внешними организациями, но способ их доставки зависит от того, какая организация управляет чат-группой:

Чат-группы, управляемые вашей организацией Google Workspace

Если в чат-группе, управляемой организацией Google Workspace, меняется состав участников, это передается как событие чат-группы.

Название ресурса для события чат-группы имеет следующий формат:

spaces/{spaceId}/spaceEvents/{spaceEventId}

Чат-группы, управляемые внешними организациями

Если статус пользователя, управляемого вашей организацией Google Workspace, меняется в чат-группе, управляемой внешней организацией (например, во внешней именованной чат-группе или прямой переписке, созданной внешним пользователем), ваша подписка получает это событие как пользовательское событие.

Название ресурса пользовательского события имеет следующий формат:

users/{userId}/userEvents/{userEventId}

Статьи по теме

• Структура событий Google Workspace
• Выбор областей действия OAuth
• Создайте подписку, чтобы получать события Chat.