# Como criar um bot no Telegram para consultar CPF usando Python > Tutorial passo a passo para criar um bot no Telegram que consulta CPF via API usando Python e a CPFHub.io. Código completo e funcional. **Publicado:** 23/02/2026 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/bot-telegram-consultar-cpf-python --- Com Python e a API CPFHub.io, é possível criar um bot funcional no Telegram para consultas de CPF em menos de 80 linhas de código. Basta uma conta gratuita na CPFHub.io, um token gerado via @BotFather e a biblioteca `python-telegram-bot` — o bot recebe um número de CPF, valida o formato localmente e retorna nome, gênero e data de nascimento em ~900ms. ## Introdução Criar um **bot no Telegram** para consultar CPF é uma forma prática de disponibilizar validações de identidade para equipes internas — como atendimento ao cliente, compliance ou operações. Com Python e a API da CPFHub.io, o processo é direto: o Telegram cuida da interface de mensagens e a CPFHub.io cuida da consulta aos dados cadastrais. A [documentação oficial da API do Telegram](https://core.telegram.org/bots/api) descreve todos os recursos disponíveis para bots, incluindo gerenciamento de grupos e controle de acesso por usuário. --- ## Pré-requisitos * Python 3.9+ * Biblioteca `python-telegram-bot` (`pip install python-telegram-bot`) * Biblioteca `requests` (`pip install requests`) * Token do bot Telegram (criado via @BotFather) * Conta gratuita na [CPFHub.io](https://www.cpfhub.io/) --- ## 1. Crie o bot no Telegram 1. Abra o Telegram e busque por **@BotFather**. 2. Envie `/newbot` e siga as instruções. 3. Copie o token gerado (ex: `123456789:ABCdefGhIJKlmNoPQRsTUVwxYZ`). --- ## 2. Configure as variáveis de ambiente Crie um arquivo `.env`: ``` TELEGRAM_BOT_TOKEN=seu_token_aqui CPFHUB_API_KEY=sua_chave_aqui ``` --- ## 3. Código completo do bot Crie o arquivo `bot.py`: ```python import os import re import requests from telegram import Update from telegram.ext import Application, CommandHandler, MessageHandler, filters, ContextTypes CPFHUB_API_KEY = os.environ['CPFHUB_API_KEY'] TELEGRAM_BOT_TOKEN = os.environ['TELEGRAM_BOT_TOKEN'] def validar_cpf_sintatico(cpf: str) -> bool: cpf = re.sub(r'\D', '', cpf) if len(cpf) != 11 or len(set(cpf)) == 1: return False for i in range(9, 11): soma = sum(int(cpf[j]) * ((i + 1) - j) for j in range(i)) digito = (soma * 10 % 11) % 10 if digito != int(cpf[i]): return False return True def consultar_cpf(cpf: str) -> dict: cpf = re.sub(r'\D', '', cpf) url = f'https://api.cpfhub.io/cpf/{cpf}' headers = { 'x-api-key': CPFHUB_API_KEY, 'Accept': 'application/json' } response = requests.get(url, headers=headers, timeout=10) return response.json() async def start(update: Update, context: ContextTypes.DEFAULT_TYPE): await update.message.reply_text( 'Bem-vindo! Envie um CPF (apenas numeros) para consultar.' ) async def handle_cpf(update: Update, context: ContextTypes.DEFAULT_TYPE): texto = re.sub(r'\D', '', update.message.text) if len(texto) != 11: await update.message.reply_text('Envie um CPF valido com 11 digitos.') return if not validar_cpf_sintatico(texto): await update.message.reply_text('CPF com formato invalido (digitos verificadores incorretos).') return await update.message.reply_text('Consultando CPF...') try: resultado = consultar_cpf(texto) if resultado.get('success'): dados = resultado['data'] resposta = ( f"CPF: {dados['cpf']}\n" f"Nome: {dados['name']}\n" f"Genero: {dados['gender']}\n" f"Nascimento: {dados['birthDate']}" ) else: resposta = 'CPF nao encontrado na base.' except requests.exceptions.Timeout: resposta = 'Tempo de resposta excedido. Tente novamente.' except Exception as e: resposta = f'Erro na consulta: {str(e)}' await update.message.reply_text(resposta) def main(): app = Application.builder().token(TELEGRAM_BOT_TOKEN).build() app.add_handler(CommandHandler('start', start)) app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, handle_cpf)) app.run_polling() if __name__ == '__main__': main() ``` --- ## 4. Executando o bot ```bash export TELEGRAM_BOT_TOKEN=seu_token_aqui export CPFHUB_API_KEY=sua_chave_aqui python bot.py ``` O bot ficará ativo e responderá no Telegram quando alguém enviar um CPF. --- ## 5. Como funciona o fluxo 1. O usuário envia um número de CPF no chat. 2. O bot valida o formato localmente (dígitos verificadores). 3. Se válido, consulta a API da CPFHub.io. 4. Retorna nome, gênero e data de nascimento. 5. Se inválido ou não encontrado, retorna mensagem de erro. --- ## 6. Boas práticas e segurança * **Restrinja o acesso** — Limite o bot a usuários ou grupos autorizados usando IDs do Telegram. * **Não exponha dados sensíveis** — Nunca exiba o CPF completo em logs ou mensagens para terceiros. * **Respeite a LGPD** — Use o bot apenas para consultas autorizadas e com consentimento. * **Variáveis de ambiente** — Nunca hardcode tokens ou chaves de API no código. --- ## 7. Possíveis melhorias * Adicionar comando `/ajuda` com instruções. * Implementar whitelist de usuários autorizados. * Adicionar logs de consulta para auditoria. * Usar Redis para cache de CPFs já consultados. * Integrar com banco de dados para histórico. --- ## Perguntas frequentes ### Qual é a latência esperada ao consultar CPF pelo bot no Telegram? A API CPFHub.io responde em ~900ms. O bot do Telegram adiciona uma latência mínima de rede, então o usuário recebe a resposta em aproximadamente 1 a 2 segundos após enviar o CPF — tempo adequado para uso em operações internas de atendimento ou compliance. ### Como restringir o acesso ao bot para apenas usuários autorizados? Implemente uma whitelist de IDs do Telegram: antes de processar qualquer mensagem, verifique se `update.effective_user.id` está na lista de IDs permitidos. Se não estiver, responda com uma mensagem genérica e encerre o handler. Isso impede que o bot seja usado por pessoas fora da equipe autorizada. ### O que acontece quando o limite de consultas gratuitas é atingido? A API CPFHub.io não bloqueia o acesso ao atingir o limite do plano gratuito (50 consultas/mês). Cada consulta adicional é cobrada a R$0,15 — o bot continua funcionando normalmente. Para equipes com volume maior, o plano Pro oferece 1.000 consultas mensais por R$149. ### Como integrar o bot com um banco de dados para histórico de consultas? Após cada consulta bem-sucedida, salve no banco um registro com o ID do usuário do Telegram, o CPF consultado (preferencialmente hasheado), o timestamp e o resultado (encontrado/não encontrado). Ferramentas como SQLite (para uso local) ou PostgreSQL (para produção) funcionam bem com Python e podem ser integradas ao handler existente sem alterar a lógica de consulta à API. ### Leia também - [Como integrar API de CPF com Django e Python](https://cpfhub.io/blog/como-integrar-api-cpf-django-python) - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) - [KYC no Brasil: quais setores são obrigados a validar CPF por lei](https://cpfhub.io/blog/kyc-no-brasil-quais-setores-sao-obrigados-a-validar-cpf-por-lei) - [Fraude de novo cadastro: como detectar CPFs que já foram banidos](https://cpfhub.io/blog/fraude-de-novo-cadastro-como-detectar-cpfs-banidos) --- ## Conclusão Com menos de 80 linhas de Python, você cria um bot funcional no Telegram que consulta CPFs em tempo real usando a API da CPFHub.io. O fluxo é simples: o usuário envia o CPF, o bot valida o formato localmente, consulta a API e devolve os dados cadastrais. Para equipes de atendimento, compliance ou operações, essa integração elimina a necessidade de acessar sistemas internos para verificações rápidas de identidade. O próximo passo é adicionar controle de acesso por whitelist de usuários e um log de consultas para auditoria — funcionalidades que levam mais uma hora de código e tornam o bot pronto para uso em produção. Crie sua conta gratuita em [cpfhub.io](https://www.cpfhub.io/) e faça até 50 consultas por mês sem cartão de crédito. Quando o volume crescer, o excedente custa R$0,15 por consulta — sem bloqueios nem interrupções.