Bot de WhatsApp com Python: Passo a Passo do Zero

Imagem: Pexels
WhatsApp tem mais de dois bilhões de usuários e é onde o cliente brasileiro realmente responde. Automatizar atendimento por lá parece caro e complicado, mas existe um caminho curto: a API oficial do WhatsApp via Twilio, que entrega um sandbox gratuito para desenvolver sem esperar aprovação de negócio. Este guia monta um bot de Python que recebe mensagem, responde por keyword e depois envia mensagem proativamente — do zero, com código que roda hoje.
1. Sandbox: como funciona antes de virar produto
O WhatsApp Sandbox da Twilio é um número compartilhado para testes. Você envia uma mensagem de código para um número de opt-in e a partir daí consegue trocar mensagens com seu bot. Limitações importantes: número único, participantes limitados por sessão e sem garantia de SLA — serve para desenvolver e validar fluxo, não para atender clientes reais em produção. Para produção, o caminho é a WhatsApp Business API oficial, com número próprio e verificação de conta comercial, que tem custo por conversa na faixa de centavos a poucos reais por mensagem, variando por país e categoria.
2. Preparando o ambiente
Você precisa de Python 3.9+, uma conta Twilio e o ngrok (ou similar) para expor sua máquina local na internet — o WhatsApp entrega os eventos por webhook, ou seja, ele chama você, e máquina atrás de NAT não recebe nada sem um túnel. Instale as dependências:
pip install flask twilio python-dotenv
No painel da Twilio, anote o Account SID, o Auth Token e o número do sandbox. Guarde em um arquivo .env — nunca no código:
TWILIO_ACCOUNT_SID=ACxxxxxxxx
TWILIO_AUTH_TOKEN=seu_token
WHATSAPP_FROM=whatsapp:+14155238886
3. O servidor que recebe e responde
O núcleo é um app Flask com duas rotas: uma para receber o webhook do WhatsApp (método POST) e outra simples de health check. A Twilio entrega a mensagem no campo Body e espera de volta um documento TwiML com a resposta:
from flask import Flask, request
from twilio.twiml.messaging_response import MessagingResponse
app = Flask(__name__)
@app.route("/whatsapp", methods=["POST"])
def whatsapp():
incoming = request.form.get("Body", "").strip().lower()
resp = MessagingResponse()
msg = resp.message()
if incoming in ("oi", "olá", "ola"):
msg.body("Olá! Envie HELP para ver o que eu faço.")
elif incoming == "help":
msg.body("Comandos: PRECOS, HORARIO, SAIR")
elif incoming == "precos":
msg.body("Planos na faixa de R$ 97 a R$ 297 por mês. Envie PRECO1 ou PRECO2.")
else:
msg.body("Não entendi. Envie HELP.")
return str(resp), 200
Rode com flask --app bot run --port 5000 e, em outro terminal, ngrok http 5000. Copie a URL gerada (formato https://xxxx.ngrok-free.app) para o campo de webhook do sandbox na Twilio, apontando para /whatsapp. Teste mandando uma mensagem pelo seu celular: a resposta deve voltar em segundos.
4. Enviando mensagem proativamente
Receber é fácil; enviar quando você quiser é o que transforma bot em ferramenta. Pela biblioteca oficial:
from twilio.rest import Client
import os
from dotenv import load_dotenv
load_dotenv()
client = Client(os.getenv("TWILIO_ACCOUNT_SID"),
os.getenv("TWILIO_AUTH_TOKEN"))
client.messages.create(
from_=os.getenv("WHATSAPP_FROM"),
to="whatsapp:+5511999999999",
body="Seu pedido 123 saiu para entrega."
)
No sandbox isso funciona para números já optados. Em produção, o envio proativo segue regras da Meta: janelas de 24 horas após a última mensagem do usuário e templates pré-aprovados fora dessa janela. Esse detalhe muda o desenho do produto — planeje o fluxo em torno da janela, não contra ela.
5. Erros que quebram o bot em produção
- Webhook apagado: ngrok morre ao fechar o terminal; em produção use um servidor ou túnel persistente.
- Resposta lenta: a Twilio tem timeout; processe pesado em fila (Celery, RQ) e responda rápido com 200.
- Segredos no repositório: Auth Token versionado é vazado garantido; use .env e .gitignore.
- Assumir que todo texto é keyword: trate texto livre com fallback e, se precisar de compreensão real, plugue um modelo de linguagem na etapa de interpretação.
O caminho deste guia leva do zero a um bot respondendo em menos de uma hora. O próximo passo real é trocar o dicionário de keywords por um roteador com IA e guardar conversas em um banco simples — mas só depois de validar com usuários de verdade que o bot responde o que as pessoas realmente perguntam, e não o que você imaginava que perguntariam.