Scheduled Messages

Manage messages created with delay or scheduleTime through POST /v1/messages and POST /v1/messages/template . The messageId in the HTTP 202 response is enough to retrieve, reschedule, or cancel a send.

Endpoint summary

Create a scheduled message

These endpoints manage messages that already exist. To create one, see Send Custom Message or Send Template and add exactly one of these fields:

• delay: from 3000 ms to 86400000 ms (24 hours).
• scheduleTime: a future ISO 8601 date, no more than 30 days after the request.

The fields are mutually exclusive. The HTTP 202 response includes the messageId used by the endpoints on this page.

Public resource

The get, reschedule, and cancel operations return this resource. In a list response, every item in messages has the same shape:

{
  "messageId": "msg_01JQ91AB7C4D8E2F6G0H",
  "kind": "template",
  "status": "scheduled",
  "channelId": "wb-12345",
  "conversationId": "5215512345678",
  "campaignId": "api",
  "messageType": null,
  "templateName": "appointment_reminder",
  "preview": "Hi Ana, this is a reminder for your appointment...",
  "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
}

List Scheduled Messages

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

Without filters, this returns active messages with status creating, delayed, scheduled, or processing.

Query parameters

Example with filters:

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_..."

Response

Pagination

count is the number of items in the current page. When another page exists, the response includes nextPageToken. Send it unchanged as pageToken and keep the same filters:

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

When nextPageToken is absent, you have reached the final page. Do not interpret or construct tokens manually.

Get Scheduled Message

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

Resource parameters

The same parameters apply to the get, reschedule, and cancel operations.

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

Response

Returns the public resource for messageId.

Reschedule Scheduled Message

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

Send exactly one of scheduleTime or delay. You do not need to send campaignId, runId, or the original payload.

Request body

Reschedule to an absolute time:

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

Or move it by a delay relative to the request time:

{
  "delay": 3600000
}

¹ Send exactly one.

Response

Returns the updated public resource . With scheduleTime, status becomes scheduled; with delay, it becomes delayed. If reschedulable is false, do not attempt to reschedule it.

Cancel Scheduled Message

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

Cancels the send and returns the resource with status cancelled:

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

Response

Returns the public resource with status: "cancelled", cancelledAt, and reschedulable: false. Cancellation is idempotent: repeating DELETE for an already cancelled message returns the same resource and causes no additional effect.

States and transitions

• creating normally lasts only a moment while the task is registered.
• delayed and scheduled represent the same pending state. PATCH can switch between them without changing the rest of the lifecycle.
• While pending, DELETE moves the message to cancelled.
• processing means execution has started; the message can no longer be rescheduled or cancelled.
• sent, cancelled, and failed are final states.
• The service window, blocked-contact status, and channel rules are checked again at execution time. An accepted message can therefore end in failed.

Dates and time zones

• Send scheduleTime, from, and to in ISO 8601 format.
• Include Z or an offset such as -06:00 to avoid ambiguity. When the zone is omitted, scheduleTime uses Mexico time.
• executeAt, createdAt, updatedAt, cancelledAt, sentAt, and failedAt are always returned normalized to UTC.
• delay is calculated from the time the API accepts the request.

Idempotency

The GET operations are safe and idempotent. A PATCH with delay is relative to each request, so do not retry it automatically after an uncertain response: retrieve the resource by messageId first. After a 409, retrieve the message again and decide based on status and reschedulable.

See API errors for the shared response format and common status codes.