Создайте приложение Google Chat в качестве веб-перехватчика.

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

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

Хотя веб-перехватчик технически не является приложением чата — веб-перехватчики соединяют приложения с помощью стандартных HTTP-запросов — эта страница называет его приложением чата для упрощения. Каждый веб-перехватчик работает только в пространстве чата, в котором он зарегистрирован. Входящие веб-перехватчики работают в прямых сообщениях, но только когда у всех пользователей включены приложения чата . Вы не можете публиковать веб-перехватчики в Google Workspace Marketplace.

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

Архитектура входящих веб-хуков для отправки асинхронных сообщений в чат.

На предыдущей диаграмме приложение чата имеет следующий поток информации:

  1. Логика приложения «Чат» получает информацию от внешних сторонних сервисов, таких как система управления проектами или инструмент управления тикетами.
  2. Логика приложения чата размещается либо в облаке, либо в локальной системе, которая может отправлять сообщения с использованием URL-адреса веб-перехватчика в определенное пространство чата.
  3. Пользователи могут получать сообщения из приложения «Чат» в этом конкретном пространстве чата, но не могут взаимодействовать с приложением «Чат».

Предпосылки

Питон

Node.js

Ява

Скрипт приложений

Создать вебхук

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

Зарегистрировать входящий вебхук

  1. В браузере откройте Chat . Вебхуки не настраиваются из мобильного приложения Chat.
  2. Перейдите в область, куда вы хотите добавить вебхук.
  3. Рядом с заголовком пространства нажмите стрелку развернуть больше), а затем нажмите Приложения и интеграции .

  4. Нажмите вебхуки» .

  5. В поле Имя введите Quickstart Webhook .

  6. В поле URL-адрес аватара введите https://developers.google.com/chat/images/chat-product-icon.png .

  7. Нажмите «Сохранить» .

  8. Чтобы скопировать URL-адрес веб-перехватчика, нажмите Еще , а затем нажмите Копировать ссылку .

Написать скрипт вебхука

Пример скрипта webhook отправляет сообщение в пространство, в котором зарегистрирован webhook, отправляя запрос POST на URL-адрес webhook. API чата отвечает экземпляром Message .

Выберите язык, чтобы узнать, как создать скрипт вебхука:

Питон

  1. В рабочем каталоге создайте файл с именем quickstart.py .

  2. В quickstart.py вставьте следующий код:

    python/webhook/quickstart.py
    from json import dumps
from httplib2 import Http

# Copy the webhook URL from the Chat space where the webhook is registered.
# The values for SPACE_ID, KEY, and TOKEN are set by Chat, and are included
# when you copy the webhook URL.

def main():
    """Google Chat incoming webhook quickstart."""
    url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?key=KEY&token=TOKEN"
    app_message = {"text": "Hello from a Python script!"}
    message_headers = {"Content-Type": "application/json; charset=UTF-8"}
    http_obj = Http()
    response = http_obj.request(
        uri=url,
        method="POST",
        headers=message_headers,
        body=dumps(app_message),
    )
    print(response)


if __name__ == "__main__":
    main()

  3. Замените значение переменной url на URL-адрес веб-хука, скопированный при регистрации веб-хука.

Node.js

  1. В рабочем каталоге создайте файл с именем index.js .

  2. В index.js вставьте следующий код:

    узел/вебхук/index.js
    /**
 * Sends asynchronous message to Google Chat
 * @return {Object} response
 */
async function webhook() {
  const url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages"
  const res = await fetch(url, {
    method: "POST",
    headers: {"Content-Type": "application/json; charset=UTF-8"},
    body: JSON.stringify({text: "Hello from a Node script!"})
  });
  return await res.json();
}

webhook().then(res => console.log(res));

  3. Замените значение переменной url на URL-адрес веб-хука, скопированный при регистрации веб-хука.

Ява

  1. В рабочем каталоге создайте файл с именем pom.xml .

  2. В pom.xml скопируйте и вставьте следующее:

    java/webhook/pom.xml
    <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.google.chat.webhook</groupId>
  <artifactId>java-webhook-app</artifactId>
  <version>0.1.0</version>

  <name>java-webhook-app</name>
  <url>https://github.com/googleworkspace/google-chat-samples/tree/main/java/webhook</url>

  <properties>
    <maven.compiler.target>11</maven.compiler.target>
    <maven.compiler.source>11</maven.compiler.source>
  </properties>

  <dependencies>
    <dependency>
        <groupId>com.google.code.gson</groupId>
        <artifactId>gson</artifactId>
        <version>2.9.1</version>
    </dependency>
  </dependencies>

  <build>
    <pluginManagement>
      <plugins>
        <plugin>
          <artifactId>maven-compiler-plugin</artifactId>
          <version>3.8.0</version>
        </plugin>
      </plugins>
    </pluginManagement>
  </build>
</project>

  3. В рабочем каталоге создайте следующую структуру каталогов src/main/java .

  4. В каталоге src/main/java создайте файл с именем App.java .

  5. В App.java вставьте следующий код:

    java/webhook/src/main/java/com/google/chat/webhook/App.java
    import com.google.gson.Gson;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Map;
import java.net.URI;

public class App {
  private static final String URL = "https://chat.googleapis.com/v1/spaces/AAAAGCYeSRY/messages";
  private static final Gson gson = new Gson();
  private static final HttpClient client = HttpClient.newHttpClient();

  public static void main(String[] args) throws Exception {
    String message = gson.toJson(Map.of("text", "Hello from Java!"));

    HttpRequest request = HttpRequest.newBuilder(URI.create(URL))
      .header("accept", "application/json; charset=UTF-8")
      .POST(HttpRequest.BodyPublishers.ofString(message)).build();

    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

    System.out.println(response.body());
  }
}

  6. Замените значение переменной URL на URL-адрес веб-перехватчика, скопированный при регистрации веб-перехватчика.

