Metadata-Version: 2.4
Name: py-whatsapp-cloud
Version: 0.1.0
Summary: SDK leve para WhatsApp Business Cloud API
Home-page: https://github.com/josuelb/py-whatsapp-cloud
Author: Josué Luiz
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: summary

# 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:

```bash
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:

```python
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

```python
# 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:

```python
# 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:

```python
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](https://www.google.com/search?q=https://github.com/josuelb)

---
