Live Agent Transfer

1. Introdução

Última atualização:23/08/2021

Transferência de agente em tempo real com o Business Messages

Com o recurso de transferência para agente em tempo real do Business Messages, o agente pode iniciar uma conversa como um bot e mudar no meio da conversa para um representante (representante humano). Seu bot pode lidar com perguntas comuns, como horário de funcionamento, enquanto seu agente humano pode oferecer uma experiência personalizada com mais acesso ao contexto do usuário. Quando a transição entre essas duas experiências é perfeita, os usuários têm suas dúvidas respondidas de forma rápida e precisa, resultando em uma taxa de engajamento de retorno maior e no aumento da satisfação do cliente.

Este codelab ensina como usar ao máximo o recurso de transferência de agente ao vivo.

O que você vai criar

Neste codelab, você criará um webhook para o agente que pode enviar e receber eventos de transferência de agente em tempo real. Você vai usar uma interface básica fornecida pelo código inicial para testar o que criou.

Observação: este codelab pressupõe que você já se registrou como um parceiro e recebeu aprovação da nossa equipe de suporte. Inscreva-se no Business Messages, caso ainda não tenha feito isso, e aguarde a aprovação antes de iniciar o codelab.

O que você vai aprender

• Como armazenar e gerenciar o estado da conversa.
• Como usar o Business Messages para enviar eventos de transferência de agente em tempo real.
• 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 agente em tempo real. Você pode ler o código inicial de cada etapa, 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 seu agente. Use o guia de início rápido do Cloud Datastore para fazer essa configuração. 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 iOS para testar a experiência do usuário.
• Experiência com programação de aplicativos da Web. Você escreverá uma pequena quantidade de código JavaScript e poderá precisar depurar isso.

2. Criar um bot do Echo

Nesta etapa, você vai implantar um representante de bot básico chamado de "bot de eco". Esse bot pega as mensagens dos usuários, 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, é possível adicioná-los para criar uma implementação completa de transferência de agente em tempo real nas etapas posteriores.

Acessar o código inicial

Em um terminal, clone o código inicial do Live Agent Transfer no 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 analisar a estrutura do código inicial com que você vai trabalhar neste codelab.

Navegue até o diretório step-1 e veja o conteúdo dele. Ela contém os seguintes elementos:

• bin: esse diretório contém o script inicial www, que define e configura o servidor.
• libs: esse diretório contém datastore_util.js, que contém métodos convenientes para leitura e gravação 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 conta de serviço como um arquivo chamado credentials.json.
• routes: o arquivo index.js contém o webhook e todos os métodos auxiliares dele. Esse é o arquivo principal com 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 etapas posteriores.
• 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 exemplo de código. Faça isso em todas as etapas do codelab.

cp credentials.json bm-nodejs-live-agent-transfer/step-<step number>/resources/credentials.json

Dica: se você precisar de ajuda para configurar ou fazer o download da chave de serviço, consulte o guia do Google Cloud para gerenciar contas de serviço.

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 que você usou 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 envia mensagens de volta para o usuário e registra linhas de execução de mensagens no Cloud Datastore.

Configure seu agente

Acesse a página de configurações da conta no Business Communications Developer Console (em inglês) e defina o webhook como o URL do aplicativo implantado. Por exemplo, https://PROJECT_ID.appspot.com/callback/.

Dica: se você precisar relembrar como definir o webhook. Consulte a seção Definir seu webhook no guia de configuração do Business Messages.

Em seguida, na página de informações do agente, configure os tipos de interação primária e secundária como "Bot" e "Human", respectivamente.

Conversando com o bot Echo

Abra seu agente no Play Console. Você verá a página Overview, que permite analisar os detalhes do agente. Copie o URL de teste do agente que corresponde ao seu dispositivo móvel de teste. Use esse URL no seu dispositivo móvel para iniciar a superfície de conversa do agente.

Interaja com o agente enviando algumas mensagens. A superfície de conversa só copia o que você diz, o que não é uma experiência muito útil para o usuário. Queria poder conversar com uma pessoa de verdade!

3. Entrando na conversa

Agora vamos analisar a conversa do ponto de vista do atendente. Como atendente, você precisa saber algumas informações sobre a conversa antes de participar, como o ID da conversa. 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 gestão de relacionamento com o cliente (CRM) para ver essas informações e participar da conversa como um agente em tempo real.

O código inicial desta etapa adiciona um CRM básico que lista todas as conversas em andamento para o agente. Vamos analisar esse CRM para identificar quais conversas exigem a atenção de um atendente.

Navegue até o diretório step-2 e implante o app novamente, como 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 bot" porque o bot eco está agindo 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 determinar se o usuário quer falar com um agente em tempo real.

O Business Messages disponibiliza um evento solicitado pelo agente em tempo real que indica quando o usuário quer falar com um atendente. Você precisa acompanhar esse estado para listá-lo na interface.

Observe o método de callback em index.js. Um comentário TODO indica onde você precisa capturar a solicitação do usuário para um agente em tempo real e atualizar o estado da linha de execução.

step-2/routes/index.js (em inglês)

