Esta página foi traduzida pela API Cloud Translation.

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 gatilhos 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 barra.

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

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 para administradores 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 que contém um comando de barra em qualquer tipo de espaço. Envia uma mensagem com um link que corresponde ao padrão de URL para visualizações de link.	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 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.

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 para administradores 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 que contém um comando de barra em qualquer tipo de espaço.
Envia uma mensagem com um link que corresponde ao padrão de URL para visualizações de link.

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

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 Removido do espaço.
`chat.buttonClickedPayload`	`object (ButtonClickedPayload)` O payload que os apps do Chat recebem quando os usuários clicam em um botão em 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 múltipla seleção 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 todos 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.

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.

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` Indica 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 do 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 de 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.

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

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:

DataActions: cria ou atualiza dados do Google Workspace. Para enviar ou atualizar mensagens de chat, o objeto precisa conter a marcação que define as mudanças nos dados Message, representados como chatDataActionMarkup.
RenderActions: exibe ou navega entre cards em mensagens e diálogos.
basic_authorization_prompt: solicita que os usuários usem um cartão de autorização para fazer login ou autenticar em um serviço externo ao Google. Saiba mais em Conectar o complemento do Google Workspace a um serviço de terceiros.

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