doja-sdk 0.2.1

Official Python SDK for DoJa Chatbots and WhatsApp Business Integration

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:

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

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.

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

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.

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

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

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

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: [e-mail]