Automação

Python WhatsApp: Guia Completo 2026

📅 24 de janeiro de 2024 ✍️ Felipe Zanoni

📚 Série: Python Automação WhatsApp → Chatbot Python | Evolution API | Automação WhatsApp

O que é Python WhatsApp?

Python WhatsApp é o uso da linguagem Python para automatizar envio de mensagens, criar chatbots e integrar WhatsApp Business com sistemas através de bibliotecas como requests (Evolution API), pywhatkit (WhatsApp Web) e twilio (API oficial). Desenvolvedores criam automações em 30-60 linhas de código que economizam 10-20h/semana de trabalho manual.

Diferencial Python: Sintaxe simples + bibliotecas poderosas = automação rápida

Popularidade: #1 linguagem para automação (Stack Overflow Survey 2024)

Métodos de integração (comparação)

MétodoDificuldadeCustoLimiteRecomendado
Evolution APIFácilR$ 0 + VPS R$ 60Ilimitado✅ Produção
PyWhatKitMuito fácilR$ 0~20/dia⚠️ Testes apenas
Twilio APIMédia$0.005/msgIlimitado🟡 Enterprise
SeleniumDifícilR$ 0~50/dia❌ Instável

Recomendação: Evolution API para 90% dos casos (estável, grátis, ilimitado)

Setup Evolution API com Python

Passo 1: Instalar biblioteca requests

pip install requests python-dotenv

Passo 2: Configurar credenciais

Criar arquivo .env:

EVOLUTION_URL=http://seu-vps:8080
EVOLUTION_API_KEY=sua_chave_secreta
EVOLUTION_INSTANCE=minha-instancia

Passo 3: Criar classe WhatsApp

import os
import requests
from dotenv import load_dotenv

load_dotenv()

class WhatsAppClient:
    def __init__(self):
        self.base_url = os.getenv('EVOLUTION_URL')
        self.api_key = os.getenv('EVOLUTION_API_KEY')
        self.instance = os.getenv('EVOLUTION_INSTANCE')

        self.headers = {
            'apikey': self.api_key,
            'Content-Type': 'application/json'
        }

    def enviar_texto(self, numero, mensagem):
        """
        Envia mensagem de texto

        Args:
            numero (str): Número com DDI (5511999999999)
            mensagem (str): Texto da mensagem

        Returns:
            dict: Resposta da API
        """
        url = f"{self.base_url}/message/sendText/{self.instance}"

        payload = {
            "number": numero,
            "text": mensagem
        }

        response = requests.post(url, json=payload, headers=self.headers)
        return response.json()

    def enviar_imagem(self, numero, url_imagem, legenda=""):
        """Envia imagem por URL"""
        url = f"{self.base_url}/message/sendMedia/{self.instance}"

        payload = {
            "number": numero,
            "mediatype": "image",
            "media": url_imagem,
            "caption": legenda
        }

        response = requests.post(url, json=payload, headers=self.headers)
        return response.json()

    def enviar_audio(self, numero, url_audio):
        """Envia áudio"""
        url = f"{self.base_url}/message/sendWhatsAppAudio/{self.instance}"

        payload = {
            "number": numero,
            "audio": url_audio
        }

        response = requests.post(url, json=payload, headers=self.headers)
        return response.json()

    def verificar_numero(self, numero):
        """Verifica se número está no WhatsApp"""
        url = f"{self.base_url}/chat/whatsappNumbers/{self.instance}"

        payload = {"numbers": [numero]}

        response = requests.post(url, json=payload, headers=self.headers)
        return response.json()

    def buscar_mensagens(self, numero=None, limite=50):
        """Busca mensagens recebidas"""
        url = f"{self.base_url}/chat/findMessages/{self.instance}"

        payload = {"limit": limite}

        if numero:
            payload["where"] = {
                "key": {
                    "remoteJid": f"{numero}@s.whatsapp.net"
                }
            }

        response = requests.post(url, json=payload, headers=self.headers)
        return response.json()

# Uso
if __name__ == "__main__":
    whats = WhatsAppClient()

    # Enviar mensagem
    resultado = whats.enviar_texto(
        "5511999999999",
        "Olá! Esta é uma mensagem automática via Python."
    )

    print(resultado)

