Enviar mensagens para o Google Chat com webhooks de entrada

Os webhooks de entrada permitem o envio de mensagens assíncronas para o Google Chat a partir de aplicativos que não são do Chat. Por exemplo, é possível configurar um aplicativo de monitoramento para notificar a equipe de plantão no Google Chat quando um servidor ficar inativo.

Para enviar, atualizar ou excluir de forma assíncrona uma mensagem em um espaço do Chat com um app Chat, consulte Criar, ler, atualizar e excluir mensagens.

Arquitetura para webhooks de entrada para enviar mensagens assíncronas ao Google Chat.

Pré-requisitos

Para executar o exemplo deste guia, você precisa de:

Python

  • Python 3.10.7 ou superior
  • Acesso à Internet e a um navegador da Web.
  • Uma conta do Google Workspace com acesso ao Google Chat.
  • Um espaço do Google Chat.

  • A biblioteca httplib2. Se necessário, execute o seguinte comando da interface de linha de comando (CLI, na sigla em inglês) para instalar a biblioteca usando o pip:

    pip install httplib2

Node.js

Apps Script

Java

Criar um webhook

Para criar um webhook, registre-o no espaço do Google Chat em que você quer receber mensagens e escreva um script que envie mensagens.

Etapa 1: registrar o webhook de entrada

  1. Em um navegador da Web, abra o Google Chat.
  2. Acesse o espaço a que você quer adicionar um webhook.
  3. Na parte superior, ao lado do título do espaço, clique na seta para baixo > Apps e integrações.
  4. Clique em Gerenciar webhooks.
  5. Se este espaço já tiver outros webhooks, clique em Adicionar outro. Caso contrário, pule esta etapa.
  6. Em Nome, insira "Quickstart Webhook".
  7. Em URL do avatar, insira https://developers.google.com/chat/images/chat-product-icon.png.
  8. Selecione SALVAR.
  9. Para copiar o URL completo do webhook, clique em Copiar.
  10. Clique fora da caixa para fechar a caixa de diálogo "Webhooks de entrada".

Etapa 2: gravar o script do webhook

O script de webhook de exemplo publica uma mensagem no espaço em que o webhook é registrado enviando uma solicitação create message para o URL do webhook. A API Google Chat responde com uma instância de Message.

Escolha uma linguagem abaixo para instruções específicas sobre como criar o script do webhook:

Python

  1. No diretório de trabalho, crie um arquivo chamado quickstart.py.

  2. Em quickstart.py, copie e cole o seguinte código:

    python/webhook/quickstart.py
    from json import dumps

from httplib2 import Http

WEBHOOK_URL = "[URL FROM WEBHOOK]"

def main():
    """Google Chat incoming webhook quickstart."""
    url = WEBHOOK_URL
    bot_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(bot_message),
    )
    print(response)


if __name__ == '__main__':
    main()

  3. Substitua o valor da variável url pelo URL do webhook que você copiou na Etapa 1: registrar o webhook de entrada.

Node.js

  1. No diretório de trabalho, crie um arquivo chamado index.js.

  2. Em index.js, copie e cole o seguinte código:

    node/webhook/index.js
    /**
 * Sends asynchronous message into Google Chat
 * @return{obj} response
 */
function webhook() {
  const fetch = require('node-fetch');
  const webhookURL = 'https://chat.googleapis.com/v1/spaces/AAAAGCYeSRY/messages?key=AIzaSyDdI0hCZtE6vySjMm-WEfRq3CPzqKqqsHI&token=u9IG_MuTBXw-tnqupPrPNinY2spKFcRBDp6dSldGUAw%3D';

  const data = JSON.stringify({
    'text': 'Hello from a Node script!',
  });
  let resp;
  fetch(webhookURL, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json; charset=UTF-8',
    },
    body: data,
  }).then((response) => {
    resp = response;
    console.log(response);
  });
  return resp;
}

  3. Substitua o valor da variável webhookURL pelo URL do webhook que você copiou na Etapa 1: registrar o webhook de entrada.

