Metadata-Version: 2.4
Name: doja-sdk
Version: 0.2.1
Summary: Official Python SDK for DoJa Chatbots and WhatsApp Business Integration
Author-email: DoJa Consulting <contact@dojaconsulting.cloud>
Project-URL: Homepage, https://dojaconsulting.cloud
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: requests

# DoJa Python SDK 🚀

El **DoJa SDK** es la librería principal de Python para conectar, automatizar y escalar plataformas de mensajería usando la **API Cloud Oficial de WhatsApp (Meta)**. Facilita la construcción de flujos de atención al cliente, notificaciones transaccionales y catálogos en minutos sin lidiar con los complejos requerimientos de configuración nativos.

*Nota: El uso de este SDK está protegido. Requieres una licencia oficial expedida por DoJa Consulting para interactuar con los servidores mediante esta capa.*

---

## 💻 Instalación

Solo requieres Python 3.7+ y `pip`:

```bash
pip install doja-sdk
```

---

## 🛠️ Configuración Rápida (Quickstart)

Para usar la librería, necesitas tu Token de Licencia de DoJa, tu Token Temporal/Permanente de Meta y tu ID del Número de Teléfono (Phone ID).

```python
from doja_sdk import DojaClient, DojaAuthError

try:
    client = DojaClient(
        doja_token="DOJA-SEC-TULICENCIA-AQUI",
        whatsapp_token="EAAB123456789...", 
        phone_id="100747123456"
    )
    print("¡Conexión establecida exitosamente!")
except DojaAuthError as e:
    print(f"Error de validación de licencia: {e}")
```

---

## 💬 Tipos de Mensajes Soportados

Todas las funciones requieren el número de teléfono del destinatario **con su código de país (sin el signo + ni espacios)**. Ejemplo para México: `"525512345678"`.

### 1. Mensaje de Texto Simple
Envía alertas, recordatorios o notificaciones de texto plano.
```python
client.send_text("525512345678", "¡Hola! Hemos recibido tu solicitud. Un asesor se pondrá en contacto contigo a la brevedad.")
```

### 2. Mensaje con Documento (PDF, Excel, etc.)
Ideal para adjuntar facturas, reportes médicos, contratos o recibos de compra mediante enlaces directos (URL).
```python
client.send_document(
    to="525512345678", 
    url="https://tu-dominio.com/factura-1234.pdf", 
    caption="Aquí tienes tu factura del mes 📝", 
    filename="Factura_Octubre.pdf"
)
```

### 3. Mensaje con Imagen
Para enviar banners promocionales, catálogos visuales o fotografías de productos.
```python
client.send_image(
    to="525512345678", 
    url="https://tu-dominio.com/promo-verano.jpg", 
    caption="¡Aprovecha nuestro descuento de temporada!"
)
```

### 4. Ubicación Compartida (Map Pin 📍)
Permite enviar coordenadas de oficinas, clínicas o sucursales físicas (Abre Maps/Waze nativamente en el móvil).
```python
client.send_location(
    to="525512345678", 
    latitude=19.432608, 
    longitude=-99.133209, 
    name="Oficinas Centrales", 
    address="Centro Histórico, CDMX, México"
)
```

### 5. Botones Interactivos (Respuesta Rápida)
Perfectos para encuestas o bifurcaciones de decisiones rápidas (Soporta máximo 3 botones).
```python
botones = [
    {"id": "btn_soporte", "title": "📞 Hablar con Soporte"},
    {"id": "btn_ventas", "title": "🛒 Cotizar Servicios"},
]

client.send_interactive_button(
    to="525512345678", 
    body_text="¡Bienvenido a nuestro canal de atención! ¿En qué área podemos apoyarte hoy?", 
    buttons_list=botones
)
```

### 6. Menú Desplegable (Lista Interactiva)
La mejor opción cuando tienes flujos complejos o más de 3 opciones (ej. Menú principal, selección de departamentos o listado de servicios).
```python
secciones = [
    {
        "title": "Áreas de Atención",
        "rows": [
            {"id": "opt_1", "title": "Soporte Técnico", "description": "Fallas o configuraciones"},
            {"id": "opt_2", "title": "Facturación", "description": "Dudas sobre pagos"},
            {"id": "opt_3", "title": "Ventas B2B", "description": "Soluciones empresariales"}
        ]
    }
]

client.send_interactive_list(
    to="525512345678", 
    body_text="Por favor selecciona el departamento con el que deseas comunicarte:", 
    button_text="Ver Opciones", 
    sections=secciones
)
```

---
**¿Dudas o requerimientos personalizados?** | Soporte Oficial: contact@dojaconsulting.cloud
