1. Introdução
Última atualização:23/08/2021
Transferência de agente ativo com o Business Messages
O recurso de transferência do agente ao vivo do Business Messages permite que seu agente inicie uma conversa como um bot e mude o meio da conversa para um atendente (representante humano). Seu bot pode lidar com perguntas comuns, como horário de funcionamento, enquanto o agente em tempo real pode oferecer uma experiência personalizada com mais acesso ao contexto do usuário. Quando a transição entre essas duas experiências é perfeita, as perguntas dos usuários são respondidas de forma rápida e precisa, o que resulta em uma maior taxa de engajamento de retorno e maior satisfação do cliente.
Este codelab ensina como usar ao máximo o recurso de transferência do agente ao vivo.
O que você vai criar
Neste codelab, você vai criar um webhook para seu agente que pode enviar e receber eventos de transferência de agentes ao vivo. Você vai usar uma interface básica fornecida pelo código inicial para testar o que criou.
O que você vai aprender
- Como armazenar e gerenciar o estado da conversa.
- Como usar o Business Messages para enviar eventos de transferência do agente ao vivo.
- Como configurar um webhook e uma interface básica para participar de conversas como agente.
- Práticas recomendadas para usar a API Business Messages.
O foco deste codelab é usar a API Business Message para implementar a transferência de agentes ativos. Você pode ler o código inicial para cada estágio, mas só precisa implementar o código relacionado ao Business Messages.
O que é necessário
- Um agente do Business Messages, incluindo a chave da sua conta de serviço Para criar um agente, siga o guia "Criar um agente".
- Uma configuração ativa do Cloud Datastore vinculada ao projeto do GCP do agente. Use o guia de início rápido do Cloud Datastore para configurar isso. Você não precisa saber como usar o Cloud Datastore.
- Um computador com o SDK Google Cloud e o Node.js (versão 10 ou mais recente) instalados.
- Um dispositivo Android (com a versão 5 ou mais recente) ou um dispositivo iOS para testar a experiência do usuário.
- Experiência com programação de aplicativos da Web. Você vai escrever uma pequena quantidade de código JavaScript e pode precisar depurar o que escreve.
2. Criar um bot echo
Nesta etapa, você implantará um representante de bot básico chamado "bot Echo". Esse bot recebe mensagens do usuário, as registra em uma conversa no Cloud Datastore e depois "ecoa" a mensagem do usuário respondendo com o mesmo conteúdo. Depois de ter um bot básico e uma infraestrutura de geração de registros, você poderá adicionar a eles para criar uma implementação completa de transferência do agente ao vivo nas próximas etapas.
Acessar o código inicial
Em um terminal, clone o código inicial do Live Agent Transfer para o diretório de trabalho do seu projeto com o seguinte comando:
git clone https://github.com/google-business-communications/bm-nodejs-live-agent-transfer
Entender o código inicial
Vamos dar uma olhada na estrutura do código inicial com que você vai trabalhar ao longo do codelab.
Navegue até o diretório step-1 e confira o conteúdo dele. Ele contém os seguintes elementos:
- bin: contém o script www starter, que define e configura o servidor.
- libs: esse diretório contém
datastore_util.js, com métodos convenientes para ler e gravar no Cloud Datastore. Você não precisa entender como esse arquivo funciona. Observe os métodos disponíveis e o que eles fazem. - resources: contém a chave da sua conta de serviço como um arquivo chamado
credentials.json. - routes: o arquivo
index.jscontém o webhook e todos os métodos auxiliares dele. Este é o arquivo principal em que você vai trabalhar e adicionar. - views: esse diretório contém arquivos de modelo EJS para elementos da interface. Ele conterá mais arquivos nas próximas etapas.
- app.js, app.yaml, package.json: esses arquivos configuram o aplicativo e as dependências dele.
Antes da implantação, faça o download da chave da conta de serviço do GCP e copie o arquivo de credenciais JSON em cada diretório de recursos no código de amostra. Faça isso em todas as etapas do codelab.
cp credentials.json bm-nodejs-live-agent-transfer/step-<step number>/resources/credentials.json
Como implantar o código inicial
Em um terminal, navegue até o diretório step-1 do exemplo. Em seguida, configure a ferramenta gcloud para usar seu projeto do Google Cloud, definindo o ID do projeto usado para se registrar nas APIs.
gcloud config set project <PROJECT_ID>
Para implantar o aplicativo, execute o seguinte comando:
gcloud app deploy
Observe o URL do aplicativo implantado na saída do último comando:
Deployed service [default] to [https://PROJECT_ID.appspot.com]
O código inicial que você acabou de implantar contém um aplicativo da Web com um webhook para receber mensagens do Business Messages. O aplicativo devolve as mensagens ao usuário e registra as conversas no Cloud Datastore.
Configure seu agente
Navegue até a página de configurações da conta no Console para desenvolvedores do Business Communications e defina o webhook como o URL do aplicativo implantado. Por exemplo, https://PROJECT_ID.appspot.com/callback/.
Em seguida, na página de informações do agente, configure os tipos de interação principal e secundário como bot e humano, respectivamente.
Conversar com o bot de eco
Abra seu agente no Play Console. Você verá a página Visão geral, que permite revisar os detalhes do agente. Copie o URL de teste do agente que corresponde ao seu dispositivo móvel de teste. Use este URL no seu dispositivo móvel para iniciar a plataforma de conversa do agente.
Interaja com o agente enviando algumas mensagens. A plataforma de conversação apenas copia o que você diz, o que não é uma experiência muito útil para o usuário. Quem dera se existisse um jeito de conversar com uma pessoa de verdade?
3. Entrando na conversa
Agora vamos analisar a conversa do ponto de vista do seu atendente. Como agente em tempo real, você precisa saber algumas informações sobre a conversa antes de participar, como o ID dela. Também é útil saber se o usuário pediu para falar com um atendente. Nesta etapa, você vai usar uma página básica de CRM (Gerenciamento de relacionamento com o cliente) para visualizar essas informações e participar da conversa como um atendente.
O código inicial desta etapa adiciona um CRM básico que lista todas as linhas de execução de conversa do agente. Vamos conferir esse CRM para ver quais conversas podem exigir a atenção de um agente em tempo real.
Navegue até o diretório step-2 e implante o app novamente, como você fez na etapa anterior.
Ao implantar o app, você vê um URL de destino. Acesse esse URL em um navegador para abrir uma listagem com a conversa iniciada na etapa anterior. No momento, o estado da conversa é "gerenciado por bots", porque o bot echo atua como representante do nosso agente nesta conversa.
O botão Participar do chat aparece, mas ainda não faz nada. Nessa interface, também não é possível saber se o usuário quer falar com um atendente.
O Business Messages oferece um evento solicitado do agente em tempo real que indica quando o usuário quer conversar com um atendente. Você precisa acompanhar esse estado para listá-lo na interface.
Confira o método de callback em index.js. Um comentário TODO indica onde você precisa capturar a solicitação do usuário por um agente em tempo real e atualizar o estado da conversa.
step-2/routes/index.js
/**
* The webhook callback method.
*/
router.post('/callback', async function(req, res, next) {
...
} else if (requestBody.userStatus !== undefined) {
if (requestBody.userStatus.requestedLiveAgent !== undefined) {
...
// TODO: Update the thread state to QUEUED_THREAD_STATE.
}
}
});
...
});
É necessário usar os métodos em libs/datastore_utils.js para carregar a linha de execução de conversa atual e atualizar o estado dela para QUEUED_THREAD_STATE.
Se você não souber o que fazer, dê uma olhada nas soluções. O código inicial inclui um diretório solutions em cada etapa em que você precisa concluir o código. Esses diretórios contêm uma cópia de todo o app com a implementação completa da etapa especificada.
Depois de concluir a implementação e reimplantar o app, use o menu flutuante na conversa no seu dispositivo móvel para solicitar um agente ao vivo.
Agora, se você navegar de volta ao CRM, verá a observação "Live agent requested" na conversa. Esse usuário precisa da ajuda de uma pessoa! É necessário implementar o endpoint joinConversation para que o botão funcione.
Encontre o outro comentário TODO no método fragmentado para /joinConversation.
step-2/routes/index.js
/**
* Updates the thread state and sends a representative join signal to the user.
*/
router.post('/joinConversation', async function(req, res, next) {
let conversationId = req.body.conversationId;
// TODO: Update the thread state to LIVE_AGENT_THREAD_STATE and post a REPRESENTATIVE_JOINED event.
res.json({
'result': 'ok',
});
});
É necessário atualizar o estado da linha de execução de novo, desta vez para LIVE_AGENT_THREAD_STATE. Além disso, você precisa usar o método conversations.events.create da API Business Messages para postar um evento REPRESENTATIVE_JOINED.
Para criar o payload da solicitação, você precisa definir os campos descritos na tabela a seguir:
Nome do campo | Dica |
| Defina como "conversations/{conversationId}". |
| Gere seu próprio ID aleatório para o evento. |
| Use o método |
| Este é o corpo do evento em si. Você deve definir o eventType e o representante. |
Acesse a página de referência do método "create" ou a página de referência de eventos para receber ajuda.
Quando você concluir a implementação, reimplante o app e clique no botão Participar do chat. A caixa de diálogo Conversa de que você participou aparece, e o status do chat muda para "Chat ao vivo". Se você abrir a conversa no seu dispositivo móvel, verá uma observação no chat informando que o agente em tempo real entrou.
Parabéns! Na próxima etapa, vamos aprender a fazer o agente em tempo real falar com o usuário.
4. Mensagens como um agente em tempo real
Agora que você entrou na conversa, é hora de enviar algumas mensagens como o atendente.
Navegue até o diretório step-3 e reimplante o app. No CRM, clique na conversa da etapa anterior. Agora você verá uma interface de chat básica. Nessa tela, é possível conferir as mensagens do usuário em tempo real.
No entanto, o envio de uma mensagem como o agente ainda não foi implementado. É necessário fazer isso nesta etapa.
Abra o arquivo routes/index.js e observe os três endpoints recém-adicionados:
/messages: recebe o arquivo de visualizaçãomessages.ejse o renderiza no navegador. Ao clicar em uma conversa do índice, você navega para uma dessas páginas./retrieveMessages: acessa o conteúdo das mensagens de uma conversa e retorna uma lista formatada com todas as mensagens. A página de mensagens chama esse endpoint periodicamente para mostrar as mensagens mais recentes./sendMessage: envia uma mensagem do representante do atendente em tempo real para o usuário. A página de mensagens chama isso quando você clica em "Enviar". No momento, ele não foi implementado.
Agora, confira o método storeAndSendResponse atual:
step-3/routes/index.js
/**
* Updates the thread, adds a new message and sends a response to the user.
*
* @param {string} message The message content that was received.
* @param {string} conversationId The unique id for this user and agent.
* @param {string} threadState Represents who is managing the conversation for the CRM.
* @param {string} representativeType The representative sending the message, BOT or HUMAN.
*/
async function storeAndSendResponse(message, conversationId, threadState, representativeType) {
...
}
O webhook já usa esse método para enviar respostas do bot echo. Primeiro, o método armazena os dados da mensagem recebida no objeto do Cloud Datastore para a conversa. Depois, ele envia a mensagem de resposta. Observe mais de perto o objeto de mensagem criado, principalmente no tipo representativo.
Agora, implemente o endpoint /sendMessage por conta própria. O método storeAndSendResponse já existente pode ser usado aqui para fazer a maior parte do trabalho. O importante é lembrar de definir o representante correto.
Depois disso, reimplante o app e volte para sua conversa no CRM. Agora suas mensagens vão aparecer no histórico de chat. Também é possível ver as mensagens do agente que aparecem no dispositivo móvel de teste.
Antes de continuar, entenda como os novos endpoints funcionam. Na próxima etapa, você adicionará seu próprio endpoint para sair da conversa.
5. Saindo da conversa
Depois de ajudar o usuário com as perguntas, convém sair da conversa e permitir que ele fale com o bot novamente. No Business Messages, essa mudança é indicada por um evento REPRESENTATIVE_LEFT.
Navegue até o diretório step-4, reimplante o app e retorne à conversa. O link Fechar e sair da conversa vai aparecer na parte de baixo da conversa. Este link ainda não funciona porque o endpoint leaveConversation não foi implementado.
Confira o arquivo index.js. Há um comentário TODO instruindo você a criar um novo endpoint leaveConversation.
step-4/routes/index.js
/*
* TODO: Create a '/leaveConversation' endpoint that does the following:
* - Updates the thread to BOT_THREAD_STATE.
* - Sends a REPRESENTATIVE_LEFT event.
* - Sends a message to the thread informing the user that they are speaking to the echo bot again.
*
* Hint: You can use the same methods that '/joinConversation' uses.
*/
Para implementar isso, reúna tudo o que você aprendeu no codelab até agora. Esse endpoint precisa fazer o seguinte:
- Atualize a linha de execução para
BOT_THREAD_STATE. - Enviar um evento
REPRESENTATIVE_LEFT. - Envie uma mensagem na conversa para informar ao usuário que ele está falando com o bot echo. Use o método
storeAndSendResponse. O representante voltou paraBOT.
A última etapa esclarece o estado da conversa para o usuário. O usuário vê um evento quando um representante sai do chat, mas não necessariamente sabe que está falando com o bot de transmissão novamente. Ao enviar uma mensagem diretamente do bot, você reduz a confusão do usuário e melhora a experiência.
Agora que o bot está cuidando de tudo, seu agente em tempo real está livre para participar de outra conversa. Teste o exemplo de código e o CRM o quanto quiser. Teste algumas ideias diferentes para a experiência de transferência do agente ao vivo da sua empresa e veja o que consegue.
6. Conclusão
Parabéns por concluir o codelab de transferência de agentes ao vivo!
Você criou um agente capaz de processar transferências de agentes em tempo real do início ao fim. Você também aprendeu uma maneira de rastrear o estado da conversa com o Cloud Datastore.
Com a transferência de atendentes em tempo real, você deixa as solicitações comuns para seu bot, enquanto seus atendentes processam consultas mais complexas. Os usuários ficarão mais satisfeitos com a nova experiência personalizada e útil, o que aumentará a probabilidade de retornarem e de recomendarem sua empresa para amigos.
Qual é a próxima etapa?
Confira alguns destes codelabs:
Leia mais
- Revise os conceitos básicos da transferência com o Guia de transferência do bot para o atendente.
- Faça upgrade do seu bot echo para um bot de perguntas frequentes com o guia do Dialogflow.