pywhatsweb 0.4.1

Biblioteca Python para WhatsApp Web corporativo baseada em sidecar Node.js com whatsapp-web.js

PyWhatsWeb 🚀 v0.2.1

Biblioteca Python pura para WhatsApp Web corporativo, baseada em sidecar Node.js com whatsapp-web.js.

🎯 O QUE É

PyWhatsWeb é uma biblioteca Python que pode ser usada em qualquer projeto Python:

• ✅ Scripts Python simples
• ✅ FastAPI
• ✅ Flask
• ✅ Django (opcional)
• ✅ Qualquer outro framework Python

NÃO é um projeto Django - é uma biblioteca Python que pode ser integrada em projetos Django se você quiser.

✨ CARACTERÍSTICAS

• 🔐 Autenticação QR Code via sidecar Node.js
• 📡 Eventos WebSocket em tempo real
• 🎯 Multi-sessão com isolamento por sessionId
• 📊 Sistema Kanban (NEW/ACTIVE/DONE) para roteamento
• 💾 Storage pluggable (FileSystem + Django opcional)
• 🌐 API HTTP para controle de sessões
• 🔒 Autenticação por API Key
• 📱 Suporte completo ao whatsapp-web.js

🚀 INSTALAÇÃO

PyPI Oficial

pip install pywhatsweb

Com suporte Django (opcional)

pip install pywhatsweb[django]

Desenvolvimento

git clone https://github.com/llongaray/pywhatsweb.git
cd pywhatsweb
pip install -e .

📖 USO BÁSICO (SEM Django)

1. Script Python Simples

from pywhatsweb import WhatsWebManager, FileSystemStore

# Criar manager com storage de filesystem
manager = WhatsWebManager(
    sidecar_host="localhost",
    sidecar_port=3000,
    api_key="sua-api-key",
    storage=FileSystemStore("./whatsapp_data")  # Storage local
)

# Criar sessão
session = manager.create_session("sessao_123")

# Configurar eventos
@session.on("qr")
def on_qr(data):
    print(f"🔍 QR Code: {data['qr'][:50]}...")

@session.on("message")
def on_message(data):
    print(f"📨 Nova mensagem: {data['body']}")

# Iniciar sessão
session.start()

2. FastAPI

from fastapi import FastAPI
from pywhatsweb import WhatsWebManager, FileSystemStore

app = FastAPI()

# Criar manager global
manager = WhatsWebManager(
    sidecar_host="localhost",
    sidecar_port=3000,
    api_key="sua-api-key",
    storage=FileSystemStore("./whatsapp_data")
)

@app.post("/whatsapp/session/{session_id}/start")
async def start_session(session_id: str):
    session = manager.create_session(session_id)
    session.start()
    return {"message": "Sessão iniciada"}

@app.post("/whatsapp/session/{session_id}/send")
async def send_message(session_id: str, to: str, message: str):
    session = manager.get_session(session_id)
    session.send_text(to, message)
    return {"message": "Mensagem enviada"}

3. Flask

from flask import Flask, request, jsonify
from pywhatsweb import WhatsWebManager, FileSystemStore

app = Flask(__name__)

# Criar manager global
manager = WhatsWebManager(
    sidecar_host="localhost",
    sidecar_port=3000,
    api_key="sua-api-key",
    storage=FileSystemStore("./whatsapp_data")
)

@app.route('/whatsapp/session/<session_id>/start', methods=['POST'])
def start_session(session_id):
    session = manager.create_session(session_id)
    session.start()
    return jsonify({"message": "Sessão iniciada"})

@app.route('/whatsapp/session/<session_id>/send', methods=['POST'])
def send_message(session_id):
    data = request.get_json()
    session = manager.get_session(session_id)
    session.send_text(data['to'], data['message'])
    return jsonify({"message": "Mensagem enviada"})

🔧 INTEGRAÇÃO COM DJANGO (OPCIONAL)

Se você quiser usar em um projeto Django, pode usar o DjangoORMStore:

from pywhatsweb import WhatsWebManager, DjangoORMStore
from .models import (WhatsAppSession, WhatsAppMessage, WhatsAppContact,
                     WhatsAppGroup, WhatsAppChat, WhatsAppSessionEvent)