Apps Script

  1. Acesse a página do Apps Script.

  2. Clique em Novo projeto.

  3. Copie e cole o seguinte código:

    apps-script/webhook/webhook.gs
    function webhook() {
  const url = "https://chat.googleapis.com/v1/spaces/AAAAGCYeSRY/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);
  Logger.log(response);
}

  4. Substitua o valor da variável url pelo URL do webhook que você copiou na Etapa 1: registrar o webhook de entrada.

Java

  1. No diretório de trabalho, crie um arquivo chamado pom.xml.

  2. Em pom.xml, copie e cole o seguinte:

    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.hangouts.chat.webhook</groupId>
  <artifactId>java-webhook-app</artifactId>
  <version>0.1.0</version>

  <name>java-webhook-app</name>
  <url>https://github.com/googleworkspace/hangouts-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. No diretório de trabalho, crie a seguinte estrutura de diretórios: src/main/java.

  4. No diretório src/main/java, crie um arquivo chamado App.java.

  5. Em App.java, copie e cole o seguinte código:

    java/webhook/src/main/java/com/google/hangouts/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. Substitua o valor da variável URL pelo URL do webhook que você copiou na Etapa 1: registrar o webhook de entrada.

Etapa 3: executar o script do webhook

Execute o exemplo a seguir executando o seguinte comando no diretório de trabalho na CLI:

Python

  python3 quickstart.py

Node.js

  node index.js

Apps Script

  • Clique em Executar.

Java

  mvn compile exec:java -Dexec.mainClass=App

Quando você executa o código de amostra, o webhook envia uma mensagem para o espaço em que você o registrou.

Iniciar ou responder a uma conversa

Para iniciar uma conversa ou responder a uma mensagem, adicione o parâmetro threadKey ao URL do webhook. Cada threadKey é exclusivo para o app que o define. Se dois apps de chat ou webhooks diferentes definirem o mesmo threadKey, duas linhas de execução diferentes serão iniciadas.

Iniciar uma conversa

Para postar a primeira mensagem de uma linha de execução com um webhook, anexe os parâmetros threadKey e messageReplyOption ao URL do webhook. Defina a threadKey como uma string arbitrária, mas lembre-se dela. Você precisará especificá-la novamente para postar uma resposta na linha de execução.

  https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?threadKey=ARBITRARY_STRING&messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD

Responder a uma conversa

Para enviar uma mensagem a uma conversa atual, anexe os parâmetros threadKey e messageReplyOption ao URL do webhook definido com o valor usado para iniciar a linha. Por exemplo, o envio de uma mensagem ao URL a seguir posta uma resposta na conversa em que threadKey é MY-THREAD e messageReplyOption é REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD:

  https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?threadKey=MY-THREAD&messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD

Limites e considerações

Ao configurar webhooks, observe estes limites e considerações:

  • Cada webhook funciona apenas no espaço do Chat em que está registrado.

  • Não é possível publicar webhooks no Google Workspace Marketplace.

  • Os webhooks não são interativos. Eles não podem responder ou receber mensagens de usuários ou eventos do Google Chat.

  • Se apenas unidades organizacionais (UOs) no seu domínio tiverem apps de chat ativados, os webhooks de entrada retornarão o seguinte erro:

    {
  "error": {
    "code": 403,
    "message": "The caller does not have permission",
    "status": "PERMISSION_DENIED"
  }
}

  • Os webhooks de entrada funcionam em mensagens diretas, mas apenas quando todos os usuários têm apps de chat ativados.

  • Como o O ícone para gerenciar webhooks Gerenciar webhooks está disponível apenas em um navegador da Web, os webhooks precisam ser configurados no app Chat para Web. Não é possível configurar os webhooks no app Chat para dispositivos móveis.