Para evitar a troca 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 que permita que as pessoas realizem ações diretamente no Google Chat.
Por exemplo, imagine um espaço do Google Chat com todos os agentes de atendimento ao cliente de uma empresa e um app do Chat chamado Case-y. Os agentes costumam compartilhar links para casos de atendimento ao cliente no espaço do Chat e, sempre que o fazem, os colegas precisam abrir o link do caso para conferir detalhes como o responsável, o status e o assunto. Da mesma forma, se alguém quiser se tornar o proprietário de um caso ou alterar o status, precisará abrir o link.
Com a visualização de links, o app do Chat residente do espaço, Case-y, anexe um card mostrando o responsável, o status e o assunto sempre que alguém compartilhar um link de caso. Com os botões no card, os agentes podem assumir a propriedade do caso e mudar o status diretamente no stream do chat.
Como funciona a visualização de links
Quando uma pessoa adiciona um link à mensagem, aparece um ícone que informa que um app do Chat pode visualizar o link.
Após o envio, o link é enviado para o app do Chat, que gera e anexa o cartão à mensagem do usuário.
Juntamente com o link, o card traz mais informações sobre o link, incluindo elementos interativos, como botões. O app do Chat pode atualizar o cartão 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 acesse a prévia do link anexando um card à mensagem, ela pode impedir a visualização clicando em
no ícone de visualização. Os usuários podem remover o cartão anexado a qualquer momento clicando em Remover visualização.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 link 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 existente, clique na seta para baixo .
No campo Padrão de host, digite o domínio do padrão de URL. O app do Chat vai visualizar os links para este domínio.
Para que os links de visualização do app do Chat de um subdomínio específico, como
subdomain.example.com
, inclua o subdomínio.Se você quiser que os links de visualização do app do Chat para todo o domínio sejam exibidos, 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 do host.
Para corresponder a todos os URLs no domínio do padrão do host, deixe Prefixo do caminho em branco.
Por exemplo, se o padrão do host for
support.example.com
, para corresponder aos URLs dos casos hospedados emsupport.example.com/cases/
, digitecases/
.Clique em Concluído.
Clique em Salvar.
Agora, sempre que alguém incluir um link que corresponda a um padrão de URL de visualização de link a uma mensagem em um espaço do Chat que inclua seu app do Chat, o app vai visualizar o link.
Visualizar um link
Depois que você configurar a visualização de um determinado link, o app do Chat poderá reconhecer e visualizar o link anexando mais informações a ele.
Dentro dos espaços do Chat que incluem o
app do Chat, quando a mensagem de alguém contém um link
correspondente a um padrão de URL de visualização de link, o app do Chat
recebe um
evento de interação MESSAGE
. O payload do JSON 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
}
Ao verificar a presença do campo matchedUrl
no payload do evento MESSAGE
, seu app do Chat pode adicionar informações à mensagem com o link visualizado. O app de chat pode
responder com uma mensagem de texto simples ou anexar 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 de URL de visualização de link.
Node.js
Apps Script
Anexar um cartão
Para anexar um cartão a um link visualizado, retorne uma ActionResponse
do tipo UPDATE_USER_MESSAGE_CARDS
. Neste exemplo, um cartão simples é anexado.
Node.js
Apps Script
Neste exemplo, uma mensagem de cartão é enviada 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 um
ActionResponse
do tipo UPDATE_USER_MESSAGE_CARDS
. Os apps de chat só podem atualizar
cards que exibem links como resposta a um
evento de interação com o app do Chat.
Os apps do Chat não podem atualizar esses cartões chamando a API Chat
de forma assíncrona.
A visualização de links não oferece suporte ao retorno de um ActionResponse
do tipo UPDATE_MESSAGE
. Como o UPDATE_MESSAGE
atualiza a mensagem inteira em vez de apenas o card, ele só funciona se o app do Chat tiver criado a mensagem original. A visualização de links anexa um card a uma mensagem criada pelo usuário. Assim, o app do Chat não tem permissão para atualizá-lo.
Para garantir que uma função atualize cards criados pelo usuário ou por um app no stream do Chat, defina dinamicamente o ActionResponse
com base no status de criação da mensagem do app do Chat ou do usuário.
- Se um usuário criou a mensagem, defina
ActionResponse
comoUPDATE_USER_MESSAGE_CARDS
. - Se a mensagem foi criada por um app do Chat, defina
ActionResponse
comoUPDATE_MESSAGE
.
Há duas maneiras de fazer isso: especificar e verificar se há um actionMethodName
personalizado como parte da propriedade onclick
do card 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
Com a "actionMethodName": "assign"
identificando o botão como parte da visualização de um link, é possível retornar dinamicamente o ActionResponse
correto, verificando se há um actionMethodName
correspondente:
Node.js
Apps Script
Neste exemplo, uma mensagem de cartão é enviada 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
Verifique se message.sender.type
é HUMAN
ou BOT
. Se for HUMAN
, defina ActionResponse
como UPDATE_USER_MESSAGE_CARDS
. Caso contrário, defina ActionResponse
como UPDATE_MESSAGE
. Veja como fazer isso:
Node.js
Apps Script
Neste exemplo, uma mensagem de cartão é enviada retornando JSON do cartão. Você também pode usar o serviço de card do Apps Script.
Um motivo típico para atualizar um card é em resposta ao clique de um 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 informe que ele foi atribuído a "Você" depois que um usuário clicar em Atribuir a mim. O exemplo define ActionResponse
dinamicamente verificando o tipo de remetente.
Exemplo completo: o app do Chat para 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
Neste exemplo, uma mensagem de cartão é enviada 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 app do Chat, observe estes limites e considerações:
- Cada app de chat tem suporte a visualizações de links de até cinco padrões de URL.
- Os apps de chat mostram um link por mensagem. Se houver vários links que podem ser visualizados em uma única mensagem, somente os primeiros serão exibidos.
- Os apps de chat só mostram uma prévia dos links que começam com
https://
. Portanto, ohttps://support.example.com/cases/
é visualizado, mas osupport.example.com/cases/
não. - A menos que a mensagem inclua outras informações enviadas ao app do Chat, como um comando de barra, somente o URL do link será enviado ao app do Chat por visualizações de link.
- Os cards anexados aos links visualizados só são compatíveis com
ActionResponse
do tipoUPDATE_USER_MESSAGE_CARDS
e apenas em resposta a um evento de interação com o app do Chat. As visualizações de links 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. Para saber mais, consulte Atualizar um cartão.
Depurar visualizações de links
Ao implementar as visualizações de link, talvez seja necessário depurar o app do Chat lendo os registros dele. Para conferir os registros, acesse a Análise de registros no console do Google Cloud.