Exibir código-fonte para WhatsApp Business API oficial

Neste capítulo, falaremos sobre o funcionamento da integração do Recuperador CRM com o WhatsApp Business API (WBA) oficial da Meta (antigo Facebook).

Em resumo, a integração lida tanto com as mensagens recebidas dos devedores de forma centralizada e integrada com o CRM, além de permitir a automatização de disparos de mensagens (templates aprovados na Meta, evitando banimentos) por meio dos recursos já existentes do sistema (notificações automáticas, régua de cobrança, mala direta etc). Ela também vem com uma central de atendimento (URA) integrada ao portal de negociação, para permitir a visualização de dívidas, segunda via de parcela de acordos e também permite o fechamento de novos acordos sem a necessidade de interação com o consultor. Por fim, temos integração com o ChatGPT para deixar essas funcionalidades mais simples para os clientes.

Em se tratando da gestão da comunicação com os clientes, a integração é bastante completa e permite enviar e receber áudio, imagem, vídeo e documento. Além disso, é possível filtrar os devedores de acordo com o consultor ou advogado responsável. Existe recurso de transferência de atendimentos, pesquisa de satisfação, relatórios, gráficos e mais.


== Planos ==

Para utilizar a integração com o WhatsApp Business API oficial, é necessário contratar um plano junto ao Recuperador CRM que permita o acesso aos recursos desejados.

A troca de mensagens pelo aplicativo WhatsApp é gratuita, mas via API não é. As mensagens são tarifadas pela Meta e o formato de cobrança, bem como os valores estão sujeitos a alteração. O modelo de parceria do Recuperador CRM com a Meta exige que o valor das mensagens seja pago diretamente para a Meta, pois somos uma empresa provedora de Soluções Meta. Por favor, confira os preços com nossa equipe comercial.

Visando um preço mais justo e competitivo, cada funcionalidade é cobrada a parte. Seguem as funcionalidades disponíveis para contratação:

# Inclusão de números de telefone para atendimento receptivo ou disparo de mensagens;
# Atendimento receptivo feito por consultores, advogados ou gestores;
# ChatGPT;

É importante destacar que alguns recursos como a URA ou o ChatGPT dependem do [[Portal de negociação]]. Logo, sua contratação também pode ser necessária.

Assim como a Meta, o OpenAI, desenvolvedora do ChatGPT também cobra pela utilização de sua API. No caso da integração com o ChatGPT, será cobrado um valor adicional pelo volume de tokens (palavras) utilizadas nas mensagens enviadas e recebidas pelo ChatGPT. Por favor, confira os preços com nossa equipe comercial.


== Configuração inicial ==

O primeiro passo é habilitar a integração no perfil do administrador. Isso pode ser feito logado como administrador por meio do menu '''User > Perfil > aba WhatsApp Business API'''. Mude o campo '''Habilita WhatsApp Business API''' para '''Sim''' e clique em '''Salvar'''.

Feito isso, serão habilitados diversos campos nesta aba WhatsApp Business API, bem como alguns botões. Exploraremos estas configurações em detalhes no decorrer desta documentação.


== Configuração do APP ==

A configuração do aplicativo WhatsApp Business depende do procedimento de onboarding na Meta. Esse procedimento será responsável por fazer o vínculo do Recuperador CRM com sua conta na Meta. Isso permitirá o cadastro do seu número de telefone e posteriomente permitirá que você vincule seu cartão de crédito na Meta. 

Para fazer o onboarding, você deverá efetuar o login com sua conta do Facebook por meio do menu '''User > Perfil > aba WhatsApp Business API > botão Login com Facebook'''. Durante o login com Facebook, você autorizará o Recuperador CRM (Catalina Sistemas de Informação Ltda) a acessar seus dados na Meta e criar um aplicativo para você. Isso gerará o  '''Business ID''' e o '''Access Token''' que serão informados automaticamente em '''User > Perfil > aba WhatsApp Business API'''. 

