Cliente con Cola (ToDusClientWithQueue)

Esta página detalla el uso específico de ToDusClientWithQueue, que combina todas las capacidades de ToDusClient2 con la cola persistente.

Constructor

ToDusClientWithQueue(
    phone_number: str,
    password: str = "",
    enable_queue: bool = True,
    queue_db_path: Optional[str] = None,
    **kwargs
)

Parámetros:

  • phone_number – Número de teléfono (formato 53XXXXXXXX).
  • password – Contraseña de la cuenta.
  • enable_queue – Activa/desactiva la cola (por defecto True).
  • queue_db_path – Ruta al archivo SQLite. Si es None, usa ~/.todus/messages.db.
  • **kwargs – Se pasan a ToDusClient2 (proxy, verify_ssl, etc.).

Método Estrella: send_message_queued()

def send_message_queued(self, to_phone: str, body: str, reply_to_id: str = "") -> str

Comportamiento:

  1. Detecta automáticamente si to_phone es un número privado o un grupo.
  2. Envía el mensaje.
  3. Lo encola en SQLite.
  4. Marca como SENT si el envío fue exitoso.
  5. Si falla, el worker automático lo reintentará.

Retorna: msg_id del mensaje.

Registro de Callbacks

client.register_on_message_delivered(callback)
client.register_on_message_read(callback)
client.register_on_message_failed(callback)

Cada callback recibe un objeto Message como argumento.

Estadísticas de la Cola

stats = client.get_queue_stats()

Ejemplo de salida:

{
    'pending': 0,
    'sent': 2,
    'delivered': 5,
    'read': 3,
    'failed': 1,
    'total_pending': 0,
    'total_failed': 1,
    'worker_running': True
}

Limpieza Automática

# Elimina mensajes con estado READ o DELIVERED de más de 30 días
deleted = client.cleanup_queue()
print(f"Limpiados {deleted} mensajes")

Ejemplo Avanzado con Progreso

from todus import ToDusClientWithQueue
from todus.types import FileType

client = ToDusClientWithQueue("5312345678", "password")
client.login()

def on_progress(current, total):
    print(f"Subiendo: {current}/{total}")

# Subir archivo
image_data = open("foto.jpg", "rb").read()
url = client.upload_file(
    image_data,
    file_type=FileType.PICTURE,
    progress_callback=on_progress,
    file_name="foto.jpg"
)

# Enviar con cola
msg_id = client.send_message_queued(
    to_phone="5387654321",
    body="Mira mi foto",
    reply_to_id=""
)

# La entrega se maneja con callbacks
def on_delivered(msg):
    if msg.msg_id == msg_id:
        print("¡Foto entregada!")

client.register_on_message_delivered(on_delivered)

Consideraciones

  • La cola no garantiza orden estricto de entrega, pero sí garantiza que cada mensaje se reintente hasta alcanzar max_retries.
  • El worker de reintentos corre en un hilo daemon; se detiene automáticamente al finalizar el programa.
  • Para detenerlo manualmente: client.queue.stop_auto_retry_worker().