Типы событий взаимодействия с приложением Google Chat

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

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

Форматы мероприятий взаимодействия

Пользователи могут взаимодействовать с приложениями чата разными способами. Для каждого типа взаимодействия Google Chat отправляет разные типы событий взаимодействия:

  • Сообщение. Пользователь отправляет вашему приложению чата сообщение или вызывает ваше приложение чата в пространстве.
  • Добавлено в пространство: пользователь добавляет ваше приложение Chat в пространство.
  • Удалено из пространства: пользователь удаляет ваше приложение Chat из пространства.
  • Щелчок по карточке: пользователь щелкает интерактивную карточку или диалоговое окно, отправленное вашим приложением Chat.

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

Дополнительную информацию о полях в событии взаимодействия см. в справочной документации Event Google Chat API.

Общие поля

Следующие поля всегда предоставляются в полезных данных события взаимодействия:

Поле Описание
type Тип события, которое получает приложение Chat, например MESSAGE или ADDED_TO_SPACE .
eventTime Временная метка , указывающая, когда событие было отправлено.
common Представляет информацию о клиенте пользователя, например языковой стандарт или платформу.

Поля по типу события взаимодействия

В зависимости от типа события полезные данные могут содержать следующие дополнительные поля:

Поле Описание Тип события
message Сообщение, связанное с событием. MESSAGE , ADDED_TO_SPACE , CARD_CLICKED .
space Пространство, связанное с событием. MESSAGE , ADDED_TO_SPACE , REMOVED_FROM_SPACE , CARD_CLICKED .
user Пользователь, связанный с событием. Пользователь — это всегда человек (а не приложение чата). MESSAGE , ADDED_TO_SPACE , REMOVED_FROM_SPACE , CARD_CLICKED .
action Функция, которую пользователь запускает, когда щелкает интерактивную карточку или диалоговое окно. CARD_CLICKED .

Пример полезных данных событий

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

Сообщение

Это событие взаимодействия представляет собой отправку пользователем сообщения в приложение Chat, например:

  • Любое сообщение в области прямых сообщений (DM) с помощью приложения Chat.
  • Сообщение в пространстве для нескольких человек, в котором человек @упоминает приложение Chat или использует одну из его косых команд.
  • Если вы настроили предварительный просмотр ссылок для своего приложения Chat, пользователь публикует сообщение, содержащее ссылку, соответствующую настроенному шаблону URL-адреса.

В следующем примере JSON показано событие взаимодействия MESSAGE , когда пользователь @упоминает приложение Chat в пространстве с несколькими людьми:

