# Como integrar API de CPF em chatbots do WhatsApp Business > Guia prático para integrar a validação de CPF via API da CPFHub.io em chatbots do WhatsApp Business com exemplos de código. **Publicado:** 10/06/2024 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/como-integrar-api-de-cpf-em-chatbots-do-whatsapp-business --- Para integrar validação de CPF em um chatbot do WhatsApp Business, o fluxo consiste em receber a mensagem via webhook da WhatsApp Business API, extrair o CPF informado pelo usuário, consultar a API da CPFHub.io e responder com o nome do titular para confirmação. A implementação básica em Node.js ou Python leva menos de 30 minutos. ## Introdução O WhatsApp é o aplicativo de mensagens mais popular do Brasil, com mais de 120 milhões de usuários ativos. Para empresas, o WhatsApp Business e a WhatsApp Business API se tornaram canais fundamentais de atendimento ao cliente, vendas e onboarding. Chatbots integrados ao WhatsApp Business podem automatizar processos que antes exigiam atendimento humano, incluindo a validação de CPF. Ao integrar a API de consulta de CPF da [**CPFHub.io**](https://www.cpfhub.io/) ao chatbot, é possível verificar a identidade do usuário em tempo real — com latência de aproximadamente 900ms — sem nenhuma intervenção manual. --- ## Casos de uso para validação de CPF no WhatsApp ### Onboarding de novos clientes O chatbot pode solicitar o CPF do cliente durante o cadastro, validar em tempo real e confirmar os dados sem intervenção humana. ### Atendimento de suporte Antes de fornecer informações sensíveis sobre conta ou pedido, o chatbot válida a identidade do solicitante por meio do CPF. ### Vendas e negociação Para vendas que exigem emissão de nota fiscal ou contrato, o chatbot coleta e válida o CPF diretamente na conversa. ### Segunda via de documentos Empresas de serviços (energia, telecomunicações, seguradoras) podem usar o CPF para localizar a conta do cliente e enviar segunda via de boletos ou documentos. ### Agendamento de serviços Clínicas, consultórios e prestadores de serviço podem validar o CPF do paciente ao agendar consultas pelo WhatsApp. --- ## Arquitetura da integração A integração envolve três componentes principais: ``` [WhatsApp Business API] <--> [Servidor do Chatbot] <--> [API CPFHub.io] ``` 1. O cliente envia uma mensagem no WhatsApp. 2. A WhatsApp Business API entrega a mensagem ao servidor do chatbot (via webhook). 3. O chatbot processa a mensagem e, quando necessário, consulta a API da CPFHub.io. 4. O chatbot responde ao cliente no WhatsApp com os dados validados. --- ## Fluxo conversacional Um fluxo típico de validação de CPF no WhatsApp seria: ``` Bot: Olá! Para continuarmos, preciso verificar sua identidade. Por favor, informe seu CPF (apenas números). Usuário: 12345678900 Bot: Aguarde um momento enquanto verifico seus dados... [Chatbot consulta API da CPFHub.io] Bot: Encontrei! Seu nome é João da Silva, correto? Usuário: Sim Bot: Identidade verificada com sucesso! Como posso ajudá-lo hoje? ``` Se o CPF for inválido ou não encontrado: ``` Bot: Não consegui localizar este CPF. Por favor, verifique o número e tente novamente. ``` --- ## Implementação com Node.js e Express ### Servidor do chatbot ```javascript const express = require('express'); const app = express(); app.use(express.json()); const CPFHUB_API_KEY = process.env.CPFHUB_API_KEY; const WHATSAPP_TOKEN = process.env.WHATSAPP_TOKEN; // Estado das conversas (em produção, use Redis ou banco de dados) const conversas = {}; // Webhook para receber mensagens do WhatsApp app.post('/webhook', async (req, res) => { const message = req.body.entry?.[0]?.changes?.[0]?.value?.messages?.[0]; if (!message) { return res.sendStatus(200); } const telefone = message.from; const texto = message.text?.body?.trim(); if (!texto) { return res.sendStatus(200); } const estado = conversas[telefone] || { etapa: 'inicio' }; if (estado.etapa === 'inicio') { await enviarMensagem(telefone, 'Olá! Para continuarmos, preciso verificar sua identidade.\n' + 'Por favor, informe seu CPF (apenas números).' ); conversas[telefone] = { etapa: 'aguardando_cpf' }; } else if (estado.etapa === 'aguardando_cpf') { const cpf = texto.replace(/\D/g, ''); if (cpf.length !== 11) { await enviarMensagem(telefone, 'O CPF deve conter 11 dígitos. Por favor, tente novamente.' ); return res.sendStatus(200); } await enviarMensagem(telefone, 'Aguarde um momento enquanto verifico seus dados...' ); // Consultar API da CPFHub.io const resultado = await consultarCPF(cpf); if (resultado.success) { const nome = resultado.data.name; await enviarMensagem(telefone, `Encontrei! Seu nome é ${nome}, correto?\n` + 'Responda SIM para confirmar ou NÃO para tentar outro CPF.' ); conversas[telefone] = { etapa: 'confirmando_nome', cpf: cpf, nome: nome }; } else { await enviarMensagem(telefone, 'Não consegui localizar este CPF. ' + 'Por favor, verifique o número e tente novamente.' ); } } else if (estado.etapa === 'confirmando_nome') { if (texto.toUpperCase() === 'SIM') { await enviarMensagem(telefone, 'Identidade verificada com sucesso!\n' + 'Como posso ajudá-lo hoje?' ); conversas[telefone] = { etapa: 'atendimento', cpf: estado.cpf, nome: estado.nome }; } else { await enviarMensagem(telefone, 'Por favor, informe o CPF correto (apenas números).' ); conversas[telefone] = { etapa: 'aguardando_cpf' }; } } res.sendStatus(200); }); async function consultarCPF(cpf) { const response = await fetch(`https://api.cpfhub.io/cpf/${cpf}`, { method: 'GET', headers: { 'x-api-key': CPFHUB_API_KEY, 'Accept': 'application/json' }, timeout: 10000 }); return response.json(); } async function enviarMensagem(telefone, texto) { await fetch( `https://graph.facebook.com/v18.0/PHONE_NUMBER_ID/messages`, { method: 'POST', headers: { 'Authorization': `Bearer ${WHATSAPP_TOKEN}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ messaging_product: 'whatsapp', to: telefone, type: 'text', text: { body: texto } }), timeout: 10000 } ); } app.listen(3000, () => { console.log('Chatbot rodando na porta 3000'); }); ``` --- ## Implementação com Python e Flask ```python from flask import Flask, request, jsonify import requests import os app = Flask(__name__) CPFHUB_API_KEY = os.environ.get("CPFHUB_API_KEY") WHATSAPP_TOKEN = os.environ.get("WHATSAPP_TOKEN") # Estado das conversas conversas = {} @app.route("/webhook", methods=["POST"]) def webhook(): data = request.get_json() message = (data.get("entry", [{}])[0] .get("changes", [{}])[0] .get("value", {}) .get("messages", [{}])[0]) telefone = message.get("from") texto = message.get("text", {}).get("body", "").strip() if not telefone or not texto: return jsonify({"status": "ok"}), 200 estado = conversas.get(telefone, {"etapa": "inicio"}) if estado["etapa"] == "inicio": enviar_mensagem(telefone, "Olá! Para continuarmos, informe seu CPF (apenas números).") conversas[telefone] = {"etapa": "aguardando_cpf"} elif estado["etapa"] == "aguardando_cpf": cpf = "".join(filter(str.isdigit, texto)) if len(cpf) != 11: enviar_mensagem(telefone, "O CPF deve conter 11 dígitos. Tente novamente.") return jsonify({"status": "ok"}), 200 resultado = consultar_cpf(cpf) if resultado.get("success"): nome = resultado["data"]["name"] enviar_mensagem(telefone, f"Encontrei! Seu nome é {nome}, correto? (SIM/NÃO)") conversas[telefone] = { "etapa": "confirmando", "cpf": cpf, "nome": nome } else: enviar_mensagem(telefone, "CPF não encontrado. Verifique e tente novamente.") elif estado["etapa"] == "confirmando": if texto.upper() == "SIM": enviar_mensagem(telefone, "Identidade verificada! Como posso ajudá-lo?") conversas[telefone] = { "etapa": "atendimento", "cpf": estado["cpf"], "nome": estado["nome"] } else: enviar_mensagem(telefone, "Informe o CPF correto (apenas números).") conversas[telefone] = {"etapa": "aguardando_cpf"} return jsonify({"status": "ok"}), 200 def consultar_cpf(cpf): response = requests.get( f"https://api.cpfhub.io/cpf/{cpf}", headers={ "x-api-key": CPFHUB_API_KEY, "Accept": "application/json" }, timeout=10 ) return response.json() def enviar_mensagem(telefone, texto): requests.post( f"https://graph.facebook.com/v18.0/PHONE_NUMBER_ID/messages", headers={ "Authorization": f"Bearer {WHATSAPP_TOKEN}", "Content-Type": "application/json" }, json={ "messaging_product": "whatsapp", "to": telefone, "type": "text", "text": {"body": texto} }, timeout=10 ) if __name__ == "__main__": app.run(port=3000) ``` --- ## Boas práticas para o chatbot ### Segurança dos dados * Nunca exiba o CPF completo nas mensagens de resposta. Se necessário, mostre apenas os últimos 4 dígitos. * Armazene as chaves de API em variáveis de ambiente, nunca no código-fonte. * Implemente timeout nas requisições para evitar que o chatbot fique travado. ### Experiência do usuário * Forneça instruções claras sobre o formato esperado (apenas números, 11 dígitos). * Exiba mensagens de erro específicas e orientativas. * Confirme os dados com o usuário antes de prosseguir. * Ofereça a opção de tentar novamente em caso de erro. ### Rate limits * Respeite o rate limit da API (1 requisição a cada 2 segundos no plano grátis, 1 por segundo no plano Pro). * Em cenários de alto volume de conversas simultâneas, considere o plano Pro ou Corporativo. ### Conformidade com a LGPD * Informe o usuário que seus dados serão consultados para verificação de identidade. * Armazene o consentimento do usuário antes de realizar a consulta. * Não retenha os dados retornados pela API além do necessário. A [ANPD](https://www.gov.br/anpd) orienta que dados de identificação coletados via canais digitais devem seguir o princípio da necessidade e ter finalidade declarada. --- ## Integração com plataformas de chatbot Além da implementação direta, é possível integrar a API da CPFHub.io com plataformas populares de criação de chatbots: * **Dialogflow (Google)** -- Use fulfillment webhooks para chamar a API da CPFHub.io quando o bot detectar a intenção de validar CPF. * **Botpress** -- Crie uma ação customizada que consulta a API e retorna os dados para o fluxo do bot. * **ManyChat** -- Utilize a funcionalidade de chamadas externas (External Request) para integrar a API. * **Take Blip** -- Configure um builder com chamadas HTTP para a API da CPFHub.io. --- ## Perguntas frequentes ### Quais permissões da WhatsApp Business API são necessárias para esse fluxo? É necessário ter acesso à WhatsApp Business API (via Meta for Developers ou um BSP — Business Solution Provider), configurar um webhook para receber mensagens e obter um token de acesso com a permissão `whatsapp_business_messaging`. A validação de CPF em si é feita pela CPFHub.io de forma independente. ### O chatbot pode validar CPF em conversas de grupo no WhatsApp? Não é recomendado. A verificação de identidade via CPF deve ocorrer em conversas individuais (1:1), onde o usuário tem contexto de que está fornecendo um dado pessoal. Grupos do WhatsApp não são adequados para esse tipo de fluxo por questões de privacidade e conformidade com a LGPD. ### Como lidar com alta concorrência de verificações simultâneas no chatbot? No plano grátis o rate limit é de 1 requisição a cada 2 segundos. Para chatbots com múltiplas conversas simultâneas, implemente uma fila de requisições (ex: Bull no Node.js ou Celery no Python) ou migre para o plano Pro (1 req/s) ou Corporativo para eliminar o gargalo. ### Quanto tempo leva para integrar a API CPFHub.io ao chatbot? A integração básica leva menos de 30 minutos: crie uma conta em cpfhub.io, gere a API key no painel e adicione a função `consultarCPF` ao webhook existente do seu chatbot. Os exemplos neste artigo em Node.js e Python estão prontos para uso em produção com pequenas adaptações. ### Leia também - [Como consumir API de CPF em n8n para automações self-hosted](https://cpfhub.io/blog/como-consumir-api-cpf-n8n-automacoes-self-hosted) - [Como consumir API de CPF em Google Apps Script para automações no Google Sheets](https://cpfhub.io/blog/como-consumir-api-cpf-google-apps-script-automacoes-google-sheets) - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) - [Diferença entre validação de CPF e consulta de CPF: quando usar cada uma](https://cpfhub.io/blog/diferenca-entre-validacao-de-cpf-e-consulta-de-cpf-quando-usar-cada-uma) --- ## Conclusão Integrar a validação de CPF em chatbots do WhatsApp Business é uma forma eficiente de automatizar a verificação de identidade diretamente no canal de comunicação preferido dos brasileiros. Com a API da [**CPFHub.io**](https://www.cpfhub.io/), o fluxo completo — receber CPF, validar e confirmar nome — funciona de forma transparente para o usuário e sem intervenção manual para a empresa. O tempo de resposta de aproximadamente 900ms garante que a experiência conversacional seja fluida, sem atrasos perceptíveis para o usuário. Com planos a partir de R$ 0 (50 consultas/mês), a solução é acessível para empresas de todos os portes. Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e adicione validação de CPF ao seu chatbot do WhatsApp hoje mesmo.