Para evitar a mudança de contexto quando os usuários compartilham um link no Google Chat, o app do Chat pode visualizar o link anexando um card à mensagem com mais informações e permitindo que as pessoas realizem ações diretamente no Google Chat.
Por exemplo, imagine um espaço do Google Chat que inclua todos os agentes de atendimento ao cliente de uma empresa e um app de chat chamado Case-y. Frequentemente, os agentes compartilham links para casos de atendimento ao cliente no espaço do Chat e, sempre que fazem isso, os colegas precisam abrir o link do caso para conferir detalhes como responsável, status e assunto. Da mesma forma, se alguém quiser assumir a propriedade de um caso ou alterar o status, precisará abrir o link.
Com a prévia do link, o app do Chat do espaço, Case-y, anexe um cartão que mostra o responsável, o status e o assunto sempre que alguém compartilha um link de caso. Os botões no card permitem que os agentes assumam a propriedade do caso e mudem o status diretamente no stream do chat.
Como funciona a visualização de links
Quando alguém adiciona um link à mensagem, um ícone aparece para informar que um app do Chat pode ter uma prévia do link.
Após o envio, o link é enviado para o app do Chat, que gera e anexa o card à mensagem do usuário.
Além do link, o card fornece informações adicionais sobre o link, incluindo elementos interativos, como botões. Seu app do Chat pode atualizar o card anexado em resposta a interações do usuário, como cliques em botões.
Se uma pessoa não quiser que o app do Chat visualize o link anexando um card à mensagem, ela pode clicar em
no ícone de visualização para impedir a visualização. Os usuários podem remover o cartão anexado a qualquer momento clicando em Remover visualização.Pré-requisitos
Node.js
Um app do Google Chat com recursos interativos ativados. Para criar um interativo do Chat que usa um serviço HTTP, conclua este guia de início rápido.
Apps Script
Um app do Google Chat com recursos interativos ativados. Para criar um interativo com o app Chat no Apps Script, conclua este guia de início rápido.
Configurar visualizações de links
Registre links específicos, como example.com
, support.example.com
e support.example.com/cases/
, como padrões de URL na página de configuração do app do Chat no console do Google Cloud para que o app do Chat possa visualizá-los.
- Abra o Console do Google Cloud.
- Ao lado de "Google Cloud", Clique na seta para baixo e abra o projeto do app do Chat.
- No campo de pesquisa, digite
Google Chat API
e clique em API Google Chat. - Clique em Gerenciar > Configuração.
- Em Visualizações de link, adicione ou edite um padrão de URL.
- Para configurar visualizações de links para um novo padrão de URL, clique em Adicionar padrão de URL.
- Para editar a configuração de um padrão de URL atual, clique na seta para baixo .
No campo Padrão de host, insira o domínio do padrão de URL. O app do Chat vai visualizar os links para este domínio.
Se quiser que os links de visualização do app do Chat para um subdomínio específico, como
subdomain.example.com
, inclua o subdomínio.Para que os links de visualização do app do Chat sejam vinculados a todo o domínio, especifique um caractere curinga com um asterisco (*) como subdomínio. Por exemplo,
*.example.com
corresponde asubdomain.example.com
eany.number.of.subdomains.example.com
.No campo Prefixo do caminho, digite um caminho para anexar ao domínio do padrão de host.
Para corresponder a todos os URLs no domínio do padrão de host, deixe o Prefixo do caminho vazio.
Por exemplo, se o padrão do host for
support.example.com
, digitecases/
para corresponder aos URLs de casos hospedados emsupport.example.com/cases/
.Clique em Concluído.
Clique em Salvar.
Agora, sempre que alguém incluir um link que corresponde a um padrão de URL de visualização de link a uma mensagem em um espaço do Chat que inclui seu app do Chat, o app vai visualizar o link.
Visualizar um link
Depois de configurar a visualização de um determinado link, seu O app do Chat pode reconhecer e visualizar o link anexando mais informações a ele.
Nos espaços do Chat que incluem seus
em um app do Chat, quando a mensagem de alguém inclui um link que
corresponder a um padrão do URL de visualização do link, seu app do Chat
recebe um
Evento de interação MESSAGE
. O arquivo JSON
o payload do evento de interação contém o campo matchedUrl
:
JSON
"message": {
. . . // other message attributes redacted
"matchedUrl": {
"url": "https://support.example.com/cases/case123"
},
. . . // other message attributes redacted
}
Verificando a presença do campo matchedUrl
no evento MESSAGE
.
payload, o app do Chat poderá adicionar informações ao
com o link da prévia. Seu app do Chat pode:
responda com uma mensagem de texto simples ou anexe um cartão.
Responder com uma mensagem de texto
Para respostas simples, o app do Chat pode visualizar um link respondendo com uma mensagem de texto simples a um link. Este exemplo anexa uma mensagem que repete o URL do link que corresponde a um padrão do URL de visualização do link.
Node.js
Apps Script
Anexar um cartão
Para anexar um card a um link visualizado,
retornar um
ActionResponse
do tipo UPDATE_USER_MESSAGE_CARDS
. Este exemplo anexa um cartão simples.
Node.js
Apps Script
Este exemplo envia uma mensagem de card retornando JSON do cartão. Você também pode usar o Serviço de card do Apps Script.
Atualizar um cartão
Para atualizar o card anexado a um link visualizado, retorne uma
ActionResponse
do tipo UPDATE_USER_MESSAGE_CARDS
. Os apps de chat só podem atualizar
cards que mostram links como resposta a uma
Evento de interação com o app do Chat.
Os apps de chat não podem atualizar esses cards chamando a API Chat
de forma assíncrona.
A visualização de links não é compatível com o retorno de um ActionResponse
do tipo UPDATE_MESSAGE
. Como o UPDATE_MESSAGE
atualiza toda a mensagem, em vez de apenas o card, ele só vai funcionar se o app do Chat tiver criado a mensagem original. A prévia do link anexa um card a uma mensagem criada pelo usuário. Assim, o app do Chat não tem permissão para fazer atualizações.
Para garantir que uma função atualize os cards criados pelo usuário e pelo app no stream do Chat, defina dinamicamente o ActionResponse
com base no fato de o app do Chat ou um usuário ter criado a mensagem.
- Se um usuário criou a mensagem, defina
ActionResponse
comoUPDATE_USER_MESSAGE_CARDS
. - Se um app do Chat criou a mensagem, defina
ActionResponse
comoUPDATE_MESSAGE
.
Há duas maneiras de fazer isso: especificar e verificar se há um actionMethodName
personalizado como parte da propriedade onclick
do cartão anexado (que identifica a mensagem como criada pelo usuário) ou verificar se ela foi criada por um usuário.
Opção 1: procurar actionMethodName
Se quiser usar actionMethodName
para processar corretamente eventos de interação CARD_CLICKED
em cards visualizados, defina um actionMethodName
personalizado como parte da propriedade onclick
do card anexado:
JSON
. . . // Preview card details
{
"textButton": {
"text": "ASSIGN TO ME",
"onClick": {
// actionMethodName identifies the button to help determine the
// appropriate ActionResponse.
"action": {
"actionMethodName": "assign",
}
}
}
}
. . . // Preview card details
Como o "actionMethodName": "assign"
identifica o botão como parte de uma visualização de link, é possível retornar dinamicamente o ActionResponse
correto, verificando se há um actionMethodName
correspondente:
Node.js
Apps Script
Este exemplo envia uma mensagem de card retornando JSON do cartão. Você também pode usar o Serviço de card do Apps Script.
Opção 2: verificar o tipo de remetente
Confira se message.sender.type
é HUMAN
ou BOT
. Se HUMAN
, defina ActionResponse
como UPDATE_USER_MESSAGE_CARDS
. Caso contrário, defina ActionResponse
como UPDATE_MESSAGE
. Veja como fazer isso:
Node.js
Apps Script
Este exemplo envia uma mensagem de card retornando JSON do cartão. Você também pode usar o Serviço de card do Apps Script.
Um motivo comum para atualizar um card é em resposta a um clique no botão. Lembre-se do botão Atribuir a mim da seção anterior, Anexar um cartão. O exemplo completo a seguir atualiza o card para que ele indique que seja atribuído a "Você". depois que o usuário clicar em Atribuir a mim. O exemplo define ActionResponse
dinamicamente, verificando o tipo de remetente.
Exemplo completo: Case-y, o app do Chat de atendimento ao cliente
Este é o código completo do Case-y, um app do Chat que mostra links para casos compartilhados em um espaço do Chat em que os agentes de atendimento ao cliente colaboram.
Node.js
Apps Script
Este exemplo envia uma mensagem de card retornando JSON do cartão. Você também pode usar o Serviço de card do Apps Script.
Limites e considerações
Ao configurar visualizações de links no seu app do Chat, preste atenção nestes limites e considerações:
- Cada app do Chat é compatível com visualizações de links de até cinco padrões de URL.
- Os apps de chat mostram um link por mensagem. Se vários links visualizáveis estiverem presentes em uma única mensagem, somente o primeiro será visualizado.
- Os apps de chat exibem somente os links que começam com
https://
. Por isso, ohttps://support.example.com/cases/
é exibido, mas osupport.example.com/cases/
não. - A menos que a mensagem inclua outras informações enviadas para o app do Chat, como um comando de barra, somente o URL do link é enviado para o app do Chat pelas visualizações de link.
- Os cards anexados a links visualizados são compatíveis apenas com
ActionResponse
do tipoUPDATE_USER_MESSAGE_CARDS
e somente em resposta a um evento de interação com o app do Chat. As visualizações de link não são compatíveis comUPDATE_MESSAGE
ou solicitações assíncronas para atualizar cards anexados a um link visualizado usando a API Chat. Saiba mais em Atualizar um cartão.
Depurar prévias de links
Ao implementar as visualizações de links, talvez seja necessário depurar o app do Chat lendo os registros dele. Para ler os registros, acesse a Análise de registros no console do Google Cloud.