{
  "type": "MESSAGE",
  "eventTime": {
      "seconds": 1691187414,
      "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "displayName": "Customer Support Superstars",
    "spaceType": "SPACE"
  },
  "message": {
    "name": "spaces/AAAAAAAAAAA/messages/CCCCCCCCCCC",
    "sender": {
      "name": "users/12345678901234567890",
      "displayName": "Izumi",
      "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
      "email": "izumi@example.com"
    },
    "createTime": {
      "seconds": 1691187386,
      "nanos": 954319000
    },
    "text": "@TestBot Create ticket.",
    "argumentText": " Create ticket.",
    "thread": {
      "name": "spaces/AAAAAAAAAAA/threads/BBBBBBBBBBB",
      "threadKey": "custom-thread-ID"
    },
    "annotations": [
      {
        "length": 8,
        "startIndex": 0,
        "userMention": {
          "type": "MENTION",
          "user": {
            "avatarUrl": "https://.../avatar.png",
            "displayName": "TestBot",
            "name": "users/1234567890987654321",
            "type": "BOT"
          }
        },
        "type": "USER_MENTION"
      }
    ],
    "attachment": [
      {
        "name": "spaces/5o6pDgAAAAE/messages/Ohu1LlUVcS8.Ohu1LlUVcS8/attachments/AATUf-Iz7d8kySEdRRZd-dznqBk3",
        "content_name": "solar.png",
        "content_type": "image/png",
        "drive_data_ref": {
          "drive_file_id": "H1HqaqRuH2Pfd_TOa1fF2_ltwDlV_yKRrr"
        },
        "source": "DRIVE_FILE"
      }
    ]
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

Добавлено в космос

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

В следующем примере JSON показано тело запроса для события взаимодействия ADDED_TO_SPACE , когда пользователь добавляет приложение чата в пространство:

{
  "type": "ADDED_TO_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "displayName": "Customer Support Superstars",
    "spaceType": "SPACE",
    "adminInstalled": "false"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

Установлено администраторами Google Workspace.

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

Администраторы могут устанавливать приложение Chat только для прямых сообщений между приложением Chat и пользователем. Установленное приложение отображается на панели личных сообщений пользователей. Когда администраторы устанавливают приложения Chat, пользователи не могут их удалить. Дополнительную информацию о приложениях Chat, установленных администраторами, можно найти в справке администратора Google Workspace «Установка приложений Marketplace в своем домене » .

В следующем примере JSON показано тело запроса для события взаимодействия ADDED_TO_SPACE , когда администратор Google Workspace устанавливает приложение Chat для пользователя. Поскольку приложение Chat установил администратор, для adminInstalled установлено значение true :

{
  "type": "ADDED_TO_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "displayName": "Customer Support Superstars",
    "spaceType": "DIRECT_MESSAGE",
    "adminInstalled": "true"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

Удален из космоса

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

В следующем примере JSON показано тело запроса для события взаимодействия REMOVED_FROM_SPACE , когда пользователь удаляет приложение Chat из пространства:

{
  "type": "REMOVED_FROM_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "spaceType": "SPACE",
    "adminInstalled": "false"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

Удален администраторами Google Workspace.

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

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

В следующем примере JSON показано тело запроса для события взаимодействия REMOVED_FROM_SPACE , когда администратор Google Workspace удаляет приложение Chat для пользователя. Поскольку приложение Chat было удалено администратором, для adminInstalled установлено значение true :

{
  "type": "REMOVED_FROM_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "spaceType": "DIRECT_MESSAGE",
    "adminInstalled": "true"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

Карта нажата

Это событие взаимодействия указывает на то, что пользователь нажал кнопку в сообщении или диалоговом окне карточки.

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

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

В следующем примере JSON показано тело запроса для события взаимодействия CARD_CLICKED , когда пользователь нажимает кнопку в сообщении с карточкой, которое назначает ему входящий запрос в службу поддержки:

{
  "type": "CARD_CLICKED",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "common": {
    "userLocale": "en",
    "hostApp": "CHAT",
    "invokedFunction": "doAssignTicket",
    "timeZone": {
      "offset": -25200000,
      "id": "America/Los_Angeles"
    }
  },
  "action": {
    "actionMethodName": "doAssignTicket"
  },
  "message": {
    "cards": [
      {
        "header": {
          "title": "Incoming support ticket."
        },
        "sections": [
          {
            "widgets": [
              {
                "textParagraph": {
                  "text": "Incoming support ticket #12345 is unassigned and needs your attention."
                }
              },
              {
                "buttons": [
                  {
                    "textButton": {
                      "onClick": {
                        "action": {
                          "actionMethodName": "doAssignTicket"
                        }
                      },
                      "text": "Assign to me"
                    }
                  }
                ]
              }
            ]
          }
        ]
      }
    ],
    "sender": {
      "avatarUrl": "https://www.example.com/images/chat-app-icon.png",
      "displayName": "Support Chat app",
      "name": "users/98765432109876543210",
      "type": "BOT"
    },
    "createTime": {
      "seconds": 1691187386,
      "nanos": 954319000
    },
    "retentionSettings": {
      "state": "PERMANENT"
    },
    "name": "spaces/AAAAAAAAAAA/messages/CCCCCCCCCCC",
    "thread": {
      "retentionSettings": {
        "state": "PERMANENT"
      },
      "name": "spaces/AAAAAAAAAAA/threads/BBBBBBBBBBB"
    },
    "messageHistoryState": "HISTORY_ON",
    "space": {
      "spaceThreadingState": "GROUPED_MESSAGES",
      "spaceType": "SPACE",
      "displayName": "Customer Support Superstars",
      "name": "spaces/AAAAAAAAAAA",
      "spaceHistoryState": "HISTORY_ON",
      "type": "ROOM",
      "threaded": true
    }
  },
  "user": {
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "displayName": "Izumi",
    "name": "users/12345678901234567890",
    "type": "HUMAN",
    "email": "izumi@example.com",
    "domainId": "ABCDEFG"
  },
  "space": {
    "spaceThreadingState": "GROUPED_MESSAGES",
    "spaceType": "SPACE",
    "displayName": "Customer Support Superstars",
    "name": "spaces/AAAAAAAAAAA",
    "spaceHistoryState": "HISTORY_ON",
    "type": "ROOM",
    "threaded": true
  }
}

Клики карточек для диалогов

Когда пользователь взаимодействует с диалоговым окном, полезные данные для события взаимодействия CARD_CLICKED включают в себя следующие дополнительные поля:

  • isDialogEvent : установите значение true для событий взаимодействия, включающих диалоги.
  • DialogEventType : тип взаимодействия с диалоговым окном, в том числе, если пользователь открывает, отправляет или отменяет диалоговое окно.

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

{
  "type": "CARD_CLICKED",
  ...
  "isDialogEvent": true,
  "dialogEventType": "SUBMIT_DIALOG",
}

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