Receber e responder a interações do usuário

Esta página descreve como seu app do Google Chat pode receber e responder às interações dos usuários, também conhecidos como eventos de interação com o app Google Chat.

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 do Chat, o Google Chat envia um evento de interação para ele. O app do Chat pode usar o evento para processar a interação e criar uma resposta.

Por exemplo, os apps do Chat usam eventos de interação para:

Exemplo de um evento de interação 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. O app do Chat processa o que a mensagem diz para criar uma 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. 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. 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 ou caixa de diálogo enviado pelo app do Chat. O app do Chat processa e armazena todos os dados enviados pelo usuário ou retorna outro cartão ou caixa de diálogo.

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 corretamente. 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 do Chat a um espaço, para que o app do Chat possa processar uma resposta, como postar uma mensagem de boas-vindas no espaço. Para ver todos os eventos de interação compatíveis, consulte a documentação de referência do EventType.

Esta página explica como fazer o seguinte:

  • Configure seu app do Chat para receber eventos.
  • Processe o evento de interação na infraestrutura.
  • Se apropriado, responda aos eventos de interação.

Receber eventos de interação com o app do Chat

Esta seção descreve como receber e processar eventos de interação para seu app do Chat.

Configurar o app do Chat para receber eventos de interação

Nem todos os apps do Chat são interativos. Por exemplo, os webhooks de entrada só podem enviar mensagens de saída e não podem responder aos usuários. Se você estiver criando um app do Chat interativo, precisará escolher um endpoint que permita que o app do Chat 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.

Se você tiver criado um app de chat interativo, configure a API Google Chat para que ele possa enviar eventos de interação:

  1. No console do Google Cloud, abra a página da API Google Chat:

    Acessar a página da API Google Chat

  2. Clique na guia Configuração.
  3. Na seção Recursos interativos, clique no botão Ativar recursos interativos para ativar o recurso.
  4. Em Funcionalidade, marque uma ou as duas caixas de seleção a seguir:
    1. Receber mensagens individuais: permite que os usuários interajam com seu app do Chat em espaços de mensagens diretas. Seu app do Chat recebe eventos de interação sempre que um usuário envia uma mensagem no espaço de mensagens diretas.
    2. Participar de espaços e conversas em grupo: permite que os usuários adicionem e removam seu app do Chat de espaços com mais de uma pessoa. Seu app do Chat recebe eventos de interação sempre que é adicionado ou removido do espaço e sempre que os usuários @mencionam ou usam um comando de barra no espaço.
  5. Em Configurações de conexão, especifique para onde o Google Chat envia os eventos de interação com o app do Chat.
  6. Opcional: nos comandos de barra, adicione e configure um ou mais comandos de barra. Para mais informações, consulte Configurar comandos de barra.
  7. Opcional: em Visualizações de links, adicione e configure um ou mais padrões de URL que vão aparecer pelo app do Chat. Para mais informações, consulte Visualizar links.
  8. Clique em Salvar.

Seu app do Chat agora está configurado para receber eventos de interação do Google Chat.

Processar novas tentativas de chamadas HTTP para o serviço

Se uma solicitação HTTPS para seu serviço falhar, como tempo limite, falha de rede temporária ou código de status HTTPS que não seja 2xx, o Google Chat poderá tentar a entrega algumas vezes em alguns minutos, mas isso não é garantido. Como resultado, um app do 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 tentará fazer a solicitação novamente.

Processar ou responder a eventos de interação

Nesta seção, explicamos 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 interativos 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 cada evento de interação, os apps do Chat recebem um corpo da 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:

Arquitetura de como os apps do Google Chat processam eventos de interação.

Resposta em tempo real

Com os eventos de interação, os apps do Chat podem responder em tempo real ou de maneira síncrona. As respostas síncronas não exigem autenticação.

Para criar respostas síncronas a eventos de interação, consulte os seguintes guias:

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.

Responder de forma assíncrona

Às vezes, os apps do 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 ver guias sobre como usar outros métodos da API Chat, consulte a Visão geral da API Chat.