Ao término do login com Facebook, será necessário clicar no botão '''Cadastro de números''' para verificar se o telefone foi cadastrado corretamente e também clicar no botão '''Webhooks''', para verificar se o webhook foi cadastrado corretamente durante o onboarding.

Por fim, deve-se cadastrar o cartão de crédito em https://business.facebook.com usando o menu '''Cobranças e Pagamentos > Contas do WhatsApp Business'''. Também, é necessário acessar o menu '''Informações da Empresa''' e analisar o campo '''Status de verificação da empresa''' para iniciar a verificação do negócio, se necessário.


== Cadastro de números de telefone ==

É necessário cadastrar o número dos telefones que serão usados para recebimento e envio das mensagens na Meta e fazer a verificação de dois fatores. Conforme dito na explicação sobre planos, o cadastro de múltiplos números é sujeito a tarifação e a Meta libera apenas dois cadastros inicialmente com limite baixo de mensagens por dia. Esse limite serão automaticamente incrementado pela Meta de acordo com a utilização do sistema.

Cadastre seus números em https://business.facebook.com e depois faça o vínculo no Recuperador CRM, por meio do menu '''User > Perfil > aba WhatsApp Business API > botão Cadastro de números'''. A tela inicial exibirá todos os telefone cadastrados. Clique no botão '''Adicionar''' para configurar um novo número, informe os dados obrigatórios (marcados com um asterisco) e clique em Salvar.

Em alguns casos, será necessário clicar no ícone Reg. (registrar) em frente ao número cadastrado no Recuperador CRM para fazer o registro do número na Meta.

É possível cadastrar vários telefones de acordo com seu plano, desde que apenas um seja o telefone principal. O telefone principal serve para centralizar o cadastro de templates, que são os modelos de mensagens a serem enviados para os devedores.

Ter vários números de telefone pode ser vantajoso no disparo das mensagens, uma vez que o sistema fará a alternância dos números, dificultando o bloqueio dos telefones por parte dos devedores.


== Cadastro de templates ==

A Meta não permite o disparo de uma mensagem qualquer para um número, sem que ele tenha conversado com você em menos de 24h. Isso é chamado de janela de conversação. 

Para enviar uma mensagem para alguém fora da janela de conversação, a Meta exige que essa mensagem seja proveniente de um template aprovado, ou seja, você deverá criar um modelo de mensagem e enviar para aprovação na Meta. Quando a Meta aprovar este template, ele poderá então ser utilizado em novos disparos.

O template aceita variáveis, ou seja, códigos que serão substituídos dinamicamente por dados do cliente, das dívidas, do acordo, do credor etc.

