Criar interfaces do Google Chat

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

No Google Chat, os complementos aparecem para os usuários como apps do Google Chat. Para saber mais, consulte a Visão geral do Extend Google Chat.

Para criar interfaces para apps de chat, use os seguintes componentes complementares:

  • Gatilhos: as maneiras como os usuários do Google Chat podem invocar um app do Chat, como adicionar o app 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 às interações, como enviar mensagens ou retornar uma interface do 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 de 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 que se abrem em uma nova janela e geralmente solicitam 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

Esta seção explica os acionadores que os complementos do Google Workspace usam no Chat.

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

A tabela a seguir mostra 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 Chat a um espaço ou um administrador do Google Workspace instala o app Chat em espaços de mensagens diretas para os 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 de ajuda do administrador do Google Workspace.

 O app 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.
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 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 de chat responde com base no conteúdo da mensagem. Por exemplo, um app de 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 os apps do Chat que foram instalados pelo administrador. Se um usuário já tiver instalado o app Chat, ele vai continuar instalado, mesmo que um administrador do Google Workspace tente desinstalá-lo.

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

Um usuário usa um comando do app Chat.

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

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

Para responder a um gatilho, consulte estes guias:

Objetos de evento

Os apps de chat recebem objetos de evento quando um acionador é acionado ou quando os usuários interagem com uma interface do app de chat (como clicar 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 estes guias:

Para saber mais sobre os objetos de eventos de complementos no Chat e em outros apps do Google Workspace, consulte Objetos de eventos.

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 complementar, um app de 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 às interações de várias maneiras. Em muitos casos, os apps de chat respondem com uma mensagem. Os apps de chat também podem pesquisar algumas informações de uma fonte de dados, registrar as informações do objeto do evento ou qualquer outra coisa. Esse comportamento de processamento é essencialmente o que define o app 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 a devolução
Enviar ou atualizar uma mensagem. DataActions
Abrir, atualizar ou fechar uma caixa de diálogo. RenderActions
Para coletar informações de um card ou diálogo, sugira itens de seleção com base no que os usuários digitam em um menu de múltipla seleção. RenderActions
Link de visualização em mensagens que os usuários do Chat enviam em um espaço. DataActions

Responder usando a API Google Chat

Em vez de retornar uma ação de complemento, os apps do Chat talvez precisem usar a API Google Chat para responder a uma interação. Por exemplo, os apps de chat precisam chamar a API Google Chat para fazer o seguinte:

  • Responda 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 complementares. Por exemplo, liste os espaços em que um usuário ou app do Chat é participante ou adicione usuários a espaços.
  • Executar 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.