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 do 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 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 Added to space é 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 do Chat usando a interface do Chat, como @menções ou comandos do 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 /about com uma mensagem que explica as tarefas que o app 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 rápido ou um comando de barra no 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 mais orientações, consulte Configurar um app do Google Chat.

Para responder a um gatilho, consulte estes guias:

Objetos de evento

Esta seção define e explica todos os elementos dos objetos de evento de chat. Para saber mais, consulte Objetos de evento.

Objeto de evento
commonEventObject object (CommonEventObject)
Um objeto que contém informações comuns a todos os objetos de evento, independente do aplicativo host.
chat object (Chat)
Um objeto que contém todas as informações sobre as interações do Chat.

Chat

Chat
chat.user object (User)
O usuário que interagiu com o app Chat.
chat.space object (Space)
O espaço do Chat em que um usuário interagiu com o app do Chat.
chat.eventTime

string (Timestamp format)

O horário em que a interação ocorreu.

Campo de união payload.

payload pode ser apenas de um dos tipos a seguir:
chat.messagePayload

object (MessagePayload)

O payload que os apps do Chat recebem de um acionador de mensagem.
chat.addedToSpacePayload

object (AddedToSpacePayload)

O payload que os apps do Chat recebem de um acionador Adicionado ao espaço.
chat.removedFromSpacePayload

object (RemovedFromSpacePayload)

O payload que os apps do Chat recebem de um acionador Removed from space.
chat.buttonClickedPayload

object (ButtonClickedPayload)

O payload que os apps do Chat recebem quando os usuários clicam em um botão de uma mensagem ou card. Se um usuário clicar em um botão para enviar informações, o objeto commonEventObject.formInputs vai conter os valores coletados do usuário. Para saber mais, consulte Coletar informações dos usuários do Google Chat.
chat.widgetUpdatedPayload

object (WidgetUpdatedPayload)

O payload que os apps de chat recebem quando os usuários digitam texto no menu de seleção múltipla de um widget selectionInput. Os apps de chat podem usar esse objeto de evento para preencher itens sugeridos de uma fonte de dados dinâmica. Por exemplo, para preencher casos de suporte de uma fonte de dados externa, um app de chat pode consultar a fonte de dados com base no que o usuário digita no menu e, em seguida, retornar os casos de suporte correspondentes como itens selecionáveis.

O objeto CommonEventObject.parameters['autocomplete_widget_query'] contém o valor da string que o usuário digita no menu.

chat.appCommandPayload

object (AppCommandPayload)

O payload que os apps de chat recebem quando um usuário usa um comando do app.

Payload

Dependendo do tipo de interação, o evento contém um payload com um ou mais recursos da API Chat.

Payload da mensagem
MessagePayload
chat.messagePayload.message object (Message)
A mensagem do Chat que acionou o evento.
chat.messagePayload.space object (Space)
O espaço do Chat em que um usuário enviou a mensagem que invocou o app Chat.

Adicionado ao payload do espaço
AddedToSpacePayload
chat.addedToSpacePayload.space object (Space)
O espaço do Chat em que o usuário adicionou ou instalou o app do Chat.

Quando os administradores instalam apps do Chat, o campo space.adminInstalled é definido como true.

chat.addedToSpacePayload.interactionAdd boolean
Informa se um usuário adiciona o app do Chat a um espaço usando uma mensagem. Por exemplo, @menciona o app Chat ou usa um comando de barra. Se true, o Chat envia outro objeto de evento com um messagePayload que contém informações sobre a mensagem.

Removido do payload do espaço
RemovedFromSpacePayload
chat.removedFromSpacePayload.space object (Space)
O espaço do Chat em que o usuário removeu ou desinstalou o app Chat.

Quando os administradores desinstalam apps do Chat, o campo space.adminInstalled é definido como false.

Payload do botão clicado
ButtonClickedPayload
chat.buttonClickedPayload.message object (Message)
A mensagem de chat que contém o botão em que um usuário clicou.
chat.buttonClickedPayload.space object (Space)
O espaço do Chat em que o usuário clicou em um botão de uma mensagem do app do Chat.
chat.buttonClickedPayload.isDialogEvent boolean
Indica se o usuário clicou no botão para interagir com uma caixa de diálogo.
chat.buttonClickedPayload.dialogEventType enum (DialogEventType)
Se isDialogEvent for true, o tipo de interação em um diálogo.

Enum DialogEventType.

O valor de dialogEventType pode ser apenas um dos seguintes:
TYPE_UNSPECIFIED Valor padrão. Não especificado.
REQUEST_DIALOG Um usuário solicita uma caixa de diálogo. Por exemplo, eles usam um comando de barra ou clicam em um botão de uma mensagem.
SUBMIT_DIALOG Um usuário clica em um elemento interativo em uma caixa de diálogo. Por exemplo, um usuário preenche informações em uma caixa de diálogo e clica em um botão para enviar as informações.

Payload atualizado do widget
WidgetUpdatedPayload
chat.widgetUpdatedPayload.space object (Space)
O espaço do Chat em que a interação ocorreu.

Payload do comando do app
AppCommandPayload
chat.appCommandPayload.appCommandMetadata object (AppCommandMetadata)
Metadados sobre qual comando o usuário usou e como ele acionou o comando.
chat.appCommandPayload.space object (Space)
O espaço do Chat em que um usuário usou o comando.
chat.appCommandPayload.thread object (Thread)
Se a interação ocorreu em uma linha de execução, a linha de execução do chat em que o usuário usou o comando.
chat.appCommandPayload.message object (Message)
A mensagem que o usuário enviou com o comando de barra.
chat.appCommandPayload.configCompleteRedirectUri string
Se for necessária autorização ou configuração para o comando, um URL para redirecionar o usuário depois que ele concluir o processo fora do Google Chat.
chat.appCommandPayload.isDialogEvent boolean
Indica se o comando abre uma caixa de diálogo.
chat.appCommandPayload.dialogEventType enum (DialogEventType)
Tipo de interação com uma caixa de diálogo.

Enum DialogEventType.

O valor de dialogEventType pode ser apenas um dos seguintes:
TYPE_UNSPECIFIED Valor padrão. Não especificado.
REQUEST_DIALOG Um usuário solicita uma caixa de diálogo. Por exemplo, eles usam um comando de barra ou clicam em um botão de uma mensagem.
SUBMIT_DIALOG Um usuário clica em um elemento interativo em uma caixa de diálogo. Por exemplo, um usuário preenche informações em uma caixa de diálogo e clica em um botão para enviar as informações.
Metadados de comando do app
AppCommandMetadata
chat.appCommandPayload.appCommandMetadata.appCommandId

string (int64 format)

O ID do comando.
chat.appCommandPayload.appCommandMetadata.appCommandType enum (AppCommandType)
O tipo de comando.

Enum AppCommandType.

O valor de AppCommandType pode ser apenas um dos seguintes:
APP_COMMAND_TYPE_UNSPECIFIED Valor padrão. Não especificado.
SLASH_COMMAND Um usuário usa o comando enviando uma mensagem que começa com um caractere de barra /.

Ações no chat

Esta seção explica como os apps de chat podem usar ações complementares 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 de 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 desejada 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 de 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 a autenticação do usuário).

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