doja-sdk 0.4.4

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 Email (Resend).

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

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).

Configuración Inicial

from doja_sdk import DojaEmailClient, DojaAuthError

try:
    email = DojaEmailClient(
        doja_token="re_123456789...",           # Tu licencia se mapea directo aquí
        from_address="[e-mail]"    # Remitente previamente 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:

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 Locales: (El SDK se encarga por debajo de codificar los archivos en Base64 de forma automática)

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"]
)

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]