Cadastre seus templates em '''User > Perfil > aba WhatsApp Business API > botão Templates''. A tela inicial exibirá todos os templates cadastrados. A coluna Status exibe a situação do template, lembrando que apenas templates aprovados poderão ser enviados. Clique no botão '''Adicionar''' para cadastrar um novo template, informe os dados obrigatórios (marcados com um asterisco) e clique em Salvar.

O cadastro do template é segmentado em título, cabeçalho, corpo e rodapé. O título é o nome do template e será utilizado para localização do mesmo na tela dos disparos. Utilize um nome fácil e descritivo para o título. O título do template não pode conter espaços, caracteres especiais e nem acentos. Exemplo de título: vamos_conversar ou parcela_vencida_ha_alguns_dias.

O cabeçalho do template é uma informação curta a ser exibida em negrito no início da mensagem. O corpo do template é a mensagem propriamente dita e aceita variáveis. Por fim, o rodapé é a última linha da mensagem e possui uma formatação diferente, com menor destaque no texto. 

Uma forma de testar a configuração do APP e o cadastro de templates é utilizar o botão '''Testar envio''' presente em '''User > Perfil > aba WhatsApp Business API'''. Selecione um template que não possua variáveis, informe um telefone com DDD sem o zero e clique em '''Enviar'''.



== Disparo de mensagens ==

Conforme explicado na seção sobre templates, o disparo ativo de mensagens deve ser feito por meio de uma mensagem de template, sendo que esse template deve ter sido aprovado pela Meta. 

É possível utilizar os recursos padrão de envio de mensagens do Recuperador CRM para automatizar disparos ou efetuar disparos manuais de mensagens de WhatsApp para os devedores. Segue a lista de recursos de disparo de mensagens que incluem WhatsApp Business API:

# Mensagem individual na tela de negociação do devedor;
# Notificações automáticas;
# Régua de cobrança;
# Mala direta;

=== Mensagem individual na tela de negociação do devedor ===

Para permitir o envio da mensagem individual na tela de negociação do devedor, deve-se habilitar o parâmetro '''Permite envio de templates do WhatsApp API na tela de negociação''' nos parâmetros globais do credor. O caminho completo para ajuste deste parâmetro é: '''Cadastros > Credores > ícone alt.''' (alterar) em frente ao credor desejado > aba '''Parâmetros Globais''' > campo '''Permite envio de templates do WhatsApp API na tela de negociação'''. Mude o valor deste campo para '''Sim''' e clique em '''Salvar'''.


[[Arquivo:TelaNegociacaoDestaqueTemplatesWBA.png | none | 900px]]
''[[:imagem:TelaNegociacaoDestaqueTemplatesWBA.png| Tela de negociação do devedor com destaque para o botão Templates WhatsApp Business API]]''


Ao clicar no botão Templates WhatsApp Business API na tela de negociação do devedor, o sistema exibirá o formulário para seleção do template a ser enviado. Clique em Enviar para confirmar o disparo da mensagem. 


[[Arquivo:BotaoTemplateTelaNegociacao.png | none | 900px]]
''[[:imagem:BotaoTemplateTelaNegociacao.png| Formulário de envio de template do WhatsApp Business API na tela de negociação do devedor]]''


Dessa forma, a mensagem será enviada para os números de telefone cadastrados no cadastro do devedor em questão e um follow-up será automaticamente gerado com o nome do template enviado.

=== Notificações automáticas e régua de cobrança ===

Para disparar [[Notificações automáticas]] ou [[Régua de cobrança]] é necessário '''criar um texto''', que é a mensagem a ser enviada com suas respectivas variáveis para serem substituídas por dados dos devedores, dívidas acordos etc. Quando a integração com o WhatsApp Business API estiver habilitada, será exibido um campo no cadastro de textos para seleção de um '''template aprovado''' na Meta para disparo pelo WhatsApp Business API como é mostrado abaixo.


[[Arquivo:CadastroTextoDestaqueTemplate.png | none | 900px]]
''[[:imagem:CadastroTextoDestaqueTemplate.png| Cadastro de textos com destaque para a seleção do template ]]''


Além disso, é necessário selecionar o '''formato''' de envio da notificação automática ou régua de cobrança para incluir '''Template do WhatsApp API oficial'''.


[[Arquivo:CadastroNotificacaoAutoDestaqueFormatoWBA.png | none | 900px]]
''[[:imagem:CadastroNotificacaoAutoDestaqueFormatoWBA.png| Cadastro de notificação automática com destaque para a seleção do formato do WBA ]]''

=== Mala direta ===

Assim como nas notificações automáticas e régua de cobrança, é necessário definir as mensagens e selecionar um formato para envio de uma [[Mala direta]]. Dessa forma, será necessário selecionar o template aprovado na Meta ao criar o conteúdo da mala direta e também selecionar o formato que inclua o WBA no disparo das mensagens.


[[Arquivo:CadastroMalaDiretaDestaqueTemplateWBA.png | none | 900px]]
''[[:imagem:CadastroMalaDiretaDestaqueTemplateWBA.png| Cadastro de mala direta com destaque para a seleção do template ]]''


Ao diparar uma mala direta, é necessário informar o formato do disparo. Neste momento, selecione '''Template do WhatsApp API oficial'''. 


[[Arquivo:NotificarMalaDiretaDestaqueFormatoWBA.png | none | 900px]]
''[[:imagem:NotificarMalaDiretaDestaqueFormatoWBA.png| Formulário de envio das notificações de mala direta com destaque para a seleção do formato do WBA ]]''

== Atendimento receptivo ==

O atendimento receptivo acontece quando o devedor envia uma mensagem para um dos telefones integrados ao WhatsApp Business API seleciona a '''opção Atendente no menu principal''' ou digita '''#atendente'''. 


