Wasapaso Python SDK

SDK oficial de Python para la API de Wasapaso. Gestiona sesiones de WhatsApp y envía mensajes de manera sencilla y eficiente.

Características

• Soporte asíncrono completo: Usa async/await para operaciones concurrentes
• Type hints: Completamente tipado para mejor autocompletado en IDEs
• Modelos validados: Utiliza Pydantic para validación de datos
• Fácil de usar: API intuitiva y bien documentada
• Manejo de errores: Excepciones específicas para diferentes tipos de errores
• Testing: Suite completa de tests con alta cobertura

Instalación

pip install wasapaso

Inicio Rápido

from wasapaso import WasapasoClient

# Inicializar el cliente con tu API key
client = WasapasoClient(api_key="wsk_your_api_key_here")

# Crear una sesión de WhatsApp
session = client.sessions.create({"name": "Mi Primera Sesión"})

# Iniciar la sesión
client.sessions.start(session.id)

# Enviar un mensaje de texto
result = client.messages.send_text(
    session_id=session.id,
    to="1234567890",
    message="¡Hola desde Wasapaso!"
)

Uso Asíncrono

import asyncio
from wasapaso import WasapasoClient

async def main():
    client = WasapasoClient(api_key="wsk_your_api_key_here")

    # Crear sesión de forma asíncrona
    session = await client.sessions.create_async({"name": "Sesión Async"})

    # Enviar mensaje de forma asíncrona
    result = await client.messages.send_text_async(
        session_id=session.id,
        to="1234567890",
        message="¡Hola async!"
    )

asyncio.run(main())

Documentación

Autenticación

Obtén tu API key desde el dashboard de Wasapaso.

from wasapaso import WasapasoClient

client = WasapasoClient(
    api_key="wsk_your_api_key",
    base_url="https://api.wasapaso.com",  # Opcional
    timeout=30.0  # Timeout en segundos (opcional)
)

Gestión de Sesiones

Crear una sesión

session = client.sessions.create({
    "name": "Mi Sesión",
    "webhookUrl": "https://myapp.com/webhook",  # Opcional
    "webhookEvents": ["message", "message.ack"],  # Opcional
})

Listar sesiones

sessions = client.sessions.list(page=1, limit=20, status="WORKING")

for session in sessions.data:
    print(f"{session.name}: {session.status}")

Obtener una sesión

session = client.sessions.get("session_id")
print(f"Status: {session.status}")

Iniciar una sesión

session = client.sessions.start("session_id")

Obtener código QR

qr = client.sessions.get_qr("session_id")
print(qr.qr)  # Código QR en base64 o formato especificado

Solicitar código de emparejamiento

pairing = client.sessions.request_pairing_code("session_id", "+1234567890")
print(f"Código: {pairing.code}")

Actualizar sesión

session = client.sessions.update("session_id", {
    "name": "Nuevo Nombre",
    "metadata": {"custom_field": "value"}
})

Detener sesión

session = client.sessions.stop("session_id")

Eliminar sesión

result = client.sessions.delete("session_id")

Envío de Mensajes

Mensaje de texto

result = client.messages.send_text(
    session_id="session_id",
    to="1234567890",
    message="Hola, ¿cómo estás?",
    reply_to="message_id"  # Opcional
)

Mensaje con imagen

result = client.messages.send_media(
    session_id="session_id",
    to="1234567890",
    media_type="image",
    media_url="https://example.com/image.jpg",
    caption="Mira esta imagen!",
    mimetype="image/jpeg"
)

Mensaje con video

result = client.messages.send_media(
    session_id="session_id",
    to="1234567890",
    media_type="video",
    media_url="https://example.com/video.mp4",
    caption="Video interesante",
    mimetype="video/mp4"
)

Mensaje con archivo

result = client.messages.send_media(
    session_id="session_id",
    to="1234567890",
    media_type="file",
    media_url="https://example.com/document.pdf",
    filename="documento.pdf",
    mimetype="application/pdf"
)

Enviar ubicación

result = client.messages.send_location(
    session_id="session_id",
    to="1234567890",
    latitude=40.7128,
    longitude=-74.0060,
    title="Nueva York"
)

Listar mensajes

messages = client.messages.list(
    session_id="session_id",
    chat_id="1234567890@c.us",  # Opcional
    limit=50,
    offset=0
)

for msg in messages.data:
    print(f"{msg.from_}: {msg.body}")

Obtener un mensaje

message = client.messages.get("message_id")

Marcar como leído

client.messages.mark_as_read("message_id")

Reaccionar a un mensaje

client.messages.react("message_id", "👍")

Eliminar un mensaje

client.messages.delete("message_id", delete_for_everyone=True)

Manejo de Errores

El SDK proporciona excepciones específicas para diferentes tipos de errores:

from wasapaso import WasapasoClient
from wasapaso.exceptions import (
    AuthenticationError,
    ValidationError,
    NotFoundError,
    RateLimitError,
    WasapasoError
)

try:
    client = WasapasoClient(api_key="wsk_invalid_key")
    session = client.sessions.get("invalid_id")
except AuthenticationError:
    print("API key inválida")
except NotFoundError:
    print("Sesión no encontrada")
except RateLimitError:
    print("Límite de tasa excedido")
except ValidationError as e:
    print(f"Error de validación: {e.message}")
except WasapasoError as e:
    print(f"Error general: {e.message}")

Ejemplos Avanzados

Enviar múltiples mensajes en paralelo

import asyncio
from wasapaso import WasapasoClient

async def send_bulk_messages():
    client = WasapasoClient(api_key="wsk_your_api_key")

    recipients = ["1111111111", "2222222222", "3333333333"]

    tasks = [
        client.messages.send_text_async(
            session_id="session_id",
            to=recipient,
            message=f"Hola {recipient}!"
        )
        for recipient in recipients
    ]

    results = await asyncio.gather(*tasks)
    return results

asyncio.run(send_bulk_messages())

Usar con context manager

from wasapaso import WasapasoClient

def main():
    client = WasapasoClient(api_key="wsk_your_api_key")

    # Crear sesión
    session = client.sessions.create({"name": "Temp Session"})

    try:
        # Usar la sesión
        client.sessions.start(session.id)
        client.messages.send_text(
            session_id=session.id,
            to="1234567890",
            message="Test"
        )
    finally:
        # Limpiar
        client.sessions.delete(session.id)

Desarrollo

Instalación para desarrollo

git clone https://github.com/wasapaso/sdk-python.git
cd sdk-python
pip install -e ".[dev]"

Ejecutar tests

pytest

Ejecutar tests con cobertura

pytest --cov=wasapaso --cov-report=html

Formatear código

black wasapaso tests

Type checking

mypy wasapaso

Requisitos

• Python >= 3.8
• httpx >= 0.25.0
• pydantic >= 2.0.0

Soporte

• Documentación: https://docs.wasapaso.com/sdk/python
• Issues: https://github.com/wasapaso/sdk-python/issues
• Email: support@wasapaso.com

Licencia

MIT License - ver LICENSE para más detalles.

Contribuir

Las contribuciones son bienvenidas! Por favor lee nuestra guía de contribución antes de enviar un pull request.

Changelog

Ver CHANGELOG.md para detalles de cambios en cada versión.

---

Desarrollado con ❤️ por el equipo de Wasapaso