Подпишитесь на события Google Chat

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

Помимо подписки на события, вы также можете запрашивать события, используя API Google Chat. Вызов API Chat позволяет периодически получать события или наверстывать упущенное из-за сбоя в работе сервиса, если вы пропустили подписку. Чтобы узнать о способах получения событий Chat и ответа на них, см. раздел «Работа с событиями из Chat» в документации Chat.

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

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

• Новые, обновленные или удаленные сообщения в этом пространстве.
• Новые или удалённые реакции на сообщение.
• В этом пространстве появились новые, обновились данные или были удалены некоторые участники .
• Изменения в пространстве , на которое вы подписаны, например, обновление названия или описания пространства.
• Изменения в доступности пользователя.
• Изменения в параметрах spaceReadState или threadReadState пользователя.

Ресурсы, за которыми вы можете следить на предмет событий.

Для получения событий необходимо указать ресурс чата, который следует отслеживать, — это целевой ресурс подписки.

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

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

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

Например, чтобы получать события о присоединении пользователей к чату, укажите чат в качестве целевого ресурса, а тип события — google.workspace.chat.membership.v1.created . Чтобы получать события о присоединении конкретного пользователя к любому чату, укажите пользователя в качестве целевого ресурса, а тип события — google.workspace.chat.membership.v1.created . Более подробную информацию о работе событий см. в разделе «Структура событий Google Workspace» .

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

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

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

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

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

В следующей таблице показаны возможные пакетные события для подписки:

данные о событии

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

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

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

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

В следующей таблице приведены примеры JSON-данных для подписки на чат 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",
    }
}
      

Общие ограничения

• Чтобы получать события, связанные с членством, пользователь или приложение чата должны быть непосредственными членами пространства. Если пользователь был добавлен, обновлен или удален из пространства косвенно через группу Google, подписка не будет получать эти события. Чтобы понять, как работает членство в группах Google, см. раздел «Добавление группы Google в пространство» .

Подписки пользователей

• Для подписок пользователей события, касающиеся новых участников в личных сообщениях или безымянных групповых чатах ( google.workspace.chat.membership.v1.created ), срабатывают только после отправки первого сообщения.

Подписки для клиентов ( science предварительная версия для разработчиков)

Для клиентских подписок действуют следующие ограничения:

• Организация Google Workspace должна иметь как минимум одну лицензию Enterprise SKU. Обратите внимание, что это требование не является строгим на этапе программы предварительного просмотра для разработчиков, но будет введено в будущем (об этом будет объявлено отдельно).
• Приложение для чата может создать только одну клиентскую подписку для данной организации Google Workspace. В общей сложности организация Google Workspace может иметь до пяти клиентских подписок (созданных разными приложениями для чата).

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

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

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

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

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

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

spaces/{spaceId}/spaceEvents/{spaceEventId}

Помещения, находящиеся в управлении сторонних организаций.

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

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

users/{userId}/userEvents/{userEventId}

Связанные темы

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