# Criar manager com storage Django
manager = WhatsWebManager(
    sidecar_host="localhost",
    sidecar_port=3000,
    api_key="sua-api-key",
    storage=DjangoORMStore()
)

# Configurar models Django (você deve implementar)
manager.storage.set_models(
    session_model=WhatsAppSession,
    message_model=WhatsAppMessage,
    contact_model=WhatsAppContact,
    group_model=WhatsAppGroup,
    chat_model=WhatsAppChat,
    event_model=WhatsAppSessionEvent
)

# Usar normalmente
session = manager.create_session("sessao_123")
session.start()

NOTA: Django NÃO é obrigatório! A biblioteca funciona perfeitamente sem Django usando FileSystemStore.

🏗️ ARQUITETURA

┌─────────────────┐    HTTP + WebSocket    ┌─────────────────┐
│   Seu App       │ ◄────────────────────► │   Sidecar       │
│   Python        │                        │   Node.js       │
│                 │                        │                 │
│  PyWhatsWeb    │                        │ whatsapp-web.js │
│  (SDK)         │                        │                 │
└─────────────────┘                        └─────────────────┘

• Seu App Python: Usa a biblioteca PyWhatsWeb
• Sidecar Node.js: Gerencia conexões WhatsApp via whatsapp-web.js
• Comunicação: HTTP (ações) + WebSocket (eventos)

📱 SIDECAR NODE.JS

A biblioteca precisa do sidecar Node.js rodando. Veja a pasta sidecar/ para instalação:

cd sidecar
npm install
npm start

🎯 SISTEMA KANBAN

A biblioteca fornece enums para roteamento de conversas:

from pywhatsweb.enums import KanbanStatus

# Status disponíveis
KanbanStatus.NEW      # Aguardando
KanbanStatus.ACTIVE   # Em atendimento  
KanbanStatus.DONE     # Concluído

# Nomes de exibição
KanbanStatus.get_display_name(KanbanStatus.NEW)  # "Aguardando"

💾 STORAGE PLUGGABLE

FileSystemStore (padrão)

from pywhatsweb import FileSystemStore

storage = FileSystemStore("./whatsapp_data")
# Salva tudo em arquivos JSON

DjangoORMStore (opcional)

from pywhatsweb import DjangoORMStore

storage = DjangoORMStore()
# Salva no banco Django (se disponível)

🔌 EVENTOS WEBSOCKET

@session.on("qr")
def on_qr(data):
    # QR Code gerado
    qr_data_url = data['qr']  # data:image/png;base64,...

@session.on("authenticated")
def on_authenticated(data):
    # Autenticação bem-sucedida

@session.on("ready")
def on_ready(data):
    # Cliente WhatsApp pronto

@session.on("message")
def on_message(data):
    # Nova mensagem recebida
    chat_id = data['chatId']
    message_body = data['body']
    sender = data['from']

@session.on("disconnected")
def on_disconnected(data):
    # Cliente desconectado

📡 API HTTP

Sessões

• POST /session/:id/start - Iniciar sessão
• POST /session/:id/stop - Parar sessão
• GET /session/:id/status - Status da sessão

Mensagens

• POST /session/:id/send-message - Enviar mensagem

Health Check

• GET /health - Status do sidecar

🚨 IMPORTANTE

• PyWhatsWeb é uma BIBLIOTECA Python, não um projeto Django
• Funciona em qualquer projeto Python usando FileSystemStore
• Django é opcional - use DjangoORMStore se quiser
• Sidecar Node.js é obrigatório para funcionar
• Não abre navegador - tudo via whatsapp-web.js headless

🧪 EXEMPLOS

Veja a pasta examples/ para exemplos completos:

• basic_usage.py - Uso básico
• django_integration.py - Integração com Django (opcional)
• django_models_example.py - Models Django de exemplo

📚 DOCUMENTAÇÃO

• Sidecar Node.js
• Exemplos
• Changelog

🤝 CONTRIBUIÇÃO

Contribuições são bem-vindas! Veja CONTRIBUTING.md.

📄 LICENÇA

MIT License - veja LICENSE.

---

PyWhatsWeb - Biblioteca Python para WhatsApp Web corporativo 🚀