Скрипт приложений

  1. В браузере перейдите в Apps Script .

  2. Нажмите «Новый проект».

  3. Вставьте следующий код:

    приложения-скрипт/webhook/webhook.gs
    function webhook() {
  const url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages"
  const options = {
    "method": "post",
    "headers": {"Content-Type": "application/json; charset=UTF-8"},
    "payload": JSON.stringify({"text": "Hello from Apps Script!"})
  };
  const response = UrlFetchApp.fetch(url, options);
  console.log(response);
}

  4. Замените значение переменной url на URL-адрес веб-хука, скопированный при регистрации веб-хука.

Запустить скрипт вебхука

В CLI запустите скрипт:

Питон 

  python3 quickstart.py

Node.js 

  node index.js

Ява 

  mvn compile exec:java -Dexec.mainClass=App

Скрипт приложений

  • Нажмите «Выполнить» .

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

Начать или ответить на цепочку сообщений

  1. Укажите spaces.messages.thread.threadKey как часть тела запроса сообщения. В зависимости от того, начинаете ли вы поток или отвечаете на него, используйте следующие значения для threadKey :

    • Если вы создаете тему, задайте для threadKey произвольную строку, но запишите это значение, чтобы опубликовать ответ в теме.

    • При ответе на ветку укажите threadKey , который был установлен при запуске ветки. Например, чтобы опубликовать ответ на ветку, где первоначальное сообщение использовало MY-THREAD , установите MY-THREAD .

  2. Определите поведение потока, если указанный threadKey не найден:

    • Ответить на поток или начать новый поток. Добавьте параметр messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD к URL-адресу веб-перехватчика. Передача этого параметра URL-адреса заставляет Chat искать существующий поток, используя указанный threadKey . Если он найден, то сообщение отправляется как ответ на этот поток. Если ничего не найдено, то сообщение начинает новый поток, соответствующий этому threadKey .

    • Ответить на поток или ничего не делать. Добавьте параметр messageReplyOption=REPLY_MESSAGE_OR_FAIL к URL-адресу веб-перехватчика. Передача этого параметра URL-адреса заставляет Chat искать существующий поток, используя указанный threadKey . Если он найден, то сообщение отправляется как ответ на этот поток. Если ничего не найдено, то сообщение не отправляется.

    Чтобы узнать больше, см. messageReplyOption .

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

Питон

python/webhook/thread-reply.py
from json import dumps
from httplib2 import Http

# Copy the webhook URL from the Chat space where the webhook is registered.
# The values for SPACE_ID, KEY, and TOKEN are set by Chat, and are included
# when you copy the webhook URL.
#
# Then, append messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD to the
# webhook URL.


def main():
    """Google Chat incoming webhook that starts or replies to a message thread."""
    url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?key=KEY&token=TOKEN&messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD"
    app_message = {
        "text": "Hello from a Python script!",
        # To start a thread, set threadKey to an arbitratry string.
        # To reply to a thread, specify that thread's threadKey value.
        "thread": {"threadKey": "THREAD_KEY_VALUE"},
    }
    message_headers = {"Content-Type": "application/json; charset=UTF-8"}
    http_obj = Http()
    response = http_obj.request(
        uri=url,
        method="POST",
        headers=message_headers,
        body=dumps(app_message),
    )
    print(response)


if __name__ == "__main__":
    main()

Node.js

узел/webhook/thread-reply.js
/**
 * Sends asynchronous message to Google Chat
 * @return {Object} response
 */
async function webhook() {
  const url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?key=KEY&token=TOKEN&messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD"
  const res = await fetch(url, {
    method: "POST",
    headers: {"Content-Type": "application/json; charset=UTF-8"},
    body: JSON.stringify({
      text: "Hello from a Node script!",
      thread: {threadKey: "THREAD_KEY_VALUE"}
    })
  });
  return await res.json();
}

webhook().then(res => console.log(res));

Скрипт приложений

apps-script/webhook/thread-reply.gs
function webhook() {
  const url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?key=KEY&token=TOKEN&messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD"
  const options = {
    "method": "post",
    "headers": {"Content-Type": "application/json; charset=UTF-8"},
    "payload": JSON.stringify({
      "text": "Hello from Apps Script!",
      "thread": {"threadKey": "THREAD_KEY_VALUE"}
    })
  };
  const response = UrlFetchApp.fetch(url, options);
  console.log(response);
}

Обработка ошибок

Запросы Webhook могут не выполняться по разным причинам, включая:

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

При создании веб-хука вам следует соответствующим образом обрабатывать ошибки:

API Google Chat возвращает ошибки как google.rpc.Status , который включает code ошибки HTTP, указывающий тип обнаруженной ошибки: ошибка клиента (серия 400) или ошибка сервера (серия 500). Чтобы просмотреть все сопоставления HTTP, см. google.rpc.Code . 

{
    "code": 503,
    "message": "The service is currently unavailable.",
    "status": "UNAVAILABLE"
}

Чтобы узнать, как интерпретировать коды состояния HTTP и обрабатывать ошибки, см. раздел Ошибки .

Ограничения и соображения

  • При создании сообщения с помощью вебхука в Google Chat API ответ не содержит полного сообщения. Ответ заполняет только поля name и thread.name .
  • На веб-перехватчики распространяется квота на пространство для spaces.messages.create : 1 запрос в секунду, общий для всех веб-перехватчиков в пространстве. Чат также может отклонять запросы веб-перехватчиков, которые превышают 1 запрос в секунду в том же пространстве. Для получения дополнительной информации о квотах API чата см. Ограничения использования .