Passo 4: Testar

from whatsapp_client import WhatsAppClient

whats = WhatsAppClient()

# Teste 1: Mensagem simples
whats.enviar_texto("5511999999999", "Teste Python!")

# Teste 2: Com emojis
whats.enviar_texto("5511999999999", "Olá! 👋 Tudo bem? 😊")

# Teste 3: Verificar número
resultado = whats.verificar_numero("5511999999999")
print(resultado)
# {'exists': True, 'jid': '5511999999999@s.whatsapp.net'}

Caso Real: Imobiliária automatizou 200 follow-ups/dia

Empresa: Imobiliária (15 corretores, Belo Horizonte)

Problema:

  • 40-60 leads/dia (sites + redes sociais)
  • Follow-up manual (corretores esqueciam 50%)
  • Tempo resposta: 4-8 horas
  • Conversão lead → visita: 12%

Solução Python:

Script automação (followup_leads.py):

import pandas as pd
from whatsapp_client import WhatsAppClient
from datetime import datetime, timedelta
import time

# Conectar banco dados (exemplo CSV)
leads = pd.read_csv('leads_pendentes.csv')

whats = WhatsAppClient()

# Template mensagem
def gerar_mensagem(nome, tipo_imovel, bairro):
    return f"""Olá {nome}! 👋

Vi que você tem interesse em {tipo_imovel} no {bairro}.

Temos 3 opções INCRÍVEIS que combinam com você:

🏠 Opção 1: [descrição]
🏠 Opção 2: [descrição]
🏠 Opção 3: [descrição]

Quando você pode fazer uma visita?

--
{whats.corretor_responsavel}
[Imobiliária Nome]
(31) 9999-9999"""

# Processar leads
for index, lead in leads.iterrows():
    try:
        # Pular se já contatado nas últimas 24h
        ultimo_contato = pd.to_datetime(lead['ultimo_contato'])
        if datetime.now() - ultimo_contato < timedelta(hours=24):
            continue

        # Enviar mensagem
        mensagem = gerar_mensagem(
            lead['nome'],
            lead['tipo_imovel'],
            lead['bairro_interesse']
        )

        whats.enviar_texto(lead['telefone'], mensagem)

        # Atualizar CSV
        leads.at[index, 'ultimo_contato'] = datetime.now()
        leads.at[index, 'status'] = 'followup_enviado'

        print(f"✅ Enviado para {lead['nome']}")

        # Delay 5-10s (humanizar)
        time.sleep(random.randint(5, 10))

    except Exception as e:
        print(f"❌ Erro {lead['nome']}: {e}")

# Salvar atualizações
leads.to_csv('leads_pendentes.csv', index=False)

print(f"\n📊 Total processado: {len(leads)}")

Agendamento automático (cron):

# Rodar a cada 2 horas (seg-sex, 9-19h)
0 9-19/2 * * 1-5 cd /home/deploy/imobiliaria && python3 followup_leads.py

Resultados (3 meses):

  • ✅ Follow-ups enviados: 200/dia (antes: 80/dia manual)
  • ✅ Tempo resposta: 8h → 15 minutos
  • ✅ Conversão lead → visita: 12% → 28% (+133%)
  • ✅ Visitas/semana: 35 → 84 (+140%)
  • ✅ Vendas/mês: 8 → 19 (+137%)
  • ✅ Economia tempo: 15h/dia corretor (dedicam a visitas)
  • ✅ ROI: 2.850% (receita adicional vs custo automação)

Investimento:

  • VPS: R$ 60/mês
  • Desenvolvimento: R$ 500 (one-time, 8h)
  • Payback: <1 semana

Envio em massa (broadcast)

import pandas as pd
from whatsapp_client import WhatsAppClient
import time
import random

