Esta página descreve como configurar um webhook para enviar mensagens assíncronas em um espaço de chat usando gatilhos externos. Por exemplo, é possível configurar um aplicativo de monitoramento para notificar o pessoal de plantão no Chat quando um servidor falhar. Para enviar uma mensagem síncrona com um app de chat, consulte Enviar uma mensagem.
Com esse tipo de design de arquitetura, os usuários não podem interagir com o webhook ou com o aplicativo externo conectado porque a comunicação é unidirecional. Os webhooks não são de conversa. Eles não podem responder ou receber mensagens dos usuários ou eventos de interação do app 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 de chat, ele conecta aplicativos usando solicitações HTTP padrão. Para simplificar, esta página se refere a ele como um app de chat. Cada webhook só funciona 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 a opção 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:
No diagrama anterior, um app de chat tem o seguinte fluxo de informações:
- 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 criação de tíquetes.
- A lógica do app do Chat é hospedada em um sistema na nuvem ou no local que pode enviar mensagens usando um URL de webhook para um espaço do Chat específico.
- Os usuários podem receber mensagens do app do Chat nesse espaço específico do Chat, mas não podem interagir com ele.
Pré-requisitos
Python
- Uma conta do Google Workspace para empresas ou empresas 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 superior
- A ferramenta de gerenciamento de pacotes pip
A biblioteca
httplib2
. Para instalar a biblioteca, execute o seguinte comando na interface de linha de comando:pip install httplib2
Um espaço do Google Chat. Para criar um usando a API Google Chat, consulte Criar um espaço. Para criar uma no Chat, acesse a documentação da Central de Ajuda.
Node.js
- Uma conta empresarial ou corporativa do Google Workspace com acesso ao Google Chat. Sua organização do Google Workspace precisa permitir que os usuários adicionem e usem webhooks de entrada.
- Node.js 14 ou mais recente
- A ferramenta de gerenciamento de pacotes npm
- Um espaço do Google Chat. Para criar um usando a API Google Chat, consulte Criar um espaço. Para criar uma no Chat, acesse a documentação da Central de Ajuda.
Java
- Uma conta do Google Workspace para empresas ou empresas com acesso ao Google Chat. Sua organização do Google Workspace precisa permitir que os usuários adicionem e usem webhooks de entrada.
- Java 11 ou mais recente
- A ferramenta de gerenciamento de pacotes Maven
- Um espaço do Google Chat. Para criar um usando a API Google Chat, consulte Criar um espaço. Para criar uma no Chat, acesse a documentação da Central de Ajuda.
Apps Script
- Uma conta empresarial ou corporativa do Google Workspace com acesso ao Google Chat. Sua organização do Google Workspace precisa permitir que os usuários adicionem e usem webhooks de entrada.
- Crie um projeto autônomo do Apps Script e ative o serviço avançado de chat.
- Um espaço do Google Chat. 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.
Criar um webhook
Para criar um webhook, registre-o no espaço do Chat em que você quer receber mensagens e escreva um script que envie mensagens.
Registrar o webhook de entrada
- Em um navegador, abra o Chat. Não é possível configurar webhooks no app Chat para dispositivos móveis.
- Acesse o espaço onde você quer adicionar um webhook.
- Ao lado do título do espaço, clique na seta "Mostrar mais" e depois em Apps e integrações.
Clique em
Adicionar webhooks.No campo Nome, use
Quickstart Webhook
.No campo URL do avatar, digite
https://developers.google.com/chat/images/chat-product-icon.png
.Clique em Salvar.
Para copiar o URL do webhook, clique em
Mais e em Copiar link.
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 saber como criar um script de webhook:
Python
No diretório de trabalho, crie um arquivo chamado
quickstart.py
.Em
quickstart.py
, cole o seguinte código:Substitua o valor da variável
url
pelo URL do webhook que você copiou ao registrar o webhook.
Node.js
No diretório de trabalho, crie um arquivo chamado
index.js
.Em
index.js
, cole o seguinte código:Substitua o valor da variável
url
pelo URL do webhook que você copiou ao registrar o webhook.
Java
No diretório de trabalho, crie um arquivo chamado
pom.xml
.Em
pom.xml
, copie e cole o seguinte:No diretório de trabalho, crie a seguinte estrutura de diretório
src/main/java
.No diretório
src/main/java
, crie um arquivo chamadoApp.java
.Em
App.java
, cole o seguinte código:Substitua o valor da variável
URL
pelo URL do webhook que você copiou quando registrou o webhook.
Apps Script
Em um navegador, acesse o Apps Script.
Clique em New Project.
Cole o seguinte código:
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:
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 em que ele foi registrado.
Iniciar ou responder a uma conversa
Especifique
spaces.messages.thread.threadKey
como parte do corpo da solicitação de mensagem. Use os valores abaixo parathreadKey
, dependendo se você está iniciando ou respondendo a uma conversa:Se você iniciar uma linha de execução, defina
threadKey
como uma string arbitrária, mas anote esse valor para postar uma resposta à linha de execução.Se você estiver respondendo a uma conversa, especifique a
threadKey
que foi definida quando a conversa foi iniciada. Por exemplo, para postar uma resposta à conversa em que a mensagem inicial usouMY-THREAD
, definaMY-THREAD
.
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 parâmetro
messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD
ao URL do webhook. Transmitir esse parâmetro de URL faz com que o Chat procure uma linha de execução existente usando othreadKey
especificado. Se uma for encontrada, a mensagem será postada como uma resposta a essa conversa. Se nenhuma for encontrada, a mensagem iniciará uma nova linha de execução correspondente a essethreadKey
.Responda a uma conversa ou não faça nada. Adicione o parâmetro
messageReplyOption=REPLY_MESSAGE_OR_FAIL
ao URL do webhook. Transmitir esse parâmetro de URL faz com que o Chat procure uma linha de execução existente usando othreadKey
especificado. Se ela for encontrada, a mensagem será postada como uma resposta a essa conversa. Se nenhum for encontrado, 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 mensagens:
Python
Node.js
Apps Script
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, processe os erros corretamente:
- Registrar a falha.
- Para erros com base em tempo, cota ou conectividade de rede, tente fazer a solicitação novamente com espera exponencial.
- Não fazer nada, o que é apropriado se o envio da mensagem do webhook não for importante.
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 de cliente (série 400) ou um erro de servidor (série 500). Para
analisar 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 só preenche os campos
name
ethread.name
.