Programar mensajes por la API de WhatsApp

La Cloud API de Meta no tiene programación: envía en el momento de la llamada. La programación es una funcionalidad de la capa de Joinotify: el mismo endpoint de envío acepta un instante absoluto o un retraso relativo, guarda la petición y entrega a la hora exacta. La respuesta es 202 y no 201, porque todavía no se ha creado nada en Meta.

Dos formas de programar, y por qué existen las dos

• sendAt — un instante absoluto. Es el caso de «el viernes a las 9».
• delaySeconds — un retraso desde ahora. Es el caso de «dos horas después del carrito abandonado».

Convertir uno en otro del lado del cliente es justo donde aparecen los errores de zona horaria; por eso existen los dos.

# Dentro de dos horas
curl -X POST https://api.joinotify.com/messages \
  -H 'Authorization: Bearer sk_live_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "text",
    "to": "5541987111527",
    "body": "Tu carrito sigue guardado 🙂",
    "delaySeconds": 7200
  }'

La respuesta trae el identificador de la programación y el instante calculado:

{
  "data": {
    "id": "clz3k1p9x0000",
    "status": "pending",
    "to": "5541987111527",
    "sendAt": "2026-08-15T21:00:00.000Z",
    "messageId": null
  }
}

El messageId es nulo porque el mensaje aún no existe en Meta. Se rellena cuando el envío ocurre de verdad, y es el wamid que casa con los eventos de entrega.

Listar y cancelar

# Qué está pendiente
curl https://api.joinotify.com/messages/scheduled?status=pending \
  -H 'Authorization: Bearer sk_live_xxx'

# Cancelar
curl -X DELETE https://api.joinotify.com/messages/scheduled/clz3k1p9x0000 \
  -H 'Authorization: Bearer sk_live_xxx'

La cancelación vale incluso a segundos vista: quien entrega relee el registro antes de salir. Un mensaje ya enviado responde 404: no hay nada que cancelar.

La cancelación es la funcionalidad, no un detalle

Programar es fácil; el valor está en poder arrepentirse. Los casos que aparecen en producción son casi siempre cancelaciones:

• El carrito se recuperó antes de las dos horas: cancela el mensaje de recuperación.
• El pedido se canceló antes del recordatorio de pago.
• El cliente respondió y el asunto se resolvió antes del seguimiento programado.
• La campaña se suspendió y hay cientos de envíos pendientes.

Guarda el id de la programación junto al registro que la originó. Sin eso, cancelar significa listarlo todo y adivinar cuál es cuál.

Qué se vuelve a comprobar al enviar

Tres cosas, y ninguna en el momento de programar:

1. El derecho de uso: una suscripción caída por el camino impide el envío.
2. El número: puede haberse desconectado entre la programación y la entrega.
3. Las reglas del mensaje: la ventana de 24 horas se evalúa al enviar, no al programar.

El tercer punto es el que más sorprende. Programar texto libre para dentro de 20 horas parece seguro si la ventana está abierta ahora, pero puede haberse cerrado cuando el mensaje salga. Para programaciones lejanas, usa plantilla.

Cuándo programar y cuándo usar cola propia

• Programa en la API cuando el retraso es del negocio: recordatorio, seguimiento, recuperación, aviso de la víspera.
• Usa cola propia cuando el retraso es técnico: reintentos con backoff, control de caudal, orden de un lote.

Mezclar las dos —programar mil mensajes para el mismo minuto— cambia un problema por otro: el límite de envío del número sigue vigente en el momento de la entrega.

Preguntas frecuentes

¿La API oficial de Meta programa mensajes?

No. La programación es de la capa del proveedor; la Cloud API envía en el momento de la llamada.

¿Puedo programar una plantilla?

Puedes, y es lo recomendable para programaciones lejanas: el texto libre depende de que la ventana esté abierta al enviar.

¿Qué pasa si la suscripción vence antes del envío?

El envío no ocurre. El derecho de uso se comprueba al enviar, no al programar.

¿Puedo editar un mensaje programado?

El camino es cancelar y volver a programar, lo que además deja un historial más claro que una edición silenciosa.