Integração Hubspot - Histórico de Atendimento 28 de novembro de 2022 13:37 Atualizado índice: Como funciona o Histórico de Atendimento Pré-Requisitos Configurando seu bot para registrar o histórico de atendimento Configurando o bloco de Atendimento Humano Configurando a aba Condições de saída Aba Conteúdo Aba Ações Cabeçalhos, Método e URL Corpo Variáveis de resposta Como funciona o Histórico de Atendimento Essa integração registra os atendimentos realizados na nossa ferramenta de atendimento, o Blip Desk. Ao finalizar um ticket de atendimento, o histórico da conversa com o atendente é registrado na atividade do contato na Hubspot. É importante ressaltar que em casos de transferência de atendimento, só é registrado o último ticket que foi finalizado. Obs: Caso esteja utilizando o recurso de router, será necessário adicionar um cabeçalho a mais, o processo de configuração deste cabeçalho segue abaixo, lembrando que a chave utilizada deve ser a do sub bot de atendimento humano. Pré-Requisitos 1 - Antes de tentar registrar um lead na HubSpot é necessário que em seu bot já tenha sido instalado o plugin da HubSpot previamente. Caso não tenha realizado esse processo, saiba Como integrar o Contato Inteligente aos fluxos de trabalho na HubSpot. 2 - É obrigatório que todo o fluxo de registro de lead tenha sido devidamente configurado e funcional, de modo que o lead tenha sido cadastrado antes de tentarmos transcrever seu ticket. 3 - É necessário que o atendimento humano tenha ocorrido e finalizado corretamente, sendo que durante o atendimento, exista a troca de mensagens entre o atendente e o cliente. 4 - O e-mail é chave para registro desse ticket, ou seja, caso o mesmo usuário informe outro e-mail, será registrado outro contato no Hubspot com o registro do ticket, podendo gerar comportamentos estranhos na integração. 5 - Ter realizado previamente a integração com a Hubspot no roteador (caso este recurso esteja sendo utilizado) ou em seu bot monolítico. 6 - Conhecimento básico de criação de fluxos no Blip. Configurando seu bot para registrar o histórico de atendimento Diferentemente do registro de Leads, o registro de histórico de atendimento não requer nenhuma informação especial para viabilizar este registro. Importante! Ter o e-mail do usuário definido no contato se faz necessário, pois, a integração utilizará esta informação para identificar para qual usuário transcrever o atendimento humano. Configurando o bloco de Atendimento Humano Antes de mais nada, é necessário fazer as configurações iniciais do bloco de atendimento humano caso ainda não o tenha feito. A documentação deste procedimento está disponível aqui. Para demonstrar como fazer essa configuração, presumimos que o seu fluxo conversacional já tenha sido criado, seja utilizando roteador ou criando um bot único e que em algum nível, o bot de atendimento humano se assemelhe muito ao fluxo hipotético abaixo, onde principalmente, já tenhamos o lead criado e o bloco de atendimento humano devidamente configurado. Neste cenário, independentemente de qual seja o bloco para o qual o atendimento humano esteja direcionando o fluxo após à sua execução (no exemplo acima, é o bloco chamado “Finalizacao”), iremos mudar este comportamento e direcionar o fluxo para um novo bloco o qual iremos renomear para Transcreve Atendimento Humano, deixando para este, a responsabilidade de direcionar para o Finalização. Configurando a aba Condições de saída Obs.: Antes de dar maiores explicações sobre as configurações desta aba, informamos que não recomendamos que outras configurações que não sejam as mencionadas neste documento sejam criadas no bloco Transcreve Atendimento Humano, visando sempre não poluir a variável input.content. Após criar e renomear o Novo bloco para Transcreve Atendimento Humano, selecione o bloco de Atendimento Humano e acesse a aba Condições de saída. Altere o valor de todos os campos Ir para onde consta Finalização de modo que apontam para o novo bloco que criamos que se houver sido criado de acordo com o instruído no parágrafo anterior, deveria se chamar Transcreve Atendimento Humano. Com isso, o resultado obtido deve ser similar à imagem abaixo. Feito este procedimento, precisamos agora atribuir ao bloco Transcreve Atendimento Humano a responsabilidade de direcionar para o Finalizacao, para isso, selecione o bloco Transcreve Atendimento Humano, selecione a aba Condições de saída e simplesmente altere os valores contidos neste bloco naa seções CONDIÇÕES DE SAÍDA e SAÍDA PADRÃO de acordo com as instruções a seguir CONDIÇÕES DE SAÍDA - Se Resposta do Usuário -> Condição Existe -> Ir Para Finalizacao (no caso do seu fluxo conversacional, será para o bloco ao qual o Atendimento Humano redirecionava anteriormente). SAÍDA PADRÃO - Em em Ir para, definir como o mesmo valor utilizado na aba de Ir para do passo anterior (CONDIÇÕES DE SAÍDA). O resultado desta configuração está demonstrado na imagem abaixo: Observação: Os passos abaixo precisam ser configurados APENAS no bloco Transcreve Atendimento Humano. Aba Conteúdo Selecione o bloco Transcreve Atendimento Humano de modo a aparecer o menu de configurações do bloco no canto direito da tela. Na aba de conteúdo passe o cursor do mouse pela área de “Entrada do usuário” e remova este conteúdo selecionando o ícone laranja de “lixeira”. Aba Ações Finalizada a configuração da aba Conteúdo, selecione a aba Ações para configurar a requisição de registro de histórico de atendimento. Para isso, clique em adicionar uma ação de entrada e logo após, selecione Requisição HTTP conforme abaixo: Cabeçalhos, Método e URL No menu “Método” selecione POST Em URL cole: https://hubspot.cs.blip.ai/api/HubSpot/v2/chat/history Expanda a aba Cabeçalhos: Adicione dois cabeçalhos clicando no botão + adicionar cabeçalho. No primeiro, em Key, preencha BotId e em Value informe o ID do bot que foi utilizado para criar a integração. Esta informação pode ser encontrada na página inicial do bot na qual a integração foi criada, como mostrado na imagem abaixo. Imagem ID do bot. Esta página pode ser acessada ao clicar na foto do seu bot destacado no canto superior esquerdo juntamente ao texto “principal97”. Observação: O ID a ser informado na aba Value onde a Key é BotId deverá ser o do bot no qual a HubSpot foi integrada. Preferencialmente, o bot a realizar a integração deverá ser sempre o router, caso este recurso esteja sendo utilizado, logo neste cenário, deve-se sempre utilizar em Value o ID do bot router. No segundo, em Key, preencha TicketId e em Value cole o valor em negrito destacado a frente {{input.content@id}}. Observação: Lembrando que a chave utilizada deve ser a do sub bot de atendimento humano. Caso esteja utilizando o recurso de router, será necessário adicionar um cabeçalho a mais, o processo de configuração deste cabeçalho segue abaixo. No terceiro (apenas para routers), para cada um dos seus bots conectados ao seu router e que realizem atendimento humano, realize os passos abaixo. Selecione as configurações do bot no menu principal conforme indicado na imagem abaixo: No menu de configurações, selecione informações de conexão conforme destacado na imagem a seguir: Desça a barra de rolagem até encontrar o item “Endpoints HTTP” e copie o valor da “Authorization Key” do seu bot clicando no ícone com dois quadrados conforme indicado na imagem abaixo: Regresse ao builder e selecione novamente o bloco que tiver criado de acordo com o bloco “Transcreve Atendimento Humano” apresentado neste documento, em seguida selecione a aba “Ações”. O passo está descrito na imagem abaixo: Selecione a requisição HTTP criada anteriormente e acesse os cabeçalhos da requisição, adicionando o valor “Authorization” no campo destacado como “Key” e o valor copiado do “Authorization Key” obtido nos passos anteriores no campo “Value” conforme mostrado nas imagens a seguir: Publique o fluxo do seu bot e lembre-se de fazer este procedimento em todos os bots que realizem “Atendimento Humano”. Corpo Corpo: Ao clicar na opção corpo, apague todo conteúdo da aba builder.json e preencha esta aba com o valor abaixo, também representado na próxima imagem: { "contact" : {{contact.serialized}}, "integrations" : [ ]} Entre os colchetes, iremos listar para quais integrações com a HubSpot queremos que a transcrição de atendimento humano ocorra, sendo que, ao deixar vazio conforme na última imagem acima, por padrão esse atendimento será transcrito para TODAS as contas com as quais o seu bot informado no cabeçalho da requisição tenha integrado. Para informar as integrações específicas com as quais queremos que a transcrição ocorra, precisaremos consultar a tela inicial do nosso Plugin e verificar os nomes que demos à nossas integrações, o passo a passo fica descrito nas imagens abaixo: Agora que sabemos o nome da nossa integração, podemos copiar e colar o nome dela dentro da área definida pelos colchetes da requisição que vimos anteriormente, para isso, volte na sua requisição HTTP, selecione corpo novamente, e dentro de aspas duplas e entre os colchetes cole o nome da sua integração, ficando conforme abaixo: Observação: Você deverá usar o nome da sua integração e não o nome exemplo deste documento. Para simular um cenário onde eu teria múltiplas integrações, imagine que na minha tela de integrações do Plugin, além da integração Demonstração Documentação, houvesse também outras três integrações chamadas N2, N3 e N4 por exemplo, onde eu não quisesse transcrever o atendimento humano para a N2. Neste caso, é preciso apenas adicionar uma vírgula, separando a integração anterior da posterior, sendo que a última integração listada sempre virá livre de vírgulas, listando as integrações N3 e N4 conforme representado na próxima figura: Repare que a integração N4, que é a última listada na imagem, vem desacompanhada de vírgula e que a integração N2 não foi listada, isso significa que a transcrição de atendimento humano irá ocorrer em todas as integrações, exceto em N2. Desta forma podemos controlar quais integrações irão receber as operações de atendimento humano através do Blip. Ao finalizar o processo de configuração das integrações a serem realizadas na tela de corpo, utilize o comando do teclado CTRL + S para salvar as suas alterações e publique o fluxo do seu bot. É possível perceber que as operações foram salvas ao notar que o círculo cinza ao lado do texto builder.json tiver desaparecido, tendo sido substituído pelo ícone de X conforme abaixo: Variáveis de resposta Antes de mais nada, não recomendamos a utilização das variáveis a serem definidas nesta etapa para definir nenhuma lógica de fluxo do seu chatbot. Informamos também que nem mesmo se faz necessário preencher alguma coisa nestes campos, podendo deixá-los completamente vazios, porém, caso ainda assim, deseje preencher estes campos, recomendamos apenas dar nomes significativos para estas variáveis, sendo algo como por exemplo attendanceTranscriptionStatus e attendanceTranscriptionResponse. Variável para status da resposta: Neste campo, basta definir uma variável para armazenar o valor da resposta da nossa API. Este ponto é opcional, porém recomendado para casos onde se deseje avaliar o comportamento da API. Por padrão, a resposta da API deverá ser 204 No Content. Lógicas de fluxo de bot para cenários onde a API der uma resposta diferente de 204 ficam a encargo de cada usuário, assim como as ações que o bot irá tomar diante destes cenários adversos. Para se entender mais sobre status de respostas HTTP, recomenda-se o estudo do protocolo REST. Variável para o corpo da resposta: Variável opcional. Nos casos de sucesso nenhum valor será atribuído a esta variável, pois, a mesma referência No Content (recomenda-se o estudo da resposta REST 204 para aqueles que não tem conhecimento deste protocolo de comunicação HTTP). Em casos de falha, uma mensagem descritiva da falha deverá vir preenchida neste campo.Para maiores informações sobre ação Requisição HTTP consulte este link: Considerações FinaisPortanto, para que o seu bot esteja apto a realizar o registro de histórico de atendimento é necessário/recomendável: Configurar o registro de lead e registrar devidamente o Lead na HubSpot com o campo de e-mail preenchido. Configurar o atendimento humano, selecionando o canal desejado, ativando-o, montando suas filas de atendimento, regras e definindo atendentes. Criar um bloco no Blip que será responsável por ações relacionadas à transcrição de atendimento humano. Definir uma ação de Requisição HTTP que irá enviar as informações do contato para nossa API de integração com a HubSpot que por sua vez irá transcrever o atendimento na HubSpot. Registro de Histórico de Atendimento na HubSpot Validando registro Uma vez que todas as configurações descritas acima tenham sido realizadas corretamente, quando os usuários interagirem com o bot, o registro do histórico de atendimento deverá ser criado com sucesso na HubSpot na timeline de eventos do usuário, conforme abaixo: Para acessar essa tela, navegue pela HubSpot acessando Contatos -> Contatos -> e por último, selecione o contato para o qual o atendimento humano foi transcrito. Caso não esteja aparecendo, certifique-se de selecionar a nossa integração com a HubSpot nos filtros de atividade, conforme abaixo: Para mais informações, acesse a discussão sobre o assunto em nossa comunidade ou os vídeos no nosso canal. 😃 Artigos relacionados Como instalar o aplicativo de integração da HubSpot Como disparar notificações através da integração com a Hubspot Como fazer o registro de leads na HubSpot Extensão Hubspot (Lanum) Como salvar o histórico de atendimento humano via Integração do Blip com Google Drive