La cola de envío

Qué pasa en realidad

Envía a alguien que no escribió a tu número en las últimas 24 horas, y la API responde queued en vez de sent:

{
  "data": {
    "id": "9c1f0b7e-8b1a-4a2e-9b0a-1f2e3d4c5b6a",
    "to": "+5511988887777",
    "status": "queued",
    "scheduledAt": "2026-08-24T19:18:00.000Z",
    "quotaRemaining": 4999,
    "newConversationsRemaining": 19
  }
}

El mensaje se descuenta de la cuota cuando la llamada lo acepta. scheduledAt es la hora prevista de envío. Los mensajes en cola salen con 15 a 25 minutos de intervalo por defecto, elegido al azar, uno por uno por número. El intervalo se cuenta desde la salida real del mensaje anterior, no desde un horario antiguo, para que una cola atrasada no salga toda de golpe. Hasta que salga, id es el id de la cola, no el del mensaje de WhatsApp.

Por qué lo retenemos

Enviar muchos mensajes en poco tiempo puede parecer spam, incluso para contactos conocidos. Espaciar la cola evita una ráfaga accidental. No garantiza que WhatsApp mantenga el número conectado.

La falla que esto evita es aburrida y común. Mandas una lista de quince, tu propio sistema agrega cuatro más atrás, y para el almuerzo el número ya no está. Nadie quiso spamear a nadie. La ráfaga es un accidente de que el software es rápido.

Todo lo demás de cómo evitar el baneo sigue valiendo. Esto resuelve el tiempo, que es justo la parte más difícil de acertar a mano.

Qué nunca se retiene

Estas son las excepciones para envíos individuales. Con la cola activada, cada mensaje de un lote espera el intervalo completo, incluso respuestas y mensajes a contactos conocidos.

• Las respuestas recientes salen al momento. La persona debe haber enviado un mensaje a este número en las últimas 24 horas. Un contacto guardado en el teléfono, un mensaje enviado en el pasado o un chat importado al vincular no bastan.
• send_otp nunca espera ni muestra "escribiendo…", porque hay alguien en un formulario esperando el código. El primer código a una persona nueva sigue usando el límite de conversaciones nuevas del día.
• skipQueue: true se salta la cola en ese envío. Úsalo solo cuando la persona espere el mensaje al momento. Los mensajes a grupos tampoco pasan por la cola en envíos individuales.
• Un número con pacing.enabled: false envía todo al instante, y espaciar los envíos pasa a ser tarea tuya.

await client.sendMessage({
  to: "+5511988887777",
  text: `Your code is ${code}`,
  // Only for something the recipient is waiting for RIGHT NOW.
  skipQueue: true,
});

Saber cuándo salió

La llamada de envío no puede darte el id de mensaje de WhatsApp, porque todavía no se envió nada. message.sent llega a tu webhook cuando el mensaje finalmente sale. Trae el id de la cola que ya tienes, junto al messageId del propio WhatsApp, que es el que usarán los acuses de entrega.

{
  "id": "6f1e…",
  "type": "message.sent",
  "timestamp": "2026-08-24T19:18:04.000Z",
  "data": {
    "number": { "id": "a1b2…", "name": "Outreach", "phone": "5511900000000" },
    "id": "9c1f0b7e-8b1a-4a2e-9b0a-1f2e3d4c5b6a",
    "messageId": "3EB0C7E5F5A2B4D9E1F3",
    "to": "+5511988887777",
    "queuedAt": "2026-08-24T19:00:00.000Z",
    "sentAt": "2026-08-24T19:18:04.000Z"
  }
}

Si el número se desconecta o queda restringido, los mensajes que aún no salieron siguen en cola. Cuando reconecta, vuelven a salir con el intervalo configurado. Un rechazo confirmado, como una url de un archivo que dejó de funcionar, puede generar message.failed y una devolución de cuota. Si no sabemos si el mensaje salió tras un timeout o una interrupción, no lo repetimos ni devolvemos la cuota como si no hubiera salido. Revisa el chat y los acuses de entrega antes de reenviarlo.

Ver y cancelar lo que espera

GET /v1/queue lista los mensajes que todavía esperan, primero los más próximos. Cancela antes de que empiece el envío. La respuesta indica si se devolvió la cuota del mensaje, y se libera cualquier parte del límite de conversaciones nuevas que hubiera reservado. En el panel, Mensajes muestra la cola de la cuenta y Números muestra la cola de cada número.

const waiting = await client.listQueuedMessages({ numberId });
// [{ id, to, kind, preview, scheduledAt, queuedAt }, …]

await client.cancelQueuedMessage({ id: waiting[0].id });
// → { canceled: true, refunded: true }

Cambiar el intervalo

El intervalo pertenece al número y por defecto es de 15–25 minutos. Cámbialo con update_number, o en el panel, en Números.

await client.updateNumber({
  numberId,
  pacing: { minMinutes: 30, maxMinutes: 90 },   // slower, safer
  humanize: { markRead: false },                // no blue ticks from us
});

Puedes desactivar la cola, pero entonces debes espaciar los envíos por tu cuenta. También se aplica cuando usas skipQueue. Evita las ráfagas y escribe solo a quien espere tus mensajes.

Enviar como una persona

La segunda mitad de la misma idea: el envío se hace como lo haría una persona, no como lo haría un software.

• El número se conecta justo antes de enviar, y se desconecta después.
• Abre lo último que escribió el destinatario, lo que marca los ticks azules, antes de responder.
• Muestra “escribiendo…” durante el tiempo que tomaría escribir el mensaje.

Esto cuesta unos segundos por llamada y viene activado. Apaga cualquier parte por número con update_number, o solo en un mensaje con humanize: false.

Qué no es esto

No es un programador de envíos. Eliges un intervalo, nunca una hora de entrega. Tampoco es una garantía de entrega. WhatsApp sigue decidiendo si el mensaje llega, y los acuses siguen llegando en message.status.

Y no reemplaza tener algo que valga la pena enviar. La cola espacia una lista mala perfectamente bien. No evita que la gente de esa lista toque Bloquear.