# 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:** Lucas Vieira **URL:** https://www.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 ~150 ms — 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 (30 requisições por minuto no plano grátis, 30 por minuto 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? O limite padrão é de 30 requisições por minuto em todos os planos (5 por minuto na Consulta em Tempo Real). Para chatbots com várias conversas ao mesmo tempo, use uma fila (Bull no Node.js ou Celery no Python) e respeite o HTTP 429. Um teto maior, se existir, fica no plano Corporativo. ### 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 ~150 ms 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.