Mensajes Programados

Administra los mensajes creados con delay o scheduleTime mediante POST /v1/messages y POST /v1/messages/template . El messageId de la respuesta HTTP 202 basta para consultar, reprogramar o cancelar un envío.

Resumen de endpoints

Crear un mensaje programado

Estos endpoints administran mensajes ya creados. Para crear uno, consulta Enviar Mensaje Personalizado o Enviar Plantilla y agrega exactamente uno de estos campos:

• delay: de 3000 ms a 86400000 ms (24 horas).
• scheduleTime: fecha futura en ISO 8601, como máximo 30 días después de la solicitud.

Los campos son mutuamente exclusivos. La respuesta HTTP 202 incluye el messageId que usarás en los endpoints de esta página.

Recurso público

Las operaciones de obtener, reprogramar y cancelar devuelven este recurso. Al listar, cada elemento de messages tiene la misma forma:

{
  "messageId": "msg_01JQ91AB7C4D8E2F6G0H",
  "kind": "template",
  "status": "scheduled",
  "channelId": "wb-12345",
  "conversationId": "5215512345678",
  "campaignId": "api",
  "messageType": null,
  "templateName": "recordatorio_cita",
  "preview": "Hola Ana, te recordamos tu cita...",
  "phoneNumber": "5215512345678",
  "name": "Ana López",
  "executeAt": "2026-10-15T15:45:00.000Z",
  "createdAt": "2026-09-20T20:00:00.000Z",
  "updatedAt": "2026-09-20T20:00:00.000Z",
  "cancelledAt": null,
  "sentAt": null,
  "failedAt": null,
  "error": null,
  "reschedulable": true
}

Listar Mensajes Programados

GET https://api.platica.mx/v1/messages/scheduled

Sin filtros, devuelve los mensajes activos con estado creating, delayed, scheduled o processing.

Parámetros de consulta

Ejemplo con filtros:

curl "https://api.platica.mx/v1/messages/scheduled?status=scheduled,processing&kind=template&from=2026-10-01T00%3A00%3A00Z&to=2026-11-01T00%3A00%3A00Z&limit=50" \
  -H "Authorization: Bearer pl_key_..."

Respuesta

Paginación

count indica cuántos elementos incluye la página actual. Cuando existe otra página, la respuesta incluye nextPageToken. Envíalo sin modificar como pageToken y conserva los mismos filtros:

curl "https://api.platica.mx/v1/messages/scheduled?status=scheduled,processing&kind=template&limit=50&pageToken=eyJleGVjdXRlQXQiOiIyMDI2LTEwLTE1VDE1OjQ1OjAwLjAwMFoifQ" \
  -H "Authorization: Bearer pl_key_..."

Cuando nextPageToken no está presente, llegaste a la última página. No interpretes ni construyas tokens manualmente.

Obtener Mensaje Programado

GET https://api.platica.mx/v1/messages/scheduled/{messageId}

Parámetros del recurso

Los mismos parámetros aplican a las operaciones de obtener, reprogramar y cancelar.

curl "https://api.platica.mx/v1/messages/scheduled/msg_01JQ91AB7C4D8E2F6G0H" \
  -H "Authorization: Bearer pl_key_..."

Respuesta

Devuelve el recurso público correspondiente a messageId.

Reprogramar Mensaje Programado

PATCH https://api.platica.mx/v1/messages/scheduled/{messageId}

Envía exactamente uno de scheduleTime o delay. No necesitas enviar campaignId, runId ni el payload original.

Cuerpo de la solicitud

Reprogramar a una fecha absoluta:

{
  "scheduleTime": "2026-10-16T10:30:00-06:00"
}

O moverlo con un retraso relativo al momento de la solicitud:

{
  "delay": 3600000
}

¹ Envía exactamente uno.

Respuesta

Devuelve el recurso público actualizado. Con scheduleTime, el estado queda scheduled; con delay, queda delayed. Si reschedulable es false, no intentes reprogramarlo.

Cancelar Mensaje Programado

DELETE https://api.platica.mx/v1/messages/scheduled/{messageId}

Cancela el envío y devuelve el recurso con estado cancelled:

curl -X DELETE "https://api.platica.mx/v1/messages/scheduled/msg_01JQ91AB7C4D8E2F6G0H" \
  -H "Authorization: Bearer pl_key_..."

Respuesta

Devuelve el recurso público con status: "cancelled", cancelledAt y reschedulable: false. La cancelación es idempotente: repetir DELETE sobre un mensaje ya cancelado devuelve el mismo recurso y no genera otro efecto.

Estados y transiciones

• creating dura normalmente solo unos instantes mientras se registra la tarea.
• delayed y scheduled representan el mismo estado pendiente. PATCH permite cambiar entre ambos sin alterar el resto del flujo.
• Mientras está pendiente, DELETE lo mueve a cancelled.
• processing significa que la ejecución ya empezó; no se puede reprogramar ni cancelar.
• sent, cancelled y failed son estados finales.
• La ventana de servicio, el estado de bloqueo del contacto y las reglas del canal se vuelven a validar al ejecutar. Un mensaje aceptado puede terminar en failed.

Fechas y zonas horarias

• Envía scheduleTime, from y to en formato ISO 8601.
• Incluye Z o un offset como -06:00 para evitar ambigüedad. Cuando omites la zona, scheduleTime usa la hora de México.
• executeAt, createdAt, updatedAt, cancelledAt, sentAt y failedAt siempre se devuelven normalizados a UTC.
• delay se calcula desde el momento en que la API acepta la solicitud.

Idempotencia

Los GET son seguros e idempotentes. Un PATCH con delay es relativo al momento de cada solicitud, así que no lo repitas automáticamente después de una respuesta incierta: consulta primero el recurso por messageId. Ante un 409, vuelve a consultar el mensaje y decide con base en status y reschedulable.

Consulta Errores de la API para conocer el formato y los códigos comunes.