Esta página descreve como o app Google Chat pode receber e responder às interações do usuário, também conhecidas como eventos de interação do app Google Chat.
Esta página explica como fazer o seguinte:
- Configure o app do Chat para receber eventos de interação.
- Processe o evento de interação na infraestrutura.
- Se apropriado, responda a eventos de interação.
Pré-requisitos
Um app do Google Chat que tenha recursos interativos ativados. Para criar um app de chat interativo, conclua um dos guias de início rápido a seguir com base na arquitetura do app que você quer usar:
- Serviço HTTP com o Google Cloud Functions
- Google Apps Script
- Dialogflow CX do Google Cloud
- Google Cloud Pub/Sub
Tipos de eventos de interação
Um evento de interação do app do Google Chat representa qualquer ação que um usuário realiza para invocar ou interagir com um app do Chat, como @mencionar um app do Chat ou adicioná-lo a um espaço.
Quando os usuários interagem com um app Chat,
o Google Chat envia um evento de interação,
representado como um tipo
Event
na
API Chat. O app do Chat pode usar o evento para processar a interação e, opcionalmente, responder com uma mensagem.
Para cada tipo de interação do usuário, o Google Chat envia um tipo diferente de evento de interação, o que ajuda o app do Chat a processar cada tipo de evento adequadamente. O tipo de evento de interação é representado usando o objeto
eventType
.
Por exemplo, o Google Chat usa o tipo de evento
ADDED_TO_SPACE
para qualquer interação em que um usuário adiciona o
app Chat a um espaço. Assim, o
app Chat pode responder imediatamente com uma mensagem de boas-vindas
no espaço.
A tabela a seguir mostra interações comuns do usuário, o tipo de evento de interação que os apps de chat recebem e como eles geralmente respondem:
Interação do usuário | eventType |
Resposta típica de um app do Chat |
---|---|---|
Um usuário invoca um app do Chat ao @mencioná-lo ou usando um comando de barra. | MESSAGE |
O
app de chat responde com base no conteúdo da
mensagem. Por exemplo, um app do Chat responde ao comando /about com uma mensagem explicando as tarefas que ele pode realizar. |
Um usuário adiciona um app do Chat a um espaço. | ADDED_TO_SPACE |
O app do Chat envia uma mensagem de integração que explica o que ele faz e como os usuários no espaço podem interagir com ele. |
Um usuário remove um app do Chat de um espaço. | REMOVED_FROM_SPACE |
O app do Chat remove todas as notificações recebidas configuradas para o espaço (como excluir um webhook) e limpa qualquer armazenamento interno. |
Um usuário clica em um botão em um card de uma mensagem, caixa de diálogo ou página inicial do app do Chat. | CARD_CLICKED |
O app do Chat processa e armazena todos os dados enviados pelo usuário ou retorna outro cartão. |
Um usuário abre a página inicial do app do Chat clicando na guia Início em uma mensagem individual. | APP_HOME |
O app do Chat retorna um card estático ou interativo da página inicial. |
Um usuário envia um formulário da página inicial do app Chat. | SUBMIT_FORM |
O app do Chat processa e armazena todos os dados enviados pelo usuário ou retorna outro cartão. |
Para ver todos os eventos de interação compatíveis, consulte a
documentação de referência do
EventType
.
Eventos de interação de caixas de diálogo
Se o app do Chat abrir caixas de diálogo, o evento de interação conterá as seguintes informações extras que podem ser usadas para processar uma resposta:
- O elemento
isDialogEvent
é definido comotrue
. - O
DialogEventType
esclarece se a interação aciona a abertura de uma caixa de diálogo, envia informações de uma caixa de diálogo ou fecha uma caixa de diálogo.
A tabela a seguir mostra as interações comuns com caixas de diálogo, os tipos de evento de caixa de diálogo correspondentes e uma descrição de como os apps de chat normalmente respondem:
Interação do usuário com uma caixa de diálogo | Tipo de evento da caixa de diálogo | Resposta típica |
---|---|---|
Um usuário aciona uma solicitação de caixa de diálogo. Por exemplo, eles usam um comando de barra ou clicam em um botão de uma mensagem. | REQUEST_DIALOG |
O app Chat abre a caixa de diálogo. |
Um usuário envia informações na caixa de diálogo clicando em um botão. | SUBMIT_DIALOG |
O app de chat navega para outra caixa de diálogo ou a fecha para concluir a interação. |
Um usuário fecha ou fecha a caixa de diálogo antes de enviar informações. | CANCEL_DIALOG |
Opcionalmente, o app de chat pode responder com uma nova mensagem ou atualizar a mensagem ou o card em que o usuário abriu a caixa de diálogo. |
Para mais informações, consulte Abrir caixas de diálogo interativas.
Receber eventos de interação com o app Chat
Esta seção descreve como receber e processar eventos de interação para seu app de chat.
Configurar o app do Chat para receber eventos de interação
Nem todos os apps de chat são interativos. Por exemplo, webhooks de entrada só podem enviar mensagens de saída e não podem responder aos usuários. Se você estiver criando um app de chat interativo, escolha um endpoint que permita que o app receba, processe e responda a eventos de interação. Para saber mais sobre como projetar seu app do Chat, consulte Arquiteturas de implementação de apps do Chat.
Para cada um dos recursos interativos que você quer criar, atualize a configuração na API Chat para que o Google Chat possa enviar eventos de interação relacionados ao app do Chat:
No console do Google Cloud, acesse a página da API Chat e clique na página Configuração:
Em Recursos interativos, revise as configurações e atualize com base nos recursos que você quer criar:
Campo Descrição Funcionalidade Obrigatório. Um conjunto de campos que determinam como o app do Chat pode interagir com os usuários: - Receber mensagens individuais: os usuários podem encontrar e enviar mensagens para o app Chat diretamente no Google Chat.
- Participar de espaços e conversas em grupo: os usuários podem adicionar o app Chat a espaços e conversas em grupo.
Configurações de conexão Obrigatório. O endpoint do app Chat, que é um dos seguintes: - URL do endpoint HTTP: um endpoint HTTPS que hospeda a implementação do app Chat.
- Apps Script: um ID de implantação para um projeto do Apps Script que implementa um app do Chat.
- Nome do tópico do Cloud Pub/Sub: um tópico do Pub/Sub em que o app Chat se inscreve como um endpoint.
- Dialogflow: registra o app do Chat com uma integração com o Dialogflow. Para mais informações, consulte Criar um app do Google Chat para Dialogflow que entenda a linguagem natural.
Comandos de barra Opcional. Comandos que podem ser exibidos aos usuários no Google Chat. Permite que os usuários vejam as principais ações do seu app de chat no Google Chat e escolham uma ação específica para interagir. Para mais informações, consulte Responder a comandos de barra como um app do Chat. Visualizações de links Opcional. Padrões de URL que o app de chat reconhece e fornece mais conteúdo para quando os usuários enviam links. Para mais informações, consulte Link de visualização. Visibilidade Opcional. Até cinco pessoas ou um ou mais Grupos do Google podem acessar e instalar o app do Chat. Use este campo para testar o app do Chat ou compartilhar o app com sua equipe. Para mais informações, consulte Testar recursos interativos. Clique em Salvar. Quando você salva a configuração do app Chat, ele fica disponível para os usuários especificados na sua organização do Google Workspace.
Seu app do Chat agora está configurado para receber eventos de interação do Google Chat.
Processar novas tentativas de chamada HTTP para seu serviço
Se uma solicitação HTTPS para seu serviço falhar (como um tempo limite, falha temporária de rede ou um código de status HTTPS diferente de 2xx), o Google Chat poderá tentar o envio algumas vezes em poucos minutos, mas isso não é garantido. Como resultado, um app de chat pode receber a mesma mensagem algumas vezes em determinadas situações. Se a solicitação for concluída, mas retornar um payload de mensagem inválido, o Google Chat não vai tentar novamente.
Processar ou responder a eventos de interação
Esta seção explica como os apps do Google Chat podem processar e responder a eventos de interação.
Depois que o app do Chat recebe um evento de interação do Google Chat, ele pode responder de várias maneiras. Em muitos casos, os apps de chat interativo respondem ao usuário com uma mensagem. O app do Google Chat também pode pesquisar algumas informações em uma fonte de dados, registrar as informações do evento de interação ou qualquer outra coisa. Esse comportamento de processamento é essencialmente o que define o app do Google Chat.
Para responder de forma síncrona, um app do Chat precisa responder em 30 segundos, e a resposta precisa ser postada no espaço em que a interação ocorreu. Caso contrário, o app do Chat poderá responder de forma assíncrona.
Para cada evento de interação, os apps do Chat recebem um corpo de solicitação, que é o payload JSON que representa o evento. É possível usar essas informações para processar uma resposta. Para ver exemplos de payloads de eventos, consulte Tipos de eventos de interação com apps do Chat.
O diagrama a seguir demonstra como o app do Google Chat normalmente processa ou responde a diferentes tipos de eventos de interação:
Resposta em tempo real
Os eventos de interação permitem que os apps do Chat respondam em tempo real ou simultaneamente. As respostas síncronas não exigem autenticação.
Para responder em tempo real, o app de chat precisa retornar um
objeto Message
. Para
responder com uma mensagem no espaço, o objeto Message
pode
conter objetos text
, cardsV2
e accessoryWidgets
. Para usar com outros
tipos de respostas, consulte estes guias:
- Abrir caixas de diálogo interativas
- Links de visualização
- Processar informações enviadas pelos usuários
Enviar uma mensagem
Neste exemplo, o app do Chat cria e envia uma mensagem de texto sempre que é adicionado a um espaço. Para saber mais sobre as práticas recomendadas de integração de usuários, consulte Apresentar o app do Chat aos usuários.
Para enviar uma mensagem de texto quando um usuário adiciona seu app do Chat
a um espaço, o app
responde a um evento de interação
ADDED_TO_SPACE
. Para responder a
eventos de interação ADDED_TO_SPACE
com uma mensagem de texto, use o seguinte código:
Node.js
/**
* Sends an onboarding message when the Chat app is added to a space.
*
* @param {Object} req The event object from Chat API.
* @param {Object} res The response object from the Chat app. An onboarding message that
* introduces the app and helps people get started with it.
*/
exports.onMessage = function onMessage(req, res) {
if (req.method === 'GET' || !req.body.message) {
res.send(
'Hello! This function is meant to be used in a Google Chat space.');
}
// Send an onboarding message when added to a Chat space
if (req.body.type === 'ADDED_TO_SPACE') {
res.json({
'text': 'Hi, Cymbal at your service. I help you manage your calendar
from Google Chat. Take a look at your schedule today by typing
`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To
learn what else I can do, type `/help`.'
});
}
};
Apps Script
/**
* Sends an onboarding message when the Chat app is added to a space.
*
* @param {Object} event The event object from Chat API.
* @return {Object} Response from the Chat app. An onboarding message that
* introduces the app and helps people get started with it.
*/
function onAddToSpace(event) {
return {
'text': 'Hi, Cymbal at your service. I help you manage your calendar
from Google Chat. Take a look at your schedule today by typing
`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn
what else I can do, type `/help`.'
}
}
O exemplo de código retorna a seguinte mensagem de texto:
Responder de forma assíncrona
Às vezes, os apps de chat precisam responder a um evento de interação após 30 segundos ou realizar tarefas fora do espaço em que o evento de interação foi gerado. Por exemplo, um app do Chat pode precisar responder ao usuário depois de concluir uma tarefa de longa duração. Nesse caso, os apps do Chat podem responder de forma assíncrona chamando a API Google Chat.
Para criar uma mensagem usando a API Chat, consulte Criar uma mensagem. Para guias sobre como usar outros métodos da API Chat, consulte a Visão geral da API Chat.
Temas relacionados
- Enviar uma mensagem
- Abrir caixas de diálogo interativas
- Visualizar vinculações
- Ler a entrada de dados de formulário pelos usuários em cards
- Responder a comandos de barra
- Criar uma página inicial para um app do Chat
- Verificar solicitações do Chat
- Testar recursos interativos para apps do Google Chat