def enviar_broadcast(arquivo_csv, coluna_numero, coluna_nome, mensagem_template):
    """
    Envia mensagem para lista de contatos

    Args:
        arquivo_csv: Caminho CSV com contatos
        coluna_numero: Nome coluna com números
        coluna_nome: Nome coluna com nomes
        mensagem_template: Template com {nome} para personalizar
    """
    whats = WhatsAppClient()

    # Ler CSV
    contatos = pd.read_csv(arquivo_csv)

    # Estatísticas
    enviados = 0
    erros = 0

    for index, contato in contatos.iterrows():
        try:
            # Personalizar mensagem
            mensagem = mensagem_template.format(nome=contato[coluna_nome])

            # Enviar
            whats.enviar_texto(contato[coluna_numero], mensagem)

            enviados += 1
            print(f"✅ {enviados}/{len(contatos)}: {contato[coluna_nome]}")

            # Delay aleatório (evitar ban)
            time.sleep(random.randint(8, 15))

        except Exception as e:
            erros += 1
            print(f"❌ Erro {contato[coluna_nome]}: {e}")

    print(f"\n📊 Resumo:")
    print(f"   Total: {len(contatos)}")
    print(f"   Enviados: {enviados}")
    print(f"   Erros: {erros}")

# Uso
mensagem = """Olá {nome}! 👋

PROMOÇÃO RELÂMPAGO (só hoje!):

🔥 50% OFF em todos cursos
⏰ Válido até 23:59

Aproveite 👉 https://link.com/promo

--
Equipe Cursos Online"""

enviar_broadcast(
    'contatos.csv',
    'telefone',
    'nome',
    mensagem
)

Boas práticas:

  • ✅ Delay 8-15s entre mensagens
  • ✅ Máximo 200-300 mensagens/dia por número
  • ✅ Personalizar com nome (mínimo)
  • ✅ Opt-in claro (permissão prévia)
  • ❌ Nunca enviar spam genérico

Webhook: receber mensagens

from flask import Flask, request, jsonify
from whatsapp_client import WhatsAppClient
import os

app = Flask(__name__)
whats = WhatsAppClient()

@app.route('/webhook', methods=['POST'])
def webhook():
    """Recebe mensagens do Evolution API"""
    try:
        data = request.json

        # Ignorar mensagens próprias
        if data['data']['key'].get('fromMe'):
            return jsonify({'status': 'ignored'}), 200

        # Extrair dados
        numero = data['data']['key']['remoteJid'].replace('@s.whatsapp.net', '')
        mensagem = (
            data['data']['message'].get('conversation') or
            data['data']['message'].get('extendedTextMessage', {}).get('text') or
            ''
        )

        if not mensagem:
            return jsonify({'status': 'no_message'}), 200

        print(f"📩 Mensagem de {numero}: {mensagem}")

        # Processar mensagem (exemplo: bot simples)
        resposta = processar_mensagem(mensagem.lower())

        # Enviar resposta
        whats.enviar_texto(numero, resposta)

        return jsonify({'status': 'success'}), 200

    except Exception as e:
        print(f"❌ Erro webhook: {e}")
        return jsonify({'error': str(e)}), 500

def processar_mensagem(texto):
    """Lógica chatbot simples"""
    if 'oi' in texto or 'olá' in texto:
        return "Olá! Como posso ajudar? 😊"

    elif 'preço' in texto or 'quanto custa' in texto:
        return "Nossos preços:\n\n✅ Plano Básico: R$ 49/mês\n✅ Plano Pro: R$ 99/mês\n\nQual te interessa?"

    elif 'horário' in texto:
        return "Atendemos:\n\n🕐 Seg-Sex: 9h-18h\n🕐 Sáb: 9h-13h\n\nPosso ajudar com algo mais?"

    elif 'humano' in texto or 'atendente' in texto:
        # Notificar equipe (implementar)
        return "Vou te transferir para um atendente humano. Aguarde 1 minuto!"

    else:
        return "Desculpe, não entendi. Pode reformular? Ou digite 'HUMANO' para falar com atendente."

if __name__ == '__main__':
    port = int(os.getenv('PORT', 5000))
    app.run(host='0.0.0.0', port=port, debug=False)

Configurar webhook Evolution:

curl -X POST http://seu-vps:8080/webhook/set/minha-instancia \
  -H "apikey: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "http://seu-servidor:5000/webhook",
    "webhook_by_events": false,
    "events": ["MESSAGES_UPSERT"]
  }'

Integração com banco de dados

import psycopg2
from datetime import datetime

