Metadata-Version: 2.4
Name: doja-sdk
Version: 0.2.3
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
)
```

### 7. Templates (Mensajes Pre-aprobados por Meta)
Los templates son la única forma de iniciar una conversación con un usuario fuera de la ventana de 24 horas. El nombre del template debe coincidir exactamente con el nombre aprobado en tu panel de Meta.

**Template solo con variables en el cuerpo:**
```python
client.send_template(
    to="525512345678",
    template_name="confirmacion_pedido",
    language_code="es",
    body_variables=["Juan", "#12345", "mañana a las 15:00"]
)
```

**Template con imagen en el encabezado:**
```python
client.send_template(
    to="525512345678",
    template_name="promo_verano",
    language_code="es",
    header_image_url="https://tu-dominio.com/banner.jpg",
    body_variables=["30%", "31 de marzo"]
)
```

**Template con texto variable en el encabezado:**
```python
client.send_template(
    to="525512345678",
    template_name="bienvenida_empresa",
    language_code="es",
    header_text_variables=["DoJa Corp"],
    body_variables=["Juan"]
)
```

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