Criar um app do Google Chat como um webhook

Esta página descreve como configurar um webhook para enviar mensagens assíncronas para um espaço do Chat usando acionadores externos. Por exemplo, é possível configurar um aplicativo de monitoramento para notificar o pessoal de plantão no Chat quando um servidor ficar inativo. Para enviar uma mensagem síncrona com um app do Chat, consulte Enviar uma mensagem.

Com esse tipo de design de arquitetura, os usuários não podem interagir com o webhook ou o aplicativo externo conectado porque a comunicação é unidirecional. Os webhooks não são conversacionais. Eles não podem responder nem receber mensagens de usuários ou eventos de interação de apps do Chat. Para responder a mensagens, crie um app do Chat em vez de um webhook.

Embora um webhook não seja tecnicamente um app do Chat (os webhooks conectam aplicativos usando solicitações HTTP padrão), esta página se refere a ele como um app do Chat para simplificação. Cada webhook funciona apenas no espaço do Chat em que 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 ao Chat:

Arquitetura para webhooks de entrada que enviam 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 de serviços externos de terceiros, como um sistema de gerenciamento de projetos ou uma ferramenta de emissão de tickets.
  2. A lógica do app do Chat é hospedada em um sistema na nuvem ou local 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 nesse espaço específico do Chat, mas não podem interagir com o app do Chat.

Pré-requisitos

Node.js

Python

  • Uma conta do Google Workspace Business ou Enterprise com acesso ao Google Chat. Sua organização do Google Workspace precisa permitir que os usuários adicionem e usem webhooks de entrada.
  • Python 3.6 ou mais recente
  • A ferramenta de gerenciamento de pacotes pip

  • A biblioteca httplib2. Para instalar a biblioteca, execute o comando a seguir na interface de linha de comando:

    pip install httplib2

  • Um espaço do Chat do Google. Para criar um usando a API Google Chat, consulte Criar um espaço. Para criar um no Chat, acesse a documentação da Central de Ajuda.

Java

Apps Script

Criar um webhook

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

Registrar o webhook de entrada

  1. Em um navegador, abra o Chat. Os webhooks não podem ser configurados no app Chat para dispositivos móveis.
  2. Acesse o espaço em que você quer adicionar um webhook.
  3. Ao lado do título do espaço, clique na seta expandir mais e em Apps e integrações.

  4. Clique em Adicionar webhooks.

  5. No campo Nome, insira Quickstart Webhook.

  6. No campo URL do avatar, insira 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 em Copiar link.

    O URL do webhook contém dois parâmetros: key, um valor comum compartilhado entre webhooks, e token que é um valor exclusivo que precisa ser mantido em segredo para preservar a segurança do webhook.

Escrever o script do webhook

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

Selecione um idioma para aprender a criar um script de webhook:

Node.js

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

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

    solutions/webhook-chat-app/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?key=KEY&token=TOKEN"
  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 você copiou ao registrar o webhook.

Python

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

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

    solutions/webhook-chat-app/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 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:

    solutions/webhook-chat-app/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>webhook-app</artifactId>
  <version>0.1.0</version>
  <name>webhook-app</name>

  <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ório 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:

    solutions/webhook-chat-app/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/SPACE_ID/messages?key=KEY&token=TOKEN";
  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 ao registrar o webhook.

Apps Script

  1. Em um navegador, acesse o Apps Script.

  2. Clique em Novo projeto.

  3. Cole o seguinte código:

    solutions/webhook-chat-app/webhook.gs
    function webhook() {
  const url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?key=KEY&token=TOKEN"
  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ê copiou ao registrar o webhook.

Executar o script do webhook

Em uma CLI, execute o script:

Node.js

  node index.js

Python

  python3 quickstart.py

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 em que você o registrou.

Iniciar ou responder a uma conversa

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

    • Se você estiver iniciando uma conversa, defina o threadKey como uma string arbitrária, mas anote esse valor para postar uma resposta na conversa.

    • Se você estiver respondendo a uma conversa, especifique o threadKey definido quando a conversa foi iniciada. Por exemplo, para postar uma resposta na conversa em que a mensagem inicial usou MY-THREAD, defina MY-THREAD.

  2. Defina o comportamento da conversa se o threadKey especificado não for encontrado:

    • Responda a uma conversa ou inicie uma nova. Adicione o parâmetro messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD ao URL do webhook. A transmissão desse parâmetro de URL faz com que o Chat procure uma conversa usando o threadKey especificado. Se uma conversa for encontrada, a mensagem será postada como uma resposta a ela. Se nenhuma for encontrada, a mensagem iniciará uma nova conversa correspondente a esse threadKey.

    • Responda a uma conversa ou não faça nada. Adicione o parâmetro messageReplyOption=REPLY_MESSAGE_OR_FAIL ao URL do webhook. A transmissão desse parâmetro de URL faz com que o Chat procure uma conversa usando o threadKey especificado. Se uma conversa for encontrada, a mensagem será postada como uma resposta a ela. Se nenhuma 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 conversa:

Node.js

solutions/webhook-chat-app/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));

Python

solutions/webhook-chat-app/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()

Java

solutions/webhook-chat-app/src/main/java/com/google/chat/webhook/AppThread.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/SPACE_ID/messages?key=KEY&token=TOKEN&messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD";
  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!",
      "thread", Map.of(
        "threadKey", "THREAD_KEY_VALUE"
      )
    ));

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

Apps Script

solutions/webhook-chat-app/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);
}

Solucionar erros

As solicitações de webhook podem falhar por vários motivos, incluindo:

  • Solicitação inválida.
  • O webhook ou o espaço que hospeda o webhook é excluído.
  • Problemas intermitentes, como conectividade de rede ou limites de cota.

Ao criar o webhook, você precisa processar os erros de maneira adequada:

A API Google Chat retorna erros como um google.rpc.Status, que inclui um erro HTTP code que indica o tipo de erro encontrado: um erro do cliente (série 400) ou um erro do servidor (série 500). Para revisar todos os mapeamentos HTTP, consulte google.rpc.Code.

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

Para saber como interpretar códigos de status HTTP e processar erros, consulte Erros.

Limitações e considerações

  • Ao criar uma mensagem com um webhook na API Google Chat, a resposta não contém a mensagem completa. A resposta preenche apenas os campos name e thread.name.
  • Os webhooks estão sujeitos à cota por espaço para spaces.messages.create: 1 solicitação por segundo, compartilhada entre todos os webhooks no espaço. O Chat também pode rejeitar solicitações de webhook que excedam 1 consulta por segundo no mesmo espaço. Para mais informações sobre as cotas da API Chat, consulte Limites de uso.