[[Arquivo:TelaAppWhatsMenuPrincipalDestaqueAtendente.png | none | 900px]]
''[[:imagem:TelaAppWhatsMenuPrincipalDestaqueAtendente.png| Tela de uma conversa no app WhatsApp com destaque para a opção Atendente ]]''


Se o seu plano permitir atendimento receptivo, será possível ativar esse recurso em '''User > Perfil > aba WhatsApp Business API > Exibir opção para falar com um atendente no WhatsApp Business API'''. Altere este campo para '''Sim''' e salve.

Após ativar o recurso, você poderá liberar o acesso para consultores e advogados. Isso pode ser feito por meio dos parâmetros '''Permite acesso de consultores no WhatsApp Business API''' e '''Permite acesso de advogados no WhatsApp Business API''' respectivamente, também presentes na tela '''User > Perfil > aba WhatsApp Business API'''.

A lista de conversas do WhatsApp Business API pode ser acessada por meio do '''ícone do WhatsApp''' no canto superior direito da tela. 


[[Arquivo:DashboardDestaqueIconeWhatsApp.png | none | 900px]]
''[[:imagem:DashboardDestaqueIconeWhatsApp.png| Tela do dashboard do administrador com destaque para o ícone do WhatsApp ]]''


Esse ícone será exibido para o administrador e para gestores. Consultores ou advogados também visualizarão este ícone dependendo dos parâmetros '''Permite acesso de consultores no WhatsApp Business API''' e '''Permite acesso de advogados no WhatsApp Business API''' explicados anteriormente. O ícone ficará em cor vermelha quando houver uma ou mais mensagens não lidas.


[[Arquivo:TelaConversasWBA.png | none | 900px]]
''[[:imagem:TelaConversasWBA.png| Tela de conversas do WhatsApp Business API]]''


A lista de conversas do WhatsApp Business API exibe um resumo das conversas ativas e é atualizada automaticamente a cada 10 segundos. Clique no '''ícone vis.''' em frente a conversa desejada para entrar na tela de chat. A tela de conversas também possui botões para filtrar as conversas por '''conversas sem responsável''' e também permite acesso ao '''Relatório de conversas'''. 


[[Arquivo:TelaConversasWBANaoLidas.png | none | 900px]]
''[[:imagem:TelaConversasWBANaoLidas.png| Tela de conversas do WhatsApp Business API com destaque para conversas novas ]]''


É importante destacar que a lista de conversas nos logins de consultor e advogado pode ser diferente da lista com o login de gestores. Isso acontece porque o sistema pode ter sido configurado para atribuir um consultor no cadastro do devedor. Nesse caso, somente serão exibidas conversas de devedores do consultor logado. Os advogados somente visualizarão conversas de devedores que possuam dívidas do tipo pré-processual cujo advogado é o advogado logado.


[[Arquivo:TelaChatBotWBA.png | none | 900px]]
''[[:imagem:TelaChatBotWBA.png| Tela de chat do WhatsApp Business API]]''


A tela do chat exibe a lista das conversas ativas no canto esquerdo da tela e as mensagens da conversa atual são exibidas na parte central. Uma '''nova mensagem''' pode ser enviada por meio do formulário da parte inferior da tela. O sistema permite o envio e recebimento de mensagens de texto, áudio, documento, imagem e vídeo. Também é possível usar a opção resposta para selecionar uma mensagem a ser respondida.


No rodapé da tela, são apresentados detalhes da conversa e opções extras. Antes de começar um atendimento, o usuário deverá assumir a sessão. Para isso, clique no '''link Assumir''' presente no canto inferior direito da tela. Para encerrar um atendimento, clique em '''Encerrar'''. O link '''Transferir''' serve para transferir esta sessão para outro usuário e o link '''Negociação''' é um atalho para a tela de negociação do devedor para facilitar o cadastro de acordos, visualização das dívidas, geração de demonstrativo de débitos etc.


