doja-sdk 0.3.3

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
)

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:

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:

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:

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