Criar um app do Google Chat como um webhook

Esta página descreve como configurar um webhook para enviar mensagens assíncronas a um Espaço do Chat usando gatilhos externos. Por exemplo, é possível configurar um aplicativo de monitoramento para notificar os funcionários de plantão sobre Bata papo quando um servidor ficar inativo. Para enviar uma mensagem síncrona com um app do Chat, consulte Enviar uma mensagem.

Com esse tipo de arquitetura os usuários não podem interagir com o webhook ou com o servidor aplicativo porque a comunicação é unidirecional. Os webhooks não são de conversa. Eles não podem responder ou receber mensagens de usuários ou Eventos de interação com o app do Chat. Para responder às mensagens: criar um app do Chat em vez de um webhook.

Embora não seja tecnicamente um webhook em um app do Chat: os webhooks conectam aplicativos usando Solicitações HTTP. Esta página se refere a ele como um app de chat para simplificação. Cada webhook só funciona no espaço do Chat do em que ele está registrado. Os webhooks de entrada funcionam em mensagens diretas, mas apenas quando todos os usuários têm Apps do Chat ativados. Não é possível publicar webhooks no Google Workspace Marketplace.

O diagrama a seguir mostra a arquitetura de um webhook conectado Chat:

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

No diagrama anterior, um app do Chat tem o seguinte fluxo de informações:

  1. A lógica do app do Chat recebe informações serviços externos de terceiros, como um sistema de gerenciamento de projetos ferramenta de venda de ingressos.
  2. A lógica do app de chat é hospedada em uma nuvem ou que pode enviar mensagens usando um URL de webhook para um espaço específico do Chat.
  3. Os usuários podem receber mensagens do app do Chat em: esse espaço específico do Chat, mas não conseguem interagir com App Chat.

Pré-requisitos

Python

Node.js

Java

Apps Script

Criar um webhook

Para criar um webhook, registre-o no espaço do Chat. para receber mensagens e depois escreva um script que as envie.

Registrar o webhook de entrada

  1. Em um navegador, abra Chat. Não é possível configurar webhooks no app Chat para dispositivos móveis.
  2. Acesse o espaço onde você quer adicionar um webhook.
  3. Ao lado do título do espaço, clique no a seta para expandir mais e depois clique em Aplicativos e integrações.

  4. Clique em Add webhooks.

  5. No campo Nome, use Quickstart Webhook.

  6. No campo URL do avatar, digite https://developers.google.com/chat/images/chat-product-icon.png

  7. Clique em Salvar.

  8. Para copiar o URL do webhook, clique em Mais e clique em Copiar link.

Criar o script do webhook

O script de webhook de exemplo envia uma mensagem para o espaço em que o webhook está registrada enviando uma solicitação POST para o URL do webhook. A A API Chat responde com uma instância Message

Selecione uma linguagem para saber como criar um script de webhook:

Python

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

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

    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. Substitua o valor da variável url pelo URL do webhook que que você copiou ao registrar o webhook.

Node.js

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

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

    node/webhook/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. Substitua o valor da variável url pelo URL do webhook que que você copiou ao registrar o webhook.

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.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. No seu 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, cole o seguinte código:

    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. Substitua o valor da variável URL pelo URL do webhook que você copiado quando você registrou o webhook.

Apps Script

  1. Em um navegador, acesse Apps Script.

  2. Clique em New Project.

  3. Cole o seguinte código:

    apps-script/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. Substitua o valor da variável url pelo URL do webhook que você copiado quando você registrou o webhook.

Executar o script do webhook

Em uma CLI, execute o script:

Python

  python3 quickstart.py

Node.js

  node index.js

Java

  mvn compile exec:java -Dexec.mainClass=App

Apps Script

  • Clique em Executar.

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

Iniciar ou responder a uma conversa

  1. Especificar spaces.messages.thread.threadKey como parte do corpo da solicitação da mensagem. Dependendo se você está iniciando ou responder a uma conversa, use os seguintes valores para threadKey:

    • Ao iniciar uma linha de execução, defina threadKey como uma string arbitrária, mas anote esse valor para postar uma resposta na conversa.

    • Ao responder a uma conversa, especifique o threadKey que foi definido quando a thread foi iniciado. Por exemplo, para postar uma resposta à conversa em que o a mensagem inicial foi usada como MY-THREAD, defina MY-THREAD.

  2. Defina o comportamento da linha de execução se o threadKey especificado não for encontrado:

    • Responda a uma conversa ou inicie uma nova. Adicione o método messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD para o URL do webhook. Transmitir esse parâmetro de URL faz com que o Chat para procurar uma linha de execução existente usando o threadKey especificado. Se um deles for encontrada, a mensagem será postada como uma resposta a essa conversa. Se nenhum for encontrada, a mensagem inicia uma nova conversa correspondente à threadKey:

    • Responder a uma conversa ou não fazer nada. Adicione o método parâmetro messageReplyOption=REPLY_MESSAGE_OR_FAIL para o URL do webhook. Transmitir esse parâmetro de URL faz com que o Chat para procurar uma linha de execução existente usando o threadKey especificado. Se um deles for encontrada, a mensagem será postada como uma resposta a essa conversa. Se nenhum for for encontrada, a mensagem não será enviada.

    Para saber mais, consulte messageReplyOption.

O exemplo de código a seguir inicia ou responde a uma linha de execução de mensagens:

Python

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

node/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

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);
}