class WhatsAppDB:
    def __init__(self, connection_string):
        self.conn = psycopg2.connect(connection_string)
        self.cursor = self.conn.cursor()

    def salvar_mensagem(self, numero, mensagem, direcao='recebida'):
        """Salva mensagem no banco"""
        query = """
            INSERT INTO mensagens (numero, mensagem, direcao, data)
            VALUES (%s, %s, %s, %s)
        """
        self.cursor.execute(query, (numero, mensagem, direcao, datetime.now()))
        self.conn.commit()

    def buscar_historico(self, numero, limite=50):
        """Busca últimas mensagens de um número"""
        query = """
            SELECT mensagem, direcao, data
            FROM mensagens
            WHERE numero = %s
            ORDER BY data DESC
            LIMIT %s
        """
        self.cursor.execute(query, (numero, limite))
        return self.cursor.fetchall()

    def estatisticas(self):
        """Estatísticas gerais"""
        query = """
            SELECT
                COUNT(*) as total,
                COUNT(CASE WHEN direcao = 'enviada' THEN 1 END) as enviadas,
                COUNT(CASE WHEN direcao = 'recebida' THEN 1 END) as recebidas,
                COUNT(DISTINCT numero) as contatos_unicos,
                DATE(data) as dia
            FROM mensagens
            WHERE data >= NOW() - INTERVAL '7 days'
            GROUP BY DATE(data)
            ORDER BY dia DESC
        """
        self.cursor.execute(query)
        return self.cursor.fetchall()

# Uso no webhook:
db = WhatsAppDB(os.getenv('DATABASE_URL'))

@app.route('/webhook', methods=['POST'])
def webhook():
    # ... (receber mensagem)

    # Salvar no banco
    db.salvar_mensagem(numero, mensagem, 'recebida')

    # Consultar histórico
    historico = db.buscar_historico(numero, limite=10)

    # Gerar resposta contexto-aware
    resposta = gerar_resposta_com_contexto(mensagem, historico)

    # Enviar e salvar
    whats.enviar_texto(numero, resposta)
    db.salvar_mensagem(numero, resposta, 'enviada')

    return jsonify({'status': 'success'}), 200

Agendamento de mensagens

from apscheduler.schedulers.background import BackgroundScheduler
from datetime import datetime, timedelta

scheduler = BackgroundScheduler()
scheduler.start()

def agendar_mensagem(numero, mensagem, quando):
    """
    Agenda envio futuro

    Args:
        numero: Telefone destino
        mensagem: Texto a enviar
        quando: datetime ou timedelta
    """
    def enviar():
        whats = WhatsAppClient()
        whats.enviar_texto(numero, mensagem)
        print(f"✅ Mensagem agendada enviada para {numero}")

    if isinstance(quando, timedelta):
        data_envio = datetime.now() + quando
    else:
        data_envio = quando

    scheduler.add_job(
        enviar,
        'date',
        run_date=data_envio,
        id=f'msg_{numero}_{data_envio.timestamp()}'
    )

    print(f"⏰ Agendado para {data_envio.strftime('%d/%m %H:%M')}")

# Exemplos:
# Enviar daqui a 1 hora
agendar_mensagem(
    "5511999999999",
    "Lembrete: reunião às 15h!",
    timedelta(hours=1)
)

# Enviar em data específica
agendar_mensagem(
    "5511999999999",
    "Feliz aniversário! 🎉",
    datetime(2026, 3, 15, 9, 0, 0)
)

Próximos passos

  1. Configurar Evolution API - Setup base
  2. Criar chatbot avançado - Bot inteligente
  3. Integrar IA ChatGPT - Respostas contextuais
  4. Automação N8N - Workflows visuais

Sobre o autor: Felipe Zanoni é desenvolvedor Python especializado em automação WhatsApp, com 400+ scripts implementados gerando economia de 10.000+ horas/ano para clientes.

💬 Precisa de Ajuda para Implementar?

A Agência Café Online já ajudou dezenas de empresas a implementarem soluções de automação e IA, com resultados reais e mensuráveis.

Fale comigo:

💡 Consultoria inicial gratuita para avaliar seu caso e propor uma solução personalizada.