/**
 * 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 conversa atual e atualizar o estado dela para QUEUED_THREAD_STATE.

Se você não tem certeza do que fazer, confira as soluções. O código inicial inclui um diretório solutions em cada etapa em que você precisa concluir algum código. Esses diretórios contêm uma cópia de todo o app com a implementação completa para a 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 em tempo real.

Dica: se você não encontrar a opção "Enviar mensagem para um agente em tempo real" como opção no menu flutuante, verifique se o agente tem um tipo de interação humana configurado no console do Business Messages.

Agora, ao retornar ao CRM, você verá a observação "Agente em tempo real solicitado" na conversa. Este usuário precisa da ajuda de um ser humano. Você precisa 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 (em inglês)

/**
 * 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 novamente, desta vez para LIVE_AGENT_THREAD_STATE. Além disso, é necessário 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
parent	Defina como "conversations/{conversationId}".
eventId	Gere um ID aleatório para o evento.
auth	Use o método initCredentials fornecido.
resource	Esse é o corpo do evento. Defina eventType e o representante.

Confira a página de referência do método "create" ou a página de referência de eventos para receber ajuda.

Quando você terminar a implementação, reimplante o app e clique no botão Participar do chat. A caixa de diálogo Participando da conversa aparece, e o status muda para "Chat ao vivo". Se você abrir a conversa no seu dispositivo móvel, verá uma observação no chat informando que o atendente entrou na conversa.

Parabéns! Na próxima etapa, veremos como fazer o agente humano se comunicar com o usuário.

4. Como enviar mensagens como um agente em tempo real

Agora que você entrou na conversa, é hora de enviar algumas mensagens como o agente em tempo real.

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. Nesse local, você pode ver as mensagens do usuário em tempo real.

No entanto, enviar uma mensagem porque o agente ainda não foi implementado. Você precisa concluir isso nesta etapa.

Abra o arquivo routes/index.js e observe os três endpoints recém-adicionados:

• /messages: recebe o arquivo de visualização messages.ejs e o renderiza no navegador. Ao clicar em uma conversa no índice, você acessa uma dessas páginas.
• /retrieveMessages: recebe o conteúdo de uma conversa e retorna uma lista formatada de todas as mensagens da conversa. A página de mensagens chama periodicamente esse endpoint para exibir 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". Ela não foi implementada no momento.

Agora, confira o método storeAndSendResponse já existente:

step-3/routes/index.js (em inglês)

/**
 * 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. O método armazena primeiro os dados da mensagem recebida no objeto do Cloud Datastore para a conversa. Em seguida, ele envia a mensagem de resposta. Observe com atenção o objeto de mensagem que ele cria, especialmente no tipo de representante.

Agora, implemente o endpoint /sendMessage. Você pode usar o método storeAndSendResponse já existente para fazer a maior parte do trabalho. O importante é lembrar de definir o representante correto.

Quando tudo estiver pronto, reimplante o app e volte à sua conversa no CRM. Agora suas mensagens vão aparecer no histórico de chat. Também é possível ver as mensagens do agente no dispositivo móvel de teste.

Antes de continuar, saiba como os novos endpoints funcionam. Na próxima etapa, você vai adicionar seu próprio endpoint para sair da conversa.

5. Saindo da conversa

Depois de ajudar o usuário com as perguntas dele, você pode sair da conversa e permitir que o usuário 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 volte à conversa. Agora há um link Fechar e sair da conversa na parte de baixo da conversa. Esse link ainda não funciona porque o endpoint leaveConversation não foi implementado.

Observe o arquivo index.js. Há um comentário TODO instruindo você a criar um novo endpoint leaveConversation.

step-4/routes/index.js (em inglês)

/* 
 * 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, você precisa reunir tudo o que aprendeu no codelab até agora. Esse endpoint precisa fazer o seguinte:

• Atualize a linha de execução para a BOT_THREAD_STATE.
• Envie 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. Lembre-se de que o representante voltou para BOT.

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 sabe necessariamente que está falando com o bot Echo de novo. 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 da parte, seu atendente 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 de agentes em tempo real da sua empresa e veja o que você consegue.

6. Conclusão

Parabéns por concluir o codelab de transferência de agente em tempo real.

Você criou um agente que lida com transferências 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 o Live Agent Transfer, você pode deixar as solicitações comuns para seu bot, enquanto seus atendentes lidam com consultas mais complexas. Seus usuários ficarão mais satisfeitos com a nova experiência, que será personalizada e útil, aumentará a probabilidade de eles retornarem e recomendarem sua empresa a amigos.

Qual é a próxima etapa?

Confira alguns destes codelabs:

• Comprar on-line para retirada na loja (parte 1)
• Comprar on-line para retirada na loja (parte 2)

Leia mais

• Revise os princípios básicos da transferência de agente ao vivo com o guia de transferência de um bot para um agente humano.
• Faça upgrade do seu bot eco para um bot de perguntas frequentes com o guia do Dialogflow.

Documentos de referência

• Método: conversations.events.create
• Método: conversas.messages.create
• Recurso: evento
• Representativo