Ao '''encerrar uma sessão''' de atendimento, o sistema gerará automaticamente um '''follow-up''' na tela de negociação do devedor com todas as mensagens da conversa encerrada. 


Se o parâmetro '''Exibir pesquisa NPS ao término dos atendimentos no WhatsApp Business API''' estiver definido como Sim no perfil do administrador, então o sistema disponibilizará ao devedor um link de acesso ao formulário de avaliação logo após o encerramento do atendimento.

== URA ==

A URA permite exibir os botões '''Consultar Dívidas''' e '''Meus Acordos''' no '''menu inicial''' do atendimento automático para permitir a autonegociação das dívidas no WhatsApp no formato do chatbot do portal de negociação. Este recurso depende da configuração do [[Portal de negociação]].


[[Arquivo:TelaMenuPrincipalDestaqueUra.png | none | 900px]]
''[[:imagem:TelaMenuPrincipalDestaqueUra.png| Tela de uma conversa no app WhatsApp com destaque para as opções da URA ]]''


Se o seu plano permitir acesso ao portal de negociação, será possível ativar esse recurso em '''User > Perfil > aba WhatsApp Business API > Exibir URA de negociação no WhatsApp Business API'''. Altere este campo para '''Sim''' e salve.

Em resumo, o objetivo da URA é tentar simplificar a conversação, guiando o usuário por etapas até o fechamento do acordo e geração do link da fatura para pagamento. É importante ressaltar que o comportamento de negociação segue a configuração do portal de negociação. 

Dessa forma, ao clicar em '''Consultar dívidas''' a URA exibirá um resumo das dívidas do devedor com o credor, oferecerá a opção de acordo para todas as dívidas e permitirá a visualização de detalhes das dívidas. Se a parametrização permitir, também será possível fazer o acordo para uma dívida individualmente. 


[[Arquivo:UraConsultaDividas.png | none | 900px]]
''[[:imagem:UraConsultaDividas.png| Exemplo de navegação pela URA de consulta de dívidas no app WhatsApp ]]''


O usuário poderá selecionar o parcelamento desejado, previamente definido nas configurações do portal de negociação. Este parcelamento pode conter descontos também definidos no portal de negociação. Ao confirmar, a URA gerará o acordo e exibirá o link da fatura para pagamento. 


[[Arquivo:UraFechamentoAcordo.png | none | 900px]]
''[[:imagem:UraFechamentoAcordo.png| Exemplo de fechamento de acordo pela URA no app WhatsApp ]]''


Já a opção '''Meus acordos''' permite a visualização de detalhes dos acordos em andamento. Isso é especialmente útil para obter a segunda via para pagamento ou para visualização do termo de acordo, quando parametrizado no credor.


[[Arquivo:UraMeusAcordos.png | none | 900px]]
''[[:imagem:UraMeusAcordos.png| Exemplo de visualização de acordo pela URA no app WhatsApp ]]''


Caso seu plano não permita o acesso ao portal de negociação ou você não queira permitir a negociação de dívidas pelo portal, é possível ativar o parâmetro '''Exibir visualização de débitos no WhatsApp Business API''' também presente em em '''User > Perfil > aba WhatsApp Business API''' para exibir o botão '''Minhas Dívidas''' no '''menu inicial''' do atendimento automático. Esse botão permite a verificação das dívidas no WhatsApp, mas não permite a autonegociação e serve apenas para informação sobre dívidas. Portanto, não tem relação com o portal de negociação.

== ChatGPT ==

O recurso do ChatGPT permite exibir o botão '''Assistente''' no '''menu inicial''' do atendimento automático para permitir a conversa com o ChatGPT. O devedor também pode acionar o ChatGPT por meio do comando #assistente. Assim como na URA, este recurso depende da configuração do [[Portal de negociação]].


[[Arquivo:TelaMenuPrincipalAssistente.png | none | 900px]]
''[[:imagem:TelaMenuPrincipalAssistente.png| Tela de uma conversa no app WhatsApp com destaque para a opção do assistente (ChatGPT) ]]''


