doja-sdk 0.4.8

Official Python SDK for DoJa Chatbots and WhatsApp Business Integration

DoJa Python SDK 🚀

El DoJa SDK es la biblioteca oficial de Python para conectar, automatizar y escalar envíos masivos o transaccionales a través de WhatsApp Cloud API (Meta) y el Gateway de Emails DoJa.

Con DoJa SDK, te olvidas de integraciones complejas. Usa la misma licencia para disparar notificaciones en ambos canales mediante un código elegante, rápido y sin dependencias pesadas.

---

💻 Instalación

Solo requieres Python 3.7+ y pip. El SDK no empuja dependencias pesadas ni requiere que instales las librerías oficiales de Meta o proveedores externos de Email:

pip install doja-sdk

---

📚 Índice

1. WhatsApp (Mensajería, Templates y Multimedia)
2. Email (Texto, HTML y Adjuntos)
3. Manejo de Errores y Excepciones

---

1. Módulo de WhatsApp 💬

Para interactuar con WhatsApp, necesitas tu Token de Licencia DoJa, tu Token de Meta y tu Phone ID.

Configuración Inicial

from doja_sdk import DojaClient, DojaAuthError

try:
    wa = DojaClient(
        doja_token="TU-LICENCIA-DOJA",   # Token de tu suscripción en DoJa
        whatsapp_token="EAAB12345...",    # Token Permanente/Temporal de Meta
        phone_id="100747123456"           # Identificador de tu número en Meta
    )
    print("¡Conexión a WhatsApp exitosa!")
except DojaAuthError as e:
    print(f"Error de licencia: {e}")

Ejemplos de Envío (WhatsApp)

(Nota: El destinatario debe incluir código de país sin el signo '+'. Ej: "525512345678")

Mensaje de Texto Simple:

wa.send_text("525512345678", "¡Hola! Hemos recibido tu pago exitosamente.")

Documentos (PDF, Facturas, Excel):

wa.send_document(
    to="525512345678", 
    url="https://ejemplo.com/factura.pdf", 
    caption="Aquí tienes tu factura del mes 📝", 
    filename="Factura_Octubre.pdf" # Opcional: Nombre con el que se descarga
)

Imágenes y Promocionales:

wa.send_image(
    to="525512345678", 
    url="https://ejemplo.com/promo.jpg", 
    caption="¡Aprovecha nuestro descuento de temporada!"
)

Ubicación Compartida (Abre interactivo en Google Maps/Waze):

wa.send_location(
    to="525512345678", 
    latitude=19.432608, 
    longitude=-99.133209, 
    name="Sucursal Centro", 
    address="Centro Histórico, CDMX, México"
)

Botones Interactivos (Máximo 3 botones):

botones = [
    {"id": "soporte", "title": "Hablar con Soporte"},
    {"id": "ventas", "title": "Cotizar Servicios"}
]

wa.send_interactive_button(
    to="525512345678", 
    body_text="¿En qué área podemos apoyarte hoy?", 
    buttons_list=botones
)

Listas Desplegables (Ideal para menús largos):

secciones = [
    {
        "title": "Áreas de Atención",
        "rows": [
            {"id": "1", "title": "Soporte", "description": "Fallas técnicas"},
            {"id": "2", "title": "Ventas", "description": "Nuevas suscripciones"}
        ]
    }
]

wa.send_interactive_list(
    to="525512345678", 
    body_text="Por favor selecciona el área deseada:", 
    button_text="Ver Opciones", 
    sections=secciones
)

Templates Aprobados por Meta: (Requerido para iniciar conversación fuera de la ventana de atención de 24 hrs)

wa.send_template(
    to="525512345678",
    template_name="confirmacion_pedido",  # Nombre idéntico al de Meta
    language_code="es",
    body_variables=["Juan", "#123456", "Mañana a las 15:00 hrs"] 
)

---

2. Módulo de Email 📧

El Módulo de Email está diseñado para ser extremadamente intuitivo. Para autenticarte, no requieres doble token. Tu clave de licencia de DoJa funciona automáticamente como la llave para despachar los correos mediante nuestro proveedor subyacente (Resend).

Configuracion Rapida - Email

from doja_sdk import DojaEmailClient

email = DojaEmailClient(
    doja_token="TU-LICENCIA-DOJA",           # La licencia que DoJa valida
    external_id="LA_LLAVE_DE_SERVICIO",      # ID proporcionado por el integrador
    from_address="[e-mail]"    # Remitente verificado
)

print("¡Conexión de Email exitosa!")

except DojaAuthError as e: print(f"Error de licencia o permisos: {e}")

### Ejemplos de Envío (Email)

**Texto Plano Rápido:**
```python
email.send(
    to="[e-mail]",
    subject="Confirmación de Registro",
    body="Gracias por registrarte en nuestra plataforma."
)

Email con HTML enriquecido:

email.send(
    to="[e-mail]",
    subject="Bienvenido a tu suscripción Pro",
    body="<h1>¡Hola Juan!</h1><p>Tu cuenta ya está activa. <a href='https://app.doja.com'>Ingresa aquí</a>.</p>",
    html=True
)

Email con Archivos Adjuntos (PDF, Excel, Imágenes, etc): (El SDK lee los archivos de tu disco duro y los codifica en Base64 hacia el Gateway)

email.send(
    to="[e-mail]",
    subject="Tu Factura de Marzo",
    body="Adjuntamos tu factura digitalizada correspondiente a este mes.",
    attachments=[
        "/ruta/absoluta/factura_marzo.pdf",
        "/ruta/absoluta/cotizacion_final.xlsx"
    ]
)

Funciones Avanzadas (Múltiples destinatarios, CC, BCC y Reply-To):

email.send(
    to="[e-mail], [e-mail]",   # Puedes separar por comas
    subject="Reporte Financiero Semanal",
    body="<h2>Reporte Generado</h2><p>Aquí tienes el archivo de esta semana.</p>",
    html=True,
    cc=["[e-mail]"],
    bcc=["[e-mail]"],
    reply_to="[e-mail]",
    attachments=["/ruta/reporte.xlsx", "/ruta/resumen.pdf"]
)

---

3. Manejo de Errores 🛡️

El SDK expone excepciones estandarizadas que te permiten saber exactamente qué falló (si fue un problema de saldo, de licencia o de la API destino). Las puedes importar todas desde doja_sdk:

from doja_sdk import (
    DojaClient,
    DojaAuthError,
    DojaQuotaExceeded,
    DojaAPIError
)

try:
    client = DojaClient(...)
    client.send_text(...)

except DojaAuthError as e:
    # 404 No encontrado, 422 Inválido, 409 Suspendido, o no tiene el canal (WhatsApp/Email) pagado
    print(f"Problema con la Licencia: {e}")

except DojaQuotaExceeded as e:
    # 409 La licencia es válida, pero el cliente se acabó su bolsa de mensajes
    print(f"Saldo Agotado: {e}")

except DojaAPIError as e:
    # Ocurre si Meta o Resend rechazan la petición (Ej: plantilla mal armada, mal teléfono, adjunto pesado)
    print(f"Problema con el Proveedor Destino: {e}")

---

¿Dudas adicionales o soporte técnico?
Comunícate directamente a: [e-mail]