Получайте сообщения и отвечайте на них в вашем приложении Google Chat.

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

Событие взаимодействия с приложением Google Chat представляет собой любое действие, которое пользователь предпринимает для вызова приложения Chat или взаимодействия с ним, например @упоминание приложения Chat или добавление его в пространство. Когда пользователи взаимодействуют с приложением Chat, Google Chat отправляет приложению Chat событие взаимодействия. Приложение Chat может использовать это событие для обработки взаимодействия и создания ответа.

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

Пример события взаимодействия Типичный ответ из приложения Chat
Пользователь вызывает приложение чата, @упомянув его или используя косую черту. Приложение Chat обрабатывает то, что говорится в сообщении, и создает сообщение. Например, приложение Chat отвечает на команду /about сообщением, объясняющим задачи, которые может выполнять приложение Chat.
Пользователь добавляет приложение Chat в пространство. Приложение Chat отправляет вводное сообщение , в котором объясняется, что оно делает и как пользователи в пространстве могут с ним взаимодействовать.
Пользователь удаляет приложение Chat из пространства. Приложение Chat удаляет все входящие уведомления, настроенные для этого пространства (например, удаление веб-перехватчика ), и очищает всю внутреннюю память.
Пользователь нажимает кнопку на карточке или в диалоговом окне, отправленном приложением Chat. Приложение «Чат» либо обрабатывает и сохраняет любые данные, отправленные пользователем, либо возвращает другую карточку или диалоговое окно.

Для каждого типа взаимодействия с пользователем Google Chat отправляет разные типы событий взаимодействия. Например, Google Chat использует тип события MESSAGE для любого взаимодействия, когда пользователь вызывает приложение Chat в сообщении. Подробную информацию см. в разделе Типы событий взаимодействия с приложением Google Chat .

На этой странице описано, как сделать следующее:

  • Настройте приложение чата для получения событий.
  • Обработайте событие взаимодействия в своей инфраструктуре.
  • При необходимости реагируйте на события взаимодействия.

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

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

Настройте приложение чата для получения событий взаимодействия.

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

Если вы создали интерактивное приложение чата, вам необходимо настроить Google Chat API, чтобы Google Chat мог отправлять вам события взаимодействия:

  1. В консоли Google Cloud откройте страницу Google Chat API:

    Перейдите на страницу API Google Chat.

  2. Откройте вкладку Конфигурация .
  3. В разделе «Интерактивные функции» установите переключатель «Включить интерактивные функции» во включенное положение.
  4. В разделе «Функциональность» установите один или оба следующих флажка:
    1. Получать сообщения 1:1 . Позволяет пользователям взаимодействовать с вашим приложением Chat в пространствах прямых сообщений (DM). Ваше приложение чата получает события взаимодействия каждый раз, когда пользователь отправляет сообщение в пространстве DM.
    2. Присоединяйтесь к группам и групповым беседам : позволяет пользователям добавлять и удалять ваше приложение чата в группах, в которых участвует более одного человека. Ваше приложение чата получает события взаимодействия всякий раз, когда оно добавляется или удаляется из пространства, а также всякий раз, когда пользователи @упоминают или используют косую черту в пространстве.
  5. В настройках подключения укажите, куда Google Chat отправляет события взаимодействия с приложением Chat.
  6. Необязательно: в разделе «Команды косой черты» добавьте и настройте одну или несколько команд косой черты. Дополнительные сведения см. в разделе Настройка команд слэша .
  7. Необязательно: в разделе «Предварительный просмотр ссылок» добавьте и настройте один или несколько шаблонов URL-адресов, которые просматриваются в приложении Chat. Дополнительную информацию см. в разделе Ссылки для предварительного просмотра .
  8. Нажмите Сохранить .

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

Аутентификация запросов от Google Chat

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

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

POST
Host: yourappurl.com
Authorization: Bearer AbCdEf123456
Content-Type: application/json
User-Agent: Google-Dynamite

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

Для токенов на предъявителя, отправляемых в запросах Google Chat, эмитентом chat@system.gserviceaccount.com , а в поле audience указывается номер проекта Google Cloud, который вы использовали для создания приложения Chat. Например, если номер облачного проекта вашего приложения Chat — 1234567890 , то поле audience в токене носителя — 1234567890 .

Если токен не проверяется для приложения Chat, ваша служба должна ответить на запрос кодом ответа HTTPS 401 (Unauthorized) .

Джава

import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.Collections;

import com.google.api.client.googleapis.auth.oauth2.GoogleIdToken;
import com.google.api.client.googleapis.auth.oauth2.GoogleIdTokenVerifier;
import com.google.api.client.googleapis.auth.oauth2.GooglePublicKeysManager;
import com.google.api.client.http.apache.ApacheHttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.jackson.JacksonFactory;