Se o seu plano permitir acesso ao portal de negociação e também ao ChatGPT no WhatsApp Business API, será possível ativar esse recurso em '''User > Perfil > aba WhatsApp Business API > Exibir opção para falar com ChatGPT no WhatsApp Business API'''. Altere este campo para '''Sim''' e salve.

Em resumo, o objetivo do ChatGPT é tentar simplificar a conversação da URA, guiando o usuário por texto e não por etapas até a geração do link para seleção do parcelamento e confirmação do acordo. É importante ressaltar que o comportamento de negociação segue a configuração do portal de negociação. 


[[Arquivo:ChatGptAcordosEmAndamento.png | none | 900px]]
''[[:imagem:ChatGptAcordosEmAndamento.png| Tela de uma conversa no app WhatsApp buscando informações sobre acordos em andamento ]]''


O ChatGPT é capaz de acessar funções do sistema para retornar dados. Segue a lista de ações que o ChatGPT consegue executar:

# Lista de acordos do devedor;
# Lista de parcelas de um acordo;
# Lista de vendas;
# Lista de dívidas com o credor para acordo total;
# Detalhes de uma dívida com link para acordo, quando permitido;
# Transferência para um atendente, quando configurado;

Existem configurações para determinar o comportamento do ChatGPT em '''User > Perfil > aba WhatsApp Business API '''. Segue uma breve explicação sobre as principais configurações do ChatGPT:

'''Mensagens de segurança de sistema do ChatGPT no WhatsApp Business API''': define as mensagens de segurança do ChatGPT para controle de escopo de conversa no WhatsApp Business API. Isso é importante definir o nome da empresa, nome do assistente e principalmente para focar a conversa na negociação e evitar que o devedor faça perguntas genéricas e o ChatGPT responda, aumentando os custos desnecessariamente. O sistema já vem com orientações básicas definidas nesse campo. Recomendamos apenas pequenas alterações neste conteúdo.

'''Limite de mensagens de histórico por conversa do ChatGPT no WhatsApp Business API''': define a quantidade máxima de mensagens anteriores a serem incluídas na conversa atual. O histórico de mensagens é importante para contextualização das respostas, porém, elas aumentam o volume de tokens e, consequentemente, aumentam o tempo de processamento e os custos. O valor sugerido aqui são 10 mensagens.

'''Quantidade máxima de tokens de saída do ChatGPT no WhatsApp Business API''': define a quantidade máxima de tokens (palavras) a serem gerados pelas respostas do ChatGPT. Lembrando que, quanto maior o volume de tokens, maior será o tamanho do texto retornado, bem como o tempo de processamento e os custos serão maiores. O valor sugerido para este campo é 800.

'''Parâmetro temperatura do ChatGPT no WhatsApp Business API''': define o valor do parâmetro temperatura do ChatGPT. Quanto maior for o valor da temperatura, maior será a criatividade das respostas do ChatGPT. A criatividade está associada ao retorno de palavras que não são muito utilizadas no dia a dia. Sugestão: 5 para uma criatividade média.

== Relatórios e dashboard ==

No dashboard do administrador, será exibida a aba '''Indicadores do WhatsApp API''', contendo gráficos e indicadores específicos para as principais atividades do WhatsApp Business API. 


[[Arquivo:DashboardDoAdmWBA.png | none | 900px]]
''[[:imagem:DashboardDoAdmWBA.png| Dashboard do administrador com destaque para a aba Indicadores do WhatsApp API ]]''


Na parte inferior da tela '''User > Perfil > aba WhatsApp Business API''', existem alguns botões para relatórios do WhatsApp Business API, com destaque para o '''Relatório de NPS''', para acompanhamento das avaliações dos atendimentos. O '''Relatório de templates''' permite acompanhar os disparos de templates por período, o '''Relatório de sessões''' permite acompanhar as sessões abertas por período e '''Conversas''' permite acesso ao '''botão Relatório de conversas'''.