Introdução
O chatbot para WhatsApp permite responder automaticamente a solicitações, enviar notificações, solicitar informações, tornando a comunicação eficaz e disponível 24/7.
Este guia para desenvolvedores é uma instrução passo a passo para configurar e lançar seu próprio chatbot usando a API Whapi.Cloud no Node.JS, além de demonstrar as principais funções e capacidades do gateway e do bot.
Você poderá usar nosso código-fonte em seu projeto, facilmente modificando e expandindo a funcionalidade do script. Com base no código, você pode criar seu próprio chatbot ou qualquer integração. Integre-o facilmente aos processos de trabalho existentes, continuando a usar o WhatsApp como de costume!
Código-fonte
O script deste chatbot inclui funções básicas frequentemente utilizadas por pequenas e médias empresas e abrange a maioria das tarefas:
- Envio de uma mensagem comum;
- Envio de mídia: imagem / arquivo / vídeo;
- Envio de contato (cartão de visita vCard);
- Envio de produto;
- Criação de grupos no WhatsApp;
- Envio de convite para o grupo;
- Envio de mensagem em grupo no WhatsApp;
- Recebimento e processamento de mensagens recebidas;
- Resposta a um comando desconhecido (para implementação de menu, instruções ou mensagem de boas-vindas).
Configuração do ambiente
Vamos preparar o ambiente de trabalho. Certifique-se de que tudo está pronto para trabalhar com o Node.js. Em seguida, vamos para o GitHub.
O processo inclui clonar o código-fonte do repositório no GitHub e instalar as dependências necessárias via npm (Node Package Manager). Você pode prosseguir para o próximo capítulo se já fez isso por conta própria.
Então, aqui estão os passos básicos para um rápido início:
1. Clonagem do repositório.
Abra o terminal ou linha de comando e navegue até o diretório onde deseja colocar o projeto. Use o seguinte comando para clonar o repositório:
git clone https://github.com/Whapi-Cloud/nodejs-whatsapp-chatbot
2. Instalação dos pacotes npm.
Após clonar o repositório, vá para a pasta do projeto:
cd your_project_name
Em seguida, execute o seguinte comando para instalar todos os pacotes npm necessários, conforme especificado no arquivo package.json:
npm install
Este comando irá baixar e instalar automaticamente todas as dependências necessárias para o funcionamento do chatbot.
Estrutura do projeto
- /files - nesta pasta estão os arquivos originais que serão usados para enviar arquivos. Você pode testar com estes arquivos e depois substituí-los pelos seus próprios. Você também poderá enviar arquivos por link (mais detalhes no final do artigo);
- config.js - configurações para iniciar o bot;
- index.js - script principal do chatbot;
Provedor da API do WhatsApp
Whapi.Cloud oferece uma API gateway fácil de usar, compatível com qualquer linguagem de programação. Isso permitirá que você integre seu site, loja, aplicativo ou CRM com o WhatsApp sem complicações.
Nossa API Cloud é um desenvolvimento independente e não tem restrições para trabalhar com envio de mensagens, grupos, canais, status, chamadas e outras funcionalidades do seu mensageiro.
Além disso, o acesso à API tem um preço fixo, sem cobrança por mensagens enviadas. Esta é a principal vantagem da nossa API simples e poderosa.
Como se conectar ao Whapi.Cloud
Outra vantagem do nosso gateway é a rapidez no onboarding e no início das operações. Você não precisará passar por uma verificação de negócios ou mudar seu número. Conecte seu próprio número e continue usando o WhatsApp como de costume!
Então, registre-se no Whapi.Cloud. Você precisará de um endereço de e-mail válido para passar pela verificação de e-mail ou de uma conta do Google.
No Dashboard, você encontrará um canal de teste, designado individualmente para você. Nos primeiros 5 dias, você terá a oportunidade de testar toda a funcionalidade da API completamente de graça.
Acesso gratuito à API por 5 dias
Acesse a página deste canal, simplesmente clicando nele.
Ao contrário de outros fornecedores, oferecemos a você a possibilidade de conectar seu WhatsApp ou WhatsApp Business existente à API.
Basta escanear o QR Code, como se faz no WhatsApp Web, e você estará pronto para operar em poucos segundos.
Para o Meta, isso é uma conexão normal com o WhatsApp Web, e se você não usar o Whapi.Cloud para enviar spam, seu número continuará funcionando normalmente.
Ignore o terceiro passo de 'Configurações do canal', pois não serão necessárias agora.
Ótimo, agora você tem acesso ao Token da API, que será necessário para testes e trabalho futuro com os endpoints. Guarde esse token, pois ele será útil muitas vezes.
Vamos ao config.js e substitua a variável do token, inserindo sua chave atual:
token: "SEU_TOKEN_DO_CANAL"
token: "SEU_TOKEN_DO_CANAL"
Configuração do Webhook
O que é um webhook e para que serve
Para receber dados de entrada do seu mensageiro, como uma mensagem de entrada, uma chamada recebida ou uma notificação de que alguém entrou no seu grupo, você precisará usar Webhook.
Essa tecnologia permitirá que você receba instantaneamente notificações sobre qualquer evento no seu WhatsApp e responda a isso.
Em palavras simples, usando um exemplo: Contato A lhe enviou uma mensagem -> O script do chatbot recebeu a mensagem do Contato A -> Verificou se esta mensagem é uma comando conhecido -> Executou o comando do script (por exemplo, enviou uma mensagem de boas-vindas ou um produto etc.)
Assim, dois sistemas (nosso gateway API conectado ao WhatsApp e seu chatbot) trocam informações sem a necessidade de quaisquer ações externas.
Tecnicamente, ao receber uma mensagem, o sistema executará uma solicitação POST com corpo JSON para o link configurado do seu script. O corpo JSON incluirá todas as informações sobre a mensagem recebida, como texto, número do remetente, hora do envio, etc., permitindo que você leia essas informações em tempo real.
Vamos configurar esse link!
Vamos configurar esse link!
Local ou no servidor
Ao desenvolver um bot para WhatsApp, você pode querer testá-lo localmente antes de implantá-lo em um servidor. A maneira mais fácil de fazer isso é usar ferramentas como o Ngrok, que cria um túnel seguro para o seu localhost, permitindo acesso ao seu servidor local pela internet.
Vamos pegar agora um link do Ngrok para testar o chatbot. Baixe o Ngrok do site oficial e descompacte-o. Abra o terminal e vá para a pasta onde o Ngrok está armazenado.
Execute ./ngrok http PORT_NUMBER, substituindo PORT_NUMBER pela porta em que seu servidor Express está operando localmente.
Agora você deve ter um URL público que pode usar como URL do webhook.
Copie este link para o arquivo config.js:
botUrl: "https://84c7-151-33-282-113.ngrok-free.app/hook"
Execute ./ngrok http PORT_NUMBER, substituindo PORT_NUMBER pela porta em que seu servidor Express está operando localmente.
Agora você deve ter um URL público que pode usar como URL do webhook.
Copie este link para o arquivo config.js:
botUrl: "https://84c7-151-33-282-113.ngrok-free.app/hook"
Atenção, deixe o “/hook” no final do link! É para esse endereço que o script do chatbot está programado atualmente!
Características do alojamento no servidor
Para receber webhooks de entrada, é necessário que o endereço IP público/host esteja acessível pela internet. Assim, o servidor Whapi.Cloud poderá enviar a solicitação para o seu servidor no endereço especificado e entregar o webhook de entrada.
Configuração do servidor:
- O Whapi.Cloud opera apenas com webhooks que usam HTTPS;
- Seu endpoint deve aceitar POST/PUT/PATCH/DELETE;
A seguir, no capítulo "Deploy", falaremos sobre alguns serviços públicos onde você pode hospedar seu chatbot.
Configuração e diferentes eventos
As configurações de canal e webhook no Whapi.Cloud oferecem amplas possibilidades de personalização, o que pode ser particularmente útil em projetos com requisitos específicos.
No entanto, para simplificar o processo de lançamento, incluímos a configuração das definições necessárias diretamente no código do nosso chatbot, livrando você da necessidade de fazer isso manualmente. Isso permite que você se concentre no desenvolvimento, sem se preocupar com configurações adicionais.
Se você desejar explorar as possibilidades de personalização ou precisar de uma configuração mais detalhada do webhook, você sempre pode consultar a lista completa de opções na Base de Conhecimento do Whapi.Cloud no artigo: Configurações detalhadas do webhook
No código fonte do GitHub, o link do webhook é automaticamente atribuído ao seu canal através do método API, então você não precisa tomar nenhuma ação adicional.
Vamos aprofundar um pouco nos modos de webhook e nos eventos sobre os quais nosso serviço pode notificá-lo.
Atualmente, o modo de envio do webhook selecionado é Method. Esse método é particularmente adequado para o processamento detalhado de eventos, permitindo o uso de diferentes métodos HTTP para ações específicas. Assim, o webhook dividirá as solicitações enviadas e as encaminhará para diferentes endereços, por exemplo, https://****/hook/messages (eventos relacionados a mensagens) ou https://****/hook/statuses (eventos relacionados a status de mensagens) ou https://****/hook/groups (eventos relacionados a grupos).
Existem outros dois modos de webhook: Body (envia diretamente para o link o corpo da solicitação) e Path (especifica completamente a URL da solicitação da API).
Existem outros dois modos de webhook: Body (envia diretamente para o link o corpo da solicitação) e Path (especifica completamente a URL da solicitação da API).
Os eventos e o método pelo qual notificamos o chatbot original são POST Messages. Este webhook monitora quaisquer alterações relacionadas a novas mensagens, incluindo mensagens enviadas e recebidas.
Para saber mais sobre todos os eventos possíveis (informações sobre grupos, canais, chamadas, status, alterações de mensagens, etc.) que nosso sistema suporta, você pode consultar o artigo: Nossos webhooks (eventos rastreados)
Início e configuração do bot
Você já pode testar o funcionamento do chatbot! Certifique-se de que no config.js o token e o endereço do webhook estejam corretos.
A inicialização do chatbot é feita executando o comando node index.js no terminal do diretório raiz do projeto.
Seu bot agora deve estar ativo e pronto para funcionar.
Ao enviar uma mensagem para o número ao qual o bot está vinculado, de outro telefone, você deve receber uma resposta automática. Caso não haja reação do bot, recomendamos consultar a seção "Solução de problemas" para diagnóstico e resolução de possíveis problemas.
Parâmetros pré-configurados (grupo e produto)
No arquivo config.js estão os valores predefinidos, incluindo os identificadores do grupo e do produto que seu chatbot usa para enviar mensagens. Para que o bot funcione corretamente no contexto dos seus dados, é necessário atualizar esses parâmetros de acordo com suas necessidades.
- group: '[email protected]'
- product: '6559353560856703'
O primeiro identificador refere-se ao grupo ao qual o chatbot enviará a mensagem.
Você pode obter esse identificador criando um grupo no WhatsApp ou usando um existente.
O identificador do grupo só pode ser obtido por meio da API.
Para isso, use a chamada da API "Obter lista de grupos" (método: https://whapi.readme.io/reference/getgroups na Documentação ). O identificador do grupo aparece assim: [email protected]
Para isso, use a chamada da API "Obter lista de grupos" (método: https://whapi.readme.io/reference/getgroups na Documentação ). O identificador do grupo aparece assim: [email protected]
Para mais informações sobre os identificadores de chat (chat_id), escrevemos um artigo separado: ID do Chat. O que é e como obtê-lo?
Então, quando você encontrar o identificador do grupo de que precisa, agora copie-o para o config.js.
Faça o mesmo com os produtos do seu catálogo (disponível apenas na versão Business do aplicativo).
Determine o identificador do produto que será enviado pelo seu chatbot.
Você pode obter a lista de produtos usando o método https://whapi.readme.io/reference/getproducts na Documentação.
Substitua os valores predefinidos no config.js pelos seus identificadores de grupo e produto.
Após fazer as alterações, salve o arquivo e reinicie o bot. Agora ele deve funcionar com os novos parâmetros, permitindo que você teste completamente sua operação.
Resolução de problemas
Durante o teste e operação do chatbot para WhatsApp, vários problemas podem surgir. Aqui estão algumas situações típicas e recomendações para resolvê-las:
Bot não responde a mensagens recebidas
- Certifique-se de que você está enviando mensagens para o número em que o bot está ativo, de outro telefone. O bot não poderá responder mensagens enviadas do mesmo número.
- Se o bot não responder a mensagens de outros números, verifique o funcionamento dos webhooks. Use serviços de simulação de webhooks, como o Webhook.site, para confirmar como as solicitações de callback estão chegando. Depois, verifique se o caminho corresponde ao configurado por você. Além disso, certifique-se de que seu servidor responde com 200Ok.
Se você encontrar dificuldades, não hesite em buscar nossa ajuda técnica. Você pode escrever para o widget de chat no nosso site ou enviar um e-mail para [email protected]. Nós vamos ajudá-lo a entender o que pode estar errado com o webhook.
Bot envia mensagens sem parar
Volte para a versão original do código. Nosso script inclui uma verificação para determinar se uma mensagem é recebida ou enviada, para evitar cair em um loop infinito de envio de mensagens. Um envio infinito pode ocorrer se a verificação de mensagens enviadas estiver ausente no código, fazendo com que o bot se auto-chame, ou se houver um envio cíclico de mensagens no código.
Bot funciona em alguns chats, mas não em outros
Verifique seu plano tarifário na Whapi.Cloud. Se você estiver usando o modo de teste ou o plano "Sandbox", a interação é limitada a um certo número de chats por mês (atualmente até 5 chats). Nesse caso, o bot não será capaz de processar mensagens no sexto chat e nos subsequentes.
É importante lembrar que muitos problemas podem ser prevenidos verificando cuidadosamente a configuração e a lógica do seu chatbot antes do lançamento. Atualizar regularmente seu código e prestar atenção aos detalhes das configurações ajudarão a evitar a maioria dos erros típicos. E nossa equipe de suporte está sempre disponível e pronta para ajudá-lo!
Deploy e uso de servidores
Para que seu chatbot do WhatsApp esteja disponível 24/7, é necessário hospedá-lo em uma plataforma de hospedagem confiável. Você pode usar seu próprio servidor, mas neste capítulo vamos considerar as três plataformas mais populares — Firebase, AWS e Heroku — e passar pelos passos básicos para implantar seu bot em cada uma delas.
A escolha da plataforma depende das suas preferências, orçamento e requisitos do projeto. Cada uma das plataformas consideradas oferece suas próprias oportunidades e vantagens únicas. Firebase e AWS Lambda fornecem um backend poderoso sem a necessidade de gerenciar um servidor, enquanto o Heroku oferece a simplicidade de implantação de aplicativos baseados em Git.
Firebase
O Firebase oferece a funcionalidade Cloud Functions, que permite executar seu bot sem se preocupar com a infraestrutura do servidor. Na nossa opinião, esta é a opção mais otimizada.
- Crie um projeto no Firebase Console;
- Instale o Firebase CLI, seguindo as instruções;
- Initialize o Firebase no diretório do seu projeto usando o comando firebase init;
- Implante seu bot usando o comando firebase deploy --only functions.
AWS (Amazon Web Services)
A AWS Lambda permite executar código em resposta a gatilhos de outros serviços AWS, o que o torna uma boa escolha para um bot.
- Registre-se ou entre no Console de Gerenciamento da AWS;
- Crie uma nova função Lambda através do console da AWS, escolhendo o API Gateway como gatilho;
- Carregue o código do seu bot na função Lambda;
- Configure o API Gateway para interação do seu bot com o mundo externo.
Heroku
O Heroku oferece uma plataforma simples para hospedagem de aplicativos, capaz de implantar automaticamente o código do seu repositório Git.
- Crie uma conta no Heroku;
- Instale o Heroku CLI e faça login;
- Crie um novo aplicativo no Heroku através do console ou usando o comando heroku create;
- Associe seu repositório Git ao Heroku e faça o deploy usando os comandos git push heroku master;
- Configure o URL do webhook fornecido pelo Heroku.
Expansão de funcionalidades
Após o sucesso no lançamento e testes do seu chatbot para WhatsApp, existem muitas maneiras de expandir ainda mais suas funcionalidades, tornando-o mais útil e interativo para os usuários. Aqui estão alguns casos de uso comuns:
- Envio de arquivos por link.
Enviar um arquivo de mídia por link é muito simples. A condição principal é que o próprio arquivo esteja diretamente acessível pelo link (por isso, serviços de nuvem como Google Drive ou Dropbox não são adequados, pois eles não fornecem acesso direto ao arquivo). Use o parâmetro media em qualquer um dos métodos que permitem enviar arquivos de mídia. Leia mais informações em nosso artigo: Endpoint para envio de arquivo de mídia.
- Distribuição de leads por grupos.
Você precisará da função de criação de grupos, bem como adicionar um participante ao grupo. Adicionar um participante ao grupo é fácil, mas há alguns nuances. Descrevemos mais detalhes no artigo: "Adicionando um novo membro ao grupo"
- Integração com CRM.
Tecnicamente, a integração com o CRM não é tão diferente do chatbot, com a diferença de que um recurso adicional com sua própria API é adicionado. Inclua funções que permitem aos usuários reservar serviços, encomendar produtos ou obter informações atualizadas de fontes externas em tempo real.
- Pesquisas como uma alternativa aos botões.
Botões interativos no WhatsApp são uma ferramenta muito conveniente para trabalhar com clientes. No entanto, essa função não está disponível para a maioria dos usuários do WhatsApp. Por isso, sugerimos uma alternativa conveniente - usar pesquisas como botões. Artigo detalhado com código fonte em NodeJS e como utilizá-lo.
- Aumento do envolvimento dos clientes.
Use stories, mude os status do seu número, coloque likes e outros emojis nas mensagens dos seus clientes, envie mensagens de voz - aumente o engajamento no atendimento aos clientes.
- Verificação de número no WhatsApp.
Verifique se o número de telefone especificado existe no WhatsApp ou não. Determine quais números de telefone estão ativos e quais não podem receber mensagens do WhatsApp. Integre em seu aplicativo antes de fazer um envio em massa! Código-fonte no GitHub e instruções aqui.
Oferecemos suporte completo aos nossos clientes! Se você tiver dúvidas sobre o funcionamento do bot, configuração da plataforma ou enfrentar dificuldades técnicas, você sempre pode contar com nossa ajuda.
Esperamos que este guia ajude você a lançar com sucesso seu chatbot para WhatsApp. Boa sorte em seus empreendimentos!
