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.

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 adicioná-lo a um espaço ou enviar uma mensagem.
  • Objetos de evento: os dados que os apps do Chat recebem de gatilhos ou interações da interface.
  • Ações: as maneiras como os apps do Chat podem responder a interações, como enviar mensagens ou retornar uma interface do usuário baseada em card.
O app Chat recebe um objeto de evento de um gatilho "Adicionado ao espaço"
Figura 1: quando um usuário adiciona um app do Chat a um espaço, o Adicionado ao espaço gatilho é acionado e envia um objeto de evento. Para responder com uma mensagem, o app do Chat processa o objeto de evento e retorna uma ação que cria a mensagem.

Os apps do 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 são abertos em uma nova janela e normalmente solicitam que os usuários enviem informações.
  • Visualizações de link, que são cards que mostram informações sobre um serviço externo.

Gatilhos

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

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

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 na 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 Ajuda para admins do Google Workspace.

 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.
Mensagem

Um usuário interage com o app do 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 que contém um link que corresponde ao padrão do URL para visualizações de link.
  • Digita texto no menu de seleção múltipla de um selectionInput widget.
 O app do Chat responde com base no conteúdo da mensagem. Por exemplo, um app do Chat responde a o comando de barra /about com uma mensagem que explica as tarefas que o app do Chat pode fazer.
Removido do espaço

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

Os usuários não podem remover apps do Chat instalados por seus administradores. Se um usuário tiver instalado o app do Chat anteriormente, ele permanecerá instalado, independentemente de um administrador do Google Workspace tentar desinstalar.

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

Um usuário usa um comando do app do Chat.

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

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

Para responder a um gatilho, consulte os seguintes guias:

Objetos de evento

Os apps do Chat recebem objetos de evento quando um gatilho do Chat é acionado ou quando os usuários do Chat interagem com uma interface do app do Chat (como clicar em um botão). O objeto de evento permite usar dados de interação 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 complemento 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 a 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 do 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 do Chat também podem pesquisar algumas informações de uma fonte de dados, registrar as informações do objeto de evento ou qualquer outra coisa. Esse comportamento de processamento é essencialmente o que define o app Google Chat.

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

A tabela a seguir mostra como os apps do Chat podem responder com ações. Os apps do Chat podem retornar objetos JSON ou criar a resposta usando o Apps Script's AddOnResponseService.

Resposta do app do Chat Ação necessária para retornar (JSON) Ação necessária para retornar (Apps Script)
Enviar ou atualizar uma mensagem. DataActions DataActionsResponse
Abrir, atualizar ou fechar uma caixa de diálogo. RenderActions ActionResponse
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 ActionResponse
Visualizar links em mensagens que os usuários do Chat enviam em um espaço. DataActions DataActionsResponse

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, listar espaços em que um usuário ou app do Chat é membro ou adicionar usuários ao espaço.
  • Realizar tarefas em nome do usuário do Chat (que exige autenticação do usuário).

Ao responder a um evento de interação após 30 segundos, para evitar uma mensagem de erro voltada ao usuário informando que o app do Chat não está respondendo, é necessário confirmar o recebimento de um evento de interação em até 30 segundos enviando uma resposta vazia, conforme mostrado aqui:

Node.js

async function onEvent(req, res) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return res.send({});
};

Python

def on_event(event) -> dict:
  # Trigger asynchronous job that will respond using the Google Chat API.
  ...

  # Respond with an empty response to the Google Chat platform.
  return {}

Java

public String onEvent(JsonNode event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return "{}";
}

Apps Script

function onEvent(event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return null;
}

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