py-whatsapp-cloud 0.1.0

SDK leve para WhatsApp Business Cloud API

py-whatsapp-cloud 🚀

Uma SDK Python ultra-leve e de alta performance para a WhatsApp Business Cloud API. Projetada especificamente para desenvolvedores que constroem aplicações multi-tenant e precisam de isolamento total de dados, simplicidade e velocidade.

Ao contrário da SDK oficial da Meta, a py-whatsapp-cloud foca exclusivamente no WhatsApp, eliminando dependências desnecessárias de marketing e anúncios.

---

✨ Funcionalidades Atuais

• Arquitetura Multi-tenant: Gerencie múltiplos tokens, Phone IDs e WABA IDs simultaneamente de forma isolada.
• Mensageria Completa: Envio de textos e templates (essenciais para iniciar conversas).
• Gestão de Mídias: Upload de arquivos para a Meta, envio de imagens/documentos e download de mídias recebidas.
• Webhooks Seguros: Validação nativa de assinatura X-Hub-Signature-256 para garantir que os dados venham da Meta.
• Perfil de Negócio: Consulta de dados do perfil da empresa diretamente via API.

---

📦 Instalação

Como a biblioteca está em desenvolvimento ativo, você pode instalá-la diretamente do GitHub:

pip install git+https://github.com/josuelb/py-whatsapp-cloud.git

---

🚀 Como usar

1. Inicializando o Cliente

Para cada empresa que você atende, basta instanciar um novo cliente com suas respectivas credenciais:

from py_whatsapp_cloud.client import WhatsAppClient

client = WhatsAppClient(
    token="SEU_ACCESS_TOKEN",
    phone_number_id="SEU_PHONE_ID",
    waba_id="SEU_WABA_ID"
)

2. Enviando Mensagens

# Texto simples
client.send_text("5511999999999", "Olá! Como posso ajudar?")

# Template (necessário para iniciar conversas fora da janela de 24h)
client.send_template("5511999999999", "boas_vindas", language_code="pt_BR")

3. Trabalhando com Mídias

O processo de upload e envio é simplificado:

# Faz o upload e obtém o ID
media_id = client.upload_media("caminho/do/arquivo.pdf", "application/pdf")

# Envia o documento para o cliente
client.send_document("5511999999999", media_id, filename="Contrato.pdf")

---

🛡️ Validação de Webhooks

Proteja seu endpoint de mensagens recebidas validando a assinatura enviada pela Meta:

from py_whatsapp_cloud.webhooks import WebhookHandler

# No seu controller de Webhook:
is_valid = WebhookHandler.verify_signature(
    payload_body=request.data,
    signature=request.headers.get("X-Hub-Signature-256"),
    app_secret="SEU_APP_SECRET_DA_META"
)

if is_valid:
    event = WebhookHandler.process_event(request.json)
    print(f"Mensagem recebida de: {event['messages'][0]['from']}")

---

🛠️ Roadmap (Evolução)

Esta biblioteca está em sua fase v0.1.0 (Alpha). As próximas atualizações incluirão:

• Suporte para Mensagens Interativas (Botões e Listas).
• Implementação de Mensagens de Localização.
• Integração com WhatsApp Flows.
• Gestão de Catálogo de Produtos.
• Tratamento de erros customizado por código de erro da Meta.

---

📄 Licença

Distribuído sob a licença MIT. Veja LICENSE para mais informações.

🤝 Contribuição

Contribuições são o que fazem a comunidade open source um lugar incrível para aprender, inspirar e criar. Sinta-se à vontade para abrir uma Issue ou enviar um Pull Request.

---

Desenvolvido com ❤️ por Josué Luiz

---