Criar interfaces do Google Chat

Esta página oferece uma visão geral de como criar interfaces de usuário (IU) para complementos do Google Workspace que ampliam o Google Chat.

Para criar interfaces para apps do Chat, use os seguintes componentes de complemento:

  • Gatilhos: as maneiras como os usuários do Google Chat podem invocar um app do Chat, como adicionar a um espaço ou enviar uma mensagem.
  • Objetos de evento: os dados que os apps de chat recebem de acionadores ou interações da interface.
  • Ações: as maneiras como os apps de chat podem responder a interações, como enviar mensagens ou retornar uma interface de usuário baseada em cards.
O app Chat recebe um objeto de evento de um acionador "Adicionado ao espaço"
Figura 1: quando um usuário adiciona um app do Chat a um espaço, o gatilho Adicionado ao espaço é acionado e envia um objeto de evento. Para responder com uma mensagem, o app Chat processa o objeto de evento e retorna uma ação que cria a mensagem.

Os apps de chat podem criar e mostrar cards nas seguintes interfaces:

  • Mensagens que podem conter texto, cards estáticos ou interativos e botões.
  • Caixas de diálogo, que são cards abertos em uma nova janela e geralmente pedem que os usuários enviem informações.
  • Visualizações de links, que são cards que mostram informações sobre um serviço externo.

Gatilhos

Nesta seção, explicamos os gatilhos usados pelos complementos do Google Workspace no Chat.

Os gatilhos são as maneiras específicas que os usuários invocam um app do Chat usando a interface do Chat, como @menções ou comandos de apps.

A tabela a seguir mostra os gatilhos do Chat, uma descrição e como os apps do Chat normalmente respondem:

Gatilho Descrição Resposta típica
Adicionado ao espaço

Um usuário adiciona o app do Chat a um espaço ou um administrador do Google Workspace instala o app do Chat em espaços de mensagens diretas para usuários da organização. Para saber mais sobre os apps do Chat instalados por administradores, consulte Instalar apps do Marketplace no seu domínio na documentação da Central de Ajuda do Admin do Google Workspace.

 O app Chat envia uma mensagem de integração explicando o que ele faz e como os usuários do espaço podem interagir com ele.
Mensagem

Um usuário interage com o app Chat em uma mensagem de uma das seguintes maneiras:

  • Envia uma mensagem em um espaço de mensagem direta (DM) com o app do Chat.
  • @menciona o app do Chat em qualquer tipo de espaço.
  • Envia uma mensagem com um link que corresponde ao padrão de URL para visualizações de link.
  • Digita texto no menu de seleção múltipla de um widget selectionInput.
 O app Chat responde com base no conteúdo da mensagem. Por exemplo, um app do Chat responde ao comando de barra /about com uma mensagem que explica as tarefas que ele pode realizar.
Removido do espaço

Um usuário remove o app Chat de um espaço ou um administrador do Google Workspace desinstala o app Chat para um usuário na organização.

Os usuários não podem remover apps do Chat instalados pelo administrador. Se um usuário já tiver instalado o app Chat, ele permanecerá instalado, mesmo que um administrador do Google Workspace tente desinstalar.

 O app Chat remove todas as notificações recebidas configuradas para o espaço (como a exclusão de um webhook) e limpa qualquer armazenamento interno. Os apps de chat não podem responder com mensagens a esse gatilho porque não são mais participantes do espaço.
Comando do app

Um usuário usa um comando do app Chat.

 O app Chat responde ao comando. Por exemplo, respostas com uma mensagem ou abertura de uma caixa de diálogo.

Ao contrário de outros complementos do Google Workspace, é necessário configurar as funções de callback para esses gatilhos usando a API Google Chat. Para orientações, consulte Configurar um app do Google Chat.

Para responder a um gatilho, consulte os seguintes guias:

Objetos de evento

Os apps de chat recebem objetos de evento quando um gatilho do Chat é acionado ou quando os usuários do Chat interagem com uma interface do app (por exemplo, clicando em um botão). O objeto de evento contém dados sobre a interação que o app Chat pode usar para responder ou atualizar uma interface.

Para saber como processar objetos de evento, consulte os seguintes guias:

Para saber mais sobre objetos de evento de complementos no Chat e em outros aplicativos do Google Workspace, consulte Objetos de evento.

Ações no chat

Esta seção explica como os apps do Chat podem usar ações de complemento para responder às interações do usuário.

Para responder com uma ação de complemento, um app do Chat precisa responder em até 30 segundos, e a resposta precisa ser postada no espaço em que a interação ocorreu. Caso contrário, o app do Chat precisa configurar a autenticação e chamar a API Google Chat para responder.

Os apps de chat podem processar e responder a interações de várias maneiras. Em muitos casos, os apps do Chat respondem com uma mensagem. Os apps de chat também podem pesquisar algumas informações em uma fonte de dados, registrar as informações do objeto de evento ou fazer quase qualquer outra coisa. Esse comportamento de processamento é essencialmente o que define o app do Google Chat.

Para responder às interações do usuário, os apps de chat precisam processar o objeto de evento correspondente e retornar um dos seguintes objetos JSON:

Resposta do app de chat Ação necessária para devolução
Enviar ou atualizar uma mensagem. DataActions
Abra, atualize ou feche uma caixa de diálogo. RenderActions
Para coletar informações de um card ou caixa de diálogo, sugira itens de seleção com base no que os usuários digitam em um menu de seleção múltipla. RenderActions
Visualizar links em mensagens enviadas por usuários do Chat em um espaço. DataActions

Responder usando a API Google Chat

Em vez de retornar uma ação de complemento, os apps do Chat podem precisar usar a API Google Chat para responder a uma interação. Por exemplo, os apps do Chat precisam chamar a API Google Chat para fazer qualquer uma das seguintes ações:

  • Responder a uma interação após 30 segundos.
  • Realizar tarefas fora do espaço em que a interação ocorreu.
  • Realizar tarefas no Chat que não estão disponíveis como ações de complemento. Por exemplo, liste os espaços de que um usuário ou app do Chat participa ou adicione usuários a um espaço.
  • Realizar tarefas em nome do usuário do Chat (o que exige autenticação do usuário).

Para saber como autenticar e chamar a API Chat, consulte a visão geral da API Chat.