/** Tool for verifying JWT Tokens for Apps in Google Chat. */
public class JWTVerify {
  // Bearer Tokens received by apps will always specify this issuer.
  static String CHAT_ISSUER = "chat@system.gserviceaccount.com";

  // Url to obtain the public certificate for the issuer.
  static String PUBLIC_CERT_URL_PREFIX =
      "https://www.googleapis.com/service_accounts/v1/metadata/x509/";

  // Intended audience of the token, which is the project number of the app.
  static String AUDIENCE = "1234567890";

  // Get this value from the request's Authorization HTTPS header.
  // For example, for "Authorization: Bearer AbCdEf123456" use "AbCdEf123456"
  static String BEARER_TOKEN = "AbCdEf123456";

  public static void main(String[] args) throws GeneralSecurityException, IOException {
    JsonFactory factory = new JacksonFactory();

    GooglePublicKeysManager.Builder keyManagerBuilder =
        new GooglePublicKeysManager.Builder(new ApacheHttpTransport(), factory);

    String certUrl = PUBLIC_CERT_URL_PREFIX + CHAT_ISSUER;
    keyManagerBuilder.setPublicCertsEncodedUrl(certUrl);

    GoogleIdTokenVerifier.Builder verifierBuilder =
        new GoogleIdTokenVerifier.Builder(keyManagerBuilder.build());
    verifierBuilder.setIssuer(CHAT_ISSUER);
    GoogleIdTokenVerifier verifier = verifierBuilder.build();

    GoogleIdToken idToken = GoogleIdToken.parse(factory, BEARER_TOKEN);
    if (idToken == null) {
      System.out.println("Token cannot be parsed");
      System.exit(-1);
    }

    // Verify valid token, signed by CHAT_ISSUER.
    if (!verifier.verify(idToken)
        || !idToken.verifyAudience(Collections.singletonList(AUDIENCE))
        || !idToken.verifyIssuer(CHAT_ISSUER)) {
      System.out.println("Invalid token");
      System.exit(-1);
    }

    // Token originates from Google and is targeted to a specific client.
    System.out.println("The token is valid");
  }
}

Питон

import sys

from oauth2client import client

# Bearer Tokens received by apps will always specify this issuer.
CHAT_ISSUER = 'chat@system.gserviceaccount.com'

# Url to obtain the public certificate for the issuer.
PUBLIC_CERT_URL_PREFIX = 'https://www.googleapis.com/service_accounts/v1/metadata/x509/'

# Intended audience of the token, which will be the project number of the app.
AUDIENCE = '1234567890'

# Get this value from the request's Authorization HTTPS header.
# For example, for 'Authorization: Bearer AbCdEf123456' use 'AbCdEf123456'.
BEARER_TOKEN = 'AbCdEf123456'

try:
  # Verify valid token, signed by CHAT_ISSUER, intended for a third party.
  token = client.verify_id_token(
      BEARER_TOKEN, AUDIENCE, cert_uri=PUBLIC_CERT_URL_PREFIX + CHAT_ISSUER)

  if token['iss'] != CHAT_ISSUER:
    sys.exit('Invalid issuee')
except:
  sys.exit('Invalid token')

# Token originates from Google and is targeted to a specific client.
print 'The token is valid'

Обработка повторных HTTP-вызовов в вашу службу

Если запрос HTTPS к вашей службе завершается неудачей (например, из-за тайм-аута, временного сбоя сети или кода состояния HTTPS, отличного от 2xx), Google Chat может повторить попытку доставки несколько раз в течение нескольких минут (но это не гарантируется). В результате в определенных ситуациях приложение чата может получать одно и то же сообщение несколько раз. Если запрос завершается успешно, но возвращает недопустимые полезные данные сообщения, Google Chat не повторяет запрос.

Обработка или реагирование на события взаимодействия

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

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

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

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

Архитектура обработки событий взаимодействия приложениями Google Chat.

Отвечайте в режиме реального времени

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

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

Чтобы ответить синхронно, приложение Chat должно ответить в течение 30 секунд, а ответ должен быть опубликован в пространстве, где произошло взаимодействие. В противном случае приложение Chat может ответить асинхронно.

Отвечать асинхронно

Иногда приложения чата должны реагировать на событие взаимодействия через 30 секунд или выполнять задачи за пределами пространства, в котором было создано событие взаимодействия. Например, приложению чата может потребоваться ответить пользователю после выполнения длительной задачи. В этом случае приложения чата могут реагировать асинхронно, вызывая API чата Google.

Чтобы создать сообщение с помощью Chat API, см. раздел Создание сообщения . Руководства по использованию дополнительных методов Chat API